System.TimeZone2 Starter Guide [Kathy Kam]

Extended Time Zone support is one of the most requested features in the BCL. System.TimeZone provides some basic support for converting from your machine Time Zone to UTC and vice versa, but it doesn’t have support to convert… say from Pacific Standard Time to Eastern Standard Time. In the “Orcas” September CTP, you’ll see that the BCL team has added a new class named “System.TimeZone2” that will allow you to:

- Convert a DateTime from one time zone (not necessarily your machine’s time zone) to another

- Get an object that describes your local time zone

- Get an array of objects that describes all the available time zones on your machine

- Serialize a time zone into a string

- Create your own time zone object to represent any custom time zones

The best part about this is that… if you are on an Vista machine… all of those functionality will have Vista’s Dynamic Time Zone support, because our calculations are done with the time zone data available on your OS.

Without further ado, let me start by showing you some samples:

1) Getting the Local time zone on your machine:

TimeZone2 GetLocalTimeZone()

{

    return TimeZone2.Local;

}

2) Get all the time zone available on your machine and put it in a list box.

ListBox CreateTimeZoneListBox(ReadOnlyCollection<TimeZone2> systemTimeZones)

{

    // Get all the time zone from your machine

    systemTimeZones = TimeZone2.GetSystemTimeZones();

    // Fill a list box

    ListBox list = new ListBox();

    list.BeginUpdate();

    foreach (TimeZone2 timeZone in systemTimeZones)

    {

        list.Items.Add(timeZone.DisplayName);

    }

    list.EndUpdate();

    return ListBox;

}

3) Get a particular time zone from the operating system by passing in an “Id”

The “Id” of your system time zone is basically the registry key name. A list can be found here.

void GetTimeZone()

{

    // Get a particular time zone

    // e.g. Time in Seattle

    TimeZone2 pacificTZ =

        TimeZone2.FindSystemTimeZoneById(“Pacific Standard Time”);

    // e.g. Time in Hong Kong

    TimeZone2 hongKongTZ =

        TimeZone2.FindSystemTimeZoneById(“China Standard Time”);

    // e.g. Time in Sydney

    TimeZone2 sydneyTZ =

        TimeZone2.FindSystemTimeZoneById(“AUS Eastern Standard Time”);

 

 

}

4) Get the information of a particular time zone

void PrintTimeZoneInformation(TimeZone2 timeZone)

{

    // Prints the display name of the time zone

    // “Pacific Standard Time” will print

    // “(GMT-08:00) Pacific Time (US & Canada); Tijuana”

    Console.WriteLine(timeZone.DisplayName);

    // Prints the base UTC Offset of the time zone

    // “Pacific Standard Time” will print

    // “-08:00:00”

    Console.WriteLine(timeZone.BaseUtcOffset);

    // Prints the UTC Offset of the time zone at a certain time

    // “Pacific Standard Time” will print

    // “-07:00:00”

    DateTime manOnMoon = new DateTime(1969, 9, 9);

    Console.WriteLine(timeZone.GetUtcOffset(manOnMoon));

    // Prints whether a certain time is in the time zone’s daylight

    // saving period

    // “Pacific Standard Time” will print

    // “true”

    Console.WriteLine(timeZone.IsDaylightSavingTime(manOnMoon));

    // Prints whether a certain time is in the missing hour

    // during a daylight savings transition. I.e. during spring ahead

    // “Pacific Standard Time” will print

    // “true”

    DateTime springAhead = new DateTime(2006, 4, 2, 2, 30, 0);

    Console.WriteLine(timeZone.IsInvalidTime(springAhead));

    // “Pacific Standard Time” will print

    // “false”

    Console.WriteLine(timeZone.IsInvalidTime(manOnMoon));

    // Prints whether a certain time is the duplicate hour

    // during a daylight savings transition. I.e. during fall back

    // “Pacific Standard Time” will print

    // “true”

    DateTime fallBack = new DateTime(2006, 10, 29, 1, 30, 0);

    Console.WriteLine(timeZone.IsAmbiguousTime(fallBack));

    // “Pacific Standard Time” will print

    // “false”

    Console.WriteLine(timeZone.IsAmbiguousTime(manOnMoon));

 

}

5) Converting from one time zone to another… Oh Yeah!

This new class allows you to do conversions in two different ways:

a) Convert using TimeZone2.Id

b) Convert using TimeZone2 object

If you already have a TimeZone2 object handy, you can simply convert by passing in the TimeZone2 object.

void ConvertTimeZoneSample()

{

    // Let’s convert my favourite show…

    // Battlestar Galactica Season 3 premier!

    DateTime bsgSeason3 = new DateTime(2006, 10, 6, 9, 0, 0);

    // What time is it in Hawaii when the BCL team and I are watching it?

    DateTime bsgSeason3Hawaii = TimeZone2.ConvertTimeBySystemTimeZoneId(

                              bsgSeason3,

                              “Pacific Standard Time”,

                              “Hawaiian Standard Time”);

    // We can also convert it by passing in TimeZone2 objects!

    TimeZone2 pacificTZ = TimeZone2.Local;

    TimeZone2 hawaiiTZ =

                TimeZone2.FindSystemTimeZoneById(“Hawaiian Standard Time”);

    DateTime bsgSeason3Hawaii = TimeZone2.ConvertTime(

                              bsgSeason3,

                              pacificTZ,

                              hawaiiTZ);

 

    // Or… I just want to know what time it is in UTC

    DateTime bsgSeason3Utc = TimeZone2.ConvertTimeToUtc(

                              bsgSeason3,

                              pacificTZ);

    // Or… from Utc to… Hawaii time

    DateTime bsgSeason3Hawaii = TimeZone2.ConvertTimeFromUtc(

                              bsgSeason3Utc,

                              hawaiiTz);

}

A key TimeZone2 concept is the “Time Zone Id” . A Time Zone Id is a string that represents a time zone on the local machine. Microsoft Windows comes preinstalled with over seventy unique time zones! Because there are no standardized ways of enumerating through time zones, we decided to use the Windows Registry Key name as the id to uniquely locate the preinstalled time zones on your machine. The IDs will be the same across all Windows machine regardless of OS language settings and will not be localized. Whereas, TimeZone2.DisplayName is a localized label of the TimeZone2 object. To help you find the “Time Zone Ids”, here is a table of Time Zone Ids and the locations they cover:

- Alphabetically sorted by “Time Zone Ids”

- Sorted by Offsets

The new TimeZone2 class can also allow developers to create their own TimeZone2 objects, compare two TimeZone2 objects, serialize the TimeZone2 object into a string and deserialize a string back to a TimeZone2 object. Since these are more advance features, I will cover them at a later date. I hope this set of examples will help you get started on using TimeZone2!

Note:

1) TimeZone2 resides in System.Core.dll. You can find this DLL in “C:\WINDOWS\Microsoft.NET\Framework\v3.5.60905”.

<Shameless Advertizing>

Check out my blog https://blogs.msdn.com/kathykam for more discussion of this new class, usage of the advance features and the design principles that I picked up from working on it!

<\Shameless Advertizing>