Export (0) Print
Expand All

TimeZoneInfo.ConvertTime Method (DateTimeOffset, TimeZoneInfo)

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

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

'Declaration
Public Shared Function ConvertTime ( _
	dateTimeOffset As DateTimeOffset, _
	destinationTimeZone As TimeZoneInfo _
) As DateTimeOffset

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
The date and time in the destination time zone.

ExceptionCondition
ArgumentNullException

The value of the destinationTimeZone parameter is Nothing.

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.

Notes to Callers

On Windows XP systems, this method applies only the current adjustment rule to the time zone conversion if dateTimeOffset is treated as a local time or if destinationTimeZone is TimeZoneInfo.Local. As a result, the method may not accurately convert times for periods before the current adjustment rule came into effect. For more information, see the Notes for Callers section in the Local property.

The following example converts an array of DateTimeOffset values to times in the Eastern Time zone of the U.S. and Canada. It illustrates that the ConvertTime method takes time zone adjustments into account, because a time zone adjustment occurs in both the source and destination time zones at 2:00 A.M. on November 7, 2010.


Module Example
   Public Sub Main()
      ' Define times to be converted.
      Dim time1 As Date = #1/1/2010 12:01AM#
      Dim time2 As Date = #11/6/2010 11:30PM#
      Dim times() As DateTimeOffset = { 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).
      Dim est As TimeZoneInfo 
      Try
         est = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time")
      Catch e As TimeZoneNotFoundException
         Console.WriteLine("Unable to retrieve the Eastern Standard time zone.")
         Exit Sub
      Catch e As InvalidTimeZoneException
         Console.WriteLine("Unable to retrieve the Eastern Standard time zone.")
         Exit Sub
      End Try   

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

      ' Convert each time in the array.
      For Each timeToConvert As DateTimeOffset In times
         Dim targetTime As DateTimeOffset = TimeZoneInfo.ConvertTime(timeToConvert, est)
         Console.WriteLine("Converted {0} to {1}.", timeToConvert, targetTime)
      Next                        
   End Sub
End Module
' 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.


.NET Framework

Supported in: 4, 3.5

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

Community Additions

ADD
Show:
© 2014 Microsoft