TimeZoneInfo::ConvertTime Method (DateTime, TimeZoneInfo^, TimeZoneInfo^)
Converts a time from one time zone to another.
Assembly: mscorlib (in mscorlib.dll)
public: static DateTime ConvertTime( DateTime dateTime, TimeZoneInfo^ sourceTimeZone, TimeZoneInfo^ destinationTimeZone )
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::DateTimeThe date and time in the destination time zone that corresponds to the dateTime parameter in the source time zone.
| Exception | Condition |
|---|---|
| ArgumentException | The Kind property of the dateTime parameter is DateTimeKind::Local, but the sourceTimeZone parameter does not equal DateTimeKind::Local. For more information, see the Remarks section. -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 null. -or- The destinationTimeZone parameter is null. |
When performing the conversion, the ConvertTime method applies any adjustment rules in effect in the destinationTimeZone time zone.
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 |
|---|---|---|
Equals TimeZoneInfo::Utc. | Converts dateTime to the destination time zone's time. | |
Does not equal TimeZoneInfo::Utc. | Throws an ArgumentException. | |
Equals TimeZoneInfo::Local. | Converts dateTime to the destination time zone's time. | |
Does not equal TimeZoneInfo::Local. | Throws an ArgumentException. | |
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 argument is TimeZoneInfo::Utc. | |
The destinationTimeZone argument is TimeZoneInfo::Local. | |
All other date and time values, source time zones, and destination time zones. |
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.
The ConvertTime(DateTime, TimeZoneInfo^, TimeZoneInfo^) method throws an ArgumentException exception if the DateTime::Kind property of the dateTime argument is DateTimeKind::Local but the sourceTimeZone argument is not TimeZoneInfo::Local. To determine whether the source time zone is the local time zone or the universal time zone, the method tests for reference equality instead of testing for value equality with the Equals(TimeZoneInfo^) method. Note that TimeZoneInfo objects that represent the local time zone and that are retrieved by calling the FindSystemTimeZoneById method do not have referential equality with TimeZoneInfo::Local. Furthermore, TimeZoneInfo objects that represent the local or universal time zone and that are retrieved by iterating the collection returned by the GetSystemTimeZones method do not have referential equality with TimeZoneInfo::Local or TimeZoneInfo::Utc. As an alternative, you can call the ConvertTimeBySystemTimeZoneId(DateTime, String^, String^) method.
Notes to Callers:
On Windows XP systems, this method applies only the current adjustment rule when performing the conversion if dateTime is treated as a local time, if sourceTimeZone is TimeZoneInfo::Local, 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.
Available since 10
.NET Framework
Available since 3.5