C# Reference ยท Date, Time and Globalization
The DateTime struct
Reference for System.DateTime in C#: constructors, components, DateTimeKind, comparison, ToString formats and when to choose DateTimeOffset or DateOnly instead.
DateTime is a value type that stores a date and a time of day as a count of 100-nanosecond ticks since midnight on 1 January 0001 in the Gregorian calendar. It also carries a Kind flag (Utc, Local or Unspecified) that says how the value should be interpreted. DateTime has no time zone or offset of its own, only that flag.
It is the oldest and most widely used date type in .NET. For new code, prefer DateOnly and TimeOnly when you only need one half, and DateTimeOffset when you store a moment that must be unambiguous. DateTime still fits local wall-clock values and many existing APIs.
var due = new DateTime(2026, 3, 15, 9, 30, 0, DateTimeKind.Utc); Console.WriteLine(due.ToString("O")); // 2026-03-15T09:30:00.0000000Z
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public readonly struct DateTime : IComparable<DateTime>, IEquatable<DateTime>, IFormattable, ISpanFormattable, IParsable<DateTime>
Common constructors:
new DateTime(int year, int month, int day) new DateTime(int year, int month, int day, int hour, int minute, int second) new DateTime(int year, int month, int day, int hour, int minute, int second, DateTimeKind kind) new DateTime(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond) new DateTime(long ticks, DateTimeKind kind = DateTimeKind.Unspecified) new DateTime(DateOnly date, TimeOnly time, DateTimeKind kind = DateTimeKind.Unspecified)
| Member | Description |
|---|---|
Year, Month, Day, Hour, Minute, Second, Millisecond, Microsecond, Nanosecond |
The components. Microsecond and Nanosecond were added in .NET 7. |
DayOfWeek, DayOfYear |
Weekday (Sunday is 0) and day number in the year (1 to 366). |
Date, TimeOfDay |
The date at midnight, and the time since midnight as a TimeSpan. |
Ticks |
100 ns units since 0001-01-01. |
Kind |
DateTimeKind.Utc, Local or Unspecified. |
Now, UtcNow, Today |
The current time. Prefer TimeProvider in testable code. |
MinValue, MaxValue, UnixEpoch |
0001-01-01, 9999-12-31 23:59:59.9999999, and 1970-01-01 UTC. |
AddDays, AddHours, AddMonths, AddYears, Add(TimeSpan)... |
Return a new value; see date arithmetic. |
ToUniversalTime(), ToLocalTime(), SpecifyKind() |
Kind conversion and relabeling. |
Parse, TryParse, ParseExact |
See parsing. |
ToString(...), ToShortDateString() |
See formatting. |
Errors: constructors throw ArgumentOutOfRangeException for impossible parts (month 13, 30 February). The Add... methods throw it when the result leaves the range 0001 to 9999.
Usage notes
DateTimeis immutable.d.AddDays(1)returns a new value and does not changed. Forgetting to use the result is a common bug.Kindis a label, not a conversion.==,<andCompareTocompare ticks only, so a UTC and a Local value with the same clock reading are equal. Convert to one kind (usually UTC) before comparing values from different sources.Unspecifiedis treated as local byToUniversalTime()and as UTC byToLocalTime(), which is why it is dangerous. SetKindwhen you create values, or useDateTimeOffset.DateTime.Nowdepends on the machine's time zone. In the browser sandbox of this site, the time zone is UTC. Store instants in UTC and convert for display.- Precision and range. One tick is 100 ns. Values print to 7 fraction digits with
"O". Years go from 1 to 9999. - Day-of-week numbering.
DayOfWeek.Sundayis 0, not Monday. - Prefer smaller types. Use
DateOnlyfor birthdays and due dates,TimeOnlyfor opening hours,TimeSpanfor durations, andDateTimeOffsetfor timestamps in APIs and databases. - Formatting is culture-sensitive. Pass
CultureInfo.InvariantCulturefor file names, logs and wire formats; this environment always uses the invariant culture. - Leap seconds do not exist in
DateTime; a second is always 60 per minute.