In this article, we are going to explore DateOnly and TimeOnly in C#, see what functionality exists for both, and help decide when to use one or the other.
When it comes to dates and times in C#, for the longest time we have been stuck with the DateTime struct, to serve both purposes. As with most software development decisions, when two requirements are solved by a single solution, often trade-offs are made. Usually, when it comes to DateTime
, it meant that even though we set up a full DateTime
instance, often we are only concerned with the date component or the time component, but rarely both.
For example:
var dateOfBirth = new DateTime(1984, 6, 13); database.Save(dateOfBirth);
In this case, we probably aren’t interested in the time component of the date of birth, but we are left with no choice. We also probably have the field set to datetime
in our database, unnecessarily persisting the time component (and having to read it back, when we select the record).
This means we’re dealing with unnecessary complexity and often storage. SQL Server for example already has separate date and time types, that we couldn’t make use of.
Well, this problem has now been solved. .NET 6/C# 10 has introduced two new structs to help with this problem, being DateOnly
and TimeOnly
.Â
Let’s start with DateOnly.
DateOnly in C#
As the name suggests, we can use the new DateOnly struct when we want to represent only the date component. A good example might be some kind of historical recording, where we aren’t interested in the time of the event, but the fact is happened such as date of birth.
Let’s see how we can declare a new DateOnly instance:
var dateOnly = new DateOnly(2022, 1, 1);
As we expect, the parameters represent the year, month, and day for the date.
Let’s also create a normal DateTime instance with the same arguments, for comparison:
var dateTime = new DateTime(2022, 1, 1);
If we print them both out, we are going to see different results:
1/01/2022 1/01/2022 12:00:00 AM
The first example for DateOnly
stores and prints exactly what we gave instructions for. However for DateTime
, we see the time component of 12:00:00 AM
being stored and presented, even though we didn’t instruct it to do so. Often we forget about this time component entirely, even storing it in the database and never questioning why there are so many records at 12:00 am.Â
Internally, DateOnly
stores its value as an integer
, where 0
is the 1st of January 0001.Â
Using the TryParse Method with DateOnly
With the DateTime
struct, we had the ability to parse a DateTime
from a string. This same functionality exists for DateOnly
:
if (DateOnly.TryParse("2022/01/01", out DateOnly result)) { Console.WriteLine($"Parsed DateOnly: {result}"); }
As with DateTime
, this works across various date formats, e.g American (MM/DD/YYYY), European (DD/MM/YYYY), and Universal (YYYY-MM-DD).
AddDays, AddMonths, AddYears Methods with DateOnly
Just like with DateTime
, the Add<component>
methods have been brought across to the DateOnly
struct:
var addDays = dateOnly.AddDays(1); var addMonths = dateOnly.AddMonths(1); var addYears = dateOnly.AddYears(1);
Of course, AddHours
, AddMinutes
and AddSeconds
aren’t available, as there is no time component. We’ll look at these in the next section when we discuss the TimeOnly
struct.
TimeOnly in C#
When we are only interested in the time component, we can use the new TimeOnly
struct. A good example here might be a repeating alarm event at 11 AM every day. The date itself is irrelevant, as it occurs every day.
Creating a new TimeOnly
instance is very simple:
var elevenAM = new TimeOnly(11, 0);
The output is as we expect:
11:00 AM
There are a few different overloads for TimeOnly
depending on the precision required. The hour component of TimeOnly
is according to a 24-hour clock, so if we want 11 PM we would use the value 23
for the hour parameter.
Internally, TimeOnly
stores its value as long
, being the ticks since midnight.
AddHours and AddMinutes Methods with TimeOnly
We already know how the AddDays()
, AddMonths()
and AddYears()
methods work with DateOnly
. Similarily with TimeOnly
, we have AddHours()
and AddMinutes()
:
var addHours = oneAM.AddHours(1); var addMinutes = oneAM.AddMinutes(5);
There is no AddSeconds()
method, but we can use the generic Add()
method, which takes a TimeSpan
giving us full flexibility:
var addSeconds = oneAM.Add(TimeSpan.FromSeconds(1));
IsBetween Method with TimeOnly
A useful method that comes with the TimeOnly
struct is the IsBetween
method. As the name suggests, it helps us understand if a TimeOnly
instance is between two other TimeOnly
instances.
Let’s put it into action by modifying our previous code:
var sevenAM = new TimeOnly(7, 0); var elevenAM = new TimeOnly(11, 0); var onePM = new TimeOnly(13, 0); Console.WriteLine(elevenAM.IsBetween(sevenAM, onePM)); //Returns True
It’s worth noting that because the hour component is on a 24-hour clock, IsBetween
works across midnight, for example, the following code also prints True:
var elevenPM = new TimeOnly(23, 0); var oneAM = new TimeOnly(1, 0); var twoAM = new TimeOnly(2, 0); Console.WriteLine(oneAM.IsBetween(elevenPM, twoAM));
IsBetween
is a handy method to quickly understand if a time falls in a range.
Manipulations and Operations
In this section, we are going to explore some of the manipulations and operations we can do on the new DateOnly
and TimeOnly
structs.
Basic Operators
We can easily use comparison operators like <
and >
to compare two instances of DateOnly
or TimeOnly
:
var firstOfJan = new DateOnly(2022, 1, 1); var secondOfJan = new DateOnly(2022, 1, 2); if (secondOfJan > firstOfJan) { Console.WriteLine($"{secondOfJan} is after {firstOfJan}"); } var oneAm = new TimeOnly(1, 0); var twoAm = new TimeOnly(2, 0); if (oneAm < twoAm) { Console.WriteLine($"{oneAm} is before {twoAm}"); }
FromDateTime
Because these structs are brand new in the framework, we’re bound to come across legacy DateTime
instances in our app, or we might still have use cases for it (for example, “timestamps” in our database). We can easily convert to DateOnly
and TimeOnly
from these instances, with the FromDateTime
method.
First, let’s set up a DateTime
for the 1st of January 2022, 11:30 AM:
var dateTime = new DateTime(2022, 1, 1, 11, 30, 0);
We can then use the static FromDateTime
method on the DateOnly
and TimeOnly
struct to create instances:
var dateOnly = DateOnly.FromDateTime(dateTime); var timeOnly = TimeOnly.FromDateTime(dateTime);
If we print these out, we see:
1/01/2022 11:30 AM
This could be handy if we want to make use of the newer date/time components, but don’t want to change the type across our entire codebase. This gives us flexibility without doing a potentially breaking change.
Database Support
We mentioned earlier that many databases already support these new types (and most already did, before they were introduced in .NET), so it’s worth spending a moment on exploring that support.
For this article, let’s focus on SQL Server.
Let’s create a simple table to hold the types:
CREATE TABLE [dbo].[DateOnlyAndTimeOnlyTesting]( [DateOnly] [date] NULL, [TimeOnly] [time] NULL ) ON [PRIMARY] GO INSERT INTO [DateOnlyAndTimeOnlyTesting]([DateOnly]) VALUES ('2022-01-01') INSERT INTO [DateOnlyAndTimeOnlyTesting]([TimeOnly]) VALUES ('11:00') SELECT * FROM [DateOnlyAndTimeOnlyTesting]
To store DateOnly
in SQL, we can use the date
type. To store TimeOnly
in SQL, we can use the time
type.
If we look at the query output, we see the records are saved exactly as we’d expect. Only the date or time is persisted, but not both.
It’s worth noting here that at the time of writing, popular ORM’s, like EF Core and Dapper, do not support mapping from the .NET types to the SQL Server types automatically, and custom solutions are required to map to the type.
When to use DateOnly and TimeOnly
The first obvious point here is around data storage. If we are only interested in either date or time, and not both, why store both? “Store” in this case could be:
- Serialization (if we were building an API)
- Persistence (writing to a file or database)
The other point worth calling out is being explicit about design decisions. In the past, if we had any problem that involved either date or time, we would automatically throw a DateTime
instance at the problem and move on with our life. The new types mean we can spend a moment thinking about which one to use. The answer still might be DateTime
, but we are now given more choices. We are being explicit about our choice, which helps other developers maintain the code base and understand our code better.
Conclusion
In this article, we’ve learned about the new DateOnly
and TimeOnly
types introduced in .NET 6. We now have better options to deal with dates and times in .NET, offering us more flexibility in our decisions.