TimeZoneInfo.ConvertTimeBySystemTimeZoneId Method

Definition

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

Overloads

ConvertTimeBySystemTimeZoneId(DateTime, String)

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

ConvertTimeBySystemTimeZoneId(DateTimeOffset, String)

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

ConvertTimeBySystemTimeZoneId(DateTime, String, String)

Converts a time from one time zone to another based on time zone identifiers.

ConvertTimeBySystemTimeZoneId(DateTime, String)

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

public:
 static DateTime ConvertTimeBySystemTimeZoneId(DateTime dateTime, System::String ^ destinationTimeZoneId);
public static DateTime ConvertTimeBySystemTimeZoneId (DateTime dateTime, string destinationTimeZoneId);
static member ConvertTimeBySystemTimeZoneId : DateTime * string -> DateTime

Parameters

dateTime
DateTime

The date and time to convert.

destinationTimeZoneId
String

The identifier of the destination time zone.

Returns

The date and time in the destination time zone.

Exceptions

destinationTimeZoneId is null.

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

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

The destinationTimeZoneId identifier was not found on the local system.

Remarks

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 information on the time zone whose identifier is specified by the destinationTimeZoneId parameter from the registry on Windows systems and from the ICU Library on Linux and macOS. 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 identifier 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.

See also

ConvertTimeBySystemTimeZoneId(DateTimeOffset, String)

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

public:
 static DateTimeOffset ConvertTimeBySystemTimeZoneId(DateTimeOffset dateTimeOffset, System::String ^ destinationTimeZoneId);
public static DateTimeOffset ConvertTimeBySystemTimeZoneId (DateTimeOffset dateTimeOffset, string destinationTimeZoneId);
static member ConvertTimeBySystemTimeZoneId : DateTimeOffset * string -> DateTimeOffset

Parameters

dateTimeOffset
DateTimeOffset

The date and time to convert.

destinationTimeZoneId
String

The identifier of the destination time zone.

Returns

The date and time in the destination time zone.

Exceptions

destinationTimeZoneId is null.

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

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

The destinationTimeZoneId identifier was not found on the local system.

Remarks

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

This overload is 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.

Because the dateTimeOffset parameter represents a date and time together with that time's offset from Coordinated Universal Time (UTC), it cannot represent either an ambiguous time or an invalid time.

This method retrieves the time zone whose identifier is specified by the destinationTimeZoneId parameter from the registry on Windows systems and from the ICU Library on Linux and macOS. 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 identifier 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.

In converting the dateTimeOffset value to the time in the destination time zone, the 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.

See also

ConvertTimeBySystemTimeZoneId(DateTime, String, String)

Converts a time from one time zone to another based on time zone identifiers.

public:
 static DateTime ConvertTimeBySystemTimeZoneId(DateTime dateTime, System::String ^ sourceTimeZoneId, System::String ^ destinationTimeZoneId);
public static DateTime ConvertTimeBySystemTimeZoneId (DateTime dateTime, string sourceTimeZoneId, string destinationTimeZoneId);
static member ConvertTimeBySystemTimeZoneId : DateTime * string * string -> DateTime

Parameters

dateTime
DateTime

The date and time to convert.

sourceTimeZoneId
String

The identifier of the source time zone.

destinationTimeZoneId
String

The identifier of the destination time zone.

Returns

The date and time in the destination time zone that corresponds to the dateTime parameter in the source time zone.

Exceptions

The Kind property of the dateTime parameter does not correspond to the source time zone.

-or-

dateTime is an invalid time in the source time zone.

sourceTimeZoneId is null.

-or-

destinationTimeZoneId is null.

The time zone identifiers were found, but the registry data is corrupted.

The user does not have the permissions required to read from the registry keys that hold time zone data.

The sourceTimeZoneId identifier was not found on the local system.

-or-

The destinationTimeZoneId identifier was not found on the local system.

Examples

The following example uses the TimeZoneInfo.ConvertTimeBySystemTimeZoneId(DateTime, String, String) method to display the time that corresponds to the local system time in eight cities of the world.

DateTime currentTime = DateTime.Now;
Console.WriteLine("Current Times:");
Console.WriteLine();
Console.WriteLine("Los Angeles: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Pacific Standard Time"));
Console.WriteLine("Chicago: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Central Standard Time"));
Console.WriteLine("New York: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Eastern Standard Time"));
Console.WriteLine("London: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "GMT Standard Time"));
Console.WriteLine("Moscow: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Russian Standard Time"));
Console.WriteLine("New Delhi: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "India Standard Time"));
Console.WriteLine("Beijing: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "China Standard Time"));
Console.WriteLine("Tokyo: {0}", 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Tokyo Standard Time"));
Dim currentTime As Date = Date.Now
Console.WriteLine("Current Times:")
Console.WriteLine()
Console.WriteLine("Los Angeles: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Pacific Standard Time"))
Console.WriteLine("Chicago: {0}", _ 
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Central Standard Time"))
Console.WriteLine("New York: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Eastern Standard Time"))
Console.WriteLine("London: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "GMT Standard Time"))
Console.WriteLine("Moscow: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Russian Standard Time"))
Console.WriteLine("New Delhi: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "India Standard Time"))
Console.WriteLine("Beijing: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "China Standard Time"))
Console.WriteLine("Tokyo: {0}", _
                  TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Tokyo Standard Time"))

Remarks

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

Although it is similar to the TimeZoneInfo.ConvertTime(DateTime, TimeZoneInfo, TimeZoneInfo) method, you can use TimeZoneInfo.ConvertTimeBySystemTimeZoneId(DateTime, String, String) to specify the source and destination time zones using their identifiers instead of their TimeZoneInfo objects. 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.

This method retrieves the time zones whose identifiers are the sourceTimeZoneId and destinationTimeZoneId parameters from the registry on Windows systems and from the ICU Library on Linux and macOS. It cannot retrieve time zone objects that are created using the CreateCustomTimeZone method.

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

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

Because it relies on calls to the FindSystemTimeZoneById method, the ConvertTimeBySystemTimeZoneId method performs a case-insensitive search to locate the time zones that correspond to sourceTimeZoneId and destinationTimeZoneId.

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.

The Kind property of the returned DateTime value is set to DateTimeKind.Unspecified unless the destination time zone is Coordinated Universal Time (UTC), in which case it is set to DateTimeKind.Utc.

See also

Applies to