Date/time best practices

Abstract

Best practices for configuring date/time in multi-instance CMS solutions across different time zones.

The following list describes the best practices for configuring date/times in multi-instance CMS solutions spread across different time zones.

  • Avoid using local time. Do not use the DateTime.Now property, use DateTime.UtcNow instead.

  • Use only the new methods of Sitecore.DateUtil class for date/time conversion operations.

  • Convert date/time to universal time using the ToUniversalTime method of the Sitecore.DateUtil class, before saving date/time to the database.

  • Sitecore applications and UI dialogs should display date/time values in the server time zone. You need to convert UTC date/time to server time using the ToServerTime method of the Sitecore.DateUtil class before displaying date/time values in the UI. This conversion can be done in application code or dialog box logic before the date/time values are assigned to UI controls.

  • Use the methods of the Sitecore.DateUtil class for parsing strings to date/time and converting date/time to strings.

  • When parsing a string to date/time, use IsoDateToDateTime or ParseDateTime methods of Sitecore.DateUtil class. The following overload of the IsoDateToDateTime method has the treatLegacyDatesAsUtc parameter that allows you to specify whether legacy dates should be treated as UTC dates: 

    public static DateTime IsoDateToDateTime([CanBeNull] string isoDate, DateTime defaultValue, bool treatLegacyDatesAsUtc)

  • When converting date/time to string representation in ISO format, use the ToIsoDate method of the Sitecore.DateUtil class.

  • When comparing two date/time values, make sure that they are both of the same kind. Results of a comparison of two date/time values with different formats will be wrong. Perform a conversion first to make sure that both values are in the same format.

  • Keep in mind that the public API (such as created, updated dates of item, etc.) returns universal time, so the client code should handle universal time appropriately.

  • When working with the date picker and time picker controls, make sure that the value assigned to the Value property of these controls is the server time ISO date. The IsoDateToServerTimeIsoDate method of the Sitecore.DateUtil class can be used to convert UTC ISO date to server time ISO date.

  • When saving input from the date picker and time picker controls to the database, make sure that the date/time value selected in the control is converted to UTC before saving. The IsoDateToUtcIsoDate method of Sitecore.DateUtil class can be used to convert server time ISO date to UTC ISO date.

  • Use the Sitecore.Utc and Sitecore.ServerTime attributes to set the DateTime properties. DateTime parameters and methods that return DateTime are handled in a specific Sitecore installation. These attributes provide additional information to developers about the expected kind of date/time.