C# Reference ยท Date, Time and Globalization
The DateOnly struct
Reference for System.DateOnly in C# (.NET 6+): create, compare, add days, parse and format calendar dates without a time of day or time zone.
DateOnly represents a calendar date: year, month and day, with no time of day, no Kind and no time zone. It was added in .NET 6 for values that are naturally just dates, such as a birthday, an invoice due date or a public holiday.
Using DateOnly removes a whole class of bugs. A DateTime at midnight can shift to the previous day when converted between time zones; a DateOnly cannot. It is a small struct (one int day number) and its API mirrors DateTime's date half.
var birthday = new DateOnly(1990, 7, 21); Console.WriteLine(birthday.AddYears(1)); // 07/21/1991 with the invariant culture
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 DateOnly : IComparable<DateOnly>, IEquatable<DateOnly>, IFormattable, IParsable<DateOnly>
new DateOnly(int year, int month, int day)
| Member | Description |
|---|---|
Year, Month, Day, DayOfWeek, DayOfYear |
The components. |
DayNumber |
Days since 0001-01-01 (that date is day 0). Subtract two values to count days. |
AddDays(int), AddMonths(int), AddYears(int) |
Return a new date. AddMonths and AddYears clamp to the last valid day. |
FromDateTime(DateTime), FromDayNumber(int) |
Static factory methods. |
ToDateTime(TimeOnly), ToDateTime(TimeOnly, DateTimeKind) |
Combine with a time of day. |
Parse, TryParse, ParseExact, TryParseExact |
Text to date. |
ToString(string?, IFormatProvider?), ToLongDateString(), ToShortDateString() |
Date formatting. Only date format specifiers are allowed. |
MinValue, MaxValue |
0001-01-01 and 9999-12-31. |
Errors: the constructor and Add... methods throw ArgumentOutOfRangeException for an impossible or out-of-range date. Parse throws FormatException. Custom format strings that contain time parts such as HH throw FormatException when formatting a DateOnly.
Usage notes
- Use it when time of day is irrelevant. Birthdays, due dates, billing days, holidays and report dates are
DateOnly. For an instant in time use DateTimeOffset. - Counting days is easy.
b.DayNumber - a.DayNumbergives the number of calendar days with no daylight saving surprises. The-operator is not defined between twoDateOnlyvalues (error CS0019: Operator '-' cannot be applied to operands of type 'DateOnly' and 'DateOnly'). AddMonthsclamps. 31 January plus one month is the last day of February. Adding a month and then subtracting one does not always return the original date.- Interop.
System.Text.Jsonand recent database providers supportDateOnly(asyyyy-MM-ddanddate). Older libraries may need conversion withFromDateTime/ToDateTime. - Defaults.
default(DateOnly)is 0001-01-01. Treat it as "not set" only if you document it, or useDateOnly?. - Formatting uses the invariant culture here. The short pattern
"d"prints like06/01/2026on the sandbox; always pass an explicit format for stored text. - No Kind, no time zone. Converting
DateTime.UtcNowto aDateOnlygives the UTC date, which may differ from the local calendar date.