🔥 مقدمه

در دنیای توسعه نرم‌افزار با Entity Framework Core، دو راه اصلی برای تعریف ساختار دیتابیس و نگاشت آن با کلاس‌های مدل وجود دارد: Data Annotations و Fluent API. در حالی که Data Annotations برای تعریف سریع و ساده استفاده می‌شود، Fluent API قدرتی بسیار بیشتر، دقیق‌تر و انعطاف‌پذیرتر را به توسعه‌دهنده می‌دهد. در این مقاله، به اعماق Fluent API سفر می‌کنیم تا ببینیم چطور می‌توان با آن، کنترل کامل ساختار دیتابیس را به دست گرفت.

 

🧠 Fluent API چیست؟

Fluent API یک رویکرد برنامه‌نویسی در Entity Framework Core است که به ما اجازه می‌دهد تنظیمات و نگاشت‌های مربوط به مدل داده را به صورت برنامه‌نویسی و قابل chain شدن انجام دهیم. این روش در متد OnModelCreating کلاس DbContext استفاده می‌شود و به‌طور معمول برای نگاشت‌های پیچیده‌تر نسبت به Data Annotations به کار می‌رود.

 

✨ چرا Fluent API؟ مزایای آن چیست؟

1. انعطاف‌پذیری بالا
   نگاشت‌های پیچیده بین کلاس‌ها و جداول، مانند روابط چند-به-چند سفارشی، کلیدهای ترکیبی و Indexهای خاص.

2. جداسازی منطق مدل از ساختار پایگاه داده
   بر خلاف Data Annotations که کلاس‌های مدل را مستقیماً تزئین می‌کند، Fluent API منطق نگاشت را جدا نگه می‌دارد.

3. امکان تعریف قراردادهای دقیق‌تر
   مانند تعیین طول رشته، نوع دیتابیس، precision اعشار، و ویژگی‌های خاص هر ستون یا رابطه.

4. سازگاری با Migration و توسعه پایدار
   Fluent API با EF Core Migrations سازگاری کامل دارد و امکان اعمال تغییرات ساختاری به مرور زمان را فراهم می‌کند.

 

🏗 ساختار کلی Fluent API

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Customer>(entity =>
    {
        entity.ToTable("tbl_Customers");

        entity.HasKey(e => e.Id);

        entity.Property(e => e.Name)
              .HasMaxLength(100)
              .IsRequired();

        entity.HasIndex(e => e.Email)
              .IsUnique();

        entity.HasOne(e => e.City)
              .WithMany(c => c.Customers)
              .HasForeignKey(e => e.CityId)
              .OnDelete(DeleteBehavior.Restrict);
    });
}

 

🧱 مقایسه Data Annotations با Fluent API

ویژگی	Data Annotations	Fluent API
سادگی	✅ بله	❌ خیر (نیاز به کدنویسی بیشتر)
نگاشت‌های پیچیده	❌ محدود	✅ کامل و دقیق
انعطاف‌پذیری در تعریف	❌ محدود	✅ بالا
جداسازی ساختار از مدل	❌ خیر	✅ بله

 

🔍 مثال‌های کاربردی Fluent API

1. تعیین نام جدول و ستون

modelBuilder.Entity<User>()
    .ToTable("tbl_Users")
    .Property(u => u.UserName)
    .HasColumnName("username")
    .HasMaxLength(50);

2. تعریف کلید ترکیبی

modelBuilder.Entity<OrderDetail>()
    .HasKey(od => new { od.OrderId, od.ProductId });

3. تعیین رفتار حذف رابطه‌ای

modelBuilder.Entity<Order>()
    .HasOne(o => o.Customer)
    .WithMany(c => c.Orders)
    .OnDelete(DeleteBehavior.Cascade);

4. تعریف مقدار پیش‌فرض

modelBuilder.Entity<Product>()
    .Property(p => p.IsAvailable)
    .HasDefaultValue(true);

 

🧠 پیشرفته‌تر: Fluent API با کلاس‌های جداگانه (Configuration Classes)

برای سازماندهی بهتر، می‌توان نگاشت‌ها را در کلاس‌های جداگانه قرار داد:

public class ProductConfiguration : IEntityTypeConfiguration<Product>
{
    public void Configure(EntityTypeBuilder<Product> builder)
    {
        builder.ToTable("tbl_Products");
        builder.HasKey(p => p.Id);
        builder.Property(p => p.Name).HasMaxLength(100);
    }
}

و در DbContext:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyConfiguration(new ProductConfiguration());
}

 

🧰 ابزارهای مکمل

• EF Core Power Tools برای بررسی و مهندسی معکوس دیتابیس

• EF Core CLI برای مدیریت Migrationها

• EF Core Profiler برای آنالیز کوئری‌های تولیدشده

 

🚧 چالش‌های احتمالی

• نوشتن Fluent API برای پروژه‌های بزرگ ممکن است زمان‌بر باشد.

• نگهداری آن در پروژه‌های پیچیده نیاز به نظم و مستندسازی دارد.

 

🏁 نتیجه‌گیری

Fluent API ابزاری قدرتمند و ضروری برای توسعه‌دهندگان حرفه‌ای .NET است. اگر به دنبال کنترل دقیق، نگاشت‌های پیچیده، و ساختاری منعطف برای پروژه‌های خود هستید، یادگیری و استفاده از Fluent API یک سرمایه‌گذاری بلندمدت است. در حالی که شاید در ابتدا کمی دشوار به‌نظر برسد، اما در پروژه‌های واقعی، مزایای آن به‌وضوح قابل مشاهده است.