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

Data Annotation چیست؟

به زبان ساده، Data Annotation مجموعه‌ای از صفت‌ها (Attributes) است که به کلاس‌ها یا اعضای کلاس اضافه می‌کنیم تا «فراداده» یا Metadata درباره آن داده را به سیستم بفهمانیم.

فرض کنید کلاسی به نام User دارید. کد شما به خودیِ خود نمی‌داند که فیلد Email حتماً باید فرمت ایمیل داشته باشد یا فیلد Password نباید خالی بماند. Data Annotationها این قوانین را به صورت توصیفی (Declarative) به کد اضافه می‌کنند.

فضای نام‌های اصلی (Namespaces)

برای استفاده از این قابلیت، معمولاً از دو فضای نام زیر استفاده می‌کنیم:

1. System.ComponentModel.DataAnnotations: شامل ویژگی‌های مربوط به اعتبارسنجی و نمایش.

2. System.ComponentModel.DataAnnotations.Schema: شامل ویژگی‌های مربوط به نحوه نقشه‌برداری (Mapping) روی دیتابیس.

چرا به Data Annotation نیاز داریم؟

بدون این ویژگی، شما مجبور بودید برای هر اعتبارسنجی ساده، چندین خط کد if-else بنویسید.

• رعایت اصل DRY (Don't Repeat Yourself): قانون را یک بار بالای فیلد تعریف می‌کنید و در کل سیستم (از سمت کاربر تا دیتابیس) اعمال می‌شود.

• خوانایی کد: هر کسی با نگاه کردن به کلاس مدل، می‌فهمد چه محدودیت‌هایی روی داده‌ها وجود دارد.

• یکپارچگی: اعتبارسنجی در لایه‌های مختلف (UI و Database) هماهنگ می‌ماند.

دسته‌بندی انواع Data Annotation

ویژگی‌های Data Annotation را می‌توان به سه دسته اصلی تقسیم کرد:

۱. ویژگی‌های اعتبارسنجی (Validation Attributes)

این‌ها پرکاربردترین نوع هستند و بررسی می‌کنند که آیا داده ورودی طبق استاندارد ما هست یا خیر.

• [Required]: مقدار فیلد نمی‌تواند null یا خالی باشد.

• [StringLength(100, MinimumLength = 10)]: حداقل و حداکثر طول یک رشته را تعیین می‌کند.

• [Range(18, 99)]: برای فیلدهای عددی، محدوده مجاز تعیین می‌کند (مثلاً سن بین ۱۸ تا ۹۹).

• [RegularExpression(@"...")]: بررسی داده بر اساس یک الگوی خاص (مثل فرمت کد ملی یا پسورد پیچیده).

• [EmailAddress]: بررسی می‌کند که ورودی حتماً یک ایمیل معتبر باشد.

• [Compare("Password")]: برای تایید رمز عبور استفاده می‌شود (بررسی تطابق دو فیلد).

۲. ویژگی‌های پایگاه داده و اسکیما (Schema Attributes)

این ویژگی‌ها به Entity Framework می‌گویند که جداول دیتابیس را چگونه بسازد.

• [Key]: مشخص می‌کند که این فیلد کلید اصلی (Primary Key) است.

• [Table("Users_Table")]: نام جدول در دیتابیس را تغییر می‌دهد.

• [Column("User_Age")]: نام ستون در دیتابیس را تغییر می‌دهد.

• [ForeignKey("CategoryId")]: ارتباط بین دو جدول را مشخص می‌کند.

• [NotMapped]: به EF می‌گوید این فیلد را در دیتابیس ذخیره نکن (فقط در کد استفاده می‌شود).

۳. ویژگی‌های نمایش (Display Attributes)

بیشتر در پروژه‌های MVC یا Blazor برای نمایش بهتر در رابط کاربری استفاده می‌شوند.

• [Display(Name = "نام کاربری")]: عنوانی که در فرم‌ها به کاربر نمایش داده می‌شود.

• [DataType(DataType.Password)]: به UI می‌گوید این فیلد را به صورت ستاره‌دار نمایش دهد.

مثال عملی: مدل یک محصول

بیایید ببینیم همه این‌ها در کنار هم چگونه به نظر می‌رسند:

Data Annotation در مقابل Fluent API

در Entity Framework، راه دیگری هم برای پیکربندی مدل‌ها وجود دارد که به آن Fluent API می‌گویند (در متد OnModelCreating).

توصیه حرفه‌ای: برای اعتبارسنجی‌های ساده و رایج از Data Annotation استفاده کنید، اما برای روابط پیچیده دیتابیس و تنظیمات خاص، به سراغ Fluent API بروید.

نحوه بررسی اعتبار در کد (Manual Validation)

در ASP.NET Core، سیستم به صورت خودکار ModelState.IsValid را چک می‌کند. اما اگر در یک برنامه کنسول یا لایه‌ای دیگر هستید، می‌توانید به صورت دستی اعتبار یک شیء را چک کنید:

نتیجه‌گیری

Data Annotationها در C# ابزاری قدرتمند برای افزایش سرعت توسعه و جلوگیری از ورود داده‌های مخرب یا اشتباه به سیستم هستند. آن‌ها به شما کمک می‌کنند تا قوانین کسب‌وکار خود را مستقیماً در قلب مدل‌هایتان تعریف کنید. با این حال، نباید در استفاده از آن‌ها زیاده‌روی کرد؛ اگر کلاس‌های مدل شما بیش از حد شلوغ شده‌اند، شاید وقت آن رسیده که بخشی از تنظیمات را به Fluent API منتقل کنید.