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

Mapster هي مكتبة عالية الأداء لتعيين الكائنات (object-to-object mapping) في بيئة .NET. تتيح لك تحويل الكائنات من نوع إلى آخر تلقائياً، مما يوفر على المطور عناء كتابة كود روتيني لنسخ الخصائص. على عكس المكتبات الضخمة مثل AutoMapper، تركز Mapster على سرعة الأداء واستهلاك أقل للذاكرة، وهو ما تؤكده العديد من اختبارات الأداء.

لماذا نحتاج إلى تعيين الكائنات؟ في المشاريع الحقيقية، نواجه باستمرار الحاجة إلى تحويل البيانات: DTO (كائن نقل البيانات) إلى Entity، ViewModel إلى Model، Model إلى Response، وهكذا. نسخ كل حقل يدوياً هو أمر ممل، وعرضة للأخطاء، ويعقد صيانة الكود. تحل Mapster هذه المشكلة من خلال توفير واجهة برمجة تطبيقات بسيطة ومرنة وسريعة للتعيين التلقائي.

تقوم Mapster بإنشاء كود التعيين في مرحلة الترجمة (عبر محللات Roslyn) أو تستخدم الترجمة الديناميكية للتعبيرات. وهذا يجعلها واحدة من أسرع أدوات التعيين في .NET، وغالباً ما تتفوق حتى على النسخ اليدوي في بعض السيناريوهات. تدعم المكتبة السيناريوهات المعقدة: الكائنات المتداخلة، المجموعات، التعيين الشرطي، تجاهل الحقول، محولات لأنواع مختلفة، وغيرها الكثير.

التثبيت

يتم تثبيت Mapster عبر NuGet Package Manager. نفّذ أحد الأوامر التالية في وحدة تحكم مدير الحزم:

dotnet add package Mapster

أو عبر Package Manager Console:

Install-Package Mapster

للعمل مع ASP.NET Core وحقن التبعيات (DI)، يُوصى بتثبيت حزمة إضافية:

dotnet add package Mapster.DependencyInjection

بعد التثبيت، أضف using Mapster; في بداية ملفك.

بداية سريعة

لننظر إلى مثال بسيط: لدينا كلاس User (نموذج من قاعدة البيانات) وكلاس UserDto (لإرساله إلى العميل).

using Mapster;

// الكلاس الأصلي
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public DateTime CreatedAt { get; set; }
}

// الكلاس الهدف
public class UserDto
{
    public int Id { get; set; }
    public string FullName { get; set; }
    public string Email { get; set; }
}

// مثال الاستخدام
public class Program
{
    public static void Main()
    {
        var user = new User
        {
            Id = 1,
            Name = "أحمد علي",
            Email = "ahmed@example.com",
            CreatedAt = DateTime.Now
        };

        // التعيين باستخدام Mapster
        var dto = user.Adapt<UserDto>();

        Console.WriteLine($"Id: {dto.Id}, Name: {dto.FullName}, Email: {dto.Email}");
        // الإخراج: Id: 1, Name: أحمد علي, Email: ahmed@example.com
    }
}

لاحظ: الخاصية Name تم تعيينها تلقائياً إلى FullName، لأن Mapster تحاول افتراضياً إيجاد تطابقات حسب الاسم (دون حساسية لحالة الأحرف). إذا كان في UserDto خاصية اسمها Name، لكانت تطابقت أيضاً.

الطرق والفئات الأساسية

لنستعرض الطرق الرئيسية في Mapster. لكل طريقة نقدم التوقيع والوصف ومثالاً.

1. Adapt<TDestination>(object source)

التوقيع: public static TDestination Adapt<TDestination>(this object source)

الوصف: طريقة التوسيع الأساسية لتعيين كائن إلى آخر. تنشئ نسخة جديدة من TDestination وتنسخ قيم الخصائص من source.

var user = new User { Id = 1, Name = "سارة" };
var dto = user.Adapt<UserDto>();
Console.WriteLine(dto.FullName); // الإخراج: سارة