آموزش پیشرفته Data Annotations در EF Core

در آموزش پیشرفته Data Annotations در Entity Framework Core، با یکی از راه‌های تعریف ویژگی‌ها و تنظیمات مربوط به مدل‌ها آشنا می‌شوید. ابتدا باید بدانید که مدل‌ها همان کلاس‌هایی هستند که نماینده جدول‌ها در دیتابیس هستند. در واقع، Data Annotationها یا همان حاشیه‌نویسی‌های داده‌ای، Attributeهایی هستند که مستقیماً بالای کلاس‌ها یا پراپرتی‌ها نوشته می‌شوند. به این ترتیب، EF Core می‌تواند موارد زیر را تشخیص دهد:

• کدام پراپرتی کلید اصلی است.
• کدام فیلدها اجباری (Required) هستند و نمی‌توانند خالی بمانند.
• طول مجاز فیلدهای متنی چقدر است.
• نام ستون یا جدول در دیتابیس چه باشد.
• ارتباط بین جداول (مانند رابطه‌ی کلید خارجی) چگونه برقرار شود.
• و حتی کدام پراپرتی اصلاً نباید به دیتابیس تبدیل شود.

در نتیجه، این روش یک راه ساده، سریع و مستقیم برای تنظیم رفتار مدل‌هاست، بدون این‌که نیازی به استفاده از روش پیچیده‌تر Fluent API داشته باشیم.

پرکاربردترین Data Annotation ها

برای شروع، بهتر است با پرکاربردترین Data Annotationها آشنا شوید. برای مثال، Attributeهایی مانند [Key] و [Required] ساختار اصلی مدل را مشخص می‌کنند. Attributeهایی مانند [StringLength] و [Range] برای تعیین محدودیت‌های داده به کار می‌روند.

به‌طور کلی، انتخاب هر Attribute به نوع پراپرتی و نیاز پروژه بستگی دارد. به‌عنوان مثال، [EmailAddress] برای بررسی ساختار ایمیل مناسب است؛ در حالی که [ForeignKey] رابطه میان موجودیت‌ها را مشخص می‌کند. علاوه بر این، می‌توان چند Data Annotation را به‌صورت هم‌زمان روی یک پراپرتی قرار داد.

Data Annotation های پیشرفته

در پروژه‌های بزرگ‌تر، گاهی تنظیمات ساده کافی نیستند. در این شرایط، Data Annotationهای پیشرفته کنترل بیشتری روی فرم‌ها و نحوه نمایش داده‌ها فراهم می‌کنند. از سوی دیگر، برخی از این Attributeها فقط به ASP.NET Core MVC مربوط هستند و ساختار دیتابیس را تغییر نمی‌دهند.

مزایای استفاده از Data Annotation

Data Annotation به توسعه‌دهنده اجازه می‌دهد تنظیمات مدل را مستقیماً در کلاس‌ها و روی ویژگی‌ها تعریف کند. بنابراین، کدنویسی ساده‌تر و سریع‌تر می‌شود و برای پروژه‌های سبک یا متوسط گزینه مناسبی است. همچنین، این روش ساختار واضحی دارد و برای افراد تازه‌کار به‌راحتی قابل درک است. علاوه بر این، می‌توان Data Annotation را در کنار Fluent API به کار برد تا تنظیمات جزئی‌تر و پیچیده‌تر نیز انجام شوند. در نتیجه، توسعه‌دهنده می‌تواند از سادگی Data Annotation و امکانات کامل Fluent API به‌صورت هم‌زمان استفاده کند. برای مثال، Data Annotation مانند برچسب‌هایی است که مستقیماً روی دیوار می‌چسبانید تا به دیگران نشان دهید هر چیزی باید کجا قرار بگیرد. بنابراین، استفاده از آن سریع، ساده و واضح است.

• در نتیجه، کدنویسی ساده و سریع می‌شود و برای پروژه‌های سبک یا متوسط مناسب است.
• همچنین، این روش برای افراد تازه‌کار قابل درک است.
• علاوه بر این، می‌توان از آن در کنار Fluent API برای تنظیمات جزئی‌تر استفاده کرد.

RegularExpression های پرکاربرد ایرانی

در ادامه، چند Regular Expression پرکاربرد برای بررسی اطلاعات ایرانی معرفی می‌کنیم. با استفاده از این الگوها می‌توان ساختار شماره موبایل، کد ملی، کد پستی، شماره تلفن ثابت، شماره کارت بانکی و شماره شبا را بررسی کرد. همچنین، برای هر مورد یک مثال عملی ارائه می‌شود تا نحوه استفاده از آن در برنامه‌نویسی روشن‌تر باشد. البته Regular Expression فقط صحیح بودن ساختار ورودی را بررسی می‌کند؛ بنابراین، معتبر یا متعلق بودن اطلاعات به یک شخص واقعی را تأیید نمی‌کند.

مثال عملی Data Annotations

اکنون می‌توان Data Annotationهای معرفی‌شده را در یک مثال کامل مشاهده کرد. ابتدا Attributeهای مربوط به دیتابیس روی مدل قرار می‌گیرند. سپس، Attributeهای اعتبارسنجی و نمایش به پراپرتی‌های مربوط اضافه می‌شوند.

```csharp
[Table("tbl_user_profiles")] // تغییر نام جدول در دیتابیس
public class UserProfile
{
    // کلید اصلی که توسط دیتابیس به‌صورت افزایشی تولید می‌شود
    [Key]
    [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    [HiddenInput(DisplayValue = false)] // در فرم HTML به صورت hidden
    public int Id { get; set; }

    // فیلد ضروری با حداقل و حداکثر طول مشخص
    [Required]
    [StringLength(100, MinimumLength = 3)]
    [Display(Name = "Full Name")]
    public string FullName { get; set; }

    // اعتبارسنجی ایمیل
    [Required]
    [EmailAddress]
    [Column(TypeName = "varchar(100)")]
    public string Email { get; set; }

    // اعتبارسنجی شماره تلفن با regex مخصوص شماره‌های ایرانی
    [Required]
    [RegularExpression(@"^09\d{9}$", ErrorMessage = "شماره موبایل باید با ۰۹ شروع شود و ۱۱ رقم باشد")]
    [StringLength(11, MinimumLength = 11)]
    [Display(Name = "Mobile Number")]
    public string PhoneNumber { get; set; }

    // فیلد آدرس سایت – URL معتبر
    [Url]
    public string Website { get; set; }

    // شماره کارت اعتباری (برای تمرین)
    [CreditCard]
    [Display(Name = "Credit Card Number")]
    public string CreditCard { get; set; }

    // سن بین ۱۸ تا ۹۹ سال
    [Range(18, 99)]
    public int Age { get; set; }

    // تاریخ تولد با فرمت خاص نمایش
    [DataType(DataType.Date)]
    [DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
    public DateTime BirthDate { get; set; }

    // فیلدی که فقط در کد مقدار می‌گیرد، نه از فرم (BindNever)
    [BindNever]
    public bool IsAdmin { get; set; }

    // فیلدی که باید در فرم ارسال شود، وگرنه خطا می‌دهد
    [BindRequired]
    public string Username { get; set; }

    // فیلد فقط‌خواندنی در فرم
    [Editable(false)]
    public string CreatedBy { get; set; }

    // فیلد محاسباتی که در دیتابیس ذخیره نمی‌شود
    [NotMapped]
    public string FullNameUpper => FullName?.ToUpper();

    // توضیحات بلند با قالب نمایشی چند خطی در فرم
    [UIHint("MultilineText")]
    public string Bio { get; set; }

    // رمز عبور: مقدار اصلی
    [Required]
    [DataType(DataType.Password)]
    [StringLength(100, MinimumLength = 6, ErrorMessage = "رمز عبور باید حداقل ۶ کاراکتر باشد.")]
    public string Password { get; set; }

    // تکرار رمز عبور: برای مقایسه با رمز اصلی
    [Compare("Password", ErrorMessage = "رمز عبور و تکرار آن یکسان نیست.")]
    [DataType(DataType.Password)]
    [Display(Name = "Confirm Password")]
    public string ConfirmPassword { get; set; }

    // کنترل همزمانی برای مدیریت تغییرات هم‌زمان رکورد
    [Timestamp]
    public byte[] RowVersion { get; set; }

    // فیلدی که در Scaffold نمایش داده نشود (مثلاً برای سیستم)
    [ScaffoldColumn(false)]
    public DateTime CreatedAt { get; set; } = DateTime.Now;
}
```

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

تفاوت Data Annotation در مدل و ViewModel

ابتدا باید توجه کرد که از Data Annotationها برای اعتبارسنجی، نمایش بهتر فرم‌ها و تنظیم رفتار فیلدها استفاده می‌شود. با این وجود، جایگاه استفاده آن‌ها بسته به نوع کلاس است. یعنی Model یا ViewModel، متفاوت است.

از یک سو، در Entity Modelها یا مدل‌های EF Core، Data Annotationهایی مانند [Key]، [ForeignKey]، [DatabaseGenerated]، [Timestamp] و [NotMapped] برای مدیریت ساختار دیتابیس به کار می‌روند.

از سوی دیگر، ViewModelها برای نمایش و دریافت اطلاعات از کاربر طراحی شده‌اند. بنابراین، در آن‌ها از Annotationهایی مانند [Required]، [StringLength]، [Display]، [UIHint]، [Compare] و [RegularExpression] برای اعتبارسنجی فرم و کنترل ظاهر استفاده می‌شود.

هر جا با دیتابیس سروکار دارید، باید از Data Annotationهای EF استفاده کنید. در مقابل، هر جا با فرم کاربر طرف هستید، باید از انوتیشن های مرتبط با UI و Validation در ViewModel استفاده کنید.

اگر در پروژه از ViewModel استفاده می‌کنید. همه انوتیشن های مرتبط با فرم، اعتبارسنجی و نمایش UI باید در ViewModel باشند. همچنین، همه انوتیشن های مربوط به EF Core و دیتابیس باید فقط در Entity Model باقی بمانند.