تكوين تطبيقات C# (.NET): Microsoft.Extensions.Configuration

تكوين تطبيقات C# (.NET): دليل شامل

إدارة التكوين هي إحدى المهام الأساسية عند تطوير التطبيقات الحديثة بلغة C# (.NET). توفر مكتبة Microsoft.Extensions.Configuration آلية قوية ومرنة لقراءة الإعدادات من مصادر مختلفة: ملفات JSON، متغيرات البيئة، وسائط سطر الأوامر والأسرار. في هذه المقالة، سنشرح بالتفصيل كيفية إعداد التكوين في تطبيقات .NET باستخدام أفضل الممارسات وأمثلة الكود.

الإمكانيات الأساسية للمكتبة

• مصادر بيانات متعددة: JSON، XML، INI، متغيرات البيئة، وسائط سطر الأوامر، Azure Key Vault وغيرها.
• هيكل هرمي: دعم الأقسام المتداخلة عبر مفاتيح بنقطتين (Section:Subsection:Key).
• الربط بالفئات (Options Pattern): تعبئة تلقائية لكائنات POCO من التكوين.
• تجاوز مرن: المصدر المضاف أخيراً له الأولوية.
• دعم الأسرار: للتطوير — Secret Manager، للإنتاج — مخازن محمية.

التثبيت والربط

للعمل مع التكوين في تطبيق .NET (تطبيق وحدة التحكم، ASP.NET Core، MAUI وغيرها)، يجب تثبيت حزمة NuGet:

dotnet add package Microsoft.Extensions.Configurationdotnet add package Microsoft.Extensions.Configuration.Jsondotnet add package Microsoft.Extensions.Configuration.EnvironmentVariablesdotnet add package Microsoft.Extensions.Configuration.CommandLine

في ASP.NET Core، هذه الحزم مضمنة افتراضياً.

مثال أساسي: القراءة من appsettings.json

لننشئ ملف appsettings.json:

{  "Logging": {    "LogLevel": {      "Default": "Information",      "Microsoft": "Warning"    }  },  "ConnectionStrings": {    "DefaultConnection": "Server=localhost;Database=MyDb;User Id=sa;Password=MyPass;"  },  "AppSettings": {    "AppName": "MyApp",    "Version": "1.0.0",    "MaxRetries": 3  }}

كود قراءة التكوين في تطبيق وحدة التحكم:

using Microsoft.Extensions.Configuration;

class Program{    static void Main(string[] args)    {        // إنشاء التكوين        var configuration = new ConfigurationBuilder()            .SetBasePath(Directory.GetCurrentDirectory())            .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)            .AddEnvironmentVariables()            .AddCommandLine(args)            .Build();

        // قراءة القيم البسيطة        string appName = configuration["AppSettings:AppName"];        Console.WriteLine($"App Name: {appName}");

        // قراءة الأقسام المتداخلة        string connString = configuration.GetConnectionString("DefaultConnection");        Console.WriteLine($"Connection String: {connString}");

        // قراءة عدد صحيح        int maxRetries = int.Parse(configuration["AppSettings:MaxRetries"]);        Console.WriteLine($"Max Retries: {maxRetries}");

        // الحصول على القسم بالكامل        var appSettingsSection = configuration.GetSection("AppSettings");        Console.WriteLine($"Version: {appSettingsSection["Version"]}");    }}

نمط الخيارات (الربط بالفئات)

أفضل ممارسة هي استخدام التكوين المقيد بالنوع عبر IOptions<T>. للقيام بذلك:

1. أنشئ فئة لقسم التكوين:

public class AppSettings{    public string AppName { get; set; }    public string Version { get; set; }    public int MaxRetries { get; set; }}

2. سجل التكوين في حاوية DI (لـ ASP.NET Core أو باستخدام Micros