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

Flurl هي مكتبة حديثة وأنيقة لـ .NET تجمع بين أداة بناء عناوين URL بأسلوب fluent وعميل HTTP. صُممت لجعل التعامل مع طلبات HTTP بسيطًا للغاية، سهل القراءة ومريحًا. بدلاً من كتابة كود طويل ومعقد باستخدام HttpClient و UriBuilder ودمج النصوص يدويًا، تقدم Flurl صياغة مختصرة ومعبرة تشبه سلاسل الدوال في LINQ.

لماذا تحتاج Flurl؟ المشكلة الأساسية في HttpClient القياسي هي الإسهاب في الكتابة. لإرسال طلب GET بسيط مع باراميترات وترويسات، تحتاج لكتابة 10-15 سطرًا من الكود. Flurl تختصر هذا إلى 2-3 أسطر فقط، مما يجعل الكود يشرح نفسه بنفسه. بالإضافة إلى ذلك، تحل Flurl مشكلة بناء عناوين URL بشكل آمن: فهي تقوم بتشفير الباراميترات تلقائيًا، وتتعامل مع المسارات واستعلامات URL، وتمنع الأخطاء الناتجة عن التهريب غير الصحيح للرموز.

المكتبة مثالية لأي سيناريو يتطلب التفاعل مع REST API: من تطبيقات الهاتف البسيطة إلى أنظمة المؤسسات المعقدة. تدعم Flurl جميع طرق HTTP الأساسية، والعمل مع JSON، ورفع الملفات، والمهلات الزمنية، وإعادة المحاولة، وغيرها الكثير. وهي غير متزامنة بالكامل ومتوافقة مع .NET Standard 2.0+، مما يسمح باستخدامها في .NET Framework و .NET Core و .NET 5/6/7/8.

التثبيت

يمكن تثبيت Flurl عبر NuGet Package Manager. للعمل مع طلبات HTTP، تحتاج إلى الحزمة Flurl.Http التي تتضمن أيضًا Flurl (أداة بناء URL).

عبر .NET CLI:

dotnet add package Flurl.Http

عبر Package Manager Console:

Install-Package Flurl.Http

عبر Visual Studio: انقر بزر الماوس الأيمن على المشروع → Manage NuGet Packages → ابحث عن "Flurl.Http" → Install.

إذا كنت تحتاج فقط إلى أداة بناء URL بدون عميل HTTP، يمكنك تثبيت:

dotnet add package Flurl

بداية سريعة

مثال عملي بسيط — جلب بيانات من API عام وعرضها في وحدة التحكم:

using Flurl.Http;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // طلب GET إلى JSON API
        var response = await "https://jsonplaceholder.typicode.com/posts/1"
            .GetJsonAsync<dynamic>();

        Console.WriteLine($"العنوان: {response.title}");
        Console.WriteLine($"المحتوى: {response.body}");
    }
}

هذا الكود يقوم بإرسال طلب GET، ويقوم تلقائيًا بتحويل استجابة JSON إلى كائن ديناميكي، ثم يعرض الحقول. لاحظ: Flurl تسمح باستدعاء الدوال مباشرة على نص عنوان URL — وهذا هو أسلوب "fluent".

الدوال والفئات الأساسية

1. Url.Combine() — دمج عناوين URL بأمان

التوقيع: public static string Combine(params string[] parts)

الوظيفة: تدمج عدة أجزاء من URL، مع إضافة/إزالة الخطوط المائلة الزائدة تلقائيًا. تمنع تكرار الخطوط المائلة.

using Flurl;

string fullUrl = Url.Combine("https://api.example.com", "/v1/", "users", "/123");
Console.WriteLine(fullUrl); // https://api.example.com/v1/users/123

2. Url.SetQueryParams() — إضافة باراميترات بأسلوب fluent

التوقيع: public static string SetQueryParams(this string url, object values)

الوظيفة: تضيف باراميترات استعلام إلى URL من كائن مجهول أو قاموس. تقوم بتشفير القيم تلقائيًا.

using Flurl;

string url = "https://api.example.com/search"
    .SetQueryParams(new { q = "مرحبا بالعالم", page = 1, limit = 10 });

Console.WriteLine(url); 
// https://api.example.com/se