TimeZoneInfo.ConvertTime Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Converts a time to the time in a particular time zone.
Overloads
ConvertTime(DateTime, TimeZoneInfo) |
Converts a time to the time in a particular time zone. |
ConvertTime(DateTimeOffset, TimeZoneInfo) |
Converts a time to the time in a particular time zone. |
ConvertTime(DateTime, TimeZoneInfo, TimeZoneInfo) |
Converts a time from one time zone to another. |
ConvertTime(DateTime, TimeZoneInfo)
- Source:
- TimeZoneInfo.cs
- Source:
- TimeZoneInfo.cs
- Source:
- TimeZoneInfo.cs
Converts a time to the time in a particular time zone.
public:
static DateTime ConvertTime(DateTime dateTime, TimeZoneInfo ^ destinationTimeZone);
public static DateTime ConvertTime (DateTime dateTime, TimeZoneInfo destinationTimeZone);
static member ConvertTime : DateTime * TimeZoneInfo -> DateTime
Public Shared Function ConvertTime (dateTime As DateTime, destinationTimeZone As TimeZoneInfo) As DateTime
Parameters
- dateTime
- DateTime
The date and time to convert.
- destinationTimeZone
- TimeZoneInfo
The time zone to convert dateTime
to.
Returns
The date and time in the destination time zone.
Exceptions
The value of the dateTime
parameter represents an invalid time.
The value of the destinationTimeZone
parameter is null
.
Examples
The following example converts an array of date and time values to times in the Eastern Time zone of the U.S. and Canada. It shows that the source time zone depends on the DateTime.Kind property of the source DateTime value. It also illustrates that the ConvertTime method takes time zone adjustments into account, because a time zone adjustment occurs in both the source and destination time zones at 2:00 A.M. on November 7, 2010.
using System;
public class Example
{
public static void Main()
{
// Define times to be converted.
DateTime[] times = { new DateTime(2010, 1, 1, 0, 1, 0),
new DateTime(2010, 1, 1, 0, 1, 0, DateTimeKind.Utc),
new DateTime(2010, 1, 1, 0, 1, 0, DateTimeKind.Local),
new DateTime(2010, 11, 6, 23, 30, 0),
new DateTime(2010, 11, 7, 2, 30, 0) };
// Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
TimeZoneInfo est;
try {
est = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");
}
catch (TimeZoneNotFoundException) {
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.");
return;
}
catch (InvalidTimeZoneException) {
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.");
return;
}
// Display the current time zone name.
Console.WriteLine("Local time zone: {0}\n", TimeZoneInfo.Local.DisplayName);
// Convert each time in the array.
foreach (DateTime timeToConvert in times)
{
DateTime targetTime = TimeZoneInfo.ConvertTime(timeToConvert, est);
Console.WriteLine("Converted {0} {1} to {2}.", timeToConvert,
timeToConvert.Kind, targetTime);
}
}
}
// The example displays the following output:
// Local time zone: (GMT-08:00) Pacific Time (US & Canada)
//
// Converted 1/1/2010 12:01:00 AM Unspecified to 1/1/2010 3:01:00 AM.
// Converted 1/1/2010 12:01:00 AM Utc to 12/31/2009 7:01:00 PM.
// Converted 1/1/2010 12:01:00 AM Local to 1/1/2010 3:01:00 AM.
// Converted 11/6/2010 11:30:00 PM Unspecified to 11/7/2010 1:30:00 AM.
// Converted 11/7/2010 2:30:00 AM Unspecified to 11/7/2010 5:30:00 AM.
open System
// Define times to be converted.
let times =
[| DateTime(2010, 1, 1, 0, 1, 0)
DateTime(2010, 1, 1, 0, 1, 0, DateTimeKind.Utc)
DateTime(2010, 1, 1, 0, 1, 0, DateTimeKind.Local)
DateTime(2010, 11, 6, 23, 30, 0)
DateTime(2010, 11, 7, 2, 30, 0) |]
// Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
try
let est = TimeZoneInfo.FindSystemTimeZoneById "Eastern Standard Time"
// Display the current time zone name.
printfn $"Local time zone: {TimeZoneInfo.Local.DisplayName}\n"
// Convert each time in the array.
for timeToConvert in times do
let targetTime = TimeZoneInfo.ConvertTime(timeToConvert, est)
printfn $"Converted {timeToConvert} {timeToConvert.Kind} to {targetTime}."
with
| :? TimeZoneNotFoundException ->
printfn "Unable to retrieve the Eastern Standard time zone."
| :? InvalidTimeZoneException ->
printfn "Unable to retrieve the Eastern Standard time zone."
// The example displays the following output:
// Local time zone: (GMT-08:00) Pacific Time (US & Canada)
//
// Converted 1/1/2010 12:01:00 AM Unspecified to 1/1/2010 3:01:00 AM.
// Converted 1/1/2010 12:01:00 AM Utc to 12/31/2009 7:01:00 PM.
// Converted 1/1/2010 12:01:00 AM Local to 1/1/2010 3:01:00 AM.
// Converted 11/6/2010 11:30:00 PM Unspecified to 11/7/2010 1:30:00 AM.
// Converted 11/7/2010 2:30:00 AM Unspecified to 11/7/2010 5:30:00 AM.
Module Example
Public Sub Main()
' Define times to be converted.
Dim times() As Date = { #1/1/2010 12:01AM#, _
DateTime.SpecifyKind(#1/1/2010 12:01AM#, DateTimeKind.Utc), _
DateTime.SpecifyKind(#1/1/2010 12:01AM#, DateTimeKind.Local), _
#11/6/2010 11:30PM#, #11/7/2010 2:30AM# }
' Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
Dim est As TimeZoneInfo
Try
est = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time")
Catch e As TimeZoneNotFoundException
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.")
Exit Sub
Catch e As InvalidTimeZoneException
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.")
Exit Sub
End Try
' Display the current time zone name.
Console.WriteLine("Local time zone: {0}", TimeZoneInfo.Local.DisplayName)
Console.WriteLine()
' Convert each time in the array.
For Each timeToConvert As Date In times
Dim targetTime As Date = TimeZoneInfo.ConvertTime(timeToConvert, est)
Console.WriteLine("Converted {0} {1} to {2}.", timeToConvert, _
timeToConvert.Kind, targetTime)
Next
End Sub
End Module
' The example displays the following output:
' Local time zone: (GMT-08:00) Pacific Time (US & Canada)
'
' Converted 1/1/2010 12:01:00 AM Unspecified to 1/1/2010 3:01:00 AM.
' Converted 1/1/2010 12:01:00 AM Utc to 12/31/2009 7:01:00 PM.
' Converted 1/1/2010 12:01:00 AM Local to 1/1/2010 3:01:00 AM.
' Converted 11/6/2010 11:30:00 PM Unspecified to 11/7/2010 1:30:00 AM.
' Converted 11/7/2010 2:30:00 AM Unspecified to 11/7/2010 5:30:00 AM.
Remarks
When performing the conversion, the ConvertTime(DateTimeOffset, TimeZoneInfo) method applies any adjustment rules in effect in the destinationTimeZone
time zone.
This overload of the ConvertTime(DateTime, TimeZoneInfo) 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. |
DateTimeKind.Utc |
The destinationTimeZone is TimeZoneInfo.Local. |
DateTimeKind.Local |
All other date and time values and destination time zones. | 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.
You can also convert to or from UTC by calling the ConvertTimeFromUtc and ConvertTimeToUtc methods.
See also
Applies to
ConvertTime(DateTimeOffset, TimeZoneInfo)
- Source:
- TimeZoneInfo.cs
- Source:
- TimeZoneInfo.cs
- Source:
- TimeZoneInfo.cs
Converts a time to the time in a particular time zone.
public:
static DateTimeOffset ConvertTime(DateTimeOffset dateTimeOffset, TimeZoneInfo ^ destinationTimeZone);
public static DateTimeOffset ConvertTime (DateTimeOffset dateTimeOffset, TimeZoneInfo destinationTimeZone);
static member ConvertTime : DateTimeOffset * TimeZoneInfo -> DateTimeOffset
Public Shared Function ConvertTime (dateTimeOffset As DateTimeOffset, destinationTimeZone As TimeZoneInfo) As DateTimeOffset
Parameters
- dateTimeOffset
- DateTimeOffset
The date and time to convert.
- destinationTimeZone
- TimeZoneInfo
The time zone to convert dateTimeOffset
to.
Returns
The date and time in the destination time zone.
Exceptions
The value of the destinationTimeZone
parameter is null
.
Examples
The following example converts an array of DateTimeOffset values to times in the Eastern Time zone of the U.S. and Canada. It illustrates that the ConvertTime method takes time zone adjustments into account, because a time zone adjustment occurs in both the source and destination time zones at 2:00 A.M. on November 7, 2010.
using System;
public class Example
{
public static void Main()
{
// Define times to be converted.
DateTime time1 = new DateTime(2010, 1, 1, 12, 1, 0);
DateTime time2 = new DateTime(2010, 11, 6, 23, 30, 0);
DateTimeOffset[] times = { new DateTimeOffset(time1, TimeZoneInfo.Local.GetUtcOffset(time1)),
new DateTimeOffset(time1, TimeSpan.Zero),
new DateTimeOffset(time2, TimeZoneInfo.Local.GetUtcOffset(time2)),
new DateTimeOffset(time2.AddHours(3), TimeZoneInfo.Local.GetUtcOffset(time2.AddHours(3))) };
// Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
TimeZoneInfo est;
try {
est = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");
}
catch (TimeZoneNotFoundException) {
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.");
return;
}
catch (InvalidTimeZoneException) {
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.");
return;
}
// Display the current time zone name.
Console.WriteLine("Local time zone: {0}\n", TimeZoneInfo.Local.DisplayName);
// Convert each time in the array.
foreach (DateTimeOffset timeToConvert in times)
{
DateTimeOffset targetTime = TimeZoneInfo.ConvertTime(timeToConvert, est);
Console.WriteLine("Converted {0} to {1}.", timeToConvert, targetTime);
}
}
}
// The example displays the following output:
// Local time zone: (GMT-08:00) Pacific Time (US & Canada)
//
// Converted 1/1/2010 12:01:00 AM -08:00 to 1/1/2010 3:01:00 AM -05:00.
// Converted 1/1/2010 12:01:00 AM +00:00 to 12/31/2009 7:01:00 PM -05:00.
// Converted 11/6/2010 11:30:00 PM -07:00 to 11/7/2010 1:30:00 AM -05:00.
// Converted 11/7/2010 2:30:00 AM -08:00 to 11/7/2010 5:30:00 AM -05:00.
open System
// Define times to be converted.
let time1 = DateTime(2010, 1, 1, 12, 1, 0)
let time2 = DateTime(2010, 11, 6, 23, 30, 0)
let times =
[| DateTimeOffset(time1, TimeZoneInfo.Local.GetUtcOffset time1)
DateTimeOffset(time1, TimeSpan.Zero)
DateTimeOffset(time2, TimeZoneInfo.Local.GetUtcOffset time2)
DateTimeOffset(time2.AddHours 3, TimeZoneInfo.Local.GetUtcOffset(time2.AddHours 3)) |]
// Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
try
let est = TimeZoneInfo.FindSystemTimeZoneById "Eastern Standard Time"
// Display the current time zone name.
printfn $"Local time zone: {TimeZoneInfo.Local.DisplayName}\n"
// Convert each time in the array.
for timeToConvert in times do
let targetTime = TimeZoneInfo.ConvertTime(timeToConvert, est)
printfn $"Converted {timeToConvert} to {targetTime}."
with
| :? TimeZoneNotFoundException ->
printfn "Unable to retrieve the Eastern Standard time zone."
| :? InvalidTimeZoneException ->
printfn "Unable to retrieve the Eastern Standard time zone."
// The example displays the following output:
// Local time zone: (GMT-08:00) Pacific Time (US & Canada)
//
// Converted 1/1/2010 12:01:00 AM -08:00 to 1/1/2010 3:01:00 AM -05:00.
// Converted 1/1/2010 12:01:00 AM +00:00 to 12/31/2009 7:01:00 PM -05:00.
// Converted 11/6/2010 11:30:00 PM -07:00 to 11/7/2010 1:30:00 AM -05:00.
// Converted 11/7/2010 2:30:00 AM -08:00 to 11/7/2010 5:30:00 AM -05:00.
Module Example
Public Sub Main()
' Define times to be converted.
Dim time1 As Date = #1/1/2010 12:01AM#
Dim time2 As Date = #11/6/2010 11:30PM#
Dim times() As DateTimeOffset = { New DateTimeOffset(time1, TimeZoneInfo.Local.GetUtcOffset(time1)), _
New DateTimeOffset(time1, Timespan.Zero), _
New DateTimeOffset(time2, TimeZoneInfo.Local.GetUtcOffset(time2)), _
New DateTimeOffset(time2.AddHours(3), TimeZoneInfo.Local.GetUtcOffset(time2.AddHours(3))) }
' Retrieve the time zone for Eastern Standard Time (U.S. and Canada).
Dim est As TimeZoneInfo
Try
est = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time")
Catch e As TimeZoneNotFoundException
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.")
Exit Sub
Catch e As InvalidTimeZoneException
Console.WriteLine("Unable to retrieve the Eastern Standard time zone.")
Exit Sub
End Try
' Display the current time zone name.
Console.WriteLine("Local time zone: {0}", TimeZoneInfo.Local.DisplayName)
Console.WriteLine()
' Convert each time in the array.
For Each timeToConvert As DateTimeOffset In times
Dim targetTime As DateTimeOffset = TimeZoneInfo.ConvertTime(timeToConvert, est)
Console.WriteLine("Converted {0} to {1}.", timeToConvert, targetTime)
Next
End Sub
End Module
' The example displays the following output:
' Local time zone: (GMT-08:00) Pacific Time (US & Canada)
'
' Converted 1/1/2010 12:01:00 AM -08:00 to 1/1/2010 3:01:00 AM -05:00.
' Converted 1/1/2010 12:01:00 AM +00:00 to 12/31/2009 7:01:00 PM -05:00.
' Converted 11/6/2010 11:30:00 PM -07:00 to 11/7/2010 1:30:00 AM -05:00.
' Converted 11/7/2010 2:30:00 AM -08:00 to 11/7/2010 5:30:00 AM -05:00.
Remarks
When performing the conversion, the ConvertTime(DateTimeOffset, TimeZoneInfo) method applies any adjustment rules in effect in the destinationTimeZone
time zone.
This overload differs from the other overloads of the ConvertTime method by accepting a DateTimeOffset value as its first parameter. This identifies the date and time as an offset from Coordinated Universal Time (UTC) rather than as the date and time in a particular time zone. As a result, the dateTimeOffset
parameter cannot represent either an ambiguous time or an invalid time.
In converting the dateTimeOffset
value to the time in the destination time zone, this 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
Applies to
ConvertTime(DateTime, TimeZoneInfo, TimeZoneInfo)
- Source:
- TimeZoneInfo.cs
- Source:
- TimeZoneInfo.cs
- Source:
- TimeZoneInfo.cs
Converts a time from one time zone to another.
public:
static DateTime ConvertTime(DateTime dateTime, TimeZoneInfo ^ sourceTimeZone, TimeZoneInfo ^ destinationTimeZone);
public static DateTime ConvertTime (DateTime dateTime, TimeZoneInfo sourceTimeZone, TimeZoneInfo destinationTimeZone);
static member ConvertTime : DateTime * TimeZoneInfo * TimeZoneInfo -> DateTime
Public Shared Function ConvertTime (dateTime As DateTime, sourceTimeZone As TimeZoneInfo, destinationTimeZone As TimeZoneInfo) As DateTime
Parameters
- dateTime
- DateTime
The date and time to convert.
- sourceTimeZone
- TimeZoneInfo
The time zone of dateTime
.
- destinationTimeZone
- TimeZoneInfo
The time zone to convert dateTime
to.
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 is Local, but the sourceTimeZone
parameter does not equal Local.
-or-
The Kind property of the dateTime
parameter is Utc, but the sourceTimeZone
parameter does not equal 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).
The sourceTimeZone
parameter is null
.
-or-
The destinationTimeZone
parameter is null
.
Examples
The following example illustrates the use of the ConvertTime(DateTime, TimeZoneInfo, TimeZoneInfo) method to convert from Hawaiian Standard Time to local time.
DateTime hwTime = new DateTime(2007, 02, 01, 08, 00, 00);
try
{
TimeZoneInfo hwZone = TimeZoneInfo.FindSystemTimeZoneById("Hawaiian Standard Time");
Console.WriteLine("{0} {1} is {2} local time.",
hwTime,
hwZone.IsDaylightSavingTime(hwTime) ? hwZone.DaylightName : hwZone.StandardName,
TimeZoneInfo.ConvertTime(hwTime, hwZone, TimeZoneInfo.Local));
}
catch (TimeZoneNotFoundException)
{
Console.WriteLine("The registry does not define the Hawaiian Standard Time zone.");
}
catch (InvalidTimeZoneException)
{
Console.WriteLine("Registry data on the Hawaiian Standard Time zone has been corrupted.");
}
let hwTime = DateTime(2007, 02, 01, 08, 00, 00)
try
let hwZone = TimeZoneInfo.FindSystemTimeZoneById "Hawaiian Standard Time"
printfn $"{hwTime} {if hwZone.IsDaylightSavingTime hwTime then hwZone.DaylightName else hwZone.StandardName} is {TimeZoneInfo.ConvertTime(hwTime, hwZone, TimeZoneInfo.Local)} local time."
with
| :? TimeZoneNotFoundException ->
printfn "The registry does not define the Hawaiian Standard Time zone."
| :? InvalidTimeZoneException ->
printfn "Registry data on the Hawaiian Standard Time zone has been corrupted."
Dim hwTime As Date = #2/01/2007 8:00:00 AM#
Try
Dim hwZone As TimeZoneInfo = TimeZoneInfo.FindSystemTimeZoneById("Hawaiian Standard Time")
Console.WriteLine("{0} {1} is {2} local time.", _
hwTime, _
IIf(hwZone.IsDaylightSavingTime(hwTime), hwZone.DaylightName, hwZone.StandardName), _
TimeZoneInfo.ConvertTime(hwTime, hwZone, TimeZoneInfo.Local))
Catch e As TimeZoneNotFoundException
Console.WriteLine("The registry does not define the Hawaiian Standard Time zone.")
Catch e As InvalidTimeZoneException
Console.WriteLine("Registry data on the Hawaiian Standard Time zone has been corrupted.")
End Try
Remarks
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. |
DateTimeKind.Unspecified | 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. |
DateTimeKind.Utc |
The destinationTimeZone argument is TimeZoneInfo.Local. |
DateTimeKind.Local |
All other date and time values, source time zones, and destination time zones. | DateTimeKind.Unspecified |
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.