تست

برای پیاده‌سازی جستجوی فوق‌پیشرفته با Elasticsearch در پروژه‌ی ASP.NET Core، بهترین و مدرن‌ترین روش استفاده از **کلاینت رسمی Elasticsearch به همراه قابلیت جدید LINQ to ES|QL** است. این روش به شما امکان می‌دهد تا کوئری‌های جستجوی پیچیده را با همان سینتکس زیبای LINQ که در EF Core استفاده می‌کنید، بنویسید.

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

### 🏗️ معماری کلی راه‌حل

فرایند کار به دو بخش اصلی تقسیم می‌شود:
1.  **همگام‌سازی داده‌ها (Sync):** اطلاعات محصولات را از دیتابیس اصلی (SQL Server) به Elasticsearch منتقل می‌کنیم تا یک ایندکس جستجو ایجاد شود .
2.  **جستجو (Search):** یک API در ASP.NET Core ایجاد می‌کنیم که کوئری‌های جستجو را دریافت و با استفاده از کلاینت Elasticsearch، ایندکس را جستجو کرده و نتایج را برمی‌گرداند.

```mermaid
flowchart TD
    A[برنامه ASP.NET Core] --> B[API جستجو]
    B --> C[کلاینت Elasticsearch]
    C --> D[کوئری LINQ to ES|QL]
    D --> E[سرور Elasticsearch]
    E --> F[ایندکس محصولات]

    G[دیتابیس SQL Server] --> H[فرایند همگام‌سازی]
    H --> F
```

### 📦 مرحله 1: نصب پکیج‌های مورد نیاز

اولین قدم، نصب کلاینت رسمی Elasticsearch برای دات‌نت است. این پکیج شامل قابلیت جدید LINQ to ES|QL نیز می‌شود .

با استفاده از Package Manager Console یا خط فرمان، دستور زیر را اجرا کنید:
```bash
dotnet add package Elastic.Clients.Elasticsearch
```

### 🗺️ مرحله 2: تعریف مدل (Model) محصول

یک کلاس ساده برای نگاشت داده‌های محصول در کد سمت سرور و همچنین در ایندکس Elasticsearch تعریف کنید. استفاده از اتریبیوت‌های `[JsonPropertyName]` به شما کمک می‌کند تا نام فیلدها را در ایندکس کنترل کنید .

```csharp
using System.Text.Json.Serialization;

public class Product
{
    // این فیلد به عنوان شناسه اصلی در Elasticsearch استفاده خواهد شد 
    [JsonPropertyName("sku")]
    public string Sku { get; set; }

    [JsonPropertyName("name")]
    public string Name { get; set; }

    [JsonPropertyName("description")]
    public string Description { get; set; }

    [JsonPropertyName("category")]
    public string Category { get; set; }

    [JsonPropertyName("price")]
    public double Price { get; set; }

    [JsonPropertyName("in_stock")]
    public bool InStock { get; set; }

    // این فیلد برای مدیریت زمان آخرین بروزرسانی مفید است 
    [JsonPropertyName("@timestamp")]
    public DateTimeOffset UpdatedAt { get; set; }
}
```

### 🔌 مرحله 3: پیکربندی کلاینت Elasticsearch

کلاینت را در برنامه‌ی ASP.NET Core به عنوان یک سرویس (Service) ثبت (Register) کنید تا بتوانید آن را در نقاط مختلف مثل کنترلرها تزریق (Inject) کنید .

```csharp
// در فایل Program.cs
using Elastic.Clients.Elasticsearch;

var builder = WebApplication.CreateBuilder(args);

// آدرس سرور Elasticsearch خود را از appsettings.json بخوانید
var elasticsearchUri = builder.Configuration["Elasticsearch:Uri"]; // مثلا http://localhost:9200
var client = new ElasticsearchClient(new Uri(elasticsearchUri));

builder.Services.AddSingleton(client);

var app = builder.Build();

// ... ادامه کد
```

### 🔍 مرحله 4: پیاده‌سازی جستجو با LINQ to ES|QL

اکنون می‌توانید در یک کنترلر یا سرویس، از کلاینت برای اجرای کوئری‌های جستجوی پیشرفته استفاده کنید. مهم‌ترین مزیت این روش، **نوشتن کوئری‌های جستجو به صورت LINQ است که به طور خودکار به زبان ES|QL تبدیل می‌شوند** . این کار، کدنویسی را بسیار ساده‌تر و امن‌تر می‌کند و از مشکلاتی مثل تزریق کوئری (Injection) جلوگیری می‌نماید .

```csharp
[ApiController]
[Route("api/[controller]")]
public class SearchController : ControllerBase
{
    private readonly ElasticsearchClient _client;

    public SearchController(ElasticsearchClient client)
    {
        _client = client;
    }

    [HttpGet("products")]
    public async Task<IActionResult> SearchProducts([FromQuery] string query)
    {
        if (string.IsNullOrWhiteSpace(query))
        {
            return BadRequest("عبارت جستجو نمی‌تواند خالی باشد.");
        }

        // کوئری جستجوی پیشرفته با LINQ
        // این کد به طور خودکار به یک کوئری ES|QL بهینه تبدیل می‌شود 
        var searchResults = await _client.Esql.QueryAsync<Product>(q => q
            .From("products") // نام ایندکسی که محصولات در آن ذخیره شده‌اند
            .Where(p =>
                p.Name.Contains(query) ||
                p.Description.Contains(query) ||
                p.Category.Contains(query)
            )
            .Where(p => p.InStock == true) // فیلترهای اضافی
            .OrderByDescending(p => p.Price) // مرتب‌سازی بر اساس قیمت
            .Take(20) // تعداد نتایج (صفحه‌بندی)
        );

        // searchResults از نوع IAsyncEnumerable<Product> است و نتایج به صورت Stream دریافت می‌شوند 
        var results = await searchResults.ToListAsync();

        return Ok(results);
    }
}
```

### 🔄 مرحله 5: همگام‌سازی اولیه و مداوم داده‌ها

داده‌های محصولات باید از دیتابیس اصلی به Elasticsearch منتقل شوند تا قابلیت جستجو داشته باشند.

*   **همگام‌سازی اولیه:** در زمان راه‌اندازی برنامه یا با یک دستور مجزا، تمام محصولات موجود در دیتابیس را واکشی کرده و با استفاده از متد `IndexAsync` در Elasticsearch ایندکس کنید .
*   **همگام‌سازی مداوم:** برای فروشگاه‌های پویا، بهتر است با هر تغییر (ایجاد، ویرایش، حذف) در محصولات، آن تغییرات را به‌روزرسانی کنید. برای این کار می‌توانید از متدهای `IndexAsync` (برای ایجاد یا آپدیت) و `DeleteAsync` (برای حذف) استفاده کنید .

```csharp
// مثالی از ایندکس کردن یک محصول جدید یا به‌روزرسانی آن
public async Task IndexProductAsync(Product product)
{
    var response = await _client.IndexAsync(product, idx => idx.Index("products"));
    if (!response.IsValidResponse)
    {
        // خطا را مدیریت کنید
    }
}
```

### 💎 خلاصه و نکات کلیدی

با این پیاده‌سازی، شما از مزایای زیر بهره‌مند می‌شوید:
*   **سرعت و مقیاس‌پذیری بالا:** Elasticsearch برای جستجو در حجم عظیم داده بهینه شده است .
*   **کدنویسی ساده و خواناتر:** به جای نوشتن کوئری‌های پیچیده و دستی ES|QL، از سینتکس آشنا و قدرتمند LINQ استفاده می‌کنید .
*   **قابلیت‌های پیشرفته جستجو:** به راحتی می‌توانید فیلترها، مرتب‌سازی‌ها، و حتی کوئری‌های مبتنی بر معیارهای چندگانه را به کوئری خود اضافه کنید .

> نکته مهم: برای پروژه‌های واقعی، نیاز به همگام‌سازی داده‌ها (به‌خصوص برای بیش از یک میلیون محصول) بسیار حیاتی است. بهتر است این کار را با استفاده از راهکارهای مدیریت خطا و پردازش دسته‌ای (Batch Processing) انجام دهید تا از فشار بیش از حد بر روی دیتابیس و سرور Elasticsearch جلوگیری شود .