CS Dev Guide: Time Zone : CSharp Feeds

CS Dev Guide: Time Zone

by Keyvan Nayyeri via Keyvan Nayyeri on 1/29/2007 12:30:18 PM

For many people around the world time zone doesn't matter at all. For some people it's important for their jobs and business but for developers it's just a pain! I can remember many situations that I've gotten in trouble with time zones myself. Two times (before release of Community Server 2.0 and launching BlogMailr) I had some conversations with Ken about them and it's still a big problem for software developers. Many users ask about the lack of their local time zone in Community Server and hopefully they can get their answer in all details after reading this post. I see some posts with my eyes where some users thought that Telligent is encouraging racism and were asking for their time zones to be included in list.

In this CS Dev Guide post I want to talk about time zones in Community Server APIs but before that I'll give short introduction to some concepts that you will see. I'm sure you know all details about time zone in general but we needs some details to be able to calculate local and universal time and convert them to each other in programming.

Background

A time zone is an area that gets a specific time based on its distance from Greenwich in England. Greenwich time is also known as UTC for you. Each area in our world gets a local time based on its distance. For example +1:00 hour, +2:00 hours, -6:00 hours and so on. Greenwich is a source for calculations so we'll be able to have different times wherever we live and find others times using some basic mathematic calculations.

Ok, stop, this is very simple, what's the problem? The trouble is with something known as daylight saving time. In many countries governments change their local time on specific dates and add or subtract one hour from their local time. There are economic benefits in doing this thing. But as there isn't any standard for daylight savings then each government has its own rules for daylight savings. And also in some modern countries some bright persons (who love tomato) suddenly decide to avoid doing this (got it?!!). However, difference comes from daylight saving and I haven't seen a good solution for it except using a webservice.

Time Zones in Community Server

Let's follow this story in Community Server ...

In Community Server we have a list of pre-defined time zones but this list doesn't include all zones. It only contains time zones with integer values so for example you have a time zone for +4:00 but don't have a time zone for +4:30. It's possible to add any new time zone to this list but as you'll see later, restriction for time zone values won't be solved unless the team changes the core code. For each time zone we have some information that helps us to calculate local and universal time and convert a DateTime value from one time zone to another. Community Server stores these information both for normal and daylight times to be able to do its calculations easier. It stores a name for each time zone for both cases as well as a bias for each case. There is also a general name for each time zone.

Alright, let's get in more technical details.

Three classes and one enumeration in CommunityServer.Components play all roles about managing time zones in Community Server:

TimeZoneArea is an enumeration of all available time zones in Community Server. It's used in other classes.
TimeZoneInternational is a class to represent a time zone in Community Server APIs.
TimeZoneInternationalCollection is a collection class to keep the list of available time zones in Community Server.
TimeZoneInternationalManager is another class that helps you to work with time zones.

You know that in Community Server most (or all?!) DateTime values will be shown to ends users based on the time zone that they have chosen in their profiles. Community Server also gets the time zone for server to do its calculations. Therefore above classes are very important for the power of Community Server in DateTime calculations.

TimeZoneArea

This enumeration simply lists all available time zone areas in Community Server to help to work with them easier.

TimeZoneInternational

This class is derived from System.TimeZone class in .NET Framework and does the main job around time zones. Community Server hasn't added many new things to .NET TimeZone object but I'll describe its properties and methods anyway. It has six properties (regarding what I wrote in background):

DaylightBias: An integer value of bias for daylight time.
DaylightName: String value of time zone name for daylight time.
DisplayName: String value of time zone name. This is what end users see as the name of time zone.
StandardBias: An integer value of bias for standard time.
StandardName: String value of time zone name for standard time.
TimeZoneArea: A corresponding TimeZoneArea enumeration value.

You see that DaylighBias and StandardBias are both integer properties so Community Server doesn't support any double values for time zones and this is the answer to a common question about Community Server. I hope that we see good changes around time zones in Calypso.

It also has five methods:

GetDaylightChanges: Gets an integer as a year and returns a System.Globalization.DaylightTime object which represents the daylight changes for that year. DaylightTime provides three properties for daylight changes: start and end date of daylight saving changes and TimeSpan of changes.
GetUtcOffset: Gets a DateTime value of local time (for current TimeZoneInternational object) and returns a TimeSpan of difference between UTC time and local time.
IsDaylightSavingTime: Get a DateTime value of local time and checks if it's time for daylight saving.
ToLocalTime: It has two overloads and converts a DateTime value from UTC or other time zones to local time zone.
ToUniversalTime: Gets a DateTime value based on local time and converts it to universal time.

TimeZoneInternationalCollection

This class is actually a collection for TimeZoneIntrernational objects so has some common methods and properties to work with collections. You can add or remove a TimeZoneInternational object to or from it or iterate through its items.

TimeZoneInternationalManager

This class is as simple as one property and one method. TimeZones is a ReadOnly property that returns a TimeZoneInternationalCollection of all available time zones in application. GetTimeZone() gets a TimeZoneArea enumeration value and returns its corresponding TimeZoneInternational object.

Examples

You know it's possible to write many good examples about time zones but I only write two examples to demonstrate some basic principles and you can find your thread to follow.

In GetAllLocalTimes() method below I use TimeZoneInternationalManager to get a TimeZoneInternationalCollection of all available TimeZoneInternational objects then use server time to calculate current time in all these areas then return a Hashtable of time zone names and DateTime value of current time for them.

Hashtable GetAllLocalTimes()
{
    DateTime serverTime = UserTime.CurrentServerTime;
 
    Hashtable results = new Hashtable();
 
    TimeZoneInternationalCollection zones =
        TimeZoneInternationalManager.TimeZones;
    foreach (TimeZoneInternational zone in zones)
    {
        results.Add(zone.DisplayName, zone.ToLocalTime(serverTime));
    }
    return results;
}

In GetLocalTimeInWestAustralia() I use TimeZoneInternationalManager to get a TimeZoneInternational object for West Australia then return a DateTime value of current local time there.

DateTime GetLocalTimeInWestAustralia()
{
    DateTime serverTime = UserTime.CurrentServerTime;
 
    TimeZoneInternational localZone = TimeZoneInternationalManager.GetTimeZone
        (TimeZoneArea.WestAustraliaStandardTime);
 
    return localZone.ToLocalTime(serverTime);
}