This documentation is archived and is not being maintained.

TimeZoneInfo.ConvertTime Method (DateTime, TimeZoneInfo)

Updated: August 2009

Converts a time to the time in a particular time zone.

Namespace:  System
Assembly:  System.Core (in System.Core.dll)

public static DateTime ConvertTime(
	DateTime dateTime,
	TimeZoneInfo destinationTimeZone
)

Parameters

dateTime
Type: System.DateTime

The date and time to convert.

destinationTimeZone
Type: System.TimeZoneInfo

The time zone to convert dateTime to.

Return Value

Type: System.DateTime
A DateTime value that represents the date and time in the destination time zone.

ExceptionCondition
ArgumentException

The value of the dateTime parameter represents an invalid time.

ArgumentNullException

The value of the destinationTimeZone parameter is null.

When performing the conversion, the ConvertTime(DateTimeOffset, TimeZoneInfo) method applies any adjustment rules in effect in the destinationTimeZone time zone.

This overload determines the source time zone from the value of the dateTime parameter's Kind property, as the following table shows.

Kind property value

Source time zone

Method behavior

DateTimeKind.Local

Local

Converts the local time to the time in destinationTimeZone.

DateTimeKind.Utc

Utc

Converts Coordinated Universal Time (UTC) to the time in destinationTimeZone.

DateTimeKind.Unspecified

Assumed to be Local.

Converts the local time to the time in destinationTimeZone.

The Kind property of the returned DateTime value is set as shown in the following table.

Condition

Returned Kind property value

The destinationTimeZone parameter is TimeZoneInfo.Utc.

DateTimeKind.Utc

The Kind property of dateTime is DateTimeKind.Local and destinationTimeZone is DateTimeKind.Local.

DateTimeKind.Local

All other date and time values and destination time zones.

DateTimeKind.Unspecified

If the value of the dateTime parameter is an ambiguous local time, it is interpreted as a standard time. If the dateTime parameter is an invalid local time, this method throws an ArgumentException.

If the conversion of dateTime results in a date and time value that is earlier than DateTime.MinValue or later than DateTime.MaxValue, this method returns DateTime.MinValue or DateTime.MaxValue, respectively.

You can also convert to or from UTC by calling the ConvertTimeFromUtc and ConvertTimeToUtc methods.

The following example converts an array of date and time values to times in the Eastern Standard Time zone of the United States and Canada. It shows that the source time zone depends on the DateTime.Kind property of the source DateTime value. It also illustrates that the ConvertTime method takes time zone adjustments into account, since a time zone adjustment occurs in both the source and destination time zones at 2:00 A.M. on November 7, 2010.

using System;

public class Example
{
   public static void Main()
   {
      // Define times to be converted.
      DateTime[] times = { new DateTime(2010, 1, 1, 0, 1, 0), 
                           new DateTime(2010, 1, 1, 0, 1, 0, DateTimeKind.Utc), 
                           new DateTime(2010, 1, 1, 0, 1, 0, DateTimeKind.Local),                            
                           new DateTime(2010, 11, 6, 23, 30, 0),
                           new DateTime(2010, 11, 7, 2, 30, 0) };

      // Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
      TimeZoneInfo est; 
      try {
         est = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");
      }
      catch (TimeZoneNotFoundException) {
         Console.WriteLine("Unable to retrieve the Eastern Standard time zone.");
         return;
      }
      catch (InvalidTimeZoneException) {
         Console.WriteLine("Unable to retrieve the Eastern Standard time zone.");
         return;
      }   

      // Display the current time zone name.
      Console.WriteLine("Local time zone: {0}\n", TimeZoneInfo.Local.DisplayName);

      // Convert each time in the array. 
      foreach (DateTime timeToConvert in times)
      {
         DateTime targetTime = TimeZoneInfo.ConvertTime(timeToConvert, est);
         Console.WriteLine("Converted {0} {1} to {2}.", timeToConvert, 
                           timeToConvert.Kind, targetTime);
      }                        
   }
}
// The example displays the following output: 
//    Local time zone: (GMT-08:00) Pacific Time (US & Canada) 
//     
//    Converted 1/1/2010 12:01:00 AM Unspecified to 1/1/2010 3:01:00 AM. 
//    Converted 1/1/2010 12:01:00 AM Utc to 12/31/2009 7:01:00 PM. 
//    Converted 1/1/2010 12:01:00 AM Local to 1/1/2010 3:01:00 AM. 
//    Converted 11/6/2010 11:30:00 PM Unspecified to 11/7/2010 1:30:00 AM. 
//    Converted 11/7/2010 2:30:00 AM Unspecified to 11/7/2010 5:30:00 AM.

Windows 7, Windows Vista, Windows XP SP2, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5

Date

History

Reason

August 2009

Added an example.

Customer feedback.

Show: