مكتبة Carter لـ C# (.NET): دليل شامل

1. ما هي مكتبة Carter ولماذا تستخدمها؟

Carter هي إطار عمل خفيف وعالي الأداء لبناء واجهات برمجة تطبيقات HTTP (HTTP API) على منصة ASP.NET Core. مستوحاة من إطار العمل الشهير NancyFX، تقدم Carter للمطورين نهجًا تصريحيًا مألوفًا لتوجيه الطلبات ومعالجتها. على عكس نمط MVC التقليدي (Model-View-Controller)، تتيح لك Carter تعريف نقاط النهاية (endpoints) مباشرة في الكود، دون الحاجة إلى إنشاء وحدات تحكم منفصلة أو إعداد توجيه معقد.

لماذا تستخدم Carter؟ السبب الرئيسي هو البساطة وسرعة التطوير. إذا كنت بحاجة إلى إنشاء API بسيط أو خدمة مصغرة (microservice) بسرعة، فإن Carter توفر لك صياغة موجزة تقلل من الكود النمطي (boilerplate code). إنها مثالية للمشاريع التي لا تحتاج إلى القوة الكاملة لـ MVC، ولكنها تتطلب مرونة وسهولة في التعامل مع الطلبات والاستجابات. تتكامل Carter بشكل ممتاز مع ASP.NET Core، مستفيدة من حاوية حقن التبعيات (DI container) والوسائط الوسيطة (middleware) والميزات الأخرى المدمجة.

تشمل الميزات الرئيسية لـ Carter: الربط التلقائي لمعاملات المسار وجسم الطلب (model binding)، دعم مدمج للتحقق من صحة البيانات (validation)، معالجة بسيطة للأخطاء، بالإضافة إلى إمكانية اختبار نقاط النهاية بسهولة. الإطار مدعوم بنشاط من قبل المجتمع ويُستخدم في بيئات الإنتاج من قبل العديد من الشركات.

2. التثبيت

لتثبيت Carter في مشروع ASP.NET Core الخاص بك، استخدم مدير الحزم NuGet. قم بتنفيذ أحد الأوامر التالية في الطرفية (Terminal):

dotnet add package Carter

أو عبر وحدة تحكم مدير الحزم في Visual Studio:

Install-Package Carter

بعد التثبيت، يجب تسجيل Carter في ملف Program.cs (أو Startup.cs في الإصدارات الأقدم):

using Carter;

var builder = WebApplication.CreateBuilder(args);

// إضافة Carter إلى حاوية DI
builder.Services.AddCarter();

var app = builder.Build();

// توصيل middleware الخاص بـ Carter
app.MapCarter();

app.Run();

ملاحظة: في الإصدارات الحديثة من .NET (6+) يتم استخدام API الحد الأدنى (Minimal API)، لكن Carter لا تزال ذات صلة بالمنطق الأكثر تعقيدًا.

3. البداية السريعة — مثال عملي بسيط

قم بإنشاء مشروع ASP.NET Core جديد (فارغ أو Web API). قم بتثبيت Carter كما هو موضح أعلاه. ثم أنشئ كلاسًا يقوم بتطبيق الواجهة ICarterModule:

using Carter;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;

public class HomeModule : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        // تعريف نقطة نهاية GET بالمسار "/"
        app.MapGet("/", () => "مرحبًا من Carter!");
        
        // تعريف نقطة نهاية GET مع معامل
        app.MapGet("/hello/{name}", (string name) => $"مرحبًا, {name}!");
    }
}

الآن، قم بتسجيل هذا الموديول في ملف Program.cs:

using Carter;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCarter();
var app = builder.Build();
app.MapCarter();
app.Run();

قم بتشغيل التطبيق وانتقل إلى العنوان http://localhost:5000/hello/World. سترى الرد: مرحبًا, World!.

4. أهم الدوال/الكلاسات

دعنا نستعرض العناصر الأساسية في Carter التي ستستخدمها بشكل متكرر.

4.1. ICarterModule

ICarterModule هي الواجهة الأساسية التي يجب على كل موديول (وحدة) Carter تطبيقها. تقوم بتعريف طريقة واحدة هي AddRoutes والتي تستقبل كائنًا من نوع IEndpointRouteBuilder لتسجيل نقاط النهاية الخاصة بك. هذا هو المكان الذي تحدد فيه مسارات API والوظائف المرتبطة بها.