This documentation is archived and is not being maintained.

TimeZoneInfo.ConvertTime Method (DateTimeOffset, 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 DateTimeOffset ConvertTime(
	DateTimeOffset dateTimeOffset,
	TimeZoneInfo destinationTimeZone
)

Parameters

dateTimeOffset
Type: System.DateTimeOffset

The date and time to convert.

destinationTimeZone
Type: System.TimeZoneInfo

The time zone to convert dateTime to.

Return Value

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

ExceptionCondition
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 differs from the other overloads of the ConvertTime method by accepting a DateTimeOffset value as its first parameter. This identifies the date and time as an offset from Coordinated Universal Time (UTC) rather than as the date and time in a particular time zone. As a result, the dateTimeOffset parameter cannot represent either an ambiguous time or an invalid time.

In converting the dateTimeOffset value to the time in the destination time zone, this method takes into account any adjustment rules in effect in the destination time zone.

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

The following example converts an array of DateTimeOffset values to times in the Eastern Standard Time zone of the United States and Canada. It 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 time1 = new DateTime(2010, 1, 1, 12, 1, 0);
      DateTime time2 = new DateTime(2010, 11, 6, 23, 30, 0);
      DateTimeOffset[] times = { new DateTimeOffset(time1, TimeZoneInfo.Local.GetUtcOffset(time1)),
                                 new DateTimeOffset(time1, TimeSpan.Zero),
                                 new DateTimeOffset(time2, TimeZoneInfo.Local.GetUtcOffset(time2)),
                                 new DateTimeOffset(time2.AddHours(3), TimeZoneInfo.Local.GetUtcOffset(time2.AddHours(3))) };

      // 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 (DateTimeOffset timeToConvert in times)
      {
         DateTimeOffset targetTime = TimeZoneInfo.ConvertTime(timeToConvert, est);
         Console.WriteLine("Converted {0} to {1}.", timeToConvert, 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 -08:00 to 1/1/2010 3:01:00 AM -05:00. 
//    Converted 1/1/2010 12:01:00 AM +00:00 to 12/31/2009 7:01:00 PM -05:00. 
//    Converted 11/6/2010 11:30:00 PM -07:00 to 11/7/2010 1:30:00 AM -05:00. 
//    Converted 11/7/2010 2:30:00 AM -08:00 to 11/7/2010 5:30:00 AM -05:00.

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: