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

يُعد التعامل مع التواريخ والأوقات من أكثر المهام تعقيدًا وعرضة للأخطاء في تطوير البرمجيات. تعاني الأنواع المدمجة DateTime و DateTimeOffset في .NET من مشاكل جوهرية: الخلط بين التوقيت المحلي والتوقيت العالمي (UTC)، وعدم وجود فصل واضح بين "لحظة زمنية" و "تاريخ تقويمي"، والغموض عند التعامل مع المناطق الزمنية والتوقيت الصيفي. صُممت مكتبة NodaTime لحل هذه المشاكل، حيث تقدم للمطورين واجهة برمجة تطبيقات (API) آمنة، معبرة، ومحصنة ضد الأخطاء للتعامل مع الوقت.

NodaTime هي مكتبة بديلة للتعامل مع التواريخ والأوقات في .NET، مستوحاة من مكتبة Joda-Time الخاصة بلغة Java. توفر فصلًا واضحًا بين مفاهيم الوقت المختلفة: Instant (لحظة زمنية)، LocalDateTime (تاريخ ووقت بدون منطقة زمنية)، ZonedDateTime (تاريخ ووقت مع منطقة زمنية)، Duration (فترة زمنية بالنانو ثانية)، و Period (فترة زمنية بالوحدات التقويمية). تستخدم المكتبة بيانات المناطق الزمنية من IANA (قاعدة tzdata)، مما يجعلها أكثر دقة وتحديثًا من الآليات المدمجة في Windows.

الهدف الرئيسي لـ NodaTime هو جعل العمليات الخاطئة على الوقت مستحيلة على مستوى الترجمة (Compile-time). على سبيل المثال، لن تتمكن عن طريق الخطأ من جمع LocalDateTime مع Duration (لأن ذلك لا معنى له بدون منطقة زمنية)، أو مقارنة Instant مع LocalDate. توفر المكتبة أيضًا إمكانيات قوية للتنسيق (Formatting)، والتحليل (Parsing)، والتعامل مع المناطق الزمنية والأنظمة التقويمية (بما في ذلك التقويم اليولياني، الإسلامي، والعبراني).

التثبيت

لتثبيت NodaTime في مشروع .NET، استخدم NuGet Package Manager. قم بتنفيذ أحد الأوامر التالية:

# عبر .NET CLI (موصى به)
dotnet add package NodaTime

# عبر Package Manager Console (في Visual Studio)
Install-Package NodaTime

# أو عبر واجهة NuGet Package Manager UI: ابحث عن "NodaTime"

بعد التثبيت، أضف التوجيه using NodaTime; في بداية ملف الكود الخاص بك. للعمل مع المناطق الزمنية، قد تحتاج أيضًا إلى using NodaTime.TimeZones;.

بداية سريعة

مثال عملي بسيط يوضح الإمكانيات الأساسية لـ NodaTime:

using NodaTime;
using NodaTime.Text;

// 1. اللحظة الزمنية الحالية بالتوقيت العالمي (UTC)
Instant now = SystemClock.Instance.GetCurrentInstant();
Console.WriteLine($"اللحظة الحالية (UTC): {now}");

// 2. التحويل إلى التوقيت المحلي (موسكو)
DateTimeZone moscowZone = DateTimeZoneProviders.Tzdb["Europe/Moscow"];
ZonedDateTime moscowTime = now.InZone(moscowZone);
Console.WriteLine($"الوقت في موسكو: {moscowTime}");

// 3. إنشاء تاريخ ووقت محددين
LocalDateTime localDate = new LocalDateTime(2024, 12, 25, 10, 30, 0);
Console.WriteLine($"التاريخ المحلي: {localDate}");

// 4. تحليل نص (Parsing)
var pattern = LocalDateTimePattern.CreateWithInvariantCulture("yyyy-MM-dd HH:mm:ss");
LocalDateTime parsed = pattern.Parse("2024-12-25 10:30:00").Value;
Console.WriteLine($"تم التحليل: {parsed}");

// 5. العمل مع الفترات الزمنية (Duration)
Duration duration = Duration.FromHours(2.5);
Instant future = now + duration;
Console.WriteLine($"بعد 2.5 ساعة: {future.InZone(moscowZone)}");

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

1. Instant — اللحظة الزمنية

التوقيع: public readonly struct Instant : IEquatable<Instant>, IComparable<Instant>

الوظيفة: تمثل نقطة على الخط الزمني، تُقاس بالنانو ثانية منذ عصر Unix (1 يناير 1970، 00:00:00 UTC). لا تعتمد على أي منطقة زمنية.

Instant epoch = Instant.FromUnixTimeTicks(0); // عصر Unix
Instant now = Sy