Export (0) Print
Expand All

TimeZoneInfo.ConvertTimeBySystemTimeZoneId Method (DateTime, String)

Converts a time to the time in another time zone based on the time zone's identifier.

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

public static DateTime ConvertTimeBySystemTimeZoneId(
	DateTime dateTime,
	string destinationTimeZoneId
)

Parameters

dateTime
Type: System.DateTime

The date and time to convert.

destinationTimeZoneId
Type: System.String

The identifier of the destination time zone.

Return Value

Type: System.DateTime
The date and time in the destination time zone.

ExceptionCondition
ArgumentNullException

destinationTimeZoneId is null.

InvalidTimeZoneException

The time zone identifier was found, but the registry data is corrupted.

SecurityException

The process does not have the permissions required to read from the registry key that contains the time zone information.

TimeZoneNotFoundException

The destinationTimeZoneId identifier was not found on the local system.

When performing the conversion, the ConvertTimeBySystemTimeZoneId method applies any adjustment rules in effect in the destinationTimeZoneId time zone.

This overload is largely identical to calling the ConvertTime(DateTime, TimeZoneInfo) method, except that it allows you to specify the destination time zone by its identifier rather than by an object reference. This method is most useful when you must convert a time without retrieving the time zone object that corresponds to it and you do not need to know whether the converted time is standard or daylight saving time.

The ConvertTimeBySystemTimeZoneId(DateTime, String) method 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 is TimeZoneInfo.Utc.Id.

DateTimeKind.Utc

Any other destinationTimeZone value.

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.

This method retrieves the time zone whose identifier is specified by the destinationTimeZoneId parameter from the registry. It cannot retrieve a time zone object that is created using the CreateCustomTimeZone method. The destinationTimeZoneId parameter must correspond exactly to the time zone's registry key in length, but not in case, for a successful match to occur; that is, the comparison of destinationTimeZoneId with time zone identifiers is case-insensitive.

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Show:
© 2014 Microsoft