Ways For Mapping in EF Core

قولنا قبل كدا اننا ممكن نعمل Mapping من الـ Database للكود والعكس، ودا بيعتمد انت شغال Code-first or Database-First.

هنركز على طريقة الـ Code-First. الطريقة دي معناها إننا بنبدأ بكتابة الـ Classes بتاعتنا بلغة C# الأول، وبعدين بنعتمد على الـ Entity Framework Core إنه هو اللي يبني أو يعدل الـ Database بناءً على الـ Classes دي.

الـ Models (أو الـ Entities)

قبل أي حاجة في الـ Code-First، لازم نجهز الـ Models بتاعتنا. دي هي الـ Classes اللي بتمثل الداتا الأساسية اللي الأبلكيشن بيتعامل معاها.

• تنظيم الشغل: عشان الكود يبقى منظم، بنعمل folder مخصوص في الـ project ونحط جواه الـ Classes دي. ممكن نسمي الـ folder ده Models أو Entities أو Domain.
• الأسماء المختلفة: الـ Classes دي ليها كذا اسم ممكن تسمعهم:
  • الـ Entities: لأنها بتمثل الكيانات أو الأشياء الأساسية في السيستم بتاعك (زي موظف، منتج، قسم، فاتورة).
  • الـ POCO Class: ودي اتكلمنا عنها بالتفصيل، وهي اختصار لـ “Plain Old CLR Object”. الفكرة إنها بتبقى Classes بسيطة جدًا، بتركز على إنها تشيل data في الـ properties بتاعتها، ومفيهاش logic كتير أو اعتمادية على framework معين.
  • الـ Domain Models: لأنها بتمثل المفاهيم الأساسية في مجال الشغل (الـ Domain) بتاع الأبلكيشن.

مثال عملي: الـ Employee Class

تعالى نعمل Class بسيط كمثال، وهنسميه Employee (موظف):

// File: Models/Employee.cs
internal class Employee
{
    // Property for Employee ID
    public int Id { get; set; }
 
    // Property for Employee Name
    public string Name { get; set; }
 
    // Property for Employee Salary
    public double Salary { get; set; }
 
    // Property for Employee Age (Nullable)
    public int? Age { get; set; }
}

• زي ما إنت شايف، الـ Class ده مثال كويس جدًا على الـ POCO Class. مجرد properties بسيطة بتستخدم الـ auto-implemented properties ({get; set;}) عشان تشيل الداتا.

الـ Mapping (التحويل من كود لداتابيز)

دلوقتي إحنا عملنا الـ Employee Class. السؤال المهم: إزاي الـ EF Core هيعرف يحول الـ Class ده لحاجة يفهمها جوه الـ Database؟ (زي إنه يعمل Table بالـ Columns المناسبة). العملية دي بنسميها Mapping.

الـ EF Core بيدينا كذا طريقة نعمل بيها الـ Mapping ده. فيه أربع طرق أساسية، والمهم نعرف إن الطرق دي بتكمل بعضها. يعني إيه؟ يعني الـ EF Core بيبدأ بالطريقة الأسهل والأكثر شيوعًا (رقم 1)، ولو إنت محتاج تتحكم أكتر أو تغير حاجة في السلوك الافتراضي ده، بتبدأ تستخدم الطرق اللي بعدها (2، 3، 4) عشان تعمل تخصيص زيادة.

1. By Convention (Default)

كلمة Convention هنا معناها “العُرف” أو “الاتفاق الضمني” أو “السلوك الافتراضي”.

• الفكرة الأساسية: دي الطريقة اللي الـ EF Core بيشتغل بيها لوحده من غير ما إنت تكتب أي كود مخصوص للـ Mapping. هو عنده مجموعة قواعد (زي اتفاق بينك وبينه) بيمشي عليها عشان يفهم الـ Classes بتاعتك ويحولها لـ Database Schema في الداتابيز.
• مين اللي بيحددها؟ الـ Conventions دي جاية مع الـ EF Core نفسه. إنت كـ developer مجرد بتكتب الكود بتاعك بطريقة قياسية (زي تسمية الـ Primary Key بـ Id)، وهو بيفهم قصدك.
• المجهود المطلوب: تقريبًا مفيش! دي الطريقة الطبيعية والافتراضية، مش محتاج تعمل أي حاجة زيادة في أغلب الحالات البسيطة.

أمثلة على الـ Conventions المشهورة:

• تحديد الـ Primary Key (المفتاح الأساسي):
  • لو عندك property في الـ Class اسمها Id (زي في مثالنا).
  • أو لو اسمها نفس اسم الـ Class + Id (يعني لو الكلاس اسمه Employee، والـ property اسمها EmployeeId).
  • في الحالتين دول، الـ EF Core لوحده (By Convention) هيفترض إن الـ property دي هي الـ Primary Key بتاع الـ Table اللي هيتعمل.
  • وكمان: في أغلب أنواع الداتابيز (زي SQL Server)، هيخلي الـ Primary Key ده من النوع Identity، يعني قيمته هتزيد تلقائيًا مع كل record جديد (Auto-increment).
• تحويل أنواع البيانات (Data Types):
  • الـ string في C# بتتحول لـ nvarchar(max) في SQL Server (يعني string يقدر يشيل عدد حروف كبير جدًا وممكن يخزن حروف Unicode).
  • الـ int بتتحول لـ int.
  • الـ double بتتحول لـ float.
  • الـ decimal بتتحول لـ decimal(18, 2) (دقة قياسية).
  • الـ DateTime بتتحول لـ datetime2.
  • وهكذا… لكل نوع داتا في C# فيه مقابل افتراضي في الداتابيز.
• تحديد الـ Nullability (هل القيمة ممكن تبقى فاضية؟):
  • دي نقطة مهمة وبتعتمد على إذا كنت مستخدم Nullable Reference Types و Nullable Value Types في C# ولا لأ (زي ما اتكلمنا في Nullable Types).
  • القاعدة:
    • لو الـ property في C# مش nullable (زي string Name أو double Salary في مثالنا الأول)، يبقى الـ Column اللي هيتعمل في الداتابيز هيبقى NOT NULL (إجباري لازم تدخله قيمة).
    • لو الـ property معمولة nullable في C# (باستخدام علامة الاستفهام ? للـ value types زي int? Age، أو لو مفعل الـ Nullable Reference Types واستخدمت string? مثلًا)، يبقى الـ Column المقابل في الداتابيز هيسمح بقيم NULL (يعني القيمة اختيارية Optional).

تطبيق الـ Conventions على الـ Employee Class بتاعنا:

لو طبقنا القواعد دي على الـ Employee class الأصلي اللي عملناه:

1. الـ Id (int):
   • عشان اسمها Id، هتبقى هي الـ Primary Key.
   • هتبقى Identity (auto-increment).
   • نوع الـ Column هيبقى int و هيبقى NOT NULL.
2. الـ Name (string):
   • هتبقى Column نوعه nvarchar(max).
   • هتبقى NOT NULL (لو مش مفعل Nullable Reference Types، أو لو مفعلها ومكتبتهاش string?).
3. الـ Salary (double):
   • هتبقى Column نوعه float.
   • هتبقى NOT NULL (لأن double العادية مش nullable).
4. الـ Age (int?):
   • عشان مستخدمين int? (يعني nullable value type)، الـ Column هيبقى نوعه int.
   • وهيسمح بقيم NULL (يعني Optional).

خطوة مهمة: إزاي الـ Class بيتحول لـ Table فعلًا؟ (دور الـ DbContext)

الكلام النظري ده جميل، بس الـ EF Core مش هيروح يدور على كل الـ Classes في الـ project بتاعك ويحولها لـ tables كده وخلاص. لازم تقوله صراحةً إيه هي الـ Classes (الـ Entities) اللي إنت عايزه يتعامل معاها كجزء من الـ Database Model بتاعك.

• الحل: بنعمل ده عن طريق إننا بنضيف property من نوع DbSet<T> جوه الكلاس الأساسي اللي بيمثل الداتابيز بتاعتنا في الكود.
• الـ Understanding DbContext in Entity Framework Core: الكلاس ده اللي بيحتوي على الـ DbSet properties هو اللي بنسميه DbContext. ده يعتبر هو “مدير الداتابيز” بتاعك في الكود، هو الوسيط اللي بين الكود بتاعك وبين الداتابيز الفعلية.

يعني، عشان الـ Employee class يتفهم ويتحول لـ table، لازم نضيف السطر ده جوه الـ DbContext بتاعنا:

// Inside your DbContext class (e.g., CompanyDbContext)
public DbSet<Employee> Employees { get; set; }
 
// Comment: We will talk to the 'Employees' table (or view/function)
//          in the database through this 'Employees' property.
 
// Example usage later in code:
// var firstEmployee = dbContext.Employees.FirstOrDefault(E => E.Id == 1);

• لما بنضيف الـ DbSet<Employee> ده، الـ EF Core وقت ما بيعمل build للـ model بتاعه، بيشوف الـ property دي وبيفهم إنه مطلوب منه يعمل mapping للـ Employee class. وساعتها بيروح يطبق قواعد الـ Convention (أو أي طريقة mapping تانية إنت محددها) عشان يعرف شكل الـ Table ده المفروض يبقى إيه.
• ليه اسمها DbSet؟ الاسم ده مرن شوية، لأن الـ DbSet مش شرط يمثل Table بس، ممكن في سيناريوهات متقدمة نخليه يعمل map لـ View في الداتابيز أو حتى يستخدم Table-Valued Function (TVF) كمصدر للداتا. بس في الأغلب بنستخدمه عشان نمثل Tables.

الخلاصة: طريقة الـ Convention هي الأساس والبداية. بتكتب الـ POCO classes بتاعتك بشكل قياسي، وتضيف لها DbSet في الـ DbContext، والـ EF Core بيقوم بالباقي بشكل افتراضي.

طيب لو الافتراضات دي مش مناسبة؟ لو عايز اسم الـ Table يبقى مختلف؟ لو عايز اسم Column يبقى مختلف؟ لو عايز نوع داتا معين في الداتابيز مش هو الافتراضي؟ لو عايز Primary Key يبقى مش Id؟ هنا بنحتاج ننتقل للطريقة التانية.

2. Data Annotation

دي الطريقة التانية عشان نخصص الـ mapping اللي بيحصل By Convention.

• الفكرة: بنستخدم حاجة اسمها Attributes في C#. الـ Attribute ده بيبقى زي “علامة” أو “تاج” بنحطه فوق الـ Class نفسه أو فوق الـ Properties بتاعته عشان ندي تعليمات زيادة للـ EF Core.

• كنا استخدمنا Attribute لو فاكر في Bit Flags with Enum

• دا بيفتحلنا كلام كتير في الـ Reflection

• الاستخدام الأساسي:

  1. تخصيص الـ Mapping: نقول للـ EF Core يعمل حاجات غير اللي كان هيعملها By Convention (زي تغيير اسم Table أو Column، تحديد نوع داتا معين، تحديد الـ Primary Key صراحةً، إلخ).
  2. عمل Data Validation: كتير من الـ Data Annotations دي ليها دور مزدوج، مش بس بتأثر على الداتابيز، دي كمان بتستخدم عشان نحط قواعد للتحقق من صحة البيانات (Validation Rules) اللي اليوزر بيدخلها.

• زي ما قولنا، الطرق بتكمل بعض: بنبدأ بالـ Convention، ولو فيه حاجة محتاجة تتغير، بنستخدم Data Annotation عشان نغيرها.

مثال: تعديل الـ Employee Class باستخدام Data Annotations

لنفترض إننا عايزين نعمل التعديلات دي على الـ Employee class:

• نغير اسم الـ Primary Key property من Id لـ EmpId.
• نخلي الـ Name مطلوب (Required) وأقصى طول ليه 100 حرف بس (بدل nvarchar(max)).
• نخلي نوع الـ Salary في الداتابيز يبقى decimal(18, 2) عشان الدقة (بدل float).
• نضيف قاعدة validation إن الـ Age لازم يكون بين 18 و 65.
• نضيف property زيادة في الكلاس اسمها FullInfo بتعرض الاسم والعمر مع بعض، بس مش عايزينها تتخزن في الداتابيز.

الكلاس هيبقى شكله كده (هنحتاج نعمل using لـ namespaces معينة):

// Need: using System.ComponentModel.DataAnnotations;
// Need: using System.ComponentModel.DataAnnotations.Schema;
 
// Example: Let's map this class to a table named "EmployeesInfo" in the "hr" schema
[Table("EmployeesInfo", Schema = "hr")]
internal class Employee
{
    // [Key] explicitly defines the Primary Key
    [Key]
    // [DatabaseGenerated(Identity)] specifies auto-increment behavior
    [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public int EmpId { get; set; } // Name changed, convention won't find PK anymore
 
    // [Required] makes the DB column NOT NULL and adds validation
    [Required(ErrorMessage = "Employee name is mandatory.")]
    // [MaxLength] limits DB column size and adds validation
    [MaxLength(100)]
    public string Name { get; set; }
 
    // [Column] allows specifying exact DB TypeName
    [Column(TypeName = "decimal(18, 2)")]
    public double Salary { get; set; } // Still double in C#, but maps to decimal in DB
 
    // [Range] primarily for validation, doesn't usually affect DB schema directly
    [Range(18, 65, ErrorMessage = "Age must be between 18 and 65.")]
    public int? Age { get; set; }
 
    // [NotMapped] tells EF Core to completely ignore this property for DB mapping
    [NotMapped]
    public string FullInfo { get { return $"{Name} ({(Age.HasValue ? Age.Value.ToString() : "N/A")})"; } }
 
    // Example: Using DataType for hints (often for UI/Validation)
    // [DataType(DataType.Currency)] // Hint for UI
    // public decimal Bonus { get; set; } // Let's assume we added a Bonus property
 
    // Example: Using EmailAddress validation shortcut
    // [EmailAddress]
    // public string WorkEmail { get; set; }
}

شرح الـ Attributes (العلامات) اللي استخدمناها:

• الـ [Key]:
  • الوظيفة: بتقول للـ EF Core صراحةً: “الـ property دي هي الـ Primary Key”. استخدمناها هنا لأننا غيرنا الاسم من Id لـ EmpId، فالـ Convention مبقتش عارفة تحدد الـ PK لوحدها.
  • المكان: فوق الـ property اللي عايزها تبقى PK.
  • الـ Namespace: System.ComponentModel.DataAnnotations.
• الـ [DatabaseGenerated(DatabaseGeneratedOption.Identity)]:
  • الوظيفة: بتقول للـ EF Core إزاي قيمة الـ property دي بتتجاب.
  • الـ DatabaseGeneratedOption.Identity: معناها إن الداتابيز هي اللي مسئولة عن توليد القيمة دي، وغالبًا بتكون عن طريق auto-increment (زيادة تلقائية).
  • خيارات تانية:
    • الـ None: معناها إن الداتابيز ملهاش دعوة بتوليد القيمة، وإنت اللي هتدخلها من الكود بتاعك (مثلًا لو الـ PK مش رقم بيزيد لوحده، زي GUID أو رقم قومي). ممكن تستخدم دي لو الـ Convention كانت هتخليها Identity وإنت مش عايز كده.
    • الـ Computed: معناها إن القيمة دي بتتحسب جوه الداتابيز نفسها، بناءً على columns تانية (زي Computed Column في SQL Server). مثال بسيط: لو عندك FirstName و LastName وعايز تعمل column اسمه FullName بيتحسب تلقائي في الداتابيز. (ملحوظة: تحديد الـ formula نفسها غالبًا بيحتاج الطريقة التالتة للـ Mapping اللي هي Fluent API).
• الـ [Required]:
  • الوظيفة: ليها دورين:
    1. الـ Schema: بتخلي الـ Column في الداتابيز يبقى NOT NULL.
    2. الـ Validation: بتستخدم في الـ frameworks زي ASP.NET Core عشان تتأكد إن اليوزر دخل قيمة للـ field ده ومتسابوش فاضي. ممكن تحط ErrorMessage عشان تظهر رسالة معينة لليوزر.
• الـ [MaxLength(100)]:
  • الوظيفة: ليها دورين:
    1. الـ Schema: بتحدد أقصى عدد حروف للـ column في الداتابيز (مثلًا هتعملها nvarchar(100) بدل nvarchar(max) الافتراضي).
    2. الـ Validation: بتستخدم عشان تتأكد إن اليوزر مدخلش حروف أكتر من المسموح.
• الـ [StringLength(max, MinimumLength = min)]:
  • الوظيفة: زي MaxLength بس ممكن تحدد كمان أقل عدد حروف مسموح بيه (MinimumLength). دي بتستخدم أكتر للـ Validation.
• الـ [Column(TypeName = "decimal(18, 2)")]:
  • الوظيفة: بتسمحلك تحدد نوع الداتا بتاع الـ Column في الداتابيز بالظبط زي ما إنت عايزه (مثلًا decimal(18, 2) أو varchar(50) أو date).
• الـ [Range(18, 65)]:
  • الوظيفة: دي أساسًا للـ Validation. بتحدد إن القيمة الرقمية (أو التاريخ) لازم تكون في نطاق معين. مش بتغير الـ Schema بتاع الداتابيز في العادي. ممكن تحط ErrorMessage.
• الـ [DataType(DataType...)]:
  • الوظيفة: بتدي معلومة إضافية عن طبيعة الداتا (زي DataType.Currency, DataType.EmailAddress, DataType.Password, DataType.Date). دي بتستخدم أكتر للـ Validation وعشان الـ UI frameworks تعرف تعرض input field مناسب (مثلًا تعرض رمز العملة، أو تخلي الـ input بتاع الباسورد نجوم). في الغالب مش بتغير نوع الـ column في الداتابيز لوحدها، لو عايز تغير نوع الداتابيز استخدم [Column(TypeName = "...")] معاها.
• الـ [EmailAddress], [Phone], [CreditCard]:
  • الوظيفة: دي اختصارات لـ [DataType] وبتضيف validation جاهزة عشان تتأكد إن الفورمات بتاعت الإيميل أو التليفون أو الكريدت كارد صح.
• الـ [NotMapped]:
  • الوظيفة: مهمة جدًا. بتقول للـ EF Core: “الـ property دي تجاهلها خالص، متعملهاش map لأي column في الداتابيز”. بنستخدمها للـ helper properties اللي بنحسبها في الكود بس ومش عايزين نخزنها.
• الـ [Table("EmployeesInfo", Schema = "hr")]:
  • الوظيفة:
    1. بتخليك تغير اسم الـ Table في الداتابيز (هنا هيبقى EmployeesInfo بدل الاسم الافتراضي اللي ممكن يكون Employee أو Employees).
    2. بتخليك تحدد الـ Schema اللي الـ Table ده هيتحط جواه (هنا hr بدل الـ schema الافتراضي اللي هو غالبًا dbo). دي ميزة مهمة مش بنقدر نعملها بسهولة بالـ Convention.
  • المكان: فوق الـ Class نفسه.

هل [Table] يغني عن DbSet؟

سؤال كويس: لو أنا استخدمت الـ [Table] attribute عشان أحدد اسم الـ Table والـ Schema، هل ده معناه إني مش محتاج أكتب DbSet<Employee> جوه الـ DbContext؟

• الإجابة من ناحية تقنية: لا، مش ممكن. الـ DbSet ضروري عشان الـ EF Core يعرف إن الـ Class ده جزء من الـ Model اللي عايز يديره ويتعامل معاه. الـ [Table] attribute بيستخدم فقط عشان يعمل override للـ convention الخاصة باسم الـ table والـ schema، لكن مش بيغني عن تعريف الـ Entity للـ DbContext عن طريق DbSet. لازم تعمل DbSet دايمًا.

أهمية الـ Data Annotations في الـ Validation

زي ما شوفنا، كتير من الـ Annotations دي ليها دور حيوي في عملية الـ Validation (التحقق من صحة البيانات).

• الـ Validation نوعين أساسيين (Application Validation):
  • الـ Front-end Validation (في المتصفح): بتحصل عند اليوزر قبل ما يبعت الداتا للسيرفر. فايدتها إنها سريعة، بتدي فيدباك فوري لليوزر (زي “مينفعش تسيب الخانة دي فاضية”)، وبتقلل الريكوستات الغلط اللي رايحة للسيرفر.
  • الـ Back-end Validation (على السيرفر): بتحصل لما الداتا توصل للسيرفر بتاعك. ودي الأهم والأساس اللي مينفعش نستغنى عنه. ليه؟ لأن أي حد ممكن بسهولة يتخطى الـ front-end validation (مثلًا يقفل الـ JavaScript أو يستخدم أدوات زي Postman). الـ Back-end validation هي الضمان الأخير إن الداتا اللي هتدخل الداتابيز بتاعتك سليمة ومطابقة للقواعد.
• ليه بنعمل الاتنين؟ بنعمل Front-end عشان نحسن تجربة المستخدم (UX)، وبنعمل Back-end عشان الأمان وتأكيد سلامة البيانات (Data Integrity).
• فين دور الـ Data Annotations هنا؟ في الـ frameworks الحديثة زي ASP.NET Core (MVC, Razor Pages, Blazor, API)، الـ Data Annotations اللي بنحطها على الـ Model classes بتاعتنا (زي Employee) ليها فايدة مزدوجة رائعة:
  • الـ Framework بيقدر يقرأ الـ Annotations دي ويستخدمها عشان يعمل generate لـ validation scripts تشتغل في الـ front-end (غالبًا JavaScript) تلقائيًا.
  • وفي نفس الوقت، الـ Framework بيستخدم نفس الـ Annotations دي عشان يعمل validation للداتا لما توصل للـ back-end (على السيرفر)، وده بيحصل غالبًا كجزء من عملية الـ Model Binding قبل ما الداتا توصل للـ Action method بتاعتك.
  • يعني بتكتب القاعدة مرة واحدة بالـ Annotation، وهي بتستخدم في الناحيتين.
• هل دي validation بتاعة MVC؟ أيوة، الـ Data Annotations هي الطريقة الأساسية والرسمية لتعريف قواعد الـ validation في ASP.NET Core. والـ validation اللي بيحصل على السيرفر باستخدام الـ Annotations دي يعتبر جزء أساسي من الـ back-end validation.
• بس مش صح ان أعمل Validation للفرونت بس في الـ Domain Model اللي بنقول عليه POCO Class لأن دي المفروض كلها حاجات تتحول في الـ Database إنما المفروض يبقا جوا View Model.

ملخص لأشهر الـ Data Annotations (باختصار ومن غير حشو)

Annotation	الغرض الأساسي	التأثير الأساسي
[Key]	تحديد الـ Primary Key	Schema
[Required]	مطلوب (NOT NULL في DB، وإجباري في الإدخال)	Schema & Validation
[MaxLength(n)]	أقصى طول للحروف	Schema & Validation
[StringLength(max, Min=min)]	أقصى وأقل طول للحروف	Validation
[Range(min, max)]	تحديد مدى مقبول للأرقام/التواريخ	Validation
[RegularExpression("...")]	مطابقة نمط معين (regex)	Validation
[EmailAddress], [Phone]	التحقق من فورمات الإيميل/التليفون	Validation
[Compare("OtherProp")]	مقارنة قيمة بـ property تانية (زي تأكيد الباسورد)	Validation
[DataType(DataType...)]	تحديد نوع الداتا (hint للـ UI/Validation)	Validation
[Timestamp]	لعمل Row Versioning (تتبع التعديلات للـ Concurrency)	Schema
[ConcurrencyCheck]	استخدام الـ column ده في الـ Optimistic Concurrency Check	Schema
[Column(TypeName="...", Order=n)]	تحديد نوع/ترتيب الـ column في DB	Schema
[Table("...", Schema="...")]	تحديد اسم الـ Table والـ Schema	Schema
[ForeignKey("NavProp")]	تحديد الـ Foreign Key المرتبط بـ Navigation Property	Schema (Relation)
[InverseProperty("...")]	تحديد الـ Navigation Property المقابل في الطرف التاني من العلاقة (1-*)	Schema (Relation)
[DatabaseGenerated(...)]	تحديد كيف تتولد القيمة (Identity, Computed, None)	Schema
[NotMapped]	تجاهل الـ property دي في الـ Mapping	Schema

إيه اللي هيحصل لو عملنا Add-Migration دلوقتي؟

بعد ما عدلنا الـ Employee class وضفنا الـ Data Annotations دي كلها (غيرنا اسم الـ PK، حددنا الطول والنوع لـ columns تانية، تجاهلنا property، حطينا rules للـ validation، غيرنا اسم الـ Table والـ Schema)، لو رحنا دلوقتي على الـ Package Manager Console (PM) وكتبنا:

Add-Migration ApplyEmployeeDataAnnotations

الـ EF Core هيعمل الخطوات دي:

1. المقارنة: هيقارن الـ Employee class الحالي (بالـ Annotations الجديدة) مع آخر Snapshot موجود عندك في ملف YourDbContextModelSnapshot.cs (اللي كان بيعكس الحالة القديمة قبل التعديلات دي، غالبًا كان بيعتمد على الـ Conventions بس).
2. اكتشاف الفروقات: هيعرف إيه اللي اتغير بالظبط:
   • اسم الـ Table اتغير وبقى في schema مختلف.
   • الـ Primary Key اتغير اسمه.
   • الـ Name بقى Required وطوله اتغير.
   • نوع الـ Salary اتغير.
   • الـ FullInfo المفروض يتجاهلها.
   • (الـ Annotations بتاعة الـ Validation زي [Range] غالبًا مش هتظهر كتغيير في الـ Schema نفسه، لكن الـ EF Core ممكن يسجلها كـ Metadata).
3. إنشاء الـ Migration File: هيعمل ملف migration جديد (..._ApplyEmployeeDataAnnotations.cs).
   • جوه الـ Up() method هتلاقي كود C# بينادي على MigrationBuilder عشان يعمل التعديلات دي في الداتابيز. ممكن تلاقي أوامر زي:
     • الـ migrationBuilder.EnsureSchema(name: "hr"); (لو الـ schema مش موجود)
     • الـ migrationBuilder.RenameTable(...) أو migrationBuilder.DropTable(...) و migrationBuilder.CreateTable(...) (حسب إزاي هينقل الـ table للـ schema الجديد ويغير اسمه).
     • الـ migrationBuilder.RenameColumn(...) أو migrationBuilder.DropPrimaryKey(...) و migrationBuilder.AddPrimaryKey(...) عشان يغير الـ PK.
     • الـ migrationBuilder.AlterColumn(...) كذا مرة عشان يغير نوع Salary ويغير طول ونوع Name ويخليه NOT NULL.
   • الـ Down() method هيبقى فيها الأوامر العكسية عشان لو حبيت تعمل Rollback.
4. تحديث الـ Snapshot: ملف الـ YourDbContextModelSnapshot.cs هيتعدل عشان يعكس الشكل الجديد للـ Employee model بكل تفاصيله الجديدة اللي جاية من الـ Annotations.

وبعد ما الـ Migration دي تتعمل، لو نفذت Update-Database في الـ PM، كل التغييرات دي هتتطبق على الداتابيز بتاعتك.

الخلاصة للطريقة التانية: الـ Data Annotations بتدينا تحكم أكبر بكتير من الـ Conventions، وبتخلينا نقدر نعمل mapping و validation في نفس الوقت بكتابة attributes بسيطة فوق الـ model classes. دي طريقة شائعة جدًا ومفيدة، خصوصًا في ASP.NET Core. بس عيبها إنها ممكن تخلي الـ POCO classes بتاعتنا فيها تفاصيل ليها علاقة بالـ Infrastructure (الداتابيز أو الـ validation)، وده ممكن ناس تعتبره بيخالف مبدأ Separation of Concerns. عشان كده فيه طريقة تالتة (Fluent API) بتفصل الـ configuration ده تمامًا في مكان لوحده.

3. Fluent API (التحكم الكامل)

دي الطريقة الأقوى والأكثر مرونة في الـ Mapping. كلمة Fluent هنا معناها إن الكود اللي بنكتبه بيكون سلس وشبه الجمل الإنجليزية شوية.

• إمتى بنستخدمها؟ بنلجأ للـ Fluent API غالبًا في سيناريوهين أساسيين:

  1. حاجات مينفعش تتعمل غير بيها: لو عايز تعمل configurations معقدة شوية أو حاجات مش مدعومة في الـ Conventions أو الـ Data Annotations. أمثلة:
     • الـ Composite Primary Key: لو الـ Primary Key بتاعك مكون من أكتر من column واحد.
     • تغيير الـ Increment Step: لو عايز الـ Identity column يزيد بمقدار مختلف عن 1 (مثلًا يزيد 5 كل مرة).
     • تحديد Default Value ديناميكي: لو عايز تحط قيمة افتراضية لـ column بس القيمة دي بتتحسب من الداتابيز نفسها (زي تاريخ ووقت الإضافة الفعلي).
     • عمل Indexes معقدة: لو عايز تعمل index على أكتر من column أو index من نوع خاص.
     • تحديد تفاصيل دقيقة في العلاقات (Relationships): زي تحديد أسماء الـ Foreign Keys أو سلوك الحذف (Cascade Delete) بشكل دقيق جدًا.
  2. لو مش معاك الـ Source Code: تخيل إن الـ Entity Class بتاعك (زي Employee أو Department) جايلك من library تانية أو من تيم تاني، وإنت مش معاك الكود المصدري (Source Code) بتاعه، معاك بس الملف الـ compiled (زي الـ .dll اللي فيه الـ IL code). في الحالة دي، إنت مش هتقدر تفتح الكلاس وتضيف عليه Data Annotations. الحل هنا هو إنك تستخدم Fluent API عشان تعمل كل الـ configuration والـ mapping المطلوب للكلاس ده من مكان خارجي (اللي هو الـ DbContext).

• بنكتبها فين؟ الـ Configurations بتاعة الـ Fluent API بتتكتب جوه الـ DbContext بتاعنا. بنعمل override لـ method مهمة جدًا اسمها OnModelCreating. الـ Method دي الـ EF Core بينادي عليها مرة واحدة لما يجي يبني الـ model بتاعه في الذاكرة.

// Inside your DbContext class (e.g., CompanyDbContext)
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    // --- Fluent API Configurations Go Here ---
 
    // Example: Set a default value for an 'Address' property in Employee
    // Assuming Employee class has an Address property now
    modelBuilder.Entity<Employee>() // Start configuring the Employee entity
        .Property(e => e.Address)   // Select the Address property using Lambda (BEST WAY)
        .HasDefaultValue("Cairo");  // Set its default value in the database
 
    // Example using nameof (Second best)
    // modelBuilder.Entity<Employee>()
    //     .Property(nameof(Employee.Address))
    //     .HasDefaultValue("Cairo");
 
    // Example using string (NOT Recommended - no compile-time check)
    // modelBuilder.Entity<Employee>()
    // 	.Property("Address") // Prone to typos if property name changes
    // 	.HasDefaultValue("Cairo");
 
 
    // --- IMPORTANT: Call the base method at the end ---
    base.OnModelCreating(modelBuilder);
}

• شرح Property() Method:
  • الـ Method دي اللي بنستخدمها عشان نختار property معينة جوه الـ Entity ونبدأ نعمل لها configuration. بتاخد اسم الـ property كـ input.
  • الطريقة الأولى (String - مش كويسة): انك تكتب اسم الـ property كـ string ("Address"). مشكلتها إن لو غيرت اسم الـ property في الكلاس الأصلي أو كتبت الاسم غلط هنا، الكود هيعمل compile عادي، ومش هتكتشف المشكلة غير وقت الـ runtime (لما تيجي تشغل البرنامج أو تعمل migration).
  • الطريقة التانية (nameof - أحسن): تستخدم nameof(Employee.Address). دي أحسن من الـ string لأن لو اسم الـ property اتغير، الكود ده مش هيعمل compile وهتعرف الغلط بدري.
  • الطريقة التالتة (Lambda Expression - الأفضل والأضمن): إنك تستخدم Lambda expression زي e => e.Address. دي أحسن وأضمن طريقة لأنها بتستخدم Strongly-typed Access، يعني الـ compiler بيتأكد إن الـ property دي موجودة فعلًا في الـ Employee class وقت الـ compile. وكمان بتدعم الـ Refactoring (لو غيرت اسم الـ property باستخدام أدوات الـ IDE، هتتغير هنا كمان).

إيه الحاجات اللي ممكن أعملها بالـ Fluent API؟ (أمثلة بسيطة)

الـ Fluent API بتغطي تقريبًا كل حاجة ممكن تحتاجها في الـ Mapping:

• تحديد الـ Table والـ Schema:

  modelBuilder.Entity<Employee>().ToTable("EmployeesInfo", schema: "hr");

• تحديد الـ Primary Key:

  modelBuilder.Entity<Employee>().HasKey(e => e.EmpId); // Single PK
  modelBuilder.Entity<OrderLine>().HasKey(ol => new { ol.OrderId, ol.ProductId }); // Composite PK

• تحديد الـ Column:

  modelBuilder.Entity<Employee>()
      .Property(e => e.Name)
      .HasColumnName("EmployeeFullName") // Change column name
      .HasColumnType("varchar(150)")    // Change data type and length
      .IsRequired();                     // Make it NOT NULL

• الـ Default Values:

  modelBuilder.Entity<Employee>()
      .Property(e => e.Status)
      .HasDefaultValue("Active"); // Default string value

• الـ Computed Columns (قيم محسوبة في الداتابيز):

  modelBuilder.Entity<Employee>()
      .Property(e => e.FullName) // Assume FullName is string in C#
      .HasComputedColumnSql("[LastName] + ', ' + [FirstName]"); // SQL expression

  • مهم: زي ما هنشوف، لو عايز قيمة بتتغير مع الوقت زي تاريخ الإنشاء، استخدم HasComputedColumnSql مع دالة الداتابيز (زي GETDATE() في SQL Server) بدل HasDefaultValue(DateTime.Now).
• الـ Identity / Auto-increment:

  modelBuilder.Entity<Employee>()
      .Property(e => e.EmpId)
      .UseIdentityColumn(seed: 100, increment: 5); // Start at 100, increment by 5

• تجاهل Property (زي [NotMapped]):

  modelBuilder.Entity<Employee>().Ignore(e => e.TemporaryNotes);

• عمل Index:

  modelBuilder.Entity<Employee>()
      .HasIndex(e => e.Email) // Index on Email
      .IsUnique();           // Make it a unique index
   
  modelBuilder.Entity<Employee>()
      .HasIndex(e => new { e.LastName, e.FirstName }); // Index on multiple columns

• تحديد العلاقات (Relationships): (ودي ليها تفاصيل كتير بس كمثال بسيط)

  // One-to-Many: Department has many Employees
  modelBuilder.Entity<Employee>()
      .HasOne(e => e.Department) // Navigation property in Employee
      .WithMany(d => d.Employees) // Navigation property in Department
      .HasForeignKey(e => e.DeptId) // Foreign key property in Employee
      .OnDelete(DeleteBehavior.Restrict); // Define delete behavior

مثال تفصيلي: Mapping لكلاس Department (بدون Source Code)

هنرجع لسيناريو إننا عندنا Class اسمه Department جاي من library تانية، وإحنا معندناش الكود بتاعه عشان نحط عليه Annotations. هنفترض إن شكل الكلاس ده كان حاجة زي كده (إحنا مش بنكتب الكلاس ده، هو جاي جاهز):

// Imagine this class comes from a compiled library (DLL)
// We cannot modify it directly
public class Department
{
    public int DeptId { get; set; } // Needs to be PK, needs Identity with custom seed/step
    public string Name { get; set; } // Needs to be required, varchar(50), different column name, default value
    public DateTime DateOfCreation { get; set; } // Needs DB default GETDATE()
}

دلوقتي، في الـ DbContext بتاعنا، هنعمل الآتي:

1. نضيف له DbSet: (حتى لو جاي من library، لازم نعرف الـ DbContext إننا عايزين نتعامل معاه)

   // Inside CompanyDbContext
   public DbSet<Department> Departments { get; set; }

2. نعمل له Configuration في OnModelCreating باستخدام Fluent API:

   protected override void OnModelCreating(ModelBuilder modelBuilder)
   {
       // --- Configure Employee (as before maybe) ---
       // modelBuilder.Entity<Employee>()...
    
       // --- Configure Department using Fluent API ---
       modelBuilder.Entity<Department>(E => // Use lambda for cleaner syntax
       {
           // Map to specific Table name and Schema
           E.ToTable("Departments", "hr"); // Map to hr.Departments table
    
           // Define the Primary Key (since it's not named 'Id' or 'DepartmentId')
           E.HasKey(D => D.DeptId);
    
           // Configure the Primary Key property to be Identity with custom seed and increment
           E.Property(D => D.DeptId)
               .UseIdentityColumn(seed: 10, increment: 10); // Start at 10, increment by 10
    
           // Configure the 'Name' property
           E.Property(D => D.Name)
               .IsRequired(true)                  // Make it NOT NULL
               .HasColumnType("varchar(50)")      // Set DB type and length
               .HasColumnName("DepartmentName")   // Change column name in DB
               .HasMaxLength(50)                  // Also specifies max length (can be redundant with TypeName)
               // .HasAnnotation("SomeMetadata", "Value") // Way to add custom metadata if needed
               .HasDefaultValue("Default Dept");  // Set a static default value
    
           // Configure the 'DateOfCreation' property
           E.Property(D => D.DateOfCreation)
               // WRONG WAY for dynamic default: .HasDefaultValue(DateTime.Now);
               // This captures the time when the MIGRATION is created, not when the row is inserted!
    
               // RIGHT WAY: Use a database function for the default value
               .HasComputedColumnSql("GETDATE()"); // For SQL Server, generates default value on insert
               // Or alternatively for default constraint: .HasDefaultValueSql("GETDATE()");
       });
    
       // --- Call base method ---
       base.OnModelCreating(modelBuilder);
   }
    

• شرح سريع للنقط المهمة في المثال ده:
  • استخدمنا Entity<Department>(E => { ... }) عشان نلم الـ configurations بتاعة Department مع بعض، ودي طريقة أجدد وأنضف (موجودة من EF Core 3.1 تقريبًا).
  • الـ ToTable() حددت اسم الـ Table والـ Schema.
  • الـ HasKey() كانت ضرورية لأن اسم الـ property (DeptId) مش ماشي مع الـ Convention بتاعة الـ PK.
  • الـ UseIdentityColumn(10, 10) دي مقدرناش نعملها بالـ Annotation، هنا بنحدد بداية العد (10) ومقدار الزيادة (10).
  • في Property(D => D.Name) شوفنا إزاي ممكن نعمل كذا configuration ورا بعض لنفس الـ property.
  • في Property(D => D.DateOfCreation)، النقطة بتاعة HasComputedColumnSql("GETDATE()") أو HasDefaultValueSql("GETDATE()") مهمة جدًا. لو كنت استخدمت HasDefaultValue(DateTime.Now)، كانت قيمة DateTime.Now اللي هتتنفذ وقت عمل الـ Migration هي اللي هتتحط كقيمة افتراضية ثابتة في الداتابيز، وده مش صح لو عايز التاريخ الفعلي لإضافة الـ row. استخدام دالة الداتابيز زي GETDATE() بيضمن إن القيمة تتحسب صح وقت الـ INSERT.

4. Configuration Classes (Organize Fluent API)

الـ Fluent API قوية جدًا، بس فيه مشكلة ممكن تظهر: لو الأبلكيشن بتاعك كبير وفيه Entities كتير، الـ OnModelCreating method دي هتبقى طويلة جدًا ومليانة configurations وممكن تبقى صعبة في القراية والصيانة.

هنا تيجي الطريقة الرابعة، وهي في الحقيقة مش طريقة mapping جديدة، قد ما هي طريقة تنظيمية للطريقة التالتة (Fluent API).

• الفكرة: بدل ما تكتب كل الـ Fluent API configurations بتاعة كل الـ Entities جوه OnModelCreating، هتعمل Class منفصل لكل Entity عشان تحط جواه الـ configurations بتاعته.
• الخطوات:
  1. عمل Folder: نعمل folder جديد في الـ Project عشان ننظم الـ configuration classes دي، نسميه مثلًا Configurations أو EntityConfigurations.
  2. عمل Class لكل Entity: لكل Entity عايز تعملها configuration (زي Employee, Department)، هتعمل Class جديد جوه الـ folder ده. اسم الـ Class ده عادة بيكون EntityNameConfiguration (مثلًا EmployeeConfiguration, DepartmentConfiguration).
  3. عمل Implement للـ Interface: كل configuration class من دول لازم يعمل implement لـ interface مهم اسمه IEntityTypeConfiguration<TEntity>. الـ TEntity هنا هو اسم الـ Entity class اللي الـ configuration class ده مسئول عنه.
     • الـ Interface ده فيه method واحدة بس اسمها Configure. جوه الـ Configure دي بقى هتحط كل كود الـ Fluent API اللي كنت هتكتبه في OnModelCreating بس للـ Entity دي بس.

مثال: عمل DepartmentConfiguration

// File: Configurations/DepartmentConfiguration.cs
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;
// Assuming Department class is accessible here
 
internal class DepartmentConfiguration : IEntityTypeConfiguration<Department>
{
    public void Configure(EntityTypeBuilder<Department> builder) // Note: It's EntityTypeBuilder here, not ModelBuilder
    {
        // --- All Fluent API for Department goes here ---
        // Move the code from OnModelCreating here, replacing 'E.' with 'builder.'
 
        builder.ToTable("Departments", "hr");
 
        builder.HasKey(D => D.DeptId);
 
        builder.Property(D => D.DeptId)
            .UseIdentityColumn(seed: 10, increment: 10);
 
        builder.Property(D => D.Name)
            .IsRequired(true)
            .HasColumnType("varchar(50)")
            .HasColumnName("DepartmentName")
            .HasMaxLength(50)
            .HasDefaultValue("Default Dept");
 
        builder.Property(D => D.DateOfCreation)
            .HasComputedColumnSql("GETDATE()");
            // .HasDefaultValueSql("GETDATE()"); // Alternative
    }
}

إزاي الـ DbContext يعرف بالـ Configuration Classes دي؟

بعد ما عملت الـ Configuration Class (زي DepartmentConfiguration)، لازم ترجع للـ DbContext وتقوله يستخدم الـ configuration دي. بنعمل ده جوه OnModelCreating برضه، بس بدل ما نكتب الكود كله، هنادي على الـ configuration class.

• الطريقة المباشرة (لكل كلاس لوحده):

  protected override void OnModelCreating(ModelBuilder modelBuilder)
  {
      // Apply the Department configuration
      modelBuilder.ApplyConfiguration(new DepartmentConfiguration());
   
      // Apply other configurations if you have them
      // modelBuilder.ApplyConfiguration(new EmployeeConfiguration());
      // ... etc ...
   
      // --- IMPORTANT: Call the base method at the end ---
      base.OnModelCreating(modelBuilder);
  }

  • بنستخدم modelBuilder.ApplyConfiguration() ونديها instance جديدة من الـ configuration class بتاعنا.

• فايدة base.OnModelCreating(modelBuilder);:

  • السطر ده مهم جدًا ومفروض نسيبه في الآخر غالبًا. فايدته إنه بيتأكد إن أي configurations تانية الـ EF Core ممكن يكون بيعملها لوحده (كجزء من الـ conventions بتاعته أو لو الـ DbContext بتاعك وارث من DbContext تاني فيه OnModelCreating) تتنفذ هي كمان. لو شيلته، ممكن بعض السلوكيات الافتراضية أو الوراثية متشتغلش.

• الطريقة الأوتوماتيكية (باستخدام Reflection):

  • لو عندك configuration classes كتير، بدل ما تقعد تضيف سطر ApplyConfiguration لكل واحد فيهم، فيه طريقة أشيك وأوتوماتيك أكتر بتستخدم Reflection. الطريقة دي بتخلي الـ EF Core يدور بنفسه على كل الـ Classes في الـ Assembly (الـ project) بتاعك اللي بتعمل implement للـ IEntityTypeConfiguration<T> ويروح عاملها apply لوحده.
  • الكود بتاعها بيبقى حاجة زي كده:

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Automatically apply all configurations from the current assembly
        modelBuilder.ApplyConfigurationsFromAssembly(System.Reflection.Assembly.GetExecutingAssembly());
     
        // No need to call ApplyConfiguration for each class manually anymore
     
        // --- IMPORTANT: Call the base method at the end ---
        base.OnModelCreating(modelBuilder);
    }

  • السطر ده كافي إنه يلاقي وينفذ كل الـ configuration classes اللي في الـ project بتاعك. دي الطريقة المفضلة في المشاريع الكبيرة.

الخطوة الأخيرة: عمل الـ Migration

بعد ما خلصت كل الـ configurations بتاعتك باستخدام Fluent API (سواء كتبتها مباشرة في OnModelCreating أو نظمتها في Configuration Classes)، الخطوة الجاية هي إنك تعمل Managing Database Schema with EF Core Migrations عشان تشوف التغييرات دي وتطبقها على الداتابيز.

1. افتح الـ Package Manager Console (PM).
2. اكتب أمر الـ Add-Migration:

   Add-Migration ConfigureDepartmentUsingFluentApi

   (أو أي اسم مناسب يوصف التغييرات اللي عملتها).
   • هنا الـ EF Core هيقرأ الـ configurations بتاعتك (بما فيها اللي جاية من الـ Fluent API) ويقارنها بالـ Snapshot القديم، ويعمل migration file جديد بالفرق. المفروض تفتح الفايل ده وتتأكد إن الـ Up() method فيها الأوامر اللي إنت متوقعها (زي CreateTable أو AlterColumn بالتفاصيل الجديدة).
3. اكتب أمر الـ Update-Database:

   Update-Database

   • ده هينفذ الـ Migration الجديدة دي على الداتابيز بتاعتك.

وبكده تكون قدرت تعمل mapping و configuration بشكل دقيق ومفصل باستخدام Fluent API ونظمت الكود بتاعك باستخدام Configuration Classes. دي تعتبر الطريقة الأكثر احترافية للتعامل مع الـ Mapping في الـ EF Core Code-First في المشاريع الكبيرة والمعقدة.