Spargine is a collection of open-source assemblies and NuGet packages designed for .NET 10, which I have been developing and maintaining since the release of .NET Framework 2. These assemblies are not only a core part of my projects but are also actively deployed in production environments across several companies I collaborate with.

Get Spargine

You can access the source code and NuGet packages here:

• GitHub: Spargine 10
• NuGet: dotNetDaveNuGet

Handling dates and times correctly is one of the most deceptively complex challenges in .NET development. Time zones, ISO week rules, formatting, ranges, and epoch conversions are all common requirements—yet they are easy to get wrong and often lead to subtle bugs that only surface in production.

The DateTimeExtensions class in the DotNetTips.Spargine.Extensions project was designed to remove that complexity. It provides a comprehensive set of well-tested extension methods for DateTime, DateTimeOffset, and DateOnly that simplify common operations while enforcing consistent, predictable behavior. These extensions eliminate repetitive code, improve readability, and help ensure that date and time logic remains correct across cultures, time zones, and calendar rules.

This article documents the available methods in DateTimeExtensions and demonstrates how they can make your date and time handling safer, clearer, and easier to maintain.

Methods

Below is the complete set of methods currently available in the DateTimeExtensions class.

• FromMilliEpochTime()
  Converts a long value representing the time in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC) back into a DateTime instance.
• GetLastDayOfWeek(DayOfWeek dayOfWeek)
  Calculates and returns the last occurrence of a specified day of the week before or on the given DateTimeOffset input.
• GetNextDayOfWeek(DayOfWeek dayOfWeek)
  Returns the next occurrence of a specified day of the week after the given DateTimeOffset input.
• GetWeekOfTheYear()
  Returns the ISO 8601 week number of the year for the specified DateOnly.
  This method is overloaded to accept DateTime.
• GetWeeksInTheYear()
  Returns the ISO 8601 number of weeks in the specified year.
• GetYear()
  Returns the ISO 8601 week number of the year for the specified DateTime.
  This method is overloaded to accept DateOnly.
• GetYearEnd()
  Returns the last day of the ISO 8601 week-based year for the specified year.
• GetYearStart()
  Returns the first day of the ISO 8601 week-based year for the specified year.
• Intersects(DateTime endDate, DateTime intersectingStartDate, DateTime intersectingEndDate)
  Intersects the specified start date.
  This method is overloaded to accept DateTimeOffset.
• IsInRange(DateTime beginningTime, DateTime endTime)
  Determines whether the value is in the range of the specified beginning time and end time.
  This method is overloaded to accept TimeSpan, and DateTimeOffset.
• IsInRangeThrowsException(DateTime beginningTime, DateTime endTime, string paramName)
  Determines whether [is in range throws exception] [the specified beginning time]. Throws Exception if invalid.
  This method is overloaded to accept TimeSpan, and DateTimeOffset.
• LocalTimeFromUtc(int timezoneFromUtc)
  Given a date, it returns the local DateTime based on a timezone.
• Max(DateTime compareTo)
  Determines the maximum of the two DateTimes.
  This method is overloaded to accept DateTimeOffset.
• TimeUntilNextHour()
  Determines how long until the next hour starts.
  This method is overloaded to accept DateTime, and DateTimeOffset.
• TimeUntilNextMinute()
  Determines how long until the next minute starts.
  This method is overloaded to accept DateTime, and DateTimeOffset.
• ToFormattedString(DateTimeFormat format)
  Converts DateTime to a formatted string.
  This method is overloaded to accept DateTimeOffset.
• ToFriendlyDateString()
  Creates a friendly date string.
  This method is overloaded to accept DateTime, and DateTimeOffset.
• ToMilliEpochTime()
  Converts convert a DateTime object into a long representing the time in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).

Examples

ToFormattedString()

var result = now.ToFormattedString(DateTimeFormat.FullDateLongTime);

Example outputs include:

• FullDateLongTime: Thursday, January 7, 2021 3:36:39 PM
• FullDateShortTime: Thursday, January 7, 2021 3:36 PM
• FullDateTime: Thursday, January 7, 2021 3:36 PM
• GeneralDateLongTime: 1/7/2021 3:36:39 PM
• GeneralDateShortTime: 1/7/2021 3:36 PM
• Jan01Comma2020: Jan 07, 2021
• Janurary01Comma2020: January 07, 2021
• LongDate: Thursday, January 7, 2021
• LongTime: 3:36:39 PM
• MonthDay: January 7
• MonthYear: January 2021
• RFC1123: Thu, 07 Jan 2021 15:36:39 GMT
• RoundTripDateTime: 2021-01-07T15:36:39.4416894-08:00
• ShortDate: 1/7/2021
• ShortTime: 3:36 PM
• SortableDateTime: 2021-01-07T15:36:39
• UniversalFullDateTime: Thursday, January 7, 2021 11:36:39

ToFriendlyDateString()

Example output:

Today @ 3:38:55 pm.

Summary

The DateTimeExtensions class eliminates much of the complexity and risk associated with date and time handling in .NET applications. By encapsulating common patterns—such as ISO week calculations, range validation, epoch conversions, and friendly formatting—these extensions make your code easier to read, harder to misuse, and more reliable.

If your applications perform scheduling, reporting, logging, validation, or time-based calculations, DateTimeExtensions provides a clean, consistent, and battle-tested foundation that helps you get dates and times right the first time.

Pick up any books by David McCarter by going to Amazon.com: http://bit.ly/RockYourCodeBooks

If you liked this article, please buy David a cup of Coffee by going here: https://www.buymeacoffee.com/dotnetdave

© The information in this article is copywritten and cannot be preproduced in any way without express permission from David McCarter.