Skip to content
Tutorials Center
My learning

Topics

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.

C#
var birthday = new DateOnly(1990, 7, 21);
Console.WriteLine(birthday.AddYears(1));   // 07/21/1991 with the invariant culture

Try it

C# Dates, arithmetic and comparison

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# Converting, parsing 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 DateOnly : IComparable<DateOnly>, IEquatable<DateOnly>, IFormattable, IParsable<DateOnly>
C#
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.DayNumber gives the number of calendar days with no daylight saving surprises. The - operator is not defined between two DateOnly values (error CS0019: Operator '-' cannot be applied to operands of type 'DateOnly' and 'DateOnly').
  • AddMonths clamps. 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.Json and recent database providers support DateOnly (as yyyy-MM-dd and date). Older libraries may need conversion with FromDateTime/ToDateTime.
  • Defaults. default(DateOnly) is 0001-01-01. Treat it as "not set" only if you document it, or use DateOnly?.
  • Formatting uses the invariant culture here. The short pattern "d" prints like 06/01/2026 on the sandbox; always pass an explicit format for stored text.
  • No Kind, no time zone. Converting DateTime.UtcNow to a DateOnly gives the UTC date, which may differ from the local calendar date.