TimeZoneInfo.ConvertTimeBySystemTimeZoneId Method

Definition

Namespace:

System

Assembly:

System.Runtime.dll

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)

Source:

TimeZoneInfo.cs

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

Public Shared Function ConvertTimeBySystemTimeZoneId (dateTime As DateTime, destinationTimeZoneId As String) As DateTime

Parameters

dateTime

DateTime

The date and time to convert.

destinationTimeZoneId

String

The identifier of the destination time zone.

Returns

DateTime

The date and time in the destination time zone.

Exceptions

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.

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

• Converting Times Between Time Zones

ConvertTimeBySystemTimeZoneId(DateTimeOffset, String)

Source:

TimeZoneInfo.cs

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

Public Shared Function ConvertTimeBySystemTimeZoneId (dateTimeOffset As DateTimeOffset, destinationTimeZoneId As String) As DateTimeOffset

Parameters

dateTimeOffset

DateTimeOffset

The date and time to convert.

destinationTimeZoneId

String

The identifier of the destination time zone.

Returns

DateTimeOffset

The date and time in the destination time zone.

Exceptions

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.

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(DateTimeOffset, 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

• Converting Times Between Time Zones

ConvertTimeBySystemTimeZoneId(DateTime, String, String)

Source:

TimeZoneInfo.cs

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

Public Shared Function ConvertTimeBySystemTimeZoneId (dateTime As DateTime, sourceTimeZoneId As String, destinationTimeZoneId As String) As 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

DateTime

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

Exceptions

ArgumentException

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.

ArgumentNullException

sourceTimeZoneId is null.

-or-

destinationTimeZoneId is null.

InvalidTimeZoneException

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

SecurityException

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

TimeZoneNotFoundException

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"));

let currentTime = DateTime.Now
printfn "Current Times:\n"
printfn $"""Los Angeles: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Pacific Standard Time")}"""
printfn $"""Chicago: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Central Standard Time")}"""
printfn $"""New York: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Eastern Standard Time")}"""
printfn $"""London: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "GMT Standard Time")}"""
printfn $"""Moscow: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "Russian Standard Time")}"""
printfn $"""New Delhi: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "India Standard Time")}"""
printfn $"""Beijing: {TimeZoneInfo.ConvertTimeBySystemTimeZoneId(currentTime, TimeZoneInfo.Local.Id, "China Standard Time")}"""
printfn $"""Tokyo: {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

• Converting Times Between Time Zones