تشخیص و تعریف کلاس‌های برنامه

public class Rectangle
{
   public double Width;
   public double Height;
 
   public double Area()
   {
      return Width*Height;
   }
 
   public double Perimeter()
   {
      return 2*(Width + Height);
   }
}

• کلاس با کلمه کلیدی class تعریف می‌شود.
• همان طور که مشاهده می‌کنید تعریف کلاس با کلمه public آغاز شده است. این کلمه محدوده دسترسی به کلاس را تعیین می‌کند. در اینجا از کلمه public استفاده کردیم تا بخش‌های دیگر برنامه امکان استفاده از این کلاس را داشته باشند.
• پس از کلمه کلیدی class نوبت به نام کلاس می‌رسد. اگرچه انتخاب نام مورد نظر امری اختیاری است اما در آینده حتماً اصول و قراردادهای نام‌گذاری در دات‌نت را مطالعه نمایید. در حال حاضر حداقل به خاطر داشته باشید تا انتخاب نامی مناسب که گویای کاربرد کلاس باشد بسیار مهم است.
• باقیمانده کد، بدنه کلاس را تشکیل می‌دهد. جاییکه ویژگی ها، رفتار‌ها و ... یا به طور کلی اعضای کلاس تعریف می‌شوند.

ایجاد شیء از یک کلاس و نحوه دسترسی به شیء ایجاد شده

Rectangle rectangle = new Rectangle();

Rectangle rectangle;

Rectangle rectangle1 = new Rectangle();
Rectangle rectangle2 = rectangle1;

Rectangle rectangle = new Rectangle();
rectangle.Width = 10.5;
rectangle.Height = 10;
double a = rectangle.Area();

فیلدها

// public field (Generally not recommended.)
public double Width;

Rectangle rectangle = new Rectangle();
rectangle.Width = 10.5;

public class Rectangle
{
   public double Width = 5;
   // ...
}

متدها

public class Rectangle
{
   // ...
 
   public double Area()
   {
      return Width*Height;
   }
 
   public double Perimeter()
   {
      return 2*(Width + Height);
   }
}

Rectangle rectangle = new Rectangle();
rectangle.Width = 10.5;
rectangle.Height = 10;
double p = rectangle.Perimeter();

public class SimpleMath
{
   public int AddTwoNumbers(int number1, int number2)
   {
      return number1 + number2;
   }
}

SimpleMath obj = new SimpleMath();

Console.WriteLine(obj.AddTwoNumbers(1, 2));

int result = obj.AddTwoNumbers(1, 2);
Console.WriteLine(result);

مطالب پیشین مرتبط با لوسین را در اینجا می‌توانید پیگیری کنید. آخرین نگارش آن که تا این تاریخ، 4.8 بتا است، با ‌دات‌نت(Core) سازگار است و روش برپایی آغازین آن ... تغییرات قابل توجهی داشته‌است که خلاصه‌ی آن‌ها را در این مطلب بررسی خواهیم کرد.

1) بسته‌های جدید مورد نیاز

برای کار با لوسین جدید، نیاز است حداقل سه‌بسته‌ی زیر را نصب کنیم تا به امکانات پایه‌ای و کوئری گیری‌های پیشرفته‌ی آن دسترسی داشته باشیم:

<PackageReference Include="Lucene.Net" Version="4.8.0-beta00016"/>
<PackageReference Include="Lucene.Net.Analysis.Common" Version="4.8.0-beta00016"/>
<PackageReference Include="Lucene.Net.QueryParser" Version="4.8.0-beta00016"/>

2) تهیه نگاشت‌های لازم

فرض کنید شیء اصلی ما چنین ساختاری را دارد:

public class WhatsNewItemModel
{
    public required int Id { set; get; }

    public required string OriginalTitle { set; get; }
}

مرحله‌ی بعد کار با لوسین، تبدیل اشیاء سفارشی خود به شیء Document لوسین و برعکس است. به همین جهت به دو مپر برای این کارها نیاز است:

الف) نگاشت‌گر یک شیء سفارشی، به شیء Document

public static class LuceneDocumentMapper
{
    public static Document MapToLuceneDocument(this WhatsNewItemModel post)
    {
        ArgumentNullException.ThrowIfNull(post);

        return
        [
            new TextField(nameof(WhatsNewItemModel.OriginalTitle), post.OriginalTitle, Field.Store.YES),

            // Document StringField instances are sort of keywords, they are not analyzed, they indexed as is (in its original case).
            new StringField(nameof(WhatsNewItemModel.Id), post.Id.ToString(CultureInfo.InvariantCulture),
                Field.Store.YES),
        ];
    }
}

در اینجا یک متدالحاقی را تهیه کرده‌ایم تا شیءای از نوع WhatsNewItemModel ما را به یک شیء Document لوسین، تبدیل کند.

چند نکته در اینجا حائز اهمیت هستند:

- در نگارش جدید لوسین، با اشیاء TextField و StringField جدید سروکار داریم و شیء قدیمی Field نگارش‌های قبلی لوسین، منسوخ شده درنظر گرفته می‌شود.

- زمانی از شیء TextField استفاده می‌کنیم که قرار است توسط لوسین، تحلیل شده و در جستجوهای پیچیده استفاده شود.

- اگر فقط قرار است، مقداری را در این ایندکس ذخیره کنیم و قصد تحلیل آن‌ها را نداریم و حداکثر یک کوئری ساده‌ی یافتن اصل آن‌ها، مدنظر ما است، باید از اشیاء StringField برای معرفی و نگاشت آن‌ها استفاده کنیم (شبیه به کار با واژه‌های کلیدی).

- پرچم Field.Store.YES به این معنا است که اصل محتوای تحلیل شده نیز در ایندکس لوسین، درج شود. اگر این پرچم را به NO تنظیم کنیم، فقط تحلیل آن صورت گرفته و نتیجه‌ی آن ذخیره می‌شود، که برای جستجوها مفید است؛ اما مقدار این فیلد دیگر قابل بازیابی نخواهد بود.

ب) نگاشت‌گر یک شیء Document لوسین، به یک شیء سفارشی

در زمان کوئری گرفتن از لوسین، خروجی نهایی یک شیء Document آن است که باید به شیء سفارشی مدنظر ما نگاشت شود:

public static class LuceneDocumentMapper
{
    public static LuceneSearchResult MapToLuceneSearchResult(this Document document)
    {
        ArgumentNullException.ThrowIfNull(document);

        return new LuceneSearchResult
        {
            Id = document.Get(nameof(WhatsNewItemModel.Id), CultureInfo.InvariantCulture).ToInt(),
            OriginalTitle = document.Get(nameof(WhatsNewItemModel.OriginalTitle), CultureInfo.InvariantCulture)
        };
    }
}

نمونه‌ای از این نگاشت را در متد الحاقی فوق مشاهده می‌کنید که توسط متد Get شیء Document قابل انجام است. بدیهی است خروجی این متد، یک رشته‌است و در صورت نیاز باید توسط ما کار تبدیلات ثانویه آن‌ها انجام شود.

3) نیاز به یک تحلیل‌گر مناسب

لوسین برای تولید ایندکس‌های جستجوی تمام متنی خود، از یک سری Analyzer استفاده می‌کنید که اگر سری پیشین مطالب مرتبط را مطالعه کنید، به نمونه‌ی StandardAnalyzer آن خواهید رسید که هنوز هم معتبر و قابل استفاده‌است و یا می‌توان همانند سایت جاری، از یک LowerCaseHtmlStripAnalyzer استفاده کرد که این کارها را همزمان انجام می‌دهد:

الف) از یک لیست PersianStopwords.List برای حذف واژه‌های کم اهمیت زبان فارسی استفاده می‌کند. برای مثال ما نمی‌خواهیم که واژه‌ی «ما» را با اهمیت شمرده و ایندکس کند و امثال آن.

ب) LowerCaseFilter را به متون دریافتی اعمال می‌کند. این کار در پشت صحنه‌ی StandardAnalyzer توکار لوسین هم اعمال می‌شود. اگر با این موضوع آشنا نباشید، ممکن است در حین کوئری گرفتن، به نتیجه‌ای نرسید! چون متن ارسالی به لوسین را ابتدا باید lower-case کنید و سپس آن‌را کوئری بگیرید.

ج) HTMLStripCharFilter توکار لوسین هم به آن اعمال شده‌است. از این جهت که متن مقالات ما به همراه تگ‌های HTML ای هم هستند. این فیلتر کار حذف کردن آن‌ها را در حین تحلیل، انجام می‌دهد و دیگر نیازی نیست تا ما خودمان متن ارسالی به لوسین را تمیز کنیم.

نکته‌ی مهم: این تحلیل‌گر ویژه، فقط باید به فیلدهایی از نوع TextField اعمال شود. اگر آن‌را به StringField ها اعمال کنیم، دیگر قادر به کوئری گرفتن از آن‌ها نخواهیم بود! چون تحلیل‌گر StringFieldها باید از نوع توکار KeywordAnalyzer ثبت و معرفی شود. این نوع فیلدها، حالت واژه‌های کلیدی را دارند (به همان صورتی که هست ثبت می‌شوند) و قرارنیست که توسط لوسین تحلیل ویژه‌ای شوند. به همین جهت برای رسیدن به یک تحلیل‌گر ترکیبی که بتواند این دو نوع فیلد را با هم پوشش دهد و کار معرفی چندین نوع تحلیل‌گر را یکجا انجام دهد، نیاز به یک PerFieldAnalyzerWrapper جدید داریم:

_keywordAnalyzer = new KeywordAnalyzer();

        _lowerCaseHtmlStripAnalyzer = new LowerCaseHtmlStripAnalyzer(LuceneVersion);

        _analyzer = new PerFieldAnalyzerWrapper(_lowerCaseHtmlStripAnalyzer, new Dictionary<string, Analyzer>
        {
            {
                nameof(WhatsNewItemModel.Id), _keywordAnalyzer
            }
        });

PerFieldAnalyzerWrapper در حقیقت برای تمام فیلدهایی که در قسمت دیکشنری فوق، ذکر نشده‌اند، از LowerCaseHtmlStripAnalyzer استفاده می‌کند. برای مابقی موارد از KeywordAnalyzer کمک خواهد گرفت.

4) روش صحیح راه اندازی reader و writer های ایندکس لوسین جدید

کار با لوسین به حدی سریع است که از کیفیت آن شگفت زده خواهید شد! اما ... به‌شرطی که بدانید دقیقا به چه صورتی باید نویسنده و خواننده‌ی ایندکس‌های آن‌را مدیریت کنید. اکثر مثال‌هایی را که بر روی اینترنت پیدا می‌کنید، به همراه متدهایی هستند که مدام در حال گشودن و dispose این نویسنده‌ها و خواننده‌های ایندکس هستند که ... این مثال‌ها، روش کار صحیح با لوسین نیستند! و به شدت آن‌‌را کند می‌کنند.

نکته‌ی مهمی که این مثال‌ها به آن توجهی نکرده‌اند، «thread-safe» بودن نویسنده و خواننده‌ی ایندکس لوسین است. یعنی می‌توان یک نمونه از این‌ها را در ابتدای کار برنامه ایجاد کرد و تا آخر کار برنامه، بدون نیاز به نمونه سازی مجدد و باز و بسته کردن آن‌ها، بارها مورد استفاده‌ی مجدد قرار داد و هیچ تداخلی هم ندارند و از قسمت‌های مختلف برنامه هم قابل دسترسی هستند.

به همین جهت باید یک سرویس مرکزی را برای اینکار تدارک دید که طول عمر آن، حتما Singleton باشد تا بتواند نویسنده و خواننده‌ی ایندکس لوسین را فقط یکبار نمونه سازی و ایجاد کرده و تا پایان کار برنامه، زنده نگه دارد (کدهای کامل این کلاس را در اینجا می‌توانید مطالعه کنید):

public class FullTextSearchService : IFullTextSearchService
{
    private const LuceneVersion LuceneVersion = Lucene.Net.Util.LuceneVersion.LUCENE_48;
    private readonly Analyzer _analyzer;

    private readonly IAppFoldersService _appFoldersService;
    private readonly FSDirectory _fsDirectory;

    //  IndexWriter instances are completely thread safe, meaning multiple threads can call any of its methods, concurrently.
    private readonly IndexWriter _indexWriter;

    private readonly KeywordAnalyzer _keywordAnalyzer;
    private readonly ILogger<FullTextSearchService> _logger;
    private readonly LowerCaseHtmlStripAnalyzer _lowerCaseHtmlStripAnalyzer;

    // Safely shares IndexSearcher instances across multiple threads, while periodically reopening.
    private readonly SearcherManager _searcherManager;

    private bool _isDisposed;

    public FullTextSearchService(IAppFoldersService appFoldersService, ILogger<FullTextSearchService> logger)
    {
        _appFoldersService = appFoldersService ?? throw new ArgumentNullException(nameof(appFoldersService));
        _logger = logger;

        _keywordAnalyzer = new KeywordAnalyzer();

        _lowerCaseHtmlStripAnalyzer = new LowerCaseHtmlStripAnalyzer(LuceneVersion);

        _analyzer = new PerFieldAnalyzerWrapper(_lowerCaseHtmlStripAnalyzer, new Dictionary<string, Analyzer>
        {
            // Document StringField instances are sort of keywords, they are not analyzed, they indexed as is (in its original case).
            // But StandardAnalyzer applies lower case filter to a query.
            // We can fix this by using KeywordAnalyzer with our query parser.
            {
                nameof(WhatsNewItemModel.Id), _keywordAnalyzer
            },
            {
                nameof(WhatsNewItemModel.DocumentTypeIdHash), _keywordAnalyzer
            },
            {
                nameof(WhatsNewItemModel.DocumentContentHash), _keywordAnalyzer
            }
        });

        _fsDirectory = FSDirectory.Open(_appFoldersService.LuceneIndexFolderPath);

        _indexWriter = new IndexWriter(_fsDirectory, new IndexWriterConfig(LuceneVersion, _analyzer));
        _searcherManager = new SearcherManager(_indexWriter, applyAllDeletes: true, searcherFactory: null);
    }

این سرویس، یک سرویس Singleton است که نحوه‌ی آغاز و شروع به کار با اشیاء لوسین را در سازنده‌ی آن مشاهده می‌کنید.

توضیحات:

الف) در اینجا، روش نمونه سازی PerFieldAnalyzerWrapper را که پیشتر در مورد آن بحث شد، مشاهده می‌کنید.

ب) سپس یک IndexWriter، نمونه سازی می‌شود که از تحلیل‌گر ترکیبی ما استفاده می‌کند.

ج) در ادامه یک SearcherManager جدید را مشاهده می‌کنید که با IndexWriter برنامه هماهنگ است و هر زمانیکه سندی به لوسین اضافه می‌شود، قادر به کوئری گرفتن از آن هم خواهیم بود.

نکته‌ی مهم: طول عمر تمام این موارد، با طول عمر کلاس سرویس جاری، یکی است. یعنی تنها یکبار در طول عمر برنامه نمونه سازی شده و تا پایان کار آن، زنده نگه داشته می‌شوند.

5) روش افزودن یک سند به ایندکس لوسین و سپس به روز رسانی آن

اکنون با استفاده از نگاشت‌گرهایی که در ابتدای بحث تهیه کردیم و همچنین شیء IndexWriter فوق، به صورت زیر می‌توان یک شیء سفارشی خود را به ایندکس لوسین اضافه کنیم:

_indexWriter.AddDocument(post.MapToLuceneDocument());
_indexWriter.Flush(triggerMerge: true, applyAllDeletes: true);
_indexWriter.Commit();

و یا اگر خواستیم سند موجودی را به روز کنیم، روش کار به شکل زیر است:

_indexWriter.UpdateDocument(new Term(nameof(WhatsNewItemModel.Id), post.Id.ToString()),
                post.MapToLuceneDocument());

new Term، در حقیقت یک کوئری جدید را سبب می‌شود که توسط آن سندی یافت شده، در پشت صحنه حذف می‌شود و سپس سند جدیدی بجای آن درج خواهد شد. در اینجا باید دقت داشت که چون Id ثبت شده از نوع StringField است، نباید حالت lower-case آن‌را جستجو کرد و باید دقیقا به همان نحوی که ثبت شده، جستجو شود.

6) روش کار با searcherManager جدید لوسین

همانطور که عنوان شد، لوسین جدید به همراه یک searcherManager هم هست که کار آن، ارائه‌ی thread-safe دسترسی به خواننده‌ی ایندکس‌ لوسین است. نحوه‌ی عمومی کار با آن را در ادامه مشاهده می‌کنید:

private TResult DoSearch<TResult>(Func<IndexSearcher, TResult> action, TResult defaultValue)
    {
        _searcherManager.MaybeRefreshBlocking();
        var indexSearcher = _searcherManager.Acquire();

        try
        {
            return action(indexSearcher);
        }
        catch (FileNotFoundException)
        {
            // It's not indexed yet.
            return defaultValue;
        }
        finally
        {
            _searcherManager.Release(indexSearcher);
        }
    }

با استفاده از searcherManager، در طول مدت زمان کوتاهی، بر روی ایندکس قفل‌گذاری شده و یک indexSearcher امن، در اختیار متدهای استفاده کننده‌ی از آن قرار می‌گیرند و در پایان کار، این قفل رها می‌شود.

برای مثال یک نمونه روش استفاده از این indexSearcher امن، به صورت زیر است:

public int GetNumberOfDocuments() => DoSearch(indexSearcher => indexSearcher.IndexReader.NumDocs, defaultValue: 0);

مابقی مثال‌های آن‌را می‌توانید در کلاس FullTextSearchService مشاهده کنید که به همراه یافتن «مطالب مشابه»، جستجوهای صفحه بندی شده، جستجوهای مرتب شده‌ی بر اساس یک فیلد، امکان دسترسی به تمام اسناد ذخیره شده‌ی در ایندکس لوسین و امثال آن است که کلیات آن با قبل تفاوتی نکرده‌است و مطالب و نکات آن‌را پیشتر در مقالات سری لوسین بررسی کرده‌ایم. تنها تفاوت مهمی که در اینجا وجود دارد، نحوه‌ی برپایی و راه اندازی تحلیل‌گر، خواننده و نویسنده‌ی ایندکس آن است که در این مطلب بررسی شدند؛ وگرنه کلیات جستجوی پیشرفته‌ی آن، مانند قبل است و تفاوت خاصی نکرده‌است.

public class Source
{
    public string Value1 { get; set; }
    public string Value2 { get; set; }
    public string Value3 { get; set; }
}

public class Destination
{
    public int Value1 { get; set; }
    public DateTime Value2 { get; set; }
    public Type Value3 { get; set; }
}

public class BooltoStringTypeConvertor : ITypeConverter<bool, string>
    {
        public string Convert(ResolutionContext context)
        {
            return (bool)context.SourceValue ? "Yes" : "No";
        }
    }

Mapper.CreateMap<bool,string>().ConvertUsing<BooltoStringTypeConvertor>();
            Mapper.CreateMap<Product, ProductDto>();
            Mapper.AssertConfigurationIsValid();

var product = new Product { Id = 1,Name ="PC" ,InStock = true };
var productDto = Mapper.Map<Product, ProductDto>(product);

نکته: TypeConvertor‌ها میدان دیدشون سراسریه و نیازی نیست به ازای هر نگاشتی اونو به AutoMapper  معرفی کنیم Global Scope.

Custom value resolvers

کلاس‌های زیر رو در نظر بگیرید

public class Person
{
    public int Id { get; set; }

    public string FirstName { get; set; }

    public string LastName { get; set; }
}

public class PersonDTO
{
    public int Id { get; set; }

    public string RawData { get; set; }
}

public class CommaDelimetedResolver:ValueResolver<Person,string>
    {
        protected override string ResolveCore(Person source)
        {
            return string.Join(",", source.Id, source.FirstName, source.LastName);
        }
    }

Mapper.CreateMap<Person, PersonDTO>().ForMember(
                des => des.RawData, op => op.ResolveUsing<CommaDelimetedResolver>());


var person = new Person
{
Id = 1,
FirstName = "Mohammad",
LastName = "Saheb",
};

var personDTO = Mapper.Map<Person, PersonDTO>(person);

public class ShamsiFormatter:IValueFormatter
    {
        public string FormatValue(ResolutionContext context)
        {
            return ToShamsi(context.SourceValue.ToString());
        }
    }

Mapper.CreateMap<Person, PersonDTO>().ForMember(
            des => des.ShamsiDate, op => op.AddFormatter<ShamsiFormatter>());

این توسعه دهندگان بیشتر سعی در تسخیر و دستیابی به یک مکانیزم کنترل مرکزی شبیه به آنچه در پارادایم action-oriented داشته‌اند، در طراحی شیء گرای خود دارند. حاصل این کار تشکیل کلاسی خواهد بود که همه کارها را انجام می‌دهد، درحالیکه جزئیات ناچیزی هم به عهده مجموعه‌ای از کلاس‌ها سپرده شده است.

قاعده شهودی 3.1

تا حد ممکن هوشمندی سیستم را به صورت افقی و به طور یکنواخت توزیع کنید. به این معنی که کلاس‌های سطح بالای موجود در طراحی، باید کار را به طور یکسان مابین خود به اشتراک بگذارند. (Distribute system intelligence horizontally as uniformly as possible, that is, the top-level classes in a design should share the work uniformly)

در سیستم خود God Class ایجاد نکنید. به کلاس هایی که نام آنها شامل Driver، Manager و یا Subsystem می‌باشد، مشکوک باشید. (Do not create god classes/objects in your system. Be very suspicious of a class whose name contains Driver, Manager, System, or Subsystem)

مانند: BlahBlahSystem یا BlahManager

مراقب کلاس هایی باشید که در واسط عمومی آنها تعداد زیادی Accessor Method تعریف شده است؛ وجود آنها نشان از این دارد که داده و رفتار، در یکجا نگه داشته نشده اند. (Beware of classes that have many accessor methods defined in their public interface. Having many implies that related data and behavior are not being kept in one place)