Developers can benefit from enhanced Date and Time types and Timezone support

[tarekgh]

Date and Time features proposal

This issue is capturing the Date and Time candidate tasks for .NET 6.0 release. It lists every proposed feature and the reason for having it in the candidate list.

Features List

• Support IANA time zone ids on Windows and Windows time zones Ids on Linux and OSX. The APIs Proposal, The fundamental change PR
• Introduce Date and Time types. PR, PR1
• Fix and enhance time zone Adjustment Rules PR1, PR2, API Proposal, PR3
• Miscellaneous fixes: TZ Display Names on Linux, DateTimeUtcNow optimization

Features Details

Time zone ids

Currently when running on Windows, .NET read the time zone data from Windows registry which include the time zone Windows Ids e.g. Standard Pacific Time. Trying to create a TimeZoneInfo using IANA time zone Ids on Windows will fail and will get exception. The reason of that is .NET don't have any source of getting such Ids and map it to Windows Ids.

The same problem occur on Linux/OSX too. On Linux/OSX we read the time zone data for the installed time zone package which include only IANA time zone Ids e.g. America/Los_Angeles. Trying to create a TimeZoneInfo using Windows Ids will fail and throw exception.

It has been requested multiple times to support IANA Ids on Windows and support Windows Ids on Linux/OSX. #14929 show the demand on this feature and capture the discussions and the demand on it. We delayed the support of this feature because we didn't have a good source of the time zone data which can help converting the IANA Ids to Windows Ids and vice versa. Also, .NET avoided carrying the data because servicing such data will be big deal especially time zone data is very dynamic and constantly change.

We have been recommending using the TimeZoneConverter library as a workaround which helped a lot to unblock user's scenarios. The issue is some users cannot take dependency on none core packages and want to have this support natively in the .NET.

Fortunately, in .NET 5.0 we have started to use ICU library for the globalization support. ICU has time zone APIs which can help in converting Windows Ids to IANA Ids and vice versa. .NET can take advantage of ICU to implement such feature.

ICU provide the TimeZone class which provide the methods TimeZone::getWindowsID and TimeZone::getIDForWindowsID can be used to implement the feature. There are some catches though which we need to consider as part of the feature design:

• The ICU time zone APIs is introduced in ICU version 52 while .NET supports ICU from versions 50. We are looking at all Linux platforms that will be supported by .NET 6.0 and find out if we can require ICU 52 as the minimum supported version. If we cannot raise the minimum ICU version to 52, then will not support the feature when using ICU version 50 and 51.
• On Windows we support running using NLS and not using ICU. We either will not support the feature when switching to NLS mode. Or we consider loading ICU in NLS mode too for calling time zone APIs. In recent Windows 10 versions, ICU get loaded in many processes anyway so there will not be much overhead.
• ICU doesn’t provide plain C APIs for time zone functionality. To use ICU for Id conversion will require to call C++ ICU APIs especially if we load ICU dynamically. There can be some challenges with that for binding to the C++ dynamically. This will need more investigation to handle that. We can investigate getting the needed information using ures_* APIs
• .NET can run on Windows down-level versions which will not have ICU. That mean we’ll not support the Ids conversion feature on such Windows versions except if the apps decide to opt-in using the local ICU feature which the app will carry ICU as part of the app.
• Although we'll allow creating TimeZoneInfo objects using either IANA or Windows Ids whereever we run on any platform, it may worth thinking if need to expose any needed APIs (e.g. TimeZoneInfo.WindowsId, TimeZoneInfo.IANAId).

Adjustment Rules Enhancement

When we ported the TimeZoneInfo code to Linux and exposed the APIs that handle the time zone adjustment rules, there was some limitations. The original design of the AdjustmentRule was based on how the time zone data format we read from Windows Registry while the data we read from Linux is very different. Although we tried to make it work with this limitation, it still not returning a prefect results in all cases. This issue is reported many times in issues like #44475, #20626, and #20624. The proposal here is do the following:

• Currently we maintain the internal UTC office for each rule. Exposing this offset is going to help in general as seeing some users using reflection to get this value. Exposing this offset is going to help in Linux scenarios too.
• Linux time zone data cannot be satisfied with the current AdjustmentRule APIs. We’ll need to expose more APIs to allow Linux rules scenarios.
• Need to investigate the current reported issues and fix any wrong calculations. This is related to the previous bullet which we may need to expose a new API for that as needed.

Date & Time types

.NET expose DateTime and DateTimeOffset for handling date and time. It has been requested multiple time to expose Date only and Time only structs. There are many scenarios users need to handle Dates without caring about time at all. And scenarios need to handle time without caring about Date. Users today try to work around that by using DateTime or DateTimeOffset but users need to truncate the parts they don’t need and want to ensure the remaining values is not affected. This is error prone as DateTime and DateTimeOffset also carry some time zone related things and it is not meant handle absolute date and time.

There is detailed discussions about such requested in the reported issues #14744, #1740 and #14089. Initially we have suggested to expose these features outside the core as a NuGet package. This is implemented in corefxlab https://github.com/dotnet/corefxlab/tree/master/src/System.Time. Users still requesting this functionality to be in core and they wanted to avoid dependencies on third party libraries and make sense such functionality be in the core. The corefxlab implementation is a good start as it has the full exposure and working functionality. Need just some polishing to be moved to core. Some points we need to consider when moving it to core:

• The type names are important. Time ok to use but it could be many users define their own Time type. When exposing Time that can conflict with user types. This is a generic issue that usually occur when using names that can conflict with user defined types (Span is a good example of that). It is important to have the right name in core though for discoverability purpose. Date is more problematic name as Visual Basic exposed aliased type with that name. This can be issue there and we need to evaluate if we can easily do something to help with that conflicts or just try to find another name.
• Interop between these types and existing types DateTime and DateTimeOffset need to be carefully designed to avoid any confusion for users to be clear which type can be used in which scenario.
• Because the current corefxlab implementation is done outside the core, it had to do some hacks to enable functionality like formatting and parsing. When moving the types to core we need to have clear design for such functionality and re-implement these parts.
• Need to decide if we’ll support any serialization support.

Miscellaneous Fixes

We have some other issues and features related to dates and time. Investigating and resolving these issues would help the users in general.

• Performance regression: DateTime.UtcNow and DateTimeOffset.UtcNow 2.5x slower
• TimeZoneInfo DisplayName is always set to StandardName on Unix ... PR

[danmoseley]

@tarekgh this is great, I retitled it in user-focused terms as it's a user story

[danmoseley]

Added to #44314 so it appears in https://themesof.net/?q=is:open%20kinds:teub

[shtratos]

A shout from the Java side: please have a look at the work done in JSR-310 to introduce modern date/time abstractions in Java 8: https://www.threeten.org/

Java has had a long and painful history with time handling (e.g. java.util.Date is mutable).
IIRC these modern types have originated as Joda time library which became widely popular and eventually assimilated into the JDK.

Also, having a standard Clock time provider is genuinely nice for injecting it as a dependency in your classes to make them testable and make dependency on the time explicit. Sadly, I frequently see time-bombs going off in our .NET tests because someone decided that using System.DateTime.UtcNow directly is good enough.

[tarekgh]

@shtratos we are aware of Joda time and there is already the Noda time library implementing that. The Clock concept is a good idea we can consider. Do you have specific concern with the proposal we have here?

[Clockwork-Muse]

@tarekgh - I think the call there is (once again) to implement a full date/time library in core, not to limit things to just the basic Date/Time types.

Outside of restating my own desires in that direction, getting new types into a new System.Time namespace (and having them not reference System.DateTime) would be my only concerns given the limitations that have been previously discussed.