Elasticsearch .NET لـ C#: دليل شامل مع أمثلة عملية

1. ما هي هذه المكتبة ولماذا تحتاجها؟

Elasticsearch .NET (NEST) هو العميل الرسمي عالي المستوى للتعامل مع محرك البحث Elasticsearch من تطبيقات C# ومنصات .NET. توفر المكتبة واجهة برمجة تطبيقات (API) مقيدة الأنواع، تتيح لك تنفيذ جميع العمليات مع Elasticsearch: فهرسة المستندات، البحث، التجميعات، إدارة الفهارس والتعيينات، باستخدام أنماط مألوفة لمطوري .NET مثل LINQ، الطرق غير المتزامنة، والتسلسل عبر System.Text.Json أو Newtonsoft.Json.

لماذا تحتاج هذه المكتبة؟ Elasticsearch هو نظام موزع قوي للبحث النصي الكامل والتحليلات في الوقت الفعلي. إذا كان تطبيقك بلغة C# يحتاج إلى إجراء بحث معقد على كميات كبيرة من البيانات (سجلات، منتجات، مستندات)، أو معالجة استعلامات تحليلية (تجميعات)، أو إدارة كتلة Elasticsearch برمجيًا، فإن NEST هو الخيار الأمثل. فهو يخفي التفاصيل منخفضة المستوى لطلبات HTTP وتسلسل JSON، ويوفر واجهة fluent وكتابة مقيدة للأنواع.

تدعم المكتبة جميع إصدارات Elasticsearch بدءًا من 6.x، كما أنها متوافقة مع .NET Standard 2.0، مما يسمح باستخدامها في مشاريع .NET Framework 4.6.1+ و.NET Core 2.0+ و.NET 5/6/7/8/9. يتم تطوير NEST بنشاط من قبل شركة Elastic والمجتمع، وتتمتع بتوثيق شامل والعديد من الأمثلة.

2. التثبيت

يتم التثبيت عبر NuGet Package Manager. استخدم أحد الأوامر التالية:

// عبر .NET CLI
dotnet add package NEST

// عبر Package Manager Console
Install-Package NEST

// أو عبر واجهة NuGet: ابحث عن "NEST" وقم بتثبيت أحدث إصدار مستقر

يمكنك أيضًا تثبيت العميل منخفض المستوى Elasticsearch.Net، لكن NEST يضمه كتبعية.

3. بداية سريعة — مثال عملي مصغر

أنشئ تطبيق وحدة تحكم .NET وأضف توجيهات using:

using System;
using System.Threading.Tasks;
using Nest;
using static System.Console;

public class Program
{
    public static async Task Main(string[] args)
    {
        // 1. إعداد الاتصال
        var settings = new ConnectionSettings(new Uri("http://localhost:9200"))
            .DefaultIndex("my_index");
        
        var client = new ElasticClient(settings);

        // 2. تعريف نموذج البيانات
        var document = new Product
        {
            Id = 1,
            Name = "لابتوب",
            Description = "لابتوب ألعاب قوي",
            Price = 1500.99
        };

        // 3. فهرسة المستند
        var indexResponse = await client.IndexAsync(document, idx => idx.Index("products"));
        if (indexResponse.IsValid)
            WriteLine($"تمت فهرسة المستند: {indexResponse.Id}");

        // 4. البحث عن مستند
        var searchResponse = await client.SearchAsync(s => s
            .Index("products")
            .Query(q => q
                .Match(m => m
                    .Field(f => f.Name)
                    .Query("لابتوب")
                )
            )
        );

        foreach (var hit in searchResponse.Hits)
        {
            WriteLine($"تم العثور على: {hit.Source.Name} - {hit.Source.Price:C}");
        }
    }
}

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public double Price { get; set; }
}

4. أهم الدوال/الكلاسات

4.1. ElasticClient.IndexAsync

التوقيع: Task<IndexResponse> IndexAsync<T>(T document, Func<IndexDescriptor<T>, IIndexRequest<T>> selector = null, CancellationToken ct = default)

الوظيفة: يقوم بفهرسة (إضافة أو تحديث) مستند في الفهرس المحدد. إذا كان المستند بنفس