TimeZoneInfo.ConvertTime Method (DateTime, TimeZoneInfo, TimeZoneInfo) (System)

ConvertTime Method (DateTime, TimeZ...

Collapse All

Language Filter

.NET Framework Class Library

TimeZoneInfo..::.ConvertTime Method (DateTime, TimeZoneInfo, TimeZoneInfo)

Updated: November 2007

Converts a time from one time zone to another.

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

Syntax

Visual Basic (Declaration)

Public Shared Function ConvertTime ( _
    dateTime As DateTime, _
    sourceTimeZone As TimeZoneInfo, _
    destinationTimeZone As TimeZoneInfo _
) As DateTime

Visual Basic (Usage)

Dim dateTime As DateTime
Dim sourceTimeZone As TimeZoneInfo
Dim destinationTimeZone As TimeZoneInfo
Dim returnValue As DateTime

returnValue = TimeZoneInfo.ConvertTime(dateTime, _
    sourceTimeZone, destinationTimeZone)

public static DateTime ConvertTime(
    DateTime dateTime,
    TimeZoneInfo sourceTimeZone,
    TimeZoneInfo destinationTimeZone
)

Visual C++

public:
static DateTime ConvertTime(
    DateTime dateTime, 
    TimeZoneInfo^ sourceTimeZone, 
    TimeZoneInfo^ destinationTimeZone
)

public static DateTime ConvertTime(
    DateTime dateTime,
    TimeZoneInfo sourceTimeZone,
    TimeZoneInfo destinationTimeZone
)

JScript

public static function ConvertTime(
    dateTime : DateTime, 
    sourceTimeZone : TimeZoneInfo, 
    destinationTimeZone : TimeZoneInfo
) : DateTime

Parameters

dateTime: Type: System..::.DateTime
The date and time to convert.

sourceTimeZone: Type: System..::.TimeZoneInfo
The time zone of dateTime.

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 that corresponds to the dateTime parameter in the source time zone.

Exceptions

Exception	Condition
ArgumentException	The Kind property of the dateTime parameter is DateTimeKind..::.Local, but the sourceTimeZone parameter does not equal DateTimeKind..::.Local. -or- The Kind property of the dateTime parameter is DateTimeKind..::.Utc, but the sourceTimeZone parameter does not equal TimeZoneInfo..::.Utc. -or- The dateTime parameter is an invalid time (that is, it represents a time that does not exist because of a time zone's adjustment rules).
ArgumentNullException	The sourceTimeZone parameter is nullNothingnullptra null reference (Nothing in Visual Basic). -or- The destinationTimeZone parameter is nullNothingnullptra null reference (Nothing in Visual Basic).

Exception

Condition

ArgumentException

The Kind property of the dateTime parameter is DateTimeKind..::.Local, but the sourceTimeZone parameter does not equal DateTimeKind..::.Local.

-or-

The Kind property of the dateTime parameter is DateTimeKind..::.Utc, but the sourceTimeZone parameter does not equal TimeZoneInfo..::.Utc.

-or-

The dateTime parameter is an invalid time (that is, it represents a time that does not exist because of a time zone's adjustment rules).

ArgumentNullException

The sourceTimeZone parameter is nullNothingnullptra null reference (Nothing in Visual Basic).

-or-

The destinationTimeZone parameter is nullNothingnullptra null reference (Nothing in Visual Basic).

Remarks

The value of the Kind property of the dateTime parameter must correspond to the sourceTimeZone parameter, as the following table shows.

DateTime.Kind value	sourceTimeZone value	Method behavior
DateTimeKind..::.Utc	Equals TimeZoneInfo..::.Utc.	Converts dateTime to the destination time zone's time.
DateTimeKind..::.Utc	Does not equal TimeZoneInfo..::.Utc.	Throws an ArgumentException.
DateTimeKind..::.Local	Equals TimeZoneInfo..::.Local.	Converts dateTime to the destination time zone's time.
DateTimeKind..::.Local	Does not equal TimeZoneInfo..::.Local.	Throws an ArgumentException.
DateTimeKind..::.Unspecified	Any.	Converts dateTime to the destination time zone's time.

You can also convert to or from Coordinated Universal Time (UTC) by calling the ConvertTimeFromUtc and ConvertTimeToUtc methods.

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 both sourceTimeZone and destinationTimeZone are DateTimeKind..::.Local.	DateTimeKind..::.Local
All other date and time values, source time zones, and destination time zones.	DateTimeKind..::.Unspecified

If the value of the dateTime parameter is an ambiguous time in the source time zone, it is interpreted as a standard time. If the dateTime parameter is an invalid time in the source time zone, 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.

Examples

The following example illustrates the use of the ConvertTime(DateTime, TimeZoneInfo, TimeZoneInfo) method to convert from Hawaiian Standard Time to local time.

Visual Basic

Dim hwTime As Date = #2/01/2007 8:00:00 AM#
Try
   Dim hwZone As TimeZoneInfo = TimeZoneInfo.FindSystemTimeZoneById("Hawaiian Standard Time")
   Console.WriteLine("{0} {1} is {2} local time.", _
                     hwTime, _
                     IIf(hwZone.IsDaylightSavingTime(hwTime), hwZone.DaylightName, hwZone.StandardName), _
                     TimeZoneInfo.ConvertTime(hwTime, hwZone, TimeZoneInfo.Local))
Catch e As TimeZoneNotFoundException
   Console.WriteLine("The registry does not define the Hawaiian Standard Time zone.")
Catch e As InvalidTimeZoneException
   Console.WriteLine("Registry data on the Hawaiian Standard Time zone has been corrupted.")
End Try

DateTime hwTime = new DateTime(2007, 02, 01, 08, 00, 00);
try
{
   TimeZoneInfo hwZone = TimeZoneInfo.FindSystemTimeZoneById("Hawaiian Standard Time");
   Console.WriteLine("{0} {1} is {2} local time.", 
           hwTime, 
           hwZone.IsDaylightSavingTime(hwTime) ? hwZone.DaylightName : hwZone.StandardName, 
           TimeZoneInfo.ConvertTime(hwTime, hwZone, TimeZoneInfo.Local));
}
catch (TimeZoneNotFoundException)
{
   Console.WriteLine("The registry does not define the Hawaiian Standard Time zone.");
}                           
catch (InvalidTimeZoneException)
{
   Console.WriteLine("Registry data on the Hawaiian STandard Time zone has been corrupted.");
}

Platforms

Windows Vista, Windows XP SP2, 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.

Version Information