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”
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>
Comments
Anonymous
October 03, 2006
I have posted my starter guide on the BCL team blog ! I'll post a follow up and advance usage here. :)Anonymous
October 03, 2006
While I agree that this functionality is needed, I'm disappointed in both the name of the class and the namespace it was put in.Since System.TimeZone is taken, why not just create a System.Globalization.TimeZone and mark the original one obsolete?Do we need to be polluting the System namespace any more? Also, do we really want to resort to the class numbering? That's worse than "TimeZoneEx."Anonymous
October 03, 2006
The comment has been removedAnonymous
October 03, 2006
I like this new functionality, but I am also very disappointed by the name change, too. If the .NET Design Guidelines require that, you should change them (after all Microsoft wrote them...). Adding a numeric suffix to the class tells you nothing about the differences between the two classes and is very confusing. What happens if you make another change to the TimeZone class, do we have TimeZone, TimeZone2 and TimeZone3 then? And if the original TimeZone class is finally removed, we are stuck with a TimeZone2 class and nobody knows why it is not simply called TimeZone.Couldn't you simply add the new members to the existing TimeZone class?If there is really no way to replace the existing class/name, I would still prefer putting the class in another namespace or giving it a more meaningful name like ExtendedTimeZone (I am sure you can come up with an even better name).Thanks for listening!Thomas KrauseAnonymous
October 03, 2006
Thanks Thomas, we actually have the guideline of using numeric suffixes to new types when we expect previous versions will become entirely superseded by new types - and we like the guidance. The reason is in these cases, we do not want the difference between types to be ambiguous. Having a numeric specifier means "only use the newer type from here out." If we called it something like TimeZoneWithConversion, users may decide to use the original TimeZone class in scenarios where they do not plan on doing conversions, but that is not our intent for users with the type.FYI The "EX" suffix is particularly problematic because then it becomes even more ugly to ship a third type in the rare case that is required.Anonymous
October 03, 2006
Can't say I like the design. Why TimeZone2.Convert...(timeZone, dateTime) and not timeZone.Convert...(dateTime)?Further more, until this very moment, you're still holding out on the redesign of TimeZone2. I don't see anything that couldn't be done with TimeZone. Heck, several people (including me), already implemented these features based on the appropriate registry keys using the original TimeZone class.Or, is the real case you've implemented TimeZone2 (in System.Core.dll rather than System.dll), because you can't touch System.dll? I've seen the term "Red bits" several times, and that Orcas would a .NET 2.0 extension, not upgrade. That would explain a lot, but I'd still like TimeZone2 to be an extension of TimeZone.Anonymous
October 03, 2006
Hi Ruben,timeZone.Convert is ambiguous as to whether you are converting to or from. We decided tat having it as a static method is more clear.After much consideration, we've determined that updating TimeZone would cause too much breaking changes because of the Vista Dynamic Time Zone support. APIs like "GetUtcOffset" and "IsDaylightSavingTime" works on a totally different logic.Thanks,KathyAnonymous
October 03, 2006
The comment has been removedAnonymous
October 03, 2006
Not that this is a great example...X509certificate2http://msdn2.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509certificate2.aspxAnonymous
October 03, 2006
Didn't I say it two weeks ago that API naming is the most difficult thing? :) My BCL post on System.TimeZone2Anonymous
October 03, 2006
I have not looked at the documentation for TimeZone2 yet, so I do not know how much these overlap. If you are replacing TimeZone, then how about making both TimeZone and TimeZone2 derive from the same interface (ITimeZone). That way it will be easier to move current code to the new TimeZone2.[Off topic]I am still very unhappy about DateTime. I would like to write my own replacement. Would you please either... 1) Provide an IDateTime (and update methods to the new signature), or 2) Unseal DateTimeAnonymous
October 04, 2006
The comment has been removedAnonymous
October 04, 2006
Kathy Kam asked for feedback on Timezone2, so tonight I decided to have a bit of a play and these areAnonymous
October 04, 2006
The complete quote from the Framework Design Guidelines is:"Do use a numeric suffix to indicate a new version of an existing API if the existing name of the API is the only name that makes sense (i.e., it is an industry standard), and adding any meaningful suffix (or changing the name) is not an appropriate option."So there is no requirement to add a numeric suffix if you can add a "meaningful" suffix or change the name.Anonymous
October 04, 2006
What about this?http://www.twinsun.com/tz/tz-link.htmBasing the internals off of the Windows registry makes sense, as most likely the software will be running on Windows. But TZ does so much more. Is the BCL team even aware of TZ and what it does? And if so, why not match the functionality? TimeZone's are a part of the BCL because people should be able to rely upon them with 100% certainty that they do everything they might need them to do. TimeZone didn't come close, and from what I've read so far, TimeZone2 still doesn't get the job done.Anonymous
October 04, 2006
The comment has been removedAnonymous
October 04, 2006
@BigJimInDC: I've asked a number of times about tz (not just Kathy), but each and every time MS has carefully sidestepped those questions.Anonymous
October 06, 2006
I'd just like to add my 5 cents in the naming discussion; TimeZone2 is just bad naming!Moving it into another namespace is a bit better, but not really, that's just hiding the problem...The best way, as far as I can see, would be to add the changes to the existing TimeZone class.Any breaking changes; fine! We'll deal with that, as we've dealt with similar issues in the past!And yes, an Ex suffix is even worse that a number suffix... Imagine a versjon 8 of TimeZone in 2024;TimeZoneExExExExExExExEx tz = ...Not pretty! :)But the feature set looks nice! I'll have to get my ol' test PC up and running again and have ago at it! :)Cheers,Jarle NygårdAnonymous
October 06, 2006
Good to see this functionality coming in, though I am more concerned, like many people, with the DateTime issues relating to timezones. I hope the design of this class has been done with that in mind.Anonymous
October 06, 2006
There is an interesting discussion on the BCL blog about a new BCL type called TimeZone2. Just take aAnonymous
October 06, 2006
There is an interesting discussion on the BCL blog about a new BCL type called TimeZone2. Just take aAnonymous
October 06, 2006
Hi, this thread is great. Lots of passion. Which can only make the Framework better. Thanks for getting involved!I am responsible for the design guidelines, so I thought I would provide some explanation and a call to action!:-)You can read it at http://blogs.msdn.com/kcwalina/archive/2006/10/06/TimeZone2Naming.aspxAnonymous
October 06, 2006
Right now, there is no easy way to convert a time from one arbitrary timezone to another arbitrary timezoneAnonymous
October 06, 2006
Taking two steps forward without taking any backAnonymous
October 07, 2006
IMO, the class doesn't actually represent a timezone; it represents a rule that applies to a timezone. As an immediate example, if you get "Pacific Time (U.S. and Canada)" from the registry today, you'll have the rules that apply right now in Los Angeles. But these are not the rules that apply in L.A. starting next March, nor are they the rules that applied in L.A. before April 1986. In other words, either IsDaylightTime(2007, 3, 16) will return false (which is incorrect) or IsDaylightTime(2006, 11, 1) will return true (which is also incorrect).I think you really need to take a look Arthur Olsen's work at NIH, since he's really the go-to person for timezones. See, e.g., ftp://ftp.elsie.nih.gov/Pub/ for the latest tzcode file, and read the theory document.Anonymous
October 08, 2006
Hi David,Actually, in Vista, if you get "Pacific Time(U.S. and Canada)", the TimeZone2 object we fill has all the rules of the Pacific time zone, not just the current one. This is part of the "Dynamic Time Zone support", I have been talking aobut. Therefore IsDaylightTime(2007, 3, 16) will return true. IsDaylightTime(2006, 3, 16) will return false.Thanks, KathyAnonymous
October 09, 2006
Please, since this is just a rehash of the registry, use the Index value for ID rather than Key name. It is much friendlier to data storage!Anonymous
October 09, 2006
HI Michael,It is interesting you brought this up. I was just on a thread with the Windows team about the fact that Vista has deprecated this "index" value.Thanks, KathyAnonymous
October 09, 2006
I prefer key names as they are more descriptive than an index value. However, you could have the best of both worlds by creating an enumeration that specifies all of the valid key names. How about an overload that takes such an enumeration?Anonymous
October 10, 2006
You say "Hi, this thread is great. Lots of passion. Which can only make the Framework better. Thanks for getting involved!I am responsible for the design guidelines, so I thought I would provide some explanation and a call to action!:-)"But you are not listening to the majority of customers that are telling you the guideline is flat out wrong. You don't need to look much further than MSHTML to see why this is wrong.In all likelihood, TimeZone was probably very rarely used anyway because it was virtually useless. Obsolete it and move it to System.Globalization.Anonymous
October 10, 2006
I noticed a good debate going on the BCL blog (and now Krzysztof Cwalina’s blog) about the naming ofAnonymous
October 10, 2006
Ever since Kathy Kam announced on her weblog that a new type named TimeZone2 will be introduced intoAnonymous
October 12, 2006
First off, guidelines are only guidelines. In this case, not a single consumer of the API is at all happy with the name. You are developing a product and that product will not be well accepted by your consumers. Change the name simply because we want you to change it. Ignore the guidelines to make your customers happy.Anonymous
October 12, 2006
As a customer, I am unhappy with the design of the type. I wish Microsoft would either 1) unseal TimeZone / TimeZone2 and DateTime or 2) create an ITimeZone and IDateTime so that I can replace the types. The interface option is more difficult because existing signatures would have to be changed to take advantage of it. I would replace it either way, so I do not mind what it is called.Anonymous
October 12, 2006
Actually, I'm just happy that this functionality is going to be provided at last (you could call it "Julie" for all I care). Is this going to be part of ... .NET 3.5? or will it be included in .NET 3.0 for Vista?Anonymous
October 13, 2006
Great to see some movement on the Timezone class. Unfortunately there is still no support for timezones that: a) Change UTC offset from year to year b) Change Daylight savings offset from year to year (e.g. the Australian timezones in April of 2006, and the American timezones next year will extend the daylight savings into November). A previous Microsoft approach has been to create newly named timezones for when things change but this caused a litany of problems for users. A timezone for e.g. "(GMT-08:00) Pacific Time (US & Canada); Tijuana" should represent the timezone of the user for 2006 and 2007 regardless of whether the daylight savings calculation is different from 2006 and 2007. This would require storing a set of daylight saving calculations for each every time it changes, rather than a single fixed calculation as per the Windows registry, but it's the only way to get it right!Anonymous
October 13, 2006
Aha! I see now that Vista will have support for exactly what I was talking about in my previous post: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sysinfo/base/dynamic_time_zone_information.aspAnonymous
October 14, 2006
Hi Kevin, It will be part of .NET Framework 3.5 Thanks,KathyAnonymous
October 14, 2006
Hi David, We do have customers who likes the naming. Of course we will take all of your feedback into account. Thanks, KathyAnonymous
October 14, 2006
Hi Chronos, We sealed the class because the internals are quite complicated. We did not want users to accidentally corrupt it. Regarding your feature request "ITimeZone" or "IDateTime", we will defintiely look into it in our next release. Thank you, KathyAnonymous
October 14, 2006
Hi Hugh, Yes, the new TimeZone2 class will support everything the Vista Dynamic Time Zone API supports. So we will have support for a) Change UTC offset from year to year b) Change Daylight savings offset from year to year (e.g. the Australian timezones in April of 2006, and the American timezones next year will extend the daylight savings into November). Thanks, KathyAnonymous
October 15, 2006
Kathy wrote: "We sealed the class because the internals are quite complicated. We did not want users to accidentally corrupt it." I do not mean to be rude, but I truly find this reasoning flawed. Typically, types are sealed to 1) promote optimization, or 2) control by ensuring that there never can be a replacement (such as System.String). Option 1 is really an excuse when the problem is with the runtime. Hopefully inlining will be improved with future releases. The Java runtime has been making great progress in this area lately. However, if you will consider an interface for a sealed type, then what does it matter how complicated the internals are? As a developer, it is my type to create (extend). Any type can be corrupted during development. Fixing bugs are part of a developers job. But by sealing it, I do not even have a chance to extend it. I am forced to use it as it is. That does not seem right to me.Anonymous
October 15, 2006
Maybe I missed something in the discussion, but it seems like the main argument against making this a breaking change is that you intend to deploy this as a replacement, not as another SxS, thereby breaking released code. (http://blogs.msdn.com/kcwalina/archive/2006/10/06/TimeZone2Naming.aspx). If this was not the case, you'd more seriously consider making a breaking change by either replacing the original TimeZone class, or maybe moving it out of the System namespace, or ...? In a nutshell, your deployment decisions are driving the design of your naming guidelines. Correct? Does that seem as backwards to you as it does to me? I'd rather you postpone introducting the new TimeZone class (named "TimeZone" not "TimeZone2") into the next version number, so that it will be keep that name that for software developed for the next 15 years, rather than make us live with a name that you couldn't do because of the way you wanted to distribute the bits.Anonymous
October 16, 2006
First and foremost I want to reiterate that I'm glad better timezone support is being added. We've all been asking for this for a long time. But I'd hate to see it messed up in this iteration and be forced to use a TimeZone3 to finally get it right (hey, third time's a charm). I still don't see why this has to be in the System namespace. Worse yet, it's not even in mscorlib.dll or System.dll, which means that when I want to use it I have to try to remember what library it's in. I think the System namespace needs to be frozen very soon, with very few exceptions. Consider putting it in a System.Core, System.Time or maybe System.Temporal namespace. Along with it you can add a time+timezone class/struct that's easily (maybe implicitly) convertible to a UTC DateTime. It's a shame there's no way to simultaneously obsolete a class and create a new one with the same name. I can think of possible ways to add this kind of support to the runtime (similar to type-forwarding), but documentation could be a nightmare. I also agree that the new TimeZone shouldn't be a sealed class. (I'm not going to say that DateTime should be unsealed because it's a value type). We should be able to create new timezones with pure managed code. The system time zones could be an internal sealed SystemTimeZone class that makes all the complicated calls to Vista's new APIs. Granted, sealing it probably makes serialization easier since you don't have to worry about custom timezones on the other end of the wire. How does that work, anyway? What if you serialize a Vista time zone and send it to a Windows 2000 machine? Is the data from the registry actually serialized as well? Could we use Vista timezones on 2000 simply by remoting a Vista server? That seems both cool and silly at the same time! (I got an idea for a web service!!) I'll admit the current System.TimeZone class is a complete mess. It's difficult to tell which methods should be overriden to do what, but I've had luck in creating timezones for everything from simple UTC offsets to historical timezones based on open-source timezone data.Anonymous
October 17, 2006
Hi Chronos, My bad... what I meant to say was "We made the class immutable because the internals are quite complicated. We did not want users to accidentally corrupt it. " Which totally didn't answer your question. That's what I get for trying to reply blog comments at 2am on a Sunday! :P Regarding why we sealed the class. That's more of a cost/benefit analysis on what we'd like to deliver in the Orcas time frame. I know that's not the best reason out there. Every feature (including unsealing a class) cost an amount of resources. There is an opportunity cost to every decision. We cut that "feature" because there are other features for the Orcas timeframe we have prioritized higher. In the next CTP, you'll get to see what other features the BCL team has come up with! Stay tuned! Thanks, KathyAnonymous
October 17, 2006
Hi Alan, Actually, Krzsyztof's statement is a little misleading. He is correct that we'll never have a breaking change in a service pack. "Changing TimeZone APIs in Orcas would amount to breaking applications in a service pack. This is a big no-no" However, that doesn't mean we're adding a new type just because this is a service pack / in-place release. If it boils down to just that question. We would have waited a release and did a red-bits changed. You are correct, deployment strategy driving our framework design is bad news all around. However, in this case, it was different. After some investigation, we decided that we would have added a new type even if we are allow to modify mscorelib.dll. I discuss this indepth here: http://blogs.msdn.com/kathykam/archive/2006/10/03/Designing-System.TimeZone2-2D00-Part-1-2800_API-naming-and-new-class-or-not_2900-.aspx Thanks, KathyAnonymous
October 17, 2006
Hi TheMuuj, We plan on posting something about serialization and other more advance samples on the new TimeZone2 class. Keep checking back~ Cheers, KathyAnonymous
October 31, 2006
Let me first start by saying I applaud your efforts. The application that I'm currently working on is 1 million+ lines of .Net 1.1 code (moving to 2.0 this winter). I was dismayed when I saw how little support there was for TimeZone manipulation in 1.1 One of the parts of the application uses a time based concurrency model to collect data from multiple sources that may be in different time zones. To get around the timezone short coming we wrapped the already functional Win32 TIME_ZONE_INFORMATION and used a combination of UTC/Local time conversions with System.Time to pull it off. My first reaction to the TimeZone2 addition was an explitive, but after seeing the direction layed out I'm glad to see that better judgement is prevailing. If this is followed in other cases similar to this I will be pleased. (and as far as the naming goes, myself, and hopefully most of the sane people would rather have a numeric suffix than a whole different name)Anonymous
February 15, 2007
Незабаром в нас буде нова версія .Net Framework 3.5, яка схоже, як і 3.0, буде спиратися на базовий .NetAnonymous
February 27, 2007
"The .NET framework is awesome." That has been my position for a few years now and probably will be forAnonymous
June 07, 2007
The main feature of the System.TimeZoneInfo class (previously named System.TimeZone2 in CTPs prior toAnonymous
August 08, 2007
While installing VisualStudio 2008 Beta2 I was surprised that the NET framework 2.0 installation gotAnonymous
November 14, 2007
Sounds like a book title, doesn't it? It's a horror story. Currently, I'm using a class libraryAnonymous
November 19, 2007
.NET Framework 3.5 and Visual Studio 2008 have officially shipped! Soma has the announcement on his blogAnonymous
December 05, 2007
If you are following blogs about .net 3.5 you might have across this interesting post . It explains theAnonymous
February 06, 2008
If you are following blogs about .net 3.5 you might have across this interesting post . It explains theAnonymous
February 06, 2008
If you are following blogs about .net 3.5 you might have across this interesting post . It explains the