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

1. ما هي مكتبة CsvHelper ولماذا تحتاجها؟

مكتبة CsvHelper هي أداة قوية ومرنة لقراءة وكتابة ملفات CSV في بيئة .NET. توفر للمطورين واجهة برمجية عالية المستوى (API) تُجرد تعقيد التعامل مع تنسيق CSV، مما يسمح لك بالتركيز على منطق تطبيقك. على عكس الطرق البدائية مثل String.Split(',')، فإن CsvHelper تتعامل بشكل صحيح مع الأحرف المُهربة، علامات الاقتباس، الحقول متعددة الأسطر، والإعدادات الثقافية المختلفة (فواصل، تنسيقات التواريخ والأرقام).

لماذا تحتاجها؟ في التطوير الحديث، يظل CSV أحد أكثر التنسيقات شيوعًا لتبادل البيانات: تصدير التقارير، استيراد من Excel، تحميل الإعدادات، التبادل مع الأنظمة القديمة، وترحيل البيانات. تحول CsvHelper مهمة التحليل الروتينية إلى كود نظيف وتصريحي، باستخدام تعيين الفئات (Attributes أو Fluent API)، والتحويل التلقائي للأنواع، والتحقق المدمج. هذا يوفر ساعات من التطوير ويقلل الأخطاء المرتبطة بالتحليل اليدوي للصفوف.

الميزات الرئيسية: دعم .NET Standard 2.0+ (يعمل في كل مكان: .NET Framework، .NET Core، .NET 5+)، معالجة تدفقية (لا تحمّل الملف بأكمله في الذاكرة)، محولات أنواع مخصصة، كشف الفواصل، التعامل مع الرؤوس والفهارس، ودعم كامل للعمليات غير المتزامنة (ReadAsync/WriteAsync).

2. التثبيت

يتم التثبيت عبر مدير الحزم NuGet. نفّذ أحد الأوامر التالية في وحدة تحكم مدير الحزم أو في terminal .NET CLI:

dotnet add package CsvHelper

أو عبر Package Manager Console:

Install-Package CsvHelper

للإصدار 31.0.2 (الأحدث وقت الكتابة) تحتاج إلى .NET Standard 2.0 أو أعلى. بعد التثبيت، أضف توجيهات using في الكود الخاص بك:

using CsvHelper;
using CsvHelper.Configuration;
using System.Globalization;

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

لننشئ نموذجًا بسيطًا ونكتب/نقرأ ملف CSV.

using System.Globalization;
using CsvHelper;
using CsvHelper.Configuration;

public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

// الكتابة
var people = new List<Person>
{
    new Person { Name = "آنا", Age = 30, Email = "anna@example.com" },
    new Person { Name = "بوريس", Age = 25, Email = "boris@example.com" }
};

using (var writer = new StreamWriter("people.csv"))
using (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))
{
    csv.WriteRecords(people);
}

// القراءة
using (var reader = new StreamReader("people.csv"))
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
    var records = csv.GetRecords<Person>().ToList();
    foreach (var p in records)
        Console.WriteLine($"{p.Name}, {p.Age}, {p.Email}");
}

يوضح هذا المثال الدورة الأساسية: إنشاء كائن CsvWriter أو CsvReader، تمرير التدفق (stream) والثقافة (culture)، واستدعاء طريقة الكتابة/القراءة. لاحظ استخدام CultureInfo.InvariantCulture — وهذا يضمن كتابة الفواصل العشرية والتواريخ بتنسيق موحد (نقطة للأرقام، ISO للتواريخ).