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. -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 nullptr. -or- The destinationTimeZone parameter is nullptr. |
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 |
|---|---|---|
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. |
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. |
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.
Notes to CallersOn 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.
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.