DateTime وTimeSpan في C#: Now وUtcNow والإضافة والطرح والمقارنة والقراءة

يمثّل System.DateTime تاريخًا ووقتًا من اليوم، من السنة 1 إلى السنة 9999، بدقة 100 نانوثانية ("tick" واحدة). ويمثّل System.TimeSpan مدة: الفرق بين قيمتي DateTime. كلاهما نوع قيمة غير قابل للتغيير (بنية)، فكل عملية تعيد قيمة جديدة.

using System;

class Program
{
    static void Main()
    {
        var launch = new DateTime(2026, 9, 24);                 // midnight
        var meeting = new DateTime(2026, 9, 24, 14, 30, 0);     // 14:30:00
        var precise = new DateTime(2026, 9, 24, 14, 30, 5, 250); // with milliseconds

        Console.WriteLine(launch.ToString("yyyy-MM-dd HH:mm:ss"));
        Console.WriteLine(meeting.ToString("yyyy-MM-dd HH:mm:ss"));
        Console.WriteLine(precise.ToString("HH:mm:ss.fff"));

        Console.WriteLine($"{meeting.Year} {meeting.Month} {meeting.Day}");
        Console.WriteLine($"{meeting.Hour}:{meeting.Minute}");
        Console.WriteLine(meeting.DayOfWeek);
        Console.WriteLine(meeting.DayOfYear);
        Console.WriteLine(meeting.Date.ToString("yyyy-MM-dd HH:mm")); // time set to 00:00
        Console.WriteLine(meeting.TimeOfDay);                          // a TimeSpan
    }
}

المخرجات:

2026-09-24 00:00:00
2026-09-24 14:30:00
14:30:05.250
2026 9 24
14:30
Thursday
267
2026-09-24 00:00
14:30:00

كل مثال في هذه الصفحة يطبع التواريخ بنص تنسيق صريح. تتبع ToString() الافتراضية الثقافة الحالية (9/24/2026 2:30:00 PM في الولايات المتحدة، و24.09.2026 14:30:00 في ألمانيا)، فتعتمد مخرجاتها على الجهاز. رموز التنسيق في تنسيق DateTime.

التاريخ غير الصالح يرمي استثناءً: new DateTime(2026, 2, 30) ترمي ArgumentOutOfRangeException، وكذلك الشهر 13 أو الساعة 24.

Now وUtcNow وToday

ثلاث خصائص ساكنة تقرأ الساعة:

using System;

class Program
{
    static void Main()
    {
        DateTime local = DateTime.Now;      // local time zone
        DateTime utc = DateTime.UtcNow;     // Coordinated Universal Time
        DateTime today = DateTime.Today;    // local date, time 00:00:00

        Console.WriteLine($"Now:    {local:yyyy-MM-dd HH:mm:ss} ({local.Kind})");
        Console.WriteLine($"UtcNow: {utc:yyyy-MM-dd HH:mm:ss} ({utc.Kind})");
        Console.WriteLine($"Today:  {today:yyyy-MM-dd HH:mm:ss}");
    }
}

مخرجات على سبيل المثال:

Now:    2026-09-24 18:20:41 (Local)
UtcNow: 2026-09-24 16:20:41 (Utc)
Today:  2026-09-24 00:00:00

في هذا المثال تسبق المنطقة الزمنية المحلية توقيت UTC بساعتين، فيختلف السطران الأولان بساعتين؛ وعلى جهاز مضبوط على UTC يتطابقان. تسجّل الخاصية Kind هل القيمة Local أو Utc أو Unspecified (الافتراضي للتواريخ التي تنشئها بنفسك). استخدم DateTime.UtcNow لكل ما تخزّنه أو تسجّله أو تقارنه أو ترسله إلى نظام آخر: لا يقفز حين يبدأ التوقيت الصيفي أو ينتهي، ويعني اللحظة نفسها على كل خادم. حوّل إلى الوقت المحلي فقط حين تعرض القيمة لشخص.

لقياس مدة تنفيذ الشيفرة استخدم System.Diagnostics.Stopwatch بدل طرح قيمتي DateTime.Now؛ فدقته أعلى بكثير ولا يتأثر بتعديلات الساعة.

إضافة الوقت وطرحه

تعيد AddDays وAddHours وAddMinutes وAddSeconds وAddMonths وAddYears قيمة DateTime جديدة. مرّر رقمًا سالبًا للرجوع. ولأن DateTime غير قابل للتغيير يجب إسناد النتيجة:

using System;

class Program
{
    static void Main()
    {
        var ordered = new DateTime(2026, 1, 31, 9, 0, 0);

        ordered.AddDays(3);                     // result discarded: no effect
        Console.WriteLine(ordered.ToString("yyyy-MM-dd"));

        DateTime shipped = ordered.AddDays(3);
        DateTime reminder = ordered.AddHours(-12);
        DateTime renewal = ordered.AddMonths(1);  // Jan 31 + 1 month
        DateTime nextYear = ordered.AddYears(1);

        Console.WriteLine(shipped.ToString("yyyy-MM-dd HH:mm"));
        Console.WriteLine(reminder.ToString("yyyy-MM-dd HH:mm"));
        Console.WriteLine(renewal.ToString("yyyy-MM-dd"));
        Console.WriteLine(nextYear.ToString("yyyy-MM-dd"));

        DateTime later = ordered + TimeSpan.FromMinutes(90);  // + a TimeSpan
        Console.WriteLine(later.ToString("HH:mm"));

        Console.WriteLine(DateTime.DaysInMonth(2028, 2));
        Console.WriteLine(DateTime.IsLeapYear(2028));
    }
}

المخرجات:

2026-01-31
2026-02-03 09:00
2026-01-30 21:00
2026-02-28
2027-01-31
10:30
29
True

تقيّد AddMonths القيمة بآخر يوم في الشهر حين لا يوجد اليوم: 31 يناير مع شهر إضافي هو 28 فبراير (أو 29 في السنة الكبيسة)، لا 3 مارس. لذلك قد تعطي إضافة شهر مرتين وإضافة شهرين تاريخين مختلفين.

طرح التواريخ: TimeSpan

طرح DateTime من آخر يعطي TimeSpan:

using System;

class Program
{
    static void Main()
    {
        var checkIn = new DateTime(2026, 9, 20, 15, 0, 0);
        var checkOut = new DateTime(2026, 9, 24, 11, 30, 0);

        TimeSpan stay = checkOut - checkIn;

        Console.WriteLine(stay);                         // d.hh:mm:ss
        Console.WriteLine($"Days: {stay.Days}, Hours: {stay.Hours}, Minutes: {stay.Minutes}");
        Console.WriteLine($"TotalDays: {stay.TotalDays:F2}");
        Console.WriteLine($"TotalHours: {stay.TotalHours}");
        Console.WriteLine($"TotalMinutes: {stay.TotalMinutes}");

        int nights = (checkOut.Date - checkIn.Date).Days;   // calendar days
        Console.WriteLine($"Nights: {nights}");
    }
}

المخرجات:

3.20:30:00
Days: 3, Hours: 20, Minutes: 30
TotalDays: 3.85
TotalHours: 92.5
TotalMinutes: 5550
Nights: 4

هذا الجزء من الواجهة هو الأكثر عرضة للخطأ. Days وHours وMinutes وSeconds هي مكوّنات المدة (3 أيام، 20 ساعة، 30 دقيقة). وTotalDays وTotalHours وTotalMinutes هي المدة كلها بوحدة واحدة، كقيمة double. "كم ساعة أقام النزيل؟" هي TotalHours (92.5)، لا Hours (20).

يُظهر السطر الأخير نقطة مرتبطة: انقضت 3.85 يوم، لكن النزيل أقام 4 ليالٍ. مقارنة أجزاء .Date تعدّ الأيام التقويمية، وهذا عادة ما تريده الفوترة وعروض "كم يومًا بقي".

إنشاء قيم TimeSpan وتنسيقها

using System;

class Program
{
    static void Main()
    {
        TimeSpan a = TimeSpan.FromMinutes(135);
        TimeSpan b = new TimeSpan(1, 30, 0);          // hours, minutes, seconds
        TimeSpan c = TimeSpan.FromDays(1.5);
        TimeSpan d = TimeSpan.Parse("02:15:00");

        Console.WriteLine(a);
        Console.WriteLine(b);
        Console.WriteLine(c);
        Console.WriteLine(a == d);
        Console.WriteLine(a + b);
        Console.WriteLine(a > b);
        Console.WriteLine(a.ToString(@"hh\:mm"));
        Console.WriteLine($"{(int)c.TotalHours}h {c.Minutes}m");
        Console.WriteLine(TimeSpan.Zero);
    }
}

المخرجات:

02:15:00
01:30:00
1.12:00:00
True
03:45:00
True
02:15
36h 0m
00:00:00

يدعم TimeSpan المعاملين + و- والمقارنات وDuration() (القيمة المطلقة) وNegate(). تحتاج التنسيقات المخصصة مثل @"hh\:mm" إلى شرطة مائلة عكسية قبل المحارف الحرفية، وhh هناك تُظهر مكوّن الساعات فقط (من 0 إلى 23)، فللمدد التي تتجاوز يومًا ابنِ النص من TotalHours كما في السطر قبل الأخير.

مقارنة التواريخ

يدعم DateTime المعاملات == و!= و< و> و<= و>=، إضافة إلى CompareTo وDateTime.Compare. لمقارنة التاريخ فقط وتجاهل الوقت قارن خصائص .Date:

using System;

class Program
{
    static void Main()
    {
        var deadline = new DateTime(2026, 10, 1, 17, 0, 0);
        var submitted = new DateTime(2026, 10, 1, 18, 45, 0);

        Console.WriteLine(submitted > deadline);            // late by time
        Console.WriteLine(submitted.Date == deadline.Date); // same day
        Console.WriteLine(DateTime.Compare(submitted, deadline)); // 1: later

        var start = new DateTime(2026, 9, 1);
        var end = new DateTime(2026, 9, 30);
        var check = new DateTime(2026, 9, 24, 12, 0, 0);
        Console.WriteLine(check >= start && check < end.AddDays(1));   // in range, inclusive of the end day

        DateTime earliest = start < check ? start : check;
        Console.WriteLine(earliest.ToString("yyyy-MM-dd"));
    }
}

المخرجات:

True
True
1
True
2026-09-01

لسؤال "هل هذا الطابع الزمني ضمن 30 سبتمبر؟" قارن ببداية اليوم التالي بـ <، كما في المثال. كتابة check <= end ستستبعد كل ما بعد منتصف الليل في اليوم الأخير، لأن end هي 2026-09-30 00:00:00.

تنظر المقارنات إلى النبضات (ticks) فقط لا إلى Kind: قيمة Local وقيمة Utc تُطبعان متطابقتين تُعتبران متساويتين مع أنهما لحظتان مختلفتان. سبب آخر لإبقاء الأوقات المخزّنة بتوقيت UTC.

يوم الأسبوع وبداية الأسبوع

DayOfWeek تعداد من Sunday (0) إلى Saturday (6). الحساب عليه يجد أيام العمل وحدود الأسبوع:

using System;

class Program
{
    static void Main()
    {
        var date = new DateTime(2026, 9, 24);
        Console.WriteLine(date.DayOfWeek);
        Console.WriteLine((int)date.DayOfWeek);

        bool weekend = date.DayOfWeek == DayOfWeek.Saturday || date.DayOfWeek == DayOfWeek.Sunday;
        Console.WriteLine($"Weekend: {weekend}");

        // Monday of the same week
        int sinceMonday = ((int)date.DayOfWeek + 6) % 7;
        DateTime monday = date.AddDays(-sinceMonday);
        Console.WriteLine($"Week starts {monday:yyyy-MM-dd} ({monday.DayOfWeek})");

        // Next Friday (today counts if it is Friday)
        int toFriday = ((int)DayOfWeek.Friday - (int)date.DayOfWeek + 7) % 7;
        Console.WriteLine($"Next Friday: {date.AddDays(toFriday):yyyy-MM-dd}");

        // First and last day of the month
        var first = new DateTime(date.Year, date.Month, 1);
        var last = first.AddMonths(1).AddDays(-1);
        Console.WriteLine($"{first:yyyy-MM-dd} to {last:yyyy-MM-dd}");
    }
}

المخرجات:

Thursday
4
Weekend: False
Week starts 2026-09-21 (Monday)
Next Friday: 2026-09-25
2026-09-01 to 2026-09-30

أسماء الأيام التي تطبعها DayOfWeek.ToString() إنجليزية دائمًا. لاسم مترجم نسّق التاريخ بـ "dddd" وثقافة.

قراءة التواريخ من النصوص

حين تعرف صيغة المدخلات استخدم ParseExact أو TryParseExact مع CultureInfo.InvariantCulture. يستخدم نص الصيغة الرموز نفسها التي يستخدمها التنسيق:

using System;
using System.Globalization;

class Program
{
    static void Main()
    {
        var inv = CultureInfo.InvariantCulture;

        DateTime a = DateTime.ParseExact("2026-09-24", "yyyy-MM-dd", inv);
        DateTime b = DateTime.ParseExact("24/09/2026 18:05", "dd/MM/yyyy HH:mm", inv);
        Console.WriteLine(a.ToString("yyyy-MM-dd HH:mm"));
        Console.WriteLine(b.ToString("yyyy-MM-dd HH:mm"));

        string[] inputs = { "2026-02-28", "2026-02-30", "28.02.2026", "" };
        foreach (string text in inputs)
        {
            if (DateTime.TryParseExact(text, "yyyy-MM-dd", inv, DateTimeStyles.None, out DateTime d))
                Console.WriteLine($"'{text}' -> {d:dddd, MMMM d}");
            else
                Console.WriteLine($"'{text}' -> invalid");
        }

        // Several accepted formats
        string[] formats = { "yyyy-MM-dd", "dd.MM.yyyy", "MM/dd/yyyy" };
        DateTime c = DateTime.ParseExact("28.02.2026", formats, inv, DateTimeStyles.None);
        Console.WriteLine(c.ToString("yyyy-MM-dd"));

        // ISO 8601 with an offset or Z
        DateTime utc = DateTime.Parse("2026-09-24T10:00:00Z", inv, DateTimeStyles.AdjustToUniversal);
        Console.WriteLine($"{utc:yyyy-MM-dd HH:mm} {utc.Kind}");
    }
}

المخرجات:

2026-09-24 00:00
2026-09-24 18:05
'2026-02-28' -> Saturday, February 28
'2026-02-30' -> invalid
'28.02.2026' -> invalid
'' -> invalid
2026-02-28
2026-09-24 10:00 Utc

تحاول DateTime.Parse(text) دون صيغة التخمين بالثقافة الحالية. "03/04/2026" هي 4 مارس على جهاز أمريكي و3 أبريل على جهاز بريطاني، والتاريخ الذي يُقرأ على حاسوبك المحمول قد يرمي FormatException على خادم. أبقِ Parse لمدخلات يكتبها مستخدم محلي؛ واستخدم ParseExact مع الثقافة الثابتة للملفات وواجهات API وقواعد البيانات. ترمي ParseExact استثناء FormatException حين لا يطابق النص؛ وتعيد TryParseExact القيمة false بدلًا من ذلك.

حساب العمر

طرح تواريخ الميلاد والقسمة على 365 خطأ حول أعياد الميلاد والسنوات الكبيسة. قارن السنوات، ثم صحّح إن لم يأتِ عيد الميلاد هذا العام بعد:

using System;

class Program
{
    static int Age(DateTime birth, DateTime today)
    {
        int age = today.Year - birth.Year;
        if (birth.Date > today.AddYears(-age)) age--;   // birthday not reached yet this year
        return age;
    }

    static void Main()
    {
        var today = new DateTime(2026, 9, 24);
        Console.WriteLine(Age(new DateTime(1990, 9, 24), today));  // birthday today
        Console.WriteLine(Age(new DateTime(1990, 9, 25), today));  // tomorrow
        Console.WriteLine(Age(new DateTime(2008, 2, 29), today));  // leap day

        var nextBirthday = new DateTime(today.Year, 12, 3);
        if (nextBirthday < today) nextBirthday = nextBirthday.AddYears(1);
        Console.WriteLine($"{(nextBirthday - today).Days} days to go");
    }
}

المخرجات:

36
35
18
70 days to go

DateTimeOffset

لا يسجّل DateTime المنطقة الزمنية التي هو فيها سوى بعلامة Kind الغامضة. أما DateTimeOffset فيخزّن القيمة مع إزاحتها عن UTC، فيحدد دائمًا لحظة واحدة دقيقة:

using System;

class Program
{
    static void Main()
    {
        var placed = new DateTimeOffset(2026, 9, 24, 14, 0, 0, TimeSpan.FromHours(2));   // UTC+2
        var received = new DateTimeOffset(2026, 9, 24, 8, 30, 0, TimeSpan.FromHours(-4)); // UTC-4

        Console.WriteLine(placed.ToString("yyyy-MM-dd HH:mm zzz"));
        Console.WriteLine(placed.UtcDateTime.ToString("yyyy-MM-dd HH:mm"));
        Console.WriteLine(received.UtcDateTime.ToString("yyyy-MM-dd HH:mm"));
        Console.WriteLine(received - placed);          // compared as moments
        Console.WriteLine(placed.ToOffset(TimeSpan.FromHours(9)).ToString("HH:mm zzz"));
    }
}

المخرجات:

2026-09-24 14:00 +02:00
2026-09-24 12:00
2026-09-24 12:30
00:30:00
21:00 +09:00

استخدم DateTimeOffset (أو قيم DateTime بتوقيت UTC) للطوابع الزمنية: متى قُدّم طلب، ومتى أُرسلت رسالة. تتعامل معه قواعد البيانات وأدوات تسلسل JSON جيدًا. وللتحويل بين مناطق زمنية مسمّاة بقواعد التوقيت الصيفي استخدم TimeZoneInfo.ConvertTime؛ تختلف معرّفات المناطق بحسب نظام التشغيل في إصدارات .NET الأقدم ("Europe/Paris" في Linux و"Romance Standard Time" في Windows)، وتقبل .NET 6 وما بعدها الاثنين.

DateOnly وTimeOnly (.NET 6 وما بعده)

قيم كثيرة تاريخ بلا وقت (عيد ميلاد، تاريخ استحقاق) أو وقت بلا تاريخ (ساعات العمل). أضافت .NET 6 نوعين لها:

// .NET 6 and later
DateOnly birthday = new DateOnly(1990, 9, 24);
DateOnly due = DateOnly.FromDateTime(DateTime.Today).AddDays(14);
int daysLeft = due.DayNumber - DateOnly.FromDateTime(DateTime.Today).DayNumber;

TimeOnly opens = new TimeOnly(9, 0);
TimeOnly closes = new TimeOnly(17, 30);
bool isOpen = TimeOnly.FromDateTime(DateTime.Now).IsBetween(opens, closes);

يزيلان فئة من الأخطاء يزيح فيها وقت شارد أو منطقة زمنية التاريخ بيوم. الشيفرة الأقدم، والشيفرة التي تستهدف .NET Framework أو Unity، تستخدم DateTime مع ترك الوقت عند منتصف الليل.

أخطاء شائعة

• تجاهل نتيجة AddDays. DateTime غير قابل للتغيير؛ أسند القيمة المعادة.
• استخدام Hours بدل TotalHours. المكوّنات مقابل المدة الكلية.
• تخزين DateTime.Now. خزّن UTC وحوّل للعرض.
• استدعاء ToString() دون تنسيق في السجلات أو الملفات أو الاختبارات، حيث تعتمد المخرجات على ثقافة الجهاز.
• القراءة بـ DateTime.Parse على بيانات الآلة. استخدم ParseExact والثقافة الثابتة.
• الخلط بين mm وMM في نصوص التنسيق (الدقائق والأشهر). راجع تنسيق DateTime.