在 DateTime 與 DateTimeOffset 之間轉換
雖然 DateTimeOffset 結構提供比 DateTime 結構更高的時區感知度,但 DateTime 參數在方法呼叫中較常用。 由於這種方法,將 DateTimeOffset 值轉換成 DateTime 值的能力很重要,反之亦然。 本文說明如何以盡可能保留盡可能多的時區資訊的方式執行這些轉換。
備註
DateTime 和 DateTimeOffset 類型在時區中代表時間時有一些限制。 利用其 Kind 屬性,DateTime 只能反映國際標準時間(UTC)和系統的當地時區。 DateTimeOffset 反映時間與UTC的位移,但不會反映該位移所屬的實際時區。 如需時區時間值和支援的詳細資訊,請參閱 選擇 DateTime、DateTimeOffset、TimeSpan 和 TimeZoneInfo。
從 DateTime 轉換為 DateTimeOffset
DateTimeOffset 結構提供兩種對等方式,適合用於大多數轉換,來執行從 DateTime 到 DateTimeOffset 的轉換。
DateTimeOffset 建構函式,它會根據 DateTime 值建立新的 DateTimeOffset 物件。
隱含轉換運算符,可讓您將 DateTime 值指派給 DateTimeOffset 物件。
針對UTC和本機 DateTime 值,所產生 DateTimeOffset 值的 Offset 屬性會準確地反映UTC或當地時區位移。 例如,下列程式代碼會將UTC時間轉換成其相等 DateTimeOffset 值:
DateTime utcTime1 = new DateTime(2008, 6, 19, 7, 0, 0);
utcTime1 = DateTime.SpecifyKind(utcTime1, DateTimeKind.Utc);
DateTimeOffset utcTime2 = utcTime1;
Console.WriteLine($"Converted {utcTime1} {utcTime1.Kind} to a DateTimeOffset value of {utcTime2}");
// This example displays the following output to the console:
// Converted 6/19/2008 7:00:00 AM Utc to a DateTimeOffset value of 6/19/2008 7:00:00 AM +00:00
Dim utcTime1 As Date = Date.SpecifyKind(#06/19/2008 7:00AM#, _
DateTimeKind.Utc)
Dim utcTime2 As DateTimeOffset = utcTime1
Console.WriteLine("Converted {0} {1} to a DateTimeOffset value of {2}", _
utcTime1, _
utcTime1.Kind.ToString(), _
utcTime2)
' This example displays the following output to the console:
' Converted 6/19/2008 7:00:00 AM Utc to a DateTimeOffset value of 6/19/2008 7:00:00 AM +00:00
在此情況下,utcTime2
變數的位移為00:00。 同樣地,下列程式代碼會將當地時間轉換成其相等 DateTimeOffset 值:
DateTime localTime1 = new DateTime(2008, 6, 19, 7, 0, 0);
localTime1 = DateTime.SpecifyKind(localTime1, DateTimeKind.Local);
DateTimeOffset localTime2 = localTime1;
Console.WriteLine($"Converted {localTime1} {localTime1.Kind} to a DateTimeOffset value of {localTime2}");
// This example displays the following output to the console:
// Converted 6/19/2008 7:00:00 AM Local to a DateTimeOffset value of 6/19/2008 7:00:00 AM -07:00
Dim localTime1 As Date = Date.SpecifyKind(#06/19/2008 7:00AM#, DateTimeKind.Local)
Dim localTime2 As DateTimeOffset = localTime1
Console.WriteLine("Converted {0} {1} to a DateTimeOffset value of {2}", _
localTime1, _
localTime1.Kind.ToString(), _
localTime2)
' This example displays the following output to the console:
' Converted 6/19/2008 7:00:00 AM Local to a DateTimeOffset value of 6/19/2008 7:00:00 AM -07:00
不過,對於 Kind 屬性為 DateTimeKind.Unspecified的 DateTime 值,這兩個轉換方法會產生 DateTimeOffset 值,其位移為當地時區的值。 轉換如下列範例所示,這會在美國太平洋標準時區執行:
DateTime time1 = new DateTime(2008, 6, 19, 7, 0, 0); // Kind is DateTimeKind.Unspecified
DateTimeOffset time2 = time1;
Console.WriteLine($"Converted {time1} {time1.Kind} to a DateTimeOffset value of {time2}");
// This example displays the following output to the console:
// Converted 6/19/2008 7:00:00 AM Unspecified to a DateTimeOffset value of 6/19/2008 7:00:00 AM -07:00
Dim time1 As Date = #06/19/2008 7:00AM# ' Kind is DateTimeKind.Unspecified
Dim time2 As DateTimeOffset = time1
Console.WriteLine("Converted {0} {1} to a DateTimeOffset value of {2}", _
time1, _
time1.Kind.ToString(), _
time2)
' This example displays the following output to the console:
' Converted 6/19/2008 7:00:00 AM Unspecified to a DateTimeOffset value of 6/19/2008 7:00:00 AM -07:00
如果 DateTime 值反映當地時區或 UTC 以外的日期和時間,您可以呼叫多載的 DateTimeOffset 建構函式,將其轉換成 DateTimeOffset 值,並保留其時區資訊。 例如,下列範例會具現化反映 Central Standard Time 的 DateTimeOffset 物件:
DateTime time1 = new DateTime(2008, 6, 19, 7, 0, 0); // Kind is DateTimeKind.Unspecified
try
{
DateTimeOffset time2 = new DateTimeOffset(time1,
TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time").GetUtcOffset(time1));
Console.WriteLine($"Converted {time1} {time1.Kind} to a DateTime value of {time2}");
}
// Handle exception if time zone is not defined in registry
catch (TimeZoneNotFoundException)
{
Console.WriteLine("Unable to identify target time zone for conversion.");
}
// This example displays the following output to the console:
// Converted 6/19/2008 7:00:00 AM Unspecified to a DateTime value of 6/19/2008 7:00:00 AM -05:00
Dim time1 As Date = #06/19/2008 7:00AM# ' Kind is DateTimeKind.Unspecified
Try
Dim time2 As New DateTimeOffset(time1, _
TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time").GetUtcOffset(time1))
Console.WriteLine("Converted {0} {1} to a DateTime value of {2}", _
time1, _
time1.Kind.ToString(), _
time2)
' Handle exception if time zone is not defined in registry
Catch e As TimeZoneNotFoundException
Console.WriteLine("Unable to identify target time zone for conversion.")
End Try
' This example displays the following output to the console:
' Converted 6/19/2008 7:00:00 AM Unspecified to a DateTime value of 6/19/2008 7:00:00 AM -05:00
這個建構函式多載的第二個參數是 TimeSpan 物件,代表時間與 UTC 的位移。 呼叫與時間對應時區相關聯的 TimeZoneInfo.GetUtcOffset(DateTime) 方法,以取得它。 方法的單一參數是 DateTime 值,代表要轉換的日期和時間。 如果時區支援日光節約時間,此參數可讓 方法判斷該特定日期和時間的適當位移。
從 DateTimeOffset 轉換為 DateTime
DateTime 屬性最常用來執行 DateTimeOffset 來 DateTime 轉換。 不過,它會傳回一個 DateTime 值,其 Kind 屬性為 Unspecified,如下列範例所示:
DateTime baseTime = new DateTime(2008, 6, 19, 7, 0, 0);
DateTimeOffset sourceTime;
DateTime targetTime;
// Convert UTC to DateTime value
sourceTime = new DateTimeOffset(baseTime, TimeSpan.Zero);
targetTime = sourceTime.DateTime;
Console.WriteLine($"{sourceTime} converts to {targetTime} {targetTime.Kind}");
// Convert local time to DateTime value
sourceTime = new DateTimeOffset(baseTime,
TimeZoneInfo.Local.GetUtcOffset(baseTime));
targetTime = sourceTime.DateTime;
Console.WriteLine($"{sourceTime} converts to {targetTime} {targetTime.Kind}");
// Convert Central Standard Time to a DateTime value
try
{
TimeSpan offset = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time").GetUtcOffset(baseTime);
sourceTime = new DateTimeOffset(baseTime, offset);
targetTime = sourceTime.DateTime;
Console.WriteLine($"{sourceTime} converts to {targetTime} {targetTime.Kind}");
}
catch (TimeZoneNotFoundException)
{
Console.WriteLine("Unable to create DateTimeOffset based on U.S. Central Standard Time.");
}
// This example displays the following output to the console:
// 6/19/2008 7:00:00 AM +00:00 converts to 6/19/2008 7:00:00 AM Unspecified
// 6/19/2008 7:00:00 AM -07:00 converts to 6/19/2008 7:00:00 AM Unspecified
// 6/19/2008 7:00:00 AM -05:00 converts to 6/19/2008 7:00:00 AM Unspecified
Const baseTime As Date = #06/19/2008 7:00AM#
Dim sourceTime As DateTimeOffset
Dim targetTime As Date
' Convert UTC to DateTime value
sourceTime = New DateTimeOffset(baseTime, TimeSpan.Zero)
targetTime = sourceTime.DateTime
Console.WriteLine("{0} converts to {1} {2}", _
sourceTime, _
targetTime, _
targetTime.Kind.ToString())
' Convert local time to DateTime value
sourceTime = New DateTimeOffset(baseTime, _
TimeZoneInfo.Local.GetUtcOffset(baseTime))
targetTime = sourceTime.DateTime
Console.WriteLine("{0} converts to {1} {2}", _
sourceTime, _
targetTime, _
targetTime.Kind.ToString())
' Convert Central Standard Time to a DateTime value
Try
Dim offset As TimeSpan = TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time").GetUtcOffset(baseTime)
sourceTime = New DateTimeOffset(baseTime, offset)
targetTime = sourceTime.DateTime
Console.WriteLine("{0} converts to {1} {2}", _
sourceTime, _
targetTime, _
targetTime.Kind.ToString())
Catch e As TimeZoneNotFoundException
Console.WriteLine("Unable to create DateTimeOffset based on U.S. Central Standard Time.")
End Try
' This example displays the following output to the console:
' 6/19/2008 7:00:00 AM +00:00 converts to 6/19/2008 7:00:00 AM Unspecified
' 6/19/2008 7:00:00 AM -07:00 converts to 6/19/2008 7:00:00 AM Unspecified
' 6/19/2008 7:00:00 AM -05:00 converts to 6/19/2008 7:00:00 AM Unspecified
上述範例顯示在使用 DateTime 屬性時,轉換會遺失 DateTimeOffset 值與 UTC 關聯性的任何資訊。 此行為也會影響對應至 UTC 時間或系統當地時間的 DateTimeOffset 值,因為 DateTime 結構只會反映其 Kind 屬性中的這兩個時區。
若要在將 DateTimeOffset 轉換成 DateTime 值時盡可能保留盡可能多的時區資訊,您可以使用 DateTimeOffset.UtcDateTime 和 DateTimeOffset.LocalDateTime 屬性。
轉換UTC時間
若要指出已轉換 DateTime 值是 UTC 時間,您可以擷取 DateTimeOffset.UtcDateTime 屬性的值。 其與 DateTime 屬性有兩種不同:
如果 Offset 屬性值不等於 TimeSpan.Zero,則會將時間轉換成 UTC。
備註
如果您的應用程式要求轉換 DateTime 值明確識別單一時間點,您應該考慮使用 DateTimeOffset.UtcDateTime 屬性來處理所有 DateTimeOffset 以 DateTime 轉換。
下列程式代碼會使用 UtcDateTime 屬性,將位移等於 TimeSpan.Zero 的 DateTimeOffset 值轉換成 DateTime 值:
DateTimeOffset utcTime1 = new DateTimeOffset(2008, 6, 19, 7, 0, 0, TimeSpan.Zero);
DateTime utcTime2 = utcTime1.UtcDateTime;
Console.WriteLine($"{utcTime1} converted to {utcTime2} {utcTime2.Kind}");
// The example displays the following output to the console:
// 6/19/2008 7:00:00 AM +00:00 converted to 6/19/2008 7:00:00 AM Utc
Dim utcTime1 As New DateTimeOffset(#06/19/2008 7:00AM#, TimeSpan.Zero)
Dim utcTime2 As Date = utcTime1.UtcDateTime
Console.WriteLine("{0} converted to {1} {2}", _
utcTime1, _
utcTime2, _
utcTime2.Kind.ToString())
' The example displays the following output to the console:
' 6/19/2008 7:00:00 AM +00:00 converted to 6/19/2008 7:00:00 AM Utc
下列程式代碼會使用 UtcDateTime 屬性,在 DateTimeOffset 值上執行時區轉換和類型轉換:
DateTimeOffset originalTime = new DateTimeOffset(2008, 6, 19, 7, 0, 0, new TimeSpan(5, 0, 0));
DateTime utcTime = originalTime.UtcDateTime;
Console.WriteLine($"{originalTime} converted to {utcTime} {utcTime.Kind}");
// The example displays the following output to the console:
// 6/19/2008 7:00:00 AM +05:00 converted to 6/19/2008 2:00:00 AM Utc
Dim originalTime As New DateTimeOffset(#6/19/2008 7:00AM#, _
New TimeSpan(5, 0, 0))
Dim utcTime As Date = originalTime.UtcDateTime
Console.WriteLine("{0} converted to {1} {2}", _
originalTime, _
utcTime, _
utcTime.Kind.ToString())
' The example displays the following output to the console:
' 6/19/2008 7:00:00 AM +05:00 converted to 6/19/2008 2:00:00 AM Utc
轉換當地時間
若要指出 DateTimeOffset 值代表當地時間,您可以將 DateTimeOffset.DateTime 屬性所傳回的 DateTime 值傳遞至 visual Basic SpecifyKind 方法 static
(Shared
)。 方法會傳回傳遞至它的日期和時間做為其第一個參數,但會將 Kind 屬性設定為其第二個參數所指定的值。 下列程式碼在將 DateTimeOffset 值轉換時,會使用 SpecifyKind 方法,該值的位移與當地時區的偏移量相對應。
DateTime sourceDate = new DateTime(2008, 6, 19, 7, 0, 0);
DateTimeOffset utcTime1 = new DateTimeOffset(sourceDate,
TimeZoneInfo.Local.GetUtcOffset(sourceDate));
DateTime utcTime2 = utcTime1.DateTime;
if (utcTime1.Offset.Equals(TimeZoneInfo.Local.GetUtcOffset(utcTime1.DateTime)))
utcTime2 = DateTime.SpecifyKind(utcTime2, DateTimeKind.Local);
Console.WriteLine($"{utcTime1} converted to {utcTime2} {utcTime2.Kind}");
// The example displays the following output to the console:
// 6/19/2008 7:00:00 AM -07:00 converted to 6/19/2008 7:00:00 AM Local
Dim sourceDate As Date = #06/19/2008 7:00AM#
Dim utcTime1 As New DateTimeOffset(sourceDate, _
TimeZoneInfo.Local.GetUtcOffset(sourceDate))
Dim utcTime2 As Date = utcTime1.DateTime
If utcTime1.Offset.Equals(TimeZoneInfo.Local.GetUtcOffset(utcTime1.DateTime)) Then
utcTime2 = DateTime.SpecifyKind(utcTime2, DateTimeKind.Local)
End If
Console.WriteLine("{0} converted to {1} {2}", _
utcTime1, _
utcTime2, _
utcTime2.Kind.ToString())
' The example displays the following output to the console:
' 6/19/2008 7:00:00 AM -07:00 converted to 6/19/2008 7:00:00 AM Local
您可以使用 DateTimeOffset.LocalDateTime 屬性將 DateTimeOffset 值轉換為本機 DateTime 值。 傳回之 DateTime 值的 Kind 屬性是 Local。 下列程式碼在轉換一個其位移對應到當地時區位移的 DateTimeOffset 值時,使用 DateTimeOffset.LocalDateTime 屬性。
DateTime sourceDate = new DateTime(2008, 6, 19, 7, 0, 0);
DateTimeOffset localTime1 = new DateTimeOffset(sourceDate,
TimeZoneInfo.Local.GetUtcOffset(sourceDate));
DateTime localTime2 = localTime1.LocalDateTime;
Console.WriteLine($"{localTime1} converted to {localTime2} {localTime2.Kind}");
// The example displays the following output to the console:
// 6/19/2008 7:00:00 AM -07:00 converted to 6/19/2008 7:00:00 AM Local
Dim sourceDate As Date = #06/19/2008 7:00AM#
Dim localTime1 As New DateTimeOffset(sourceDate, _
TimeZoneInfo.Local.GetUtcOffset(sourceDate))
Dim localTime2 As Date = localTime1.LocalDateTime
Console.WriteLine("{0} converted to {1} {2}", _
localTime1, _
localTime2, _
localTime2.Kind.ToString())
' The example displays the following output to the console:
' 6/19/2008 7:00:00 AM -07:00 converted to 6/19/2008 7:00:00 AM Local
當您使用 DateTimeOffset.LocalDateTime 屬性擷取 DateTime 值時,屬性的 get
存取子會先將 DateTimeOffset 值轉換成 UTC,然後藉由呼叫 ToLocalTime 方法將它轉換成當地時間。 此行為表示您可以從 DateTimeOffset.LocalDateTime 屬性擷取值,以在您執行類型轉換的同時執行時區轉換。 這也表示會套用當地時區的調整規則,以執行轉換。 下列程式代碼說明如何使用 DateTimeOffset.LocalDateTime 屬性來執行型別和時區轉換。 範例輸出適用於設定為太平洋時區(美國和加拿大)的計算機。 11 月日期是太平洋標準時間,也就是 UTC-8,而 6 月日期為日光節約時間,也就是 UTC-7。
DateTimeOffset originalDate;
DateTime localDate;
// Convert time originating in a different time zone
originalDate = new DateTimeOffset(2008, 6, 18, 7, 0, 0,
new TimeSpan(-5, 0, 0));
localDate = originalDate.LocalDateTime;
Console.WriteLine($"{originalDate} converted to {localDate} {localDate.Kind}");
// Convert time originating in a different time zone
// so local time zone's adjustment rules are applied
originalDate = new DateTimeOffset(2007, 11, 4, 4, 0, 0,
new TimeSpan(-5, 0, 0));
localDate = originalDate.LocalDateTime;
Console.WriteLine($"{originalDate} converted to {localDate} {localDate.Kind}");
// The example displays the following output to the console,
// when you run it on a machine that is set to Pacific Time (US & Canada):
// 6/18/2008 7:00:00 AM -05:00 converted to 6/18/2008 5:00:00 AM Local
// 11/4/2007 4:00:00 AM -05:00 converted to 11/4/2007 1:00:00 AM Local
Dim originalDate As DateTimeOffset
Dim localDate As Date
' Convert time originating in a different time zone
originalDate = New DateTimeOffset(#06/19/2008 7:00AM#, _
New TimeSpan(-5, 0, 0))
localDate = originalDate.LocalDateTime
Console.WriteLine("{0} converted to {1} {2}", _
originalDate, _
localDate, _
localDate.Kind.ToString())
' Convert time originating in a different time zone
' so local time zone's adjustment rules are applied
originalDate = New DateTimeOffset(#11/04/2007 4:00AM#, _
New TimeSpan(-5, 0, 0))
localDate = originalDate.LocalDateTime
Console.WriteLine("{0} converted to {1} {2}", _
originalDate, _
localDate, _
localDate.Kind.ToString())
' The example displays the following output to the console,
' when you run it on a machine that is set to Pacific Time (US & Canada):
' 6/18/2008 7:00:00 AM -05:00 converted to 6/18/2008 5:00:00 AM Local
' 11/4/2007 4:00:00 AM -05:00 converted to 11/4/2007 1:00:00 AM Local
一般用途轉換方法
下列範例會定義名為 ConvertFromDateTimeOffset
的方法,將 DateTimeOffset 值轉換成 DateTime 值。 根據其位移,它會判斷 DateTimeOffset 值是否為 UTC 時間、當地時間或其他時間,並據此定義傳回的日期和時間值 Kind 屬性。
static DateTime ConvertFromDateTimeOffset(DateTimeOffset dateTime)
{
if (dateTime.Offset.Equals(TimeSpan.Zero))
return dateTime.UtcDateTime;
else if (dateTime.Offset.Equals(TimeZoneInfo.Local.GetUtcOffset(dateTime.DateTime)))
return DateTime.SpecifyKind(dateTime.DateTime, DateTimeKind.Local);
else
return dateTime.DateTime;
}
Function ConvertFromDateTimeOffset(dateTime As DateTimeOffset) As Date
If dateTime.Offset.Equals(TimeSpan.Zero) Then
Return dateTime.UtcDateTime
ElseIf dateTime.Offset.Equals(TimeZoneInfo.Local.GetUtcOffset(dateTime.DateTime))
Return Date.SpecifyKind(dateTime.DateTime, DateTimeKind.Local)
Else
Return dateTime.DateTime
End If
End Function
下列範例會呼叫 ConvertFromDateTimeOffset
方法來轉換 DateTimeOffset 值,這些值代表 UTC 時間、當地時間,以及美國中部標準時區的時間。
DateTime timeComponent = new DateTime(2008, 6, 19, 7, 0, 0);
DateTime returnedDate;
// Convert UTC time
DateTimeOffset utcTime = new DateTimeOffset(timeComponent, TimeSpan.Zero);
returnedDate = ConvertFromDateTimeOffset(utcTime);
Console.WriteLine($"{utcTime} converted to {returnedDate} {returnedDate.Kind}");
// Convert local time
DateTimeOffset localTime = new DateTimeOffset(timeComponent,
TimeZoneInfo.Local.GetUtcOffset(timeComponent));
returnedDate = ConvertFromDateTimeOffset(localTime);
Console.WriteLine($"{localTime} converted to {returnedDate} {returnedDate.Kind}");
// Convert Central Standard Time
DateTimeOffset cstTime = new DateTimeOffset(timeComponent,
TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time").GetUtcOffset(timeComponent));
returnedDate = ConvertFromDateTimeOffset(cstTime);
Console.WriteLine($"{cstTime} converted to {returnedDate} {returnedDate.Kind}");
// The example displays the following output to the console:
// 6/19/2008 7:00:00 AM +00:00 converted to 6/19/2008 7:00:00 AM Utc
// 6/19/2008 7:00:00 AM -07:00 converted to 6/19/2008 7:00:00 AM Local
// 6/19/2008 7:00:00 AM -05:00 converted to 6/19/2008 7:00:00 AM Unspecified
Dim timeComponent As Date = #06/19/2008 7:00AM#
Dim returnedDate As Date
' Convert UTC time
Dim utcTime As New DateTimeOffset(timeComponent, TimeSpan.Zero)
returnedDate = ConvertFromDateTimeOffset(utcTime)
Console.WriteLine("{0} converted to {1} {2}", _
utcTime, _
returnedDate, _
returnedDate.Kind.ToString())
' Convert local time
Dim localTime As New DateTimeOffset(timeComponent, _
TimeZoneInfo.Local.GetUtcOffset(timeComponent))
returnedDate = ConvertFromDateTimeOffset(localTime)
Console.WriteLine("{0} converted to {1} {2}", _
localTime, _
returnedDate, _
returnedDate.Kind.ToString())
' Convert Central Standard Time
Dim cstTime As New DateTimeOffset(timeComponent, _
TimeZoneInfo.FindSystemTimeZoneById("Central Standard Time").GetUtcOffset(timeComponent))
returnedDate = ConvertFromDateTimeOffset(cstTime)
Console.WriteLine("{0} converted to {1} {2}", _
cstTime, _
returnedDate, _
returnedDate.Kind.ToString())
' The example displays the following output to the console:
' 6/19/2008 7:00:00 AM +00:00 converted to 6/19/2008 7:00:00 AM Utc
' 6/19/2008 7:00:00 AM -07:00 converted to 6/19/2008 7:00:00 AM Local
' 6/19/2008 7:00:00 AM -05:00 converted to 6/19/2008 7:00:00 AM Unspecified
備註
程式代碼會根據應用程式和其日期和時間值的來源,進行下列兩個假設,可能不一定有效:
它會假設其位移為 TimeSpan.Zero 的日期和時間值代表 UTC。 事實上,UTC 不是屬於特定時區的時間,而是世界各地時區標準化的基準時間。 時區也可以有 Zero的時差。
它假設其位移等於當地時區的日期和時間代表當地時區。 因為日期和時間值會與其原始時區解除關聯,因此情況可能並非如此:日期和時間可能源自於具有相同位移的另一個時區。