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

ما هو RestSharp ولماذا تحتاجه؟

RestSharp هي مكتبة مفتوحة المصدر شهيرة للغة C# (.NET)، مصممة لتبسيط التعامل مع RESTful API. توفر واجهة سهلة وبديهية لتنفيذ طلبات HTTP (GET, POST, PUT, DELETE, PATCH وغيرها) ومعالجة الردود من خدمات الويب.

تحل RestSharp عدة مشاكل رئيسية:

• تبسيط الكود: بدلاً من كتابة كود طويل باستخدام HttpClient، تقدم RestSharp واجهة fluent موجزة.
• التسلسل/إلغاء التسلسل تلقائياً: تقوم المكتبة تلقائياً بتحويل كائنات C# الخاصة بك إلى JSON/XML والعكس، مما يوفر عليك العمل اليدوي.
• معالجة الأخطاء بسهولة: توفر RestSharp فئات واضحة لمعالجة حالات HTTP والاستثناءات.
• دعم المصادقة: دعم مدمج لـ OAuth و Basic Auth و JWT وغيرها من المخططات.
• التعامل مع الملفات: رفع وتنزيل الملفات ببساطة.

تُستخدم المكتبة بنشاط في تطبيقات .NET (ASP.NET Core، تطبيقات الكونسول، Xamarin، Unity) للتكامل مع الخدمات الخارجية: شبكات التواصل الاجتماعي، أنظمة الدفع، المنصات السحابية، وغيرها.

تثبيت RestSharp

يتم تثبيت RestSharp عبر مدير الحزم NuGet. اختر إحدى الطرق التالية:

عبر Package Manager Console (في Visual Studio):

Install-Package RestSharp

عبر .NET CLI (سطر الأوامر):

dotnet add package RestSharp

عبر واجهة NuGet (Visual Studio/Rider):

افتح Manage NuGet Packages ← ابحث عن RestSharp ← قم بتثبيت أحدث إصدار مستقر.

بعد التثبيت، أضف التوجيه using إلى الكود الخاص بك:

using RestSharp;

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

لنقم بعمل طلب GET بسيط إلى API عام (JSONPlaceholder) ونحصل على قائمة المستخدمين.

using RestSharp;

var client = new RestClient("https://jsonplaceholder.typicode.com");
var request = new RestRequest("/users", Method.Get);

var response = client.Execute(request);

if (response.IsSuccessful)
{
    Console.WriteLine(response.Content); // سيتم طباعة نص JSON
}
else
{
    Console.WriteLine($"خطأ: {response.StatusCode} - {response.ErrorMessage}");
}

يقوم هذا الكود بإنشاء عميل، وتشكيل طلب GET إلى نقطة النهاية /users، وطباعة الرد في الكونسول. لاحظ أن response.IsSuccessful تتحقق من أن حالة الرد تقع في النطاق 200-299.

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

فيما يلي الطرق الرئيسية للمكتبة مع الشرح والمعاملات والأمثلة.

1. RestClient(string baseUrl) — مُنشئ العميل

الوصف: ينشئ مثيلاً لعميل HTTP مع عنوان URL أساسي. جميع الطلبات اللاحقة ستستخدم هذا العنوان كأساس.

المعاملات:

• baseUrl (string) — عنوان API الأساسي (مثال: "https://api.example.com").

مثال:

var client = new RestClient("https://api.github.com");

2. RestRequest(string resource, Method method) — إنشاء طلب

الوصف: يشكل طلب HTTP إلى المورد المحدد بالطريقة المعطاة (GET, POST, PUT, DELETE، إلخ).

المعاملات:

• resource (string) — المسار النسبي للمورد (مثال: "/users").
• method (Method) — طريقة HTTP من التعداد Method (Get, Post, Put, Delete, Patch, Head, Options).

مثال:

var request = new RestRequest("/users/1", Method.Get);

3. client.Execute(IRe