A few years ago, I was reviewing a pull request for a medical records system. The developer had used DateTime to store patient birthdates. It seemed fine until we deployed to a server in a different time zone. Suddenly, patients born on the 1st of the month were appearing as if they were born on the 31st of the previous month. Because DateTime includes a time component, the system was trying to be "helpful" by adjusting the time to the local zone, which pushed the date back a few hours—and into the previous day. It was a classic, frustrating bug that could have been avoided if we had a type that simply didn't care about hours, minutes, or time zones.

The Complexity of DateTime and its Kind

For a long time, DateTime was the only tool in the shed. It represents a point in time, combining both a date and a time of day. The trickiest part of DateTime is the Kind property. You'll see DateTimeKind.Utc, DateTimeKind.Local, and DateTimeKind.Unspecified. If you're building an app that users access globally, you should almost always store your data in UTC. I can't stress this enough: avoid DateTime.Now in your business logic; use DateTime.UtcNow instead. If you use local time, you're essentially gambling that your server's regional settings will never change.

// The common way to capture the exact moment something happened
DateTime timestamp = DateTime.UtcNow;
Console.WriteLine($"Event occurred at: {timestamp}");

// Converting it to the user's local time for display
DateTime localTime = timestamp.ToLocalTime();
Console.WriteLine($"Local time: {localTime}");

The problem is that DateTime is "heavy." When you only need to know that someone was born on May 12th, you don't need to know that they were born at 12:00:00 AM UTC. That extra precision is where the time zone bugs I mentioned earlier creep in.

When to Reach for DateOnly

Introduced in .NET 6, DateOnly is exactly what it sounds like: a date without a time. It's a value type that represents a date, and it doesn't have a Kind property because it doesn't have a time zone. This makes it the perfect choice for birthdays, anniversary dates, or any calendar-based deadline where the specific hour of the day is irrelevant. It removes the ambiguity and prevents the "shifting date" bug entirely.

// Creating a specific date (Year, Month, Day)
DateOnly birthday = new DateOnly(1990, 5, 12);
Console.WriteLine($"Birthday: {birthday}");

// You can easily create a DateOnly from an existing DateTime
DateTime now = DateTime.UtcNow;
DateOnly today = DateOnly.FromDateTime(now);

// Adding days is straightforward
DateOnly nextWeek = today.AddDays(7);

If you're working with a legacy database that only provides DateTime, you can use DateOnly.FromDateTime() to strip away the time component as soon as the data enters your application logic. Conversely, if you need to perform a calculation that requires a time (like calculating the exact number of seconds until a date), you can use birthday.ToDateTime(TimeOnly.MinValue) to turn it back into a DateTime. Just be mindful of which time zone you're assuming when you make that jump.

📋 Practical Task

Build a Subscription Expiry Tracker

Create a small program that manages a user's subscription. Your goal is to use both DateTime and DateOnly appropriately to avoid the "time zone shift" problem.

• Create a DateOnly variable representing the SubscriptionEndDate (set it to a date 30 days from today).
• Create a DateTime variable representing the LastLoginTimestamp using DateTime.UtcNow.
• Write a method that takes these two values and calculates how many full days are remaining until the subscription expires.
• Print a summary to the console that looks like this:
  Last Login: [UTC Timestamp]
Subscription Ends: [DateOnly Value]
Days Remaining: [Number]

Hint: Since you cannot subtract a DateOnly from a DateTime directly, you will need to convert the LastLoginTimestamp to a DateOnly first.