Skip to content
Tutorials Center
My learning

Topics

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.

C#
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

C# Creating a DateTime and reading its parts

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.

C# Kind, comparison and formatting

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

C#
public readonly struct DateTime : IComparable<DateTime>, IEquatable<DateTime>, IFormattable, ISpanFormattable, IParsable<DateTime>

Common constructors:

C#
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

  • DateTime is immutable. d.AddDays(1) returns a new value and does not change d. Forgetting to use the result is a common bug.
  • Kind is a label, not a conversion. ==, < and CompareTo compare 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.
  • Unspecified is treated as local by ToUniversalTime() and as UTC by ToLocalTime(), which is why it is dangerous. Set Kind when you create values, or use DateTimeOffset.
  • DateTime.Now depends 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.Sunday is 0, not Monday.
  • Prefer smaller types. Use DateOnly for birthdays and due dates, TimeOnly for opening hours, TimeSpan for durations, and DateTimeOffset for timestamps in APIs and databases.
  • Formatting is culture-sensitive. Pass CultureInfo.InvariantCulture for 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.