AutoMapper لـ C# (.NET): دليل كامل مع أمثلة

مقدمة إلى AutoMapper لـ C# (.NET)

\n\n

في التطوير الحديث باستخدام C# (.NET)، غالبًا ما تنشأ الحاجة لتحويل كائن إلى آخر. قد يكون ذلك ضروريًا عند نقل البيانات بين طبقات التطبيق (مثلًا، من قاعدة البيانات إلى DTO لواجهة API)، أو عند تعيين ViewModel إلى Entity، أو عند العمل مع إصدارات مختلفة من API. كتابة الكود يدويًا لكل تحويل من هذا القبيل هي مهمة شاقة، وعرضة للأخطاء، ويصعب صيانتها. وهنا يأتي دور AutoMapper.

\n\n

AutoMapper هي مكتبة شائعة مفتوحة المصدر لـ .NET تعمل على أتمتة عملية تعيين (مطابقة) خصائص كائن مع آخر. تعتمد على مبدأ "الاتفاقية قبل التكوين" (convention over configuration). وهذا يعني أنه إذا تطابقت أسماء وأنواع الخصائص في الكائن المصدر والهدف (أو اتبعت قواعد معينة)، يمكن لـ AutoMapper إجراء التعيين دون تحديد قواعد صريحة. أما إذا اختلفت القواعد، فيمكنك بسهولة تكوينها باستخدام API مرن.

\n\n

تعمل المكتبة على تقليل حجم الكود النمطي بشكل كبير، وتجعل الكود أنظف، وتقلل من عدد الأخطاء المرتبطة بالتخصيص اليدوي، وتُبسّط إعادة الهيكلة. يُستخدم AutoMapper على نطاق واسع في مشاريع ASP.NET Core وWPF وXamarin وتطبيقات .NET الأخرى.

\n\n

تثبيت AutoMapper

\n\n

يتم توزيع AutoMapper عبر NuGet - مدير الحزم الرسمي لـ .NET. يمكن تثبيته بعدة طرق:

\n\n

1. عبر وحدة تحكم مدير الحزم (Package Manager Console)

\n

Install-Package AutoMapper

\n\n

2. عبر .NET CLI

\n

dotnet add package AutoMapper

\n\n

3. عبر واجهة Visual Studio (Manage NuGet Packages)

\n

افتح المشروع -> انقر بزر الماوس الأيمن على المشروع -> "Manage NuGet Packages" -> ابحث عن "AutoMapper" -> قم بتثبيت أحدث إصدار مستقر.

\n\n

للعمل مع ASP.NET Core، يُوصى أيضًا بتثبيت الحزمة AutoMapper.Extensions.Microsoft.DependencyInjection، والتي تُبسّط التكامل مع حاوية DI:

\n

dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection

\n\n

بداية سريعة: أول تعيين

\n\n

لنقم بإنشاء مثال بسيط. لدينا الفئة UserEntity (من قاعدة البيانات) والفئة UserDto (لنقلها إلى العميل).

\n\n

using AutoMapper;\n\n// 1. الفئة المصدر والهدف\npublic class UserEntity\n{\n    public int Id { get; set; }\n    public string FirstName { get; set; }\n    public string LastName { get; set; }\n    public string Email { get; set; }\n}\n\npublic class UserDto\n{\n    public int Id { get; set; }\n    public string FirstName { get; set; }\n    public string LastName { get; set; }\n    public string Email { get; set; }\n}\n\n// 2. إنشاء التكوين و Mapper\nvar config = new MapperConfiguration(cfg =>\n{\n    cfg.CreateMap<UserEntity, UserDto>();\n});\n\nvar mapper = config.CreateMapper();\n\n// 3. الاستخدام\nvar userEntity = new UserEntity\n{\n    Id = 1,\n    FirstName = "إيفان",\n    LastName = "بيتروف",\n    Email = "ivan@example.com"\n};\n\nvar userDto = mapper.Map<UserDto>(userEntity);\n\nConsole.WriteLine(userDto.FirstName); // سيُظهر: إيفان

\n\n

في هذا المثال، أنشأنا خريطة (Map) بين UserEntity و UserDto. نظرًا لتطابق أسماء الخصائص، قام AutoMapper بمطابقتها تلقائيًا. الطريقة Map<TDestination>(source) تقوم بالتعيين وتعيد كائنًا جديدًا من النوع الهدف.

\n\n

الطرق والوظائف الأساسية لـ AutoMapper

\n\n

يوفر AutoMapper API غني لتكوين التعيين. فيما يلي 10 طرق ووظائف رئيسية ستستخدمها في أغلب الأحيان.

\n\n

1. CreateMap<TSource, TDestination>()

\n

ما تفعله: تنشئ تكوين تعيين بين نوعين. هذه هي الطريقة الأساسية للإعلان عن خريطة.