هنطلع من الدرس بإيه؟
هتقدر تضيف SQLite لمشروع .NET بـ EF Core، تفهم إيه اللي بيختلف عن SQL Server، تكتب اختبارات على database حقيقية في الذاكرة، وتصمم تطبيق بيشتغل offline ويزامن لما النت يرجع.
- تكوّن
DbContextبـ SQLite وتعمل entity configuration و constraints. - تشرح ليه
UseInMemoryDatabaseمش بديل صحيح لاختبار SQLite. - تطبق optimistic concurrency يدويًا (مفيش rowversion في SQLite).
- تصمم outbox للـ sync وتشرح مسألة الـ conflicts.
المتطلبات: SQLite الأساسي وSQLite المتقدم وEF Core.
ابدأ بمثال صغير
using Microsoft.EntityFrameworkCore;
using var db = new ShopContext();
db.Database.EnsureCreated(); // للتجارب فقط؛ في المشاريع الحقيقية استخدم Migrations
db.Items.Add(new Item { Name = "Keyboard" });
db.SaveChanges();
foreach (var i in db.Items.AsNoTracking().OrderBy(i => i.Id)) Console.WriteLine($"{i.Id}: {i.Name}");
public class Item { public int Id { get; set; } public string Name { get; set; } = ""; }
public class ShopContext : DbContext
{
public DbSet<Item> Items => Set<Item>();
protected override void OnConfiguring(DbContextOptionsBuilder o) => o.UseSqlite("Data Source=shop.db");
}الإعداد: dotnet new console ثم dotnet add package Microsoft.EntityFrameworkCore.Sqlite. حالة التحقق: Not Executed (مفيش .NET SDK في بيئة بناء الموسوعة). المتوقع: ملف shop.db ويظهر 1: Keyboard.
الفروق اللي لازم تعرفها عن SQL Server
EF Core بيخبّي معظم الفروق، لكن SQLite محرك مختلف، وموثّق إن فيه limitations في الـ provider. أهم نقط للمطور (راجع صفحة limitations الرسمية لإصدارك، لأنها بتتغير):
- Migrations: SQLite مش بتدعم كل أوامر
ALTER TABLE؛ EF بيعوض ببناء الجدول من جديد (rebuild) في بعض العمليات، وبعض التغييرات (زي تعديل constraint) محتاجة انتباه وتجربة على نسخة من البيانات. - الأنواع: مفيش decimal أصلي ولا DateTimeOffset: EF بيخزنهم كـ TEXT/INTEGER، وفيه قيود على الترتيب والعمليات الحسابية في SQL. للأموال خزّن
longcents (زي مشروعنا). - Concurrency: مفيش
rowversion؛ استخدم عمود counter بتزوّده بنفسك واجعلهIsConcurrencyToken(). - Foreign keys: Microsoft.Data.Sqlite بتفعلها افتراضيًا على الـ connection حسب توثيقها (Version Verification Required لإصدارك)، بعكس الأدوات الخام.
- Concurrency الكتابة: كاتب واحد؛ اضبط WAL و busy timeout زي الدرس السابق.
الاختبار: SQLite in-memory الحقيقية مش EF InMemory
مزود UseInMemoryDatabase مش قاعدة بيانات علائقية: مش بيفرض foreign keys ولا CHECK ولا unique indexes بنفس سلوك محرك حقيقي، فاختبارات بتعدي عليه ممكن تفشل في الإنتاج. الأفضل SQLite in-memory حقيقية، بشرط تفضل الـ connection مفتوحة (لأن الـ database بتعيش بعمر الـ connection).
using Microsoft.Data.Sqlite;
using Microsoft.EntityFrameworkCore;
public sealed class TestDb : IAsyncDisposable
{
private readonly SqliteConnection _conn = new("Data Source=:memory:");
public InventoryDbContext Db { get; private set; } = null!;
public static async Task<TestDb> CreateAsync()
{
var t = new TestDb();
await t._conn.OpenAsync(); // لو اتقفلت الـ connection الـ database بتختفي
t.Db = new InventoryDbContext(new DbContextOptionsBuilder<InventoryDbContext>().UseSqlite(t._conn).Options);
await t.Db.Database.EnsureCreatedAsync();
return t;
}
public async ValueTask DisposeAsync() { await Db.DisposeAsync(); await _conn.DisposeAsync(); }
}ده اللي بيستخدمه مشروعنا في dotnet/tests/Inventory.Tests. نفس القواعد (duplicate SKU، stock سالب، LIKE escaping) اتختبرت فعلاً في النسخة المرجعية Python (Tested: 11/11 passed)، أما نسخة C# فـ Not Executed.
Offline-first: الـ outbox وحل الـ conflicts
الفكرة: التطبيق بيكتب دايمًا على database محلية (فالواجهة سريعة وتشتغل من غير نت)، وبعدين بيزامن في الخلفية. Outbox هو جدول بيسجل كل تغيير محلي برقم فريد (change_id) مولّد من العميل. الـ sync بيبعت التغييرات بالترتيب ويعلّم اللي اتأكد استلامه. لو الشبكة وقعت في النص، نوقف ونكمل بعدين؛ ولو اتبعت تغيير مرتين السيرفر يتجاهل التكرار بفضل الـ change_id (idempotency).
النقطة المحورية: تعديل البيانات وإضافة الـ outbox يحصلوا في نفس الـ transaction (زي AdjustStockAsync في المشروع)، فمستحيل يتسجل تغيير من غير ما يتبعت، أو يتبعت تغيير ما حصلش. أما الـ conflicts (جهازين عدّلوا نفس الصف offline) فمفيش حل عام: last-writer-wins بسيط لكن بيضيّع بيانات، الـ merge على مستوى الحقول أدق، والـ manual resolution بتحتاج واجهة. القرار منتج مش تقني بحت. المشروع بيوضح الجزء المحلي (optimistic concurrency) والتسليم الآمن، وبيعتبر الـ server خارج النطاق.
.db في مجلد sync (OneDrive/Dropbox) وتفتحه من جهازين: التصادم هيفسد الملف. التزامن بيتم على مستوى التغييرات (outbox) مش الملف.المشروع: Offline-first Inventory
المشروع موجود في EXAMPLES/InventoryOffline (راجع README.md جواه). الهيكل:
InventoryOffline/
├─ sql/schema.sql # STRICT tables, CHECKs, FKs, outbox
├─ python-reference/ # تنفيذ مرجعي + 11 اختبار (Tested)
│ ├─ inventory.py
│ └─ test_inventory.py
├─ dotnet/ # نسخة EF Core + xUnit (Not Executed)
│ ├─ src/Inventory.Core/{Models,InventoryDbContext,InventoryService}.cs
│ └─ tests/Inventory.Tests/InventoryServiceTests.cs
├─ Dockerfile · docker-compose.yml · .github/workflows/ci.yml
└─ README.mdخد الـ InventoryService.AdjustStockAsync كمثال لـ execution trace: (1) تبدأ transaction. (2) تجيب الـ product (tracking). (3) تعدّل Qty وتزوّد RowVersion. (4) تضيف movement و outbox. (5) SaveChanges بيطلّع UPDATE بشرط RowVersion القديم، فلو حد غيّر الصف في النص EF هيرمي DbUpdateConcurrencyException. (6) لو الـ stock هيبقى سالب، الـ CHECK بيرفض والـ transaction بتتراجع، فلا movement ولا outbox. الاختبار test_stock_cannot_go_negative_and_is_atomic في النسخة المرجعية بيثبت السلوك ده بالفعل.
الإعداد الصح لـ SQLite مع EF Core
SQLite مش «قاعدة بيانات لعبة». هي أكتر database مستخدمة في العالم (كل موبايل وكل browser). لكن ليها شخصية مختلفة: ملف واحد، writer واحد في نفس اللحظة، و types مرنة. الإعداد الافتراضي مش مناسب لتطبيق فيه concurrency.
var dbPath = Path.Combine(FileSystem.AppDataDirectory, "inventory.db"); // MAUI; use a writable app-data path elsewhere
builder.Services.AddDbContextFactory<AppDb>(o =>
o.UseSqlite($"Data Source={dbPath};Cache=Shared;Foreign Keys=True",
s => s.CommandTimeout(30)));
// once at startup: WAL lets readers run while one writer writes; NORMAL sync is safe with WAL
await using (var db = await factory.CreateDbContextAsync())
{
await db.Database.MigrateAsync();
await db.Database.ExecuteSqlRawAsync("PRAGMA journal_mode=WAL;");
await db.Database.ExecuteSqlRawAsync("PRAGMA synchronous=NORMAL;");
await db.Database.ExecuteSqlRawAsync("PRAGMA busy_timeout=5000;"); // wait for the writer instead of failing at once
}| الإعداد | ليه | الـ trade-off |
|---|---|---|
journal_mode=WAL | القرّاء ما بيستنوش الكاتب | ملفات -wal و-shm جنب الـ db؛ لازم تتنقل مع الـ backup (أو اعمل checkpoint) |
busy_timeout | بدل SQLITE_BUSY فورًا | الكتابة الطويلة بتبطّأ الباقي — خلّي transactions الكتابة قصيرة |
Foreign Keys=True | SQLite بتقفلها افتراضيًا تاريخيًا | لازم تتفعل لكل connection (الـ connection string بيعمل ده) |
DbContextFactory | تطبيقات desktop/MAUI ما فيهاش request scope | context قصير العمر لكل عملية |
Migrations على SQLite: حدود ALTER TABLE
SQLite بتدعم ALTER TABLE بشكل محدود (add column، rename column/table، drop column في النسخ الحديثة)، لكن تغييرات زي تعديل type أو إضافة constraint على عمود موجود مش مدعومة مباشرة. EF Core بيحل ده بـ table rebuild: ينشئ جدول جديد بالشكل الجديد، ينسخ البيانات، يمسح القديم، ويعيد التسمية — جوه transaction. ده آمن على جدول صغير، لكن على جدول فيه ملايين صفوف على موبايل ممكن ياخد وقت ملحوظ عند أول تشغيل بعد التحديث.
- اختبر الـ migration على نسخة من DB حقيقية بحجم واقعي قبل الـ release.
- اعرض progress أو شاشة «جاري التحديث» بدل ما التطبيق يبان معلّق.
- خد backup للملف قبل
MigrateAsyncعلى أجهزة المستخدمين — لو فشل، ترجع. - ما تعتمدش على
EnsureCreatedفي تطبيق هيتطور: ما بيعملش migrations خالص.
بروتوكول الـ sync بالتفصيل: change tracking و version vectors بسيطة
التصميم: كل عملية محلية بتتسجل في outbox فيها OpId (Guid للـ idempotency)، نوعها، الـ payload، و BaseVersion (نسخة السجل اللي العميل عدّل عليها). السيرفر بيطبّق العملية لو BaseVersion = النسخة الحالية، وإلا بيرجع conflict. بعد الـ push، العميل بيعمل pull لكل التغييرات بعد آخر cursor (رقم sequence متزايد في ChangeLog عند السيرفر) — ده أبسط وأوثق من الاعتماد على ساعة الجهاز.
app.MapPost("/sync/push", async (PushRequest req, AppDb db, CancellationToken ct) =>
{
var results = new List<OpResult>();
foreach (var op in req.Ops)
{
if (await db.AppliedOps.AnyAsync(a => a.OpId == op.OpId, ct)) { results.Add(new(op.OpId, "duplicate")); continue; }
var item = await db.Items.FindAsync([op.ItemId], ct);
if (item is not null && item.Version != op.BaseVersion)
{ results.Add(new(op.OpId, "conflict", item)); continue; } // client decides: merge, keep mine, keep theirs
item = Apply(item, op); // create/update/soft-delete
item.Version++;
db.ChangeLog.Add(new Change { ItemId = item.Id, Version = item.Version }); // Seq is an identity column
db.AppliedOps.Add(new AppliedOp { OpId = op.OpId });
results.Add(new(op.OpId, "applied"));
}
await db.SaveChangesAsync(ct);
return Results.Ok(results);
});| استراتيجية الـ conflict | مناسبة لـ | عيبها |
|---|---|---|
| Last-write-wins | إعدادات شخصية، بيانات قليلة الأهمية | بيضيّع تعديل بصمت |
| Server wins + إشعار | أسعار، صلاحيات | المستخدم يعيد شغله |
| Field-level merge | سجلات بحقول مستقلة (اسم/عنوان) | تعقيد، ومحتاج تخزين القيمة الأساسية |
| Operations (inc/dec) بدل القيم | المخزون: «−3» بدل «الكمية = 7» | مش كل العمليات commutative؛ لازم تحقق الحدود عند السيرفر |
الحذف: soft delete (tombstone) إجباري، وإلا الجهاز اللي offline هيرجّع السجل المحذوف عند الـ sync الجاي. CRDTs حل أكاديمي وعملي للدمج التلقائي (Automerge، Yjs) — مفيدة للـ collaborative editing، لكن أغلب تطبيقات البيزنس بتكفيها الاستراتيجيات فوق.
أمان الملف المحلي
ملف SQLite على جهاز = بيانات ممكن تتنسخ لو الجهاز اتسرق أو اتعمله backup غير مشفر. الخيارات: تشفير الملف كله (SQLCipher عبر bundle مناسب من SQLitePCLRaw)، أو تشفير الحقول الحساسة بس، مع حفظ المفتاح في secure storage الخاص بالنظام (Keychain/Keystore عبر SecureStorage في MAUI) — مش في الكود ولا في config. وقلل البيانات المخزنة أصلًا: الجهاز يحتاج بيانات الشغل بتاعه بس، مش نسخة من الـ DB كلها. ده نفس مبدأ data minimization في Governance.
Knowledge check
جهاز عمل offline حذف منتج، وجهاز تاني عدّل نفس المنتج. السيرفر بيستخدم hard delete. إيه اللي هيحصل؟
ليه الـ pull بيعتمد على sequence من السيرفر مش على UpdatedAt من الجهاز؟
الـ client side: background sync و retries و connectivity
الـ sync مش زرار. هو background process لازم يتحمل: النت بيقطع في نص الـ request، التطبيق بيتقفل، والمستخدم بيعدل أثناء الـ sync.
public sealed class SyncService(IDbContextFactory<AppDb> dbf, ISyncApi api, IConnectivity net, ILogger<SyncService> log)
{
private readonly SemaphoreSlim _gate = new(1, 1); // one sync at a time per device
public async Task SyncAsync(CancellationToken ct)
{
if (net.NetworkAccess != NetworkAccess.Internet) return;
if (!await _gate.WaitAsync(0, ct)) return; // already running: skip, don't queue
try
{
await using var db = await dbf.CreateDbContextAsync(ct);
var pending = await db.Outbox.OrderBy(o => o.CreatedAt).Take(100).ToListAsync(ct);
if (pending.Count > 0)
{
var results = await api.PushAsync(pending.Select(o => o.ToOp()), ct); // idempotent by OpId
foreach (var r in results)
{
var op = pending.Single(p => p.OpId == r.OpId);
switch (r.Status)
{
case "applied" or "duplicate": db.Outbox.Remove(op); break;
case "conflict": op.State = OutboxState.Conflict; op.ServerCopy = r.ServerJson; break; // surface to the user
}
}
await db.SaveChangesAsync(ct);
}
var cursor = await db.SyncState.Select(s => s.Cursor).SingleAsync(ct);
var changes = await api.PullAsync(cursor, ct);
await ApplyServerChangesAsync(db, changes, ct); // skip items that have a local pending op
await db.SaveChangesAsync(ct); // cursor saved in the SAME transaction as the data
}
catch (HttpRequestException ex) { log.LogInformation(ex, "Sync deferred: network"); } // retry later with backoff
finally { _gate.Release(); }
}
}- الـ cursor والبيانات في نفس الـ transaction: لو حفظت الـ cursor وبعدين التطبيق وقع قبل البيانات، هتفوّت تغييرات للأبد.
- ما تكتبش فوق تعديل محلي pending: لو السجل عليه op في الـ outbox، التغيير الجاي من السيرفر ده conflict مش overwrite.
- Backoff: 5s ← 30s ← 2m ← 10m مع jitter، ومش كل دقيقة على بطارية فاضية.
- UX: اعرض حالة واضحة: «محفوظ على الجهاز» / «جارٍ المزامنة» / «تعارض يحتاج قرارك».
اختبار الـ sync: السيناريوهات اللي بتكسر
| السيناريو | المتوقع | إزاي تختبره |
|---|---|---|
| نفس الـ push اتبعت مرتين (timeout بعد ما السيرفر طبّق) | «duplicate»، مفيش تطبيق مزدوج | Integration test يبعت نفس OpIds مرتين |
| جهازين عدّلوا نفس السجل | الأول applied، التاني conflict | two clients على نفس SQLite server test DB |
| حذف offline + تعديل على جهاز تاني | حسب السياسة (tombstone يكسب أو conflict) | test صريح للسياسة |
| التطبيق وقع بين pull و save | إعادة الـ pull من نفس الـ cursor بأمان | throw بعد pull في fake |
| migration جديدة والـ outbox فيه ops بالـ schema القديم | الـ ops لسه بتتطبق | versioned op payloads + test |
استخدم SQLite in-memory الحقيقية (مش EF InMemory provider) زي ما شرحنا فوق، و fake للـ API عشان تتحكم في الأعطال. ده نفس فكر الـ Distributed Systems: الشبكة بتفشل في أسوأ لحظة.
إمتى offline-first مش القرار الصح؟
Offline-first بيضاعف التعقيد: conflicts، migrations على أجهزة مش متحكم فيها، أمان بيانات محلية، ودعم نسخ تطبيق قديمة. يستاهل لما: الشغل الأساسي بيحصل في أماكن من غير نت مستقر (مخازن، مواقع عمل، مندوبين)، أو الـ latency لازم تكون صفر. ما يستاهلش لما: البيانات لازم تكون لحظية ومشتركة (حجز مقاعد، رصيد بنكي)، أو المستخدم دايمًا online — هنا cache بسيط + retry كفاية. الحل الوسط الشائع: read-only offline (كتالوج، مستندات) مع كتابة online فقط.
(Senior) صمّم sync لتطبيق مندوبين مبيعات، 2,000 جهاز، كل جهاز بياخد عملاء منطقته بس.
أخطاء شائعة
- اختبار بـ
UseInMemoryDatabaseوافتراض إن الـ constraints شغالة. - غلق الـ connection في اختبار in-memory فتختفي الـ database.
- استخدام
decimalللأموال والاعتماد على ترتيب/جمع SQL عليها. - الكتابة من أكتر من thread/connection بدون WAL و busy timeout.
- تشغيل
EnsureCreatedفي الإنتاج بدل Migrations. - افتراض إن الـ sync = نسخ الملف.
خمس تمارين محلولة
1 (Easy): ليه الـ test بيفشل بـ no such table بعد ما الـ connection اتقفلت؟
الحل: الـ in-memory database بتعيش بعمر الـ connection اللي فتحتها. لازم تفتح SqliteConnection وتسيبها مفتوحة طول الاختبار وتمررها لـ UseSqlite(connection).
2 (Easy): إزاي تخزن سعر بدقة في SQLite من EF؟
الحل: long PriceCents (integer). لو لازم decimal للعرض، حوّل في طبقة الـ view model. ده بيتجنب قيود EF على decimal في SQLite وأخطاء الـ floating point.
3 (Intermediate): اكتب entity configuration لعمود Version كـ concurrency token وشرح ازاي هتزوده
الحل: e.Property(p => p.RowVersion).IsConcurrencyToken(); وفي الكود p.RowVersion++ قبل SaveChanges. EF بيضيف WHERE row_version = @old للـ UPDATE، ولو صفر صفوف اتأثرت بيرمي DbUpdateConcurrencyException فتعمل retry أو تعرض للمستخدم.
4 (Intermediate): ليه لازم الـ outbox يتكتب في نفس transaction بتاعة التعديل؟
الحل: لو اتكتبوا منفصلين ممكن التطبيق يقع بينهم: تعديل من غير outbox (بيانات ما اتزامنتش أبدًا) أو outbox من غير تعديل (بنزامن حاجة ما حصلتش). الـ transaction الواحدة بتضمن الاتنين مع بعض أو ولا واحد (atomicity).
5 (Challenging): جهازين عدلوا نفس المنتج offline. قارن 3 سياسات حل وحدد إمتى كل واحدة
الحل: (1) Last-writer-wins: بسيطة، تصلح لبيانات قليلة الأهمية (تفضيلات)، لكن بتفقد تعديلات. (2) Field-level merge: لو الجهازين غيّروا حقول مختلفة ندمجهم؛ ممتازة للـ inventory لو التغيير على delta للكمية (نجمع +3 و−2) بدل القيمة المطلقة. (3) Manual: للبيانات الحساسة (سعر/عقد) نعرض التعارض للمستخدم. اختيارك بيعتمد على تكلفة فقد البيانات مقابل تعقيد الواجهة. لاحظ إن مشروعنا بيخزن stock كـ movements (delta) وده بيسهّل الـ merge.
Mini Project: Sync server بسيط
أضف لمشروع Inventory خدمة HTTP صغيرة (ASP.NET Core Minimal API أو Flask) بـ endpoint POST /changes بيستقبل change_id ويخزنه في جدول processed_changes بـ PRIMARY KEY، ويرجّع 200 للتكرار من غير ما يطبق التغيير مرتين. معيار النجاح: (1) إرسال نفس التغيير مرتين = أثر واحد، (2) قطع الشبكة في النص ثم إعادة المحاولة بيكمل من حيث وقف، (3) اختبار يغطي الحالتين، (4) توثيق سياسة الـ conflict المختارة وسببها.
أسئلة إنترفيو إضافية
(Mid) ليه busy_timeout مهم في SQLite مع WAL؟
(Senior) إزاي تتعامل مع migration لـ outbox فيه ops بالـ schema القديم على أجهزة ما اتحدّثتش؟
أسئلة إنترفيو
ليه مش أستخدم UseInMemoryDatabase لاختبار الـ repositories؟
إزاي تطبق optimistic concurrency في SQLite؟
IsConcurrencyToken، فـ EF يضيفه لشرط الـ UPDATE ويرمي DbUpdateConcurrencyException عند التعارض.يعني إيه offline-first؟
إيه فايدة الـ outbox pattern؟
إمتى تنتقل من SQLite لـ PostgreSQL/SQL Server؟
(أصعب) إيه المشكلة لو الـ sync worker بعت التغيير ثم وقع قبل ما يعلّمه synced؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.