‫راهنمای مدیریت عملیات رشته‌ای و نگاشت آن‌ها در نگاشت‌های EF Core

۱. چکیده: یکی از چالش‌های رایج توسعه‌دهندگان دات‌نت هنگام استفاده از Entity Framework Core، درک تفاوت میان «عبارات معتبر در زبان #C» و «عبارات قابل ترجمه به SQL (SQL Translation)» است. در لایه نگاشت داده (Projection) یا عبارات شرطی، استفاده نادرست از متدهای دستکاری رشته (مانند string.Format، برخی سربارگذاری‌های ToString، و فرمت‌بندی‌های مبتنی بر فرهنگ داده) می‌تواند به شکست ترجمه، پرتاب استثنا در زمان اجرا یا ارزیابی ناخواسته سمت کلاینت (Client Evaluation) منجر شود. هدف این مقاله، تحلیل علمی و کاربردی نحوه برخورد موتور پردازش کوئری EF Core با توابع رشته‌ای، تفکیک دقیق بین Translation و Client Evaluation، دسته‌بندی عملیات مجاز و غیرمجاز، و ارائه یک الگوی معماری دو‌مرحله‌ای جهت تضمین کارایی (Performance) و تمیزی کد است.

• ارزیابی خودکار سمت کلاینت در بخش‌های میانی (مانند Where، OrderBy و GroupBy) به کلی حذف شد. در صورت عدم امکان ترجمه این متدها به SQL، موتور پردازشگر کوئری بی‌درنگ استثنای زمان اجرا (مانند InvalidOperationException) صادر می‌کند.
• ارزیابی سمت کلاینت تنها در آخرین لایه نگاشت نهایی (Top-level Projection) مجاز شمرده شد.

var query = await db.Customers
    .Select(x => new
    {
        x.Id,
        FormattedText = string.Format("{0} - {1}", x.FirstName, x.LastName)
    })
    .ToListAsync();

• استفاده از این فیلد فرمت‌شده در شروط Where یا OrderBy غیرممکن است و خطای ترجمه خواهد داد.
• اجرای مکرر فرمت‌بندی‌های سنگین در کلاینت برای رکوردهای پرتعداد، بار پردازشی بیهوده‌ای به حافظه تخصیص می‌دهد.

• حالت ساده: زمانی که اینترپولیشن تنها شامل متغیرهای متنی ساده باشد ($"{x.FirstName} {x.LastName}")، کامپایلر آن را به string.Concat تبدیل کرده و EF Core به خوبی آن را به عملگر + یا CONCAT ترجمه می‌کند.
• حالت فرمت‌دار: اگر ساختار شامل Format Specifier باشد (مانند $"{x.FirstName} - {x.Balance:N2}")، به دلیل کامپایل شدن به متدهای پیچیده قالب‌بندی .NET، ترجمه سمت دیتابیس با شکست مواجه می‌شود.

• تبدیل انواع عددی یا شناسه ساده مانند x.Id.ToString() به دستور CONVERT(varchar, [Id]) یا CAST تبدیل می‌شود.
• در مقابل، فرمت‌های شرطی یا فرهنگ‌محور نظیر x.Date.ToString("yyyy-MM-dd") یا x.Price.ToString("C") به SQL ترجمه نخواهند شد.

// نادرست: عدم امکان ترجمه به SQL
.Where(x => x.Name.Equals("admin", StringComparison.OrdinalIgnoreCase))

.Where(x => EF.Functions.Collate(x.Name, "SQL_Latin1_General_CP1_CI_AS") == "admin")

[ IQueryable<Entity> ]
                            │
               ┌────────────┴────────────┐
               │    SQL-Safe Logic       │
               │ (Where, Join, OrderBy)  │
               └────────────┬────────────┘
                            │
                            ▼
               [ SQL Translation & Exec ]
                            │
                            ▼
                  [ ToListAsync() ]   <─── مرز تفکیک (Materialization)
                            │
               ┌────────────┴────────────┐
               │   In-Memory Processing  │
               │ (string.Format, Regex,  │
               │  ToString("N2"), DTOs)  │
               └────────────┬────────────┘
                            │
                            ▼
                   [ Final Result DTO ]

public async Task<List<CustomerDto>> GetCustomerReportsAsync(CancellationToken cancellationToken)
{
    // فاز ۱: واکشی امن و بهینه از پایگاه‌داده با استفاده از Projection خالص
    var rawData = await _context.Customers
        .AsNoTracking()
        .Where(c => c.IsActive && c.LastName.StartsWith("A")) // استفاده بهینه از ایندکس
        .Select(c => new
        {
            c.Id,
            c.FirstName,
            c.LastName,
            c.Balance,
            c.RegisteredDate
        })
        .ToListAsync(cancellationToken); // نقطه انتقال به حافظه (Materialization)

    // فاز ۲: اعمال فرمت‌بندی، منطق تجاری و غنی‌سازی داده در حافظه
    var result = rawData.Select(c => new CustomerDto
    {
        Id = c.Id,
        FullName = string.Format("{0} {1}", c.FirstName, c.LastName),
        FormattedBalance = c.Balance.ToString("N2", CultureInfo.InvariantCulture),
        PersianDate = ConvertToJalali(c.RegisteredDate) // متدهای سفارشی به‌راحتی اجرا می‌شوند
    }).ToList();

    return result;
}

var query = _context.Customers
    .Select(x => new
    {
        FullName = x.FirstName + " " + x.LastName
    });

// بررسی SQL خروجی
string generatedSql = query.ToQueryString();
Console.WriteLine(generatedSql);