Entity Framework Core

#EF Core و DbContext كـ Unit of WorkEF Core and DbContext as a unit of work

كتابة mapping و SQL متكرر لكل CRUD بتستهلك وقت. EF Core هو ORM بيحوّل LINQ مدعوم لـ queries، ويرجع objects، ويتابع التغييرات ويحفظها. مش بيغنيك عن فهم SQL أو الـ provider.

using Microsoft.EntityFrameworkCore;

public sealed class StoreDb(DbContextOptions<StoreDb> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();       // (1)
}
public sealed class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
}

// In Program.cs, with the SQL Server provider installed:
builder.Services.AddDbContext<StoreDb>(o => o.UseSqlServer(connectionString)); // (2)
// In a scoped handler receiving StoreDb db:
db.Products.Add(new Product { Name = "Mug", Price = 120m });
await db.SaveChangesAsync(ct);                             // (3)

generic repository بيكرر DbSet و SaveChanges مش شرط يضيف قيمة. اعمل abstraction لو بيحمي boundary أو business queries حقيقية.

#Fluent API و schema ownershipFluent API and schema ownership

conventions بداية كويسة، لكنها مش بديل تعريف precision والعلاقات والـ indexes. Fluent API بتفصل persistence rules عن الـ entity.

using Microsoft.EntityFrameworkCore.Metadata.Builders;

public sealed class ProductConfig : IEntityTypeConfiguration<Product>
{
    public void Configure(EntityTypeBuilder<Product> e)
    {
        e.ToTable("Products");
        e.HasKey(p => p.Id);                              // (1)
        e.Property(p => p.Name).HasMaxLength(200).IsRequired();
        e.Property(p => p.Price).HasPrecision(18, 2);       // (2)
        e.HasIndex(p => p.Name);                          // (3)
    }
}
// Inside StoreDb:
// protected override void OnModelCreating(ModelBuilder b) =>
//     b.ApplyConfigurationsFromAssembly(typeof(StoreDb).Assembly);

للعلاقات استخدم HasMany و WithOne و HasForeignKey وحدد DeleteBehavior بوعي. database-first بيعمل scaffold من schema موجودة؛ code-first بيقود schema من model و migrations. اختار مصدر حقيقة واحد وماتعدّلش generated scaffold عشوائي من غير خطة إعادة توليد.

#Loading strategies و projectionLoading strategies and projection

عرض order summary مش محتاج تحميل كل product وكل payment. اختار أقل داتا تحقق المطلوب، وخلي الرحلات للـ database ظاهرة.

// These snippets assume an Order model with Lines and Customer navigations.
var entity = await db.Orders.Include(o => o.Lines)
    .SingleAsync(o => o.Id == id, ct);                     // (1)

await db.Entry(entity).Reference(o => o.Customer).LoadAsync(ct); // (2)

var summary = await db.Orders.Where(o => o.Id == id)
    .Select(o => new { o.Id, o.Total, LineCount = o.Lines.Count })
    .SingleAsync(ct);                                     // (3)

lazy loading يعمل query لما navigation تتقري. الـ proxies محتاجة package وإعدادات و navigations قابلة للـ override؛ ILazyLoader بديل. الاتنين ممكن يخبّوا I/O ويسببوا N+1. الـ projection اللي جواها entity، زي new { Order = o }، ممكن تعمل tracking للـ entity دي.

#Tracking و AsNoTracking و identity resolutionTracking, no-tracking and identity resolution

لو هتعدّل entity وتحفظها، EF محتاج يعرف الأصل والتغيير. لو بتعرض catalog بس، bookkeeping ده غالباً مش مطلوب.

var product = await db.Products.SingleAsync(p => p.Id == id, ct); // (1)
product.Price = newPrice;
await db.SaveChangesAsync(ct);

var catalog = await db.Products.AsNoTracking()
    .OrderBy(p => p.Id).Take(20).ToListAsync(ct);             // (2)

var graph = await db.Orders.AsNoTrackingWithIdentityResolution()
    .Include(o => o.Customer).Take(20).ToListAsync(ct);       // (3)

tracking query ممكن ترجع object موجود بالفعل في context بقيمه الحالية؛ مش refresh مضمون. للـ detached updates اعمل attach بحذر وحدد الحقول المسموحة و original concurrency token. Update على graph جاي من client ممكن يعلّم حقول زيادة ويعمل over-posting.

#N+1 و cartesian explosion و split queriesN+1, cartesian explosion and split queries

endpoint ممكن يبقى بطيء من عدد الرحلات أو من حجم query واحدة. دول مش نفس المشكلة.

var orders = await db.Orders.ToListAsync(ct);
foreach (var order in orders)
    Console.WriteLine(order.Lines.Count);

var counts = await db.Orders
    .Select(o => new { o.Id, Count = o.Lines.Count })
    .ToListAsync(ct);

var orders = await db.Orders
    .Include(o => o.Lines)
    .Include(o => o.Payments)
    .AsSplitQuery()                                       // (1)
    .OrderBy(o => o.Id).Take(20).ToListAsync(ct);

split بيقلل التكرار لكن بيزود round trips والـ buffering. مجرد transaction على Read Committed مش snapshot موحّد؛ لو الاتساق بين statements مطلوب، اختار snapshot أو serializable مناسبين والـ cost بتاعتهم. راقب SQL logs وعدد queries والـ actual plan قبل الاختيار. ماتفعّلش sensitive data logging في production لمجرد التشخيص.

#ExecuteUpdate و ExecuteDelete في EF Core 10Set-based changes in EF Core 10

تعديل آلاف entities بعد تحميلها بيكلف memory و tracking و SQL كتير. set-based operations بتعمل التغيير في الـ database مباشرة.

int changed = await db.Orders.Where(o => o.Status == "Pending")
    .ExecuteUpdateAsync(setters =>                         // (1)
    {
        setters.SetProperty(o => o.Status, "Expired");
        if (stampTime)
            setters.SetProperty(o => o.UpdatedAt, now);
    }, ct);

int deleted = await db.Orders
    .Where(o => o.Status == "Draft" && o.CreatedAt < cutoff)
    .ExecuteDeleteAsync(ct);                              // (2)

#Migrations في production و expand-contractProduction migrations and expand-contract

schema change ممكن يقفل جدول أو يكسر النسخة القديمة أثناء rolling deploy. migration ملف قابل للمراجعة، مش إذن لتنفيذه تلقائي من كل instance.

# Requires matching dotnet-ef tools and EF Core Design package.
dotnet ef migrations add AddMobileNumber
dotnet ef migrations script --idempotent --output migrate.sql
# Alternative deployment artifact; self-contained requires an explicit option.
dotnet ef migrations bundle --self-contained -r linux-x64 -o efbundle

راجع SQL وجرّبه على حجم قريب من production، وخطط للـ backup والـ forward repair والـ lock duration. نفّذ script أو bundle في deployment step واحدة بصلاحية مخصصة. EF الحديث فيه migration locking لبعض providers، لكنه مش بيحل compatibility أو صلاحيات التطبيق أو كل أخطار DDL.

1. Expand: ضيف MobileNumber nullable وسيب Phone.
2. انشر كود متوافق. طول ما فيه writers قديمة، القديم هو المصدر المعتمد أو استخدم آلية sync موثوقة.
3. بعد خروج writers القديمة، اكتب في الاتنين واعمل backfill على batches مع معالجة concurrent writes.
4. اتحقق من اكتمال النقل، حوّل القراءة للجديد، وراقب.
5. Contract: شيل القديم في release لاحقة لما rollback والـ consumers القديمة مايحتاجوهوش.

code-first بيولّد migration بمقارنة model بالـ snapshot، مش diff شامل للـ live database. خلّي ownership واضح وراجع drift. database-first يناسب schema بتديرها جهة تانية. ماتخلطش EnsureCreated مع migrations لنفس database.

#Optimistic و pessimistic concurrencyOptimistic and pessimistic concurrency

اتنين بيعدّلوا نفس product؛ آخر حفظ ماينفعش يمسح تعديل الأول بصمت. optimistic concurrency بيكتشف version اتغير وقت الكتابة.

// On an order entity, add: public byte[] Version { get; set; } = [];
// SQL Server configuration:
modelBuilder.Entity<Order>().Property(o => o.Version).IsRowVersion(); // (1)

try
{
    order.Status = "Confirmed";
    await db.SaveChangesAsync(ct);                         // (2)
}
catch (DbUpdateConcurrencyException)
{
    return Results.Conflict(new { code = "order.changed" }); // (3)
}

-- PostgreSQL: inside a short transaction, lock before read-modify-write.
SELECT id, available FROM products WHERE id = @id FOR UPDATE;

-- For a simple reservation, an atomic statement can be enough.
UPDATE products SET available = available - @qty
WHERE id = @id AND available >= @qty;

pessimistic locking يمنع المنافس من التعديل لحد transaction تنتهي، بس ممكن يسبب blocking و deadlocks. EF مفيهوش portable LINQ lock hint لكل providers. للـ conditional update تحقق من qty موجبة وافحص affected rows؛ صفر ممكن يعني missing row أو stock مش كفاية.

#Transactions والـ execution strategyTransactions and execution strategies

SaveChanges واحدة غالباً كفاية. لو عندك أكتر من save أو bulk statement لازم ينجحوا مع بعض، حدد transaction boundary، ومع retry strategy أعد الوحدة كلها.

// probe and factory use identical provider options with retries configured.
await using var probe = await factory.CreateDbContextAsync(ct);
var strategy = probe.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>                    // (1)
{
    await using var db = await factory.CreateDbContextAsync(ct);
    await using var tx = await db.Database.BeginTransactionAsync(ct); // (2)
    var order = await db.Orders.SingleAsync(o => o.Id == orderId, ct);
    order.Status = "Confirmed";
    await db.SaveChangesAsync(ct);
    await db.OrderLines.Where(l => l.OrderId == orderId)
        .ExecuteUpdateAsync(s => s.SetProperty(l => l.IsReserved, true), ct);
    await tx.CommitAsync(ct);                              // (3)
});

ماتحطش email أو gateway charge جوه retry delegate؛ استخدم outbox في نفس transaction. SaveChanges جوه transaction قائمة ممكن يستخدم savepoint؛ SQL Server MARS بيمنع savepoints الآلية. cancellation مش إثبات إن commit ماحصلش. ما تعملش retry لكل exception، خصوصاً validation و conflicts.

#Raw SQL و query filters المسماةSafe raw SQL and named query filters

query معقدة ممكن تحتاج SQL مباشر. ده escape hatch، مش سبب نتخلى عن parameterization أو tenant isolation.

var products = await db.Products
    .FromSql($"SELECT * FROM Products WHERE Price > {minimum}") // (1)
    .AsNoTracking().ToListAsync(ct);

var prices = await db.Database
    .SqlQuery<decimal>($"SELECT Price AS Value FROM Products WHERE Id = {id}")
    .ToListAsync(ct);                                     // (2)

// In OnModelCreating; tenantId is current context state.
modelBuilder.Entity<Order>()
    .HasQueryFilter("SoftDelete", o => !o.IsDeleted)
    .HasQueryFilter("Tenant", o => o.TenantId == tenantId);  // (3)
var archived = await db.Orders.IgnoreQueryFilters(["SoftDelete"])
    .ToListAsync(ct);                                     // (4)

#Owned و complex و JSON و اختيار أداة الداتاValue mapping and choosing a data tool

عنوان الشحن value داخل order، مش لازم يبقى entity مستقلة. اختار mapping حسب الهوية وطريقة query، وبعدها اختار أداة مناسبة للـ workload.

// EF Core 10, with a relational provider supporting complex JSON mapping.
modelBuilder.Entity<Order>()
    .ComplexProperty(o => o.ShippingAddress, address => address.ToJson()); // (1)

// Earlier owned-entity approach, as an ALTERNATIVE mapping:
// modelBuilder.Entity<Order>().OwnsOne(o => o.ShippingAddress);

JSON يقلل جداول لبيانات بتتقري مع بعض؛ querying والـ indexing والـ constraints وتحديث أجزاء الوثيقة يعتمدوا على provider و database version. ماتحطش aggregate عملاق بيتعدل كله أو محتاج joins وتقارير كتير في JSON لمجرد المرونة.

مفيش قاعدة إن Dapper أسرع دايماً؛ SQL والـ round trips والـ payload غالباً أهم. خلط الأداتين محتاج shared connection و transaction لو العمليات لازم تبقى atomic.