Scegliere tra DateTime, DateOnly, DateTimeOffset, TimeSpan, TimeOnly e TimeZoneInfo
Le applicazioni .NET possono usare informazioni di data e ora in diversi modi. Gli usi più comuni delle informazioni relative a data e ora includono:
- Indicare solo una data, perché le informazioni sull'ora non sono importanti.
- Indicare solo un'ora, perché le informazioni sulla data non sono importanti.
- Per riflettere una data e un'ora astratte che non sono legate a un'ora e un luogo specifici (ad esempio, la maggior parte dei negozi in una catena internazionale aperta nei giorni feriali alle 9:00).
- Per recuperare informazioni di data e ora da origini esterne a .NET, in genere in cui le informazioni di data e ora vengono archiviate in un tipo di dati semplice.
- Identificare in modo univoco e senza ambiguità un singolo momento. Alcune applicazioni richiedono che una data e un'ora siano ambigue solo nel sistema host. Altre app richiedono che siano ambigue in tutti i sistemi( ovvero una data serializzata in un sistema può essere deserializzata in modo significativo e usata in un altro sistema in qualsiasi punto del mondo).
- Per mantenere più volte correlate, ad esempio l'ora locale del richiedente e l'ora di ricezione del server per una richiesta Web.
- Eseguire operazioni aritmetiche per date e ore, possibilmente con un risultato che identifichi in modo univoco e senza ambiguità una singolo momento.
.NET include i DateTimetipi , DateTimeOffsetDateOnly, TimeSpan, TimeOnly, e TimeZoneInfo , che possono essere usati per compilare applicazioni che funzionano con date e ore.
Nota
Questo articolo non illustra TimeZone perché la sua funzionalità è quasi interamente incorporata nella TimeZoneInfo classe . Quando possibile, usare la TimeZoneInfo classe anziché la TimeZone classe .
Struttura DateTimeOffset
La struttura DateTimeOffset rappresenta un valore di data e ora, insieme a un offset che indica la differenza di tale valore rispetto all'ora UTC. In questo modo, il valore identifica sempre senza ambiguità un singolo momento.
Il tipo DateTimeOffset include tutte le funzionalità del tipo DateTime insieme alla compatibilità del fuso orario. In questo modo è adatto per le applicazioni che:
- Identificano in modo univoco e non ambiguo un singolo momento. Il tipo DateTimeOffset può essere usato per definire senza ambiguità il significato di "adesso", per registrare data e ora delle transazioni, del sistema o degli eventi delle applicazioni, nonché registrare data e ora di creazione e modifica dei file.
- Eseguono operazioni aritmetiche su data e ora.
- Mantengono più date e ore correlate, purché vengano archiviate come due valori separati o due membri di una struttura.
Nota
Questi utilizzi per i valori DateTimeOffset sono molto più comuni di quelli per i valori DateTime . Di conseguenza, considerare DateTimeOffset come tipo di data e ora predefinito per lo sviluppo di applicazioni.
Un DateTimeOffset valore non è associato a un determinato fuso orario, ma può provenire da un'ampia gamma di fusi orari. L'esempio seguente elenca i fusi orari a cui può appartenere un numero di DateTimeOffset valori (incluso un orario standard del Pacifico locale).
using System;
using System.Collections.ObjectModel;
public class TimeOffsets
{
public static void Main()
{
DateTime thisDate = new DateTime(2007, 3, 10, 0, 0, 0);
DateTime dstDate = new DateTime(2007, 6, 10, 0, 0, 0);
DateTimeOffset thisTime;
thisTime = new DateTimeOffset(dstDate, new TimeSpan(-7, 0, 0));
ShowPossibleTimeZones(thisTime);
thisTime = new DateTimeOffset(thisDate, new TimeSpan(-6, 0, 0));
ShowPossibleTimeZones(thisTime);
thisTime = new DateTimeOffset(thisDate, new TimeSpan(+1, 0, 0));
ShowPossibleTimeZones(thisTime);
}
private static void ShowPossibleTimeZones(DateTimeOffset offsetTime)
{
TimeSpan offset = offsetTime.Offset;
ReadOnlyCollection<TimeZoneInfo> timeZones;
Console.WriteLine("{0} could belong to the following time zones:",
offsetTime.ToString());
// Get all time zones defined on local system
timeZones = TimeZoneInfo.GetSystemTimeZones();
// Iterate time zones
foreach (TimeZoneInfo timeZone in timeZones)
{
// Compare offset with offset for that date in that time zone
if (timeZone.GetUtcOffset(offsetTime.DateTime).Equals(offset))
Console.WriteLine(" {0}", timeZone.DisplayName);
}
Console.WriteLine();
}
}
// This example displays the following output to the console:
// 6/10/2007 12:00:00 AM -07:00 could belong to the following time zones:
// (GMT-07:00) Arizona
// (GMT-08:00) Pacific Time (US & Canada)
// (GMT-08:00) Tijuana, Baja California
//
// 3/10/2007 12:00:00 AM -06:00 could belong to the following time zones:
// (GMT-06:00) Central America
// (GMT-06:00) Central Time (US & Canada)
// (GMT-06:00) Guadalajara, Mexico City, Monterrey - New
// (GMT-06:00) Guadalajara, Mexico City, Monterrey - Old
// (GMT-06:00) Saskatchewan
//
// 3/10/2007 12:00:00 AM +01:00 could belong to the following time zones:
// (GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna
// (GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague
// (GMT+01:00) Brussels, Copenhagen, Madrid, Paris
// (GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb
// (GMT+01:00) West Central Africa
Imports System.Collections.ObjectModel
Module TimeOffsets
Public Sub Main()
Dim thisTime As DateTimeOffset
thisTime = New DateTimeOffset(#06/10/2007#, New TimeSpan(-7, 0, 0))
ShowPossibleTimeZones(thisTime)
thisTime = New DateTimeOffset(#03/10/2007#, New TimeSpan(-6, 0, 0))
ShowPossibleTimeZones(thisTime)
thisTime = New DateTimeOffset(#03/10/2007#, New TimeSpan(+1, 0, 0))
ShowPossibleTimeZones(thisTime)
End Sub
Private Sub ShowPossibleTimeZones(offsetTime As DateTimeOffset)
Dim offset As TimeSpan = offsetTime.Offset
Dim timeZones As ReadOnlyCollection(Of TimeZoneInfo)
Console.WriteLine("{0} could belong to the following time zones:", _
offsetTime.ToString())
' Get all time zones defined on local system
timeZones = TimeZoneInfo.GetSystemTimeZones()
' Iterate time zones
For Each timeZone As TimeZoneInfo In timeZones
' Compare offset with offset for that date in that time zone
If timeZone.GetUtcOffset(offsetTime.DateTime).Equals(offset) Then
Console.WriteLine(" {0}", timeZone.DisplayName)
End If
Next
Console.WriteLine()
End Sub
End Module
' This example displays the following output to the console:
' 6/10/2007 12:00:00 AM -07:00 could belong to the following time zones:
' (GMT-07:00) Arizona
' (GMT-08:00) Pacific Time (US & Canada)
' (GMT-08:00) Tijuana, Baja California
'
' 3/10/2007 12:00:00 AM -06:00 could belong to the following time zones:
' (GMT-06:00) Central America
' (GMT-06:00) Central Time (US & Canada)
' (GMT-06:00) Guadalajara, Mexico City, Monterrey - New
' (GMT-06:00) Guadalajara, Mexico City, Monterrey - Old
' (GMT-06:00) Saskatchewan
'
' 3/10/2007 12:00:00 AM +01:00 could belong to the following time zones:
' (GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna
' (GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague
' (GMT+01:00) Brussels, Copenhagen, Madrid, Paris
' (GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb
' (GMT+01:00) West Central Africa
L'output mostra che ogni valore di data e ora nell'esempio può appartenere almeno a tre fusi orari diversi. Il DateTimeOffset valore 10/6/2007 indica che se un valore di data e ora rappresenta un'ora legale, la differenza rispetto all'ora UTC non corrisponde necessariamente all'offset UTC di base del fuso orario di origine o all'offset dall'ora UTC trovata nel nome visualizzato. Poiché un singolo DateTimeOffset valore non è strettamente associato al proprio fuso orario, non può riflettere la transizione di un fuso orario da e verso l'ora legale. Ciò può essere problematico quando viene usata l'aritmetica di data e ora per modificare un DateTimeOffset valore. Per informazioni su come eseguire operazioni aritmetiche per date e ore che tengano conto delle regole di adeguamento del fuso orario, vedere Performing arithmetic operations with dates and times (Esecuzione di operazioni aritmetiche con date e ore).
Struttura DateTime
Un valore DateTime definisce una data e un'ora specifiche. Include una Kind proprietà che fornisce informazioni limitate sul fuso orario a cui appartiene la data e l'ora. Il valore DateTimeKind restituito dalla proprietà Kind indica se il valore DateTime rappresenta l'ora locale (DateTimeKind.Local), l'ora UTC (Coordinated Universal Time) (DateTimeKind.Utc) o un'ora non specificata (DateTimeKind.Unspecified).
La DateTime struttura è adatta alle applicazioni con una o più delle caratteristiche seguenti:
- Usano date e ore astratte.
- Usano date e ore per le quali mancano informazioni sul fuso orario.
- Usano solo date e ore UTC.
- Eseguono operazioni aritmetiche su date e ore, ma con particolare attenzione ai risultati generali. Ad esempio, in un'operazione di addizione che aggiunge sei mesi a una data e un'ora specifiche, spesso non è importante se il risultato viene adattato per l'ora legale.
A meno che un determinato valore DateTime non rappresenti un'ora UTC, il valore di data e ora è spesso ambiguo e limitato in fatto di portabilità. Ad esempio, se un DateTime valore rappresenta l'ora locale, è portabile all'interno del fuso orario locale, ovvero se il valore viene deserializzato in un altro sistema nello stesso fuso orario, tale valore identifica comunque un singolo punto nel tempo. Al di fuori del fuso orario locale, tale valore DateTime è soggetto a più interpretazioni. Se la proprietà del Kind valore è DateTimeKind.Unspecified, è ancora meno portabile: ora è ambigua all'interno dello stesso fuso orario e possibilmente anche nello stesso sistema in cui è stata serializzata per la prima volta. Solo se un valore DateTime rappresenta un'ora UTC, identifica senza ambiguità un singolo momento, indipendentemente dal sistema o dal fuso orario in cui viene usato.
Importante
Quando si salvano o si condividono DateTime i dati, usare utc e impostare la DateTime proprietà del Kind valore su DateTimeKind.Utc.
Struttura DateOnly
La DateOnly struttura rappresenta una data specifica, senza ora. Poiché non dispone di alcun componente ora, rappresenta una data dall'inizio del giorno alla fine del giorno. Questa struttura è ideale per archiviare date specifiche, ad esempio una data di nascita, una data di anniversario, una festività o una data di business.
Anche se è possibile usare durante l'ignorare il componente time, esistono alcuni vantaggi da usare DateTime
DateOnly
in DateTime
:
- La
DateTime
struttura può essere spostata nel giorno precedente o successivo se è scostato da un fuso orario.DateOnly
non può essere offset in base a un fuso orario e rappresenta sempre la data impostata. - La serializzazione di una
DateTime
struttura include il componente time, che può nascondere la finalità dei dati.DateOnly
Serializza anche meno dati. - Quando il codice interagisce con un database, ad esempio SQL Server, le date intere vengono in genere archiviate come tipo di dati, che non includono un'ora
date
.DateOnly
corrisponde al tipo di database migliore.
Per altre informazioni su DateOnly
, vedere Come usare le strutture DateOnly e TimeOnly.
Importante
DateOnly
non è disponibile in .NET Framework.
Struttura TimeSpan
La struttura TimeSpan rappresenta un intervallo di tempo. Ecco i due utilizzi tipici:
- Indicare l'intervallo di tempo tra due valori di data e ora. Ad esempio, la sottrazione di un valore DateTime da un altro restituisce un valore TimeSpan .
- Misurare il tempo trascorso. Ad esempio, la Stopwatch.Elapsed proprietà restituisce un TimeSpan valore che riflette l'intervallo di tempo trascorso dalla chiamata a uno dei Stopwatch metodi che inizia a misurare il tempo trascorso.
Un TimeSpan valore può essere usato anche come sostituzione di un DateTime valore quando tale valore riflette un'ora senza riferimento a un determinato giorno. Questo utilizzo è simile alle DateTime.TimeOfDay proprietà e DateTimeOffset.TimeOfDay , che restituiscono un TimeSpan valore che rappresenta l'ora senza riferimento a una data. Ad esempio, la struttura TimeSpan può essere usata per indicare l'ora di apertura o di chiusura di un negozio oppure per rappresentare l'ora a cui si verifica un evento regolare.
L'esempio seguente definisce una struttura StoreInfo
che include oggetti TimeSpan per le ore di apertura e di chiusura di un negozio, nonché un oggetto TimeZoneInfo che rappresenta il fuso orario del negozio. La struttura include anche due metodi, IsOpenNow
e IsOpenAt
, che indicano se il negozio è aperto a un'ora specificata dall'utente, che si suppone si trovi nel fuso orario locale.
using System;
public struct StoreInfo
{
public String store;
public TimeZoneInfo tz;
public TimeSpan open;
public TimeSpan close;
public bool IsOpenNow()
{
return IsOpenAt(DateTime.Now.TimeOfDay);
}
public bool IsOpenAt(TimeSpan time)
{
TimeZoneInfo local = TimeZoneInfo.Local;
TimeSpan offset = TimeZoneInfo.Local.BaseUtcOffset;
// Is the store in the same time zone?
if (tz.Equals(local)) {
return time >= open & time <= close;
}
else {
TimeSpan delta = TimeSpan.Zero;
TimeSpan storeDelta = TimeSpan.Zero;
// Is it daylight saving time in either time zone?
if (local.IsDaylightSavingTime(DateTime.Now.Date + time))
delta = local.GetAdjustmentRules()[local.GetAdjustmentRules().Length - 1].DaylightDelta;
if (tz.IsDaylightSavingTime(TimeZoneInfo.ConvertTime(DateTime.Now.Date + time, local, tz)))
storeDelta = tz.GetAdjustmentRules()[tz.GetAdjustmentRules().Length - 1].DaylightDelta;
TimeSpan comparisonTime = time + (offset - tz.BaseUtcOffset).Negate() + (delta - storeDelta).Negate();
return comparisonTime >= open & comparisonTime <= close;
}
}
}
Public Structure StoreInfo
Dim store As String
Dim tz As TimeZoneInfo
Dim open As TimeSpan
Dim close As TimeSpan
Public Function IsOpenNow() As Boolean
Return IsOpenAt(Date.Now.TimeOfDay)
End Function
Public Function IsOpenAt(time As TimeSpan) As Boolean
Dim local As TimeZoneInfo = TimeZoneInfo.Local
Dim offset As TimeSpan = TimeZoneInfo.Local.BaseUtcOffset
' Is the store in the same time zone?
If tz.Equals(local) Then
Return time >= open AndAlso time <= close
Else
Dim delta As TimeSpan = TimeSpan.Zero
Dim storeDelta As TimeSpan = TimeSpan.Zero
' Is it daylight saving time in either time zone?
If local.IsDaylightSavingTime(Date.Now.Date + time) Then
delta = local.GetAdjustmentRules(local.GetAdjustmentRules().Length - 1).DaylightDelta
End If
If tz.IsDaylightSavingTime(TimeZoneInfo.ConvertTime(Date.Now.Date + time, local, tz))
storeDelta = tz.GetAdjustmentRules(tz.GetAdjustmentRules().Length - 1).DaylightDelta
End If
Dim comparisonTime As TimeSpan = time + (offset - tz.BaseUtcOffset).Negate() + (delta - storeDelta).Negate
Return (comparisonTime >= open AndAlso comparisonTime <= close)
End If
End Function
End Structure
La struttura StoreInfo
può quindi essere usata da codice client simile al seguente.
public class Example
{
public static void Main()
{
// Instantiate a StoreInfo object.
var store103 = new StoreInfo();
store103.store = "Store #103";
store103.tz = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time");
// Store opens at 8:00.
store103.open = new TimeSpan(8, 0, 0);
// Store closes at 9:30.
store103.close = new TimeSpan(21, 30, 0);
Console.WriteLine("Store is open now at {0}: {1}",
DateTime.Now.TimeOfDay, store103.IsOpenNow());
TimeSpan[] times = { new TimeSpan(8, 0, 0), new TimeSpan(21, 0, 0),
new TimeSpan(4, 59, 0), new TimeSpan(18, 31, 0) };
foreach (var time in times)
Console.WriteLine("Store is open at {0}: {1}",
time, store103.IsOpenAt(time));
}
}
// The example displays the following output:
// Store is open now at 15:29:01.6129911: True
// Store is open at 08:00:00: True
// Store is open at 21:00:00: False
// Store is open at 04:59:00: False
// Store is open at 18:31:00: False
Module Example
Public Sub Main()
' Instantiate a StoreInfo object.
Dim store103 As New StoreInfo()
store103.store = "Store #103"
store103.tz = TimeZoneInfo.FindSystemTimeZoneById("Eastern Standard Time")
' Store opens at 8:00.
store103.open = new TimeSpan(8, 0, 0)
' Store closes at 9:30.
store103.close = new TimeSpan(21, 30, 0)
Console.WriteLine("Store is open now at {0}: {1}",
Date.Now.TimeOfDay, store103.IsOpenNow())
Dim times() As TimeSpan = {New TimeSpan(8, 0, 0),
New TimeSpan(21, 0, 0),
New TimeSpan(4, 59, 0),
New TimeSpan(18, 31, 0)}
For Each time In times
Console.WriteLine("Store is open at {0}: {1}",
time, store103.IsOpenAt(time))
Next
End Sub
End Module
' The example displays the following output:
' Store is open now at 15:29:01.6129911: True
' Store is open at 08:00:00: True
' Store is open at 21:00:00: False
' Store is open at 04:59:00: False
' Store is open at 18:31:00: False
Struttura TimeOnly
La TimeOnly struttura rappresenta un valore di ora del giorno, ad esempio un orario di sveglia giornaliero o l'ora in cui si mangia il pranzo ogni giorno. TimeOnly
è limitato all'intervallo di 00:00:00.00000000 - 23:59:59.999999999, un'ora specifica del giorno.
Prima dell'introduzione del TimeOnly
tipo, i programmatori usano in genere il DateTime tipo o il TimeSpan tipo per rappresentare un orario specifico. Tuttavia, l'uso di queste strutture per simulare un'ora senza una data può introdurre alcuni problemi, che TimeOnly
risolvono:
TimeSpan
rappresenta il tempo trascorso, ad esempio il tempo misurato con un orologio di arresto. L'intervallo superiore è superiore a 29.000 anni e il relativo valore può essere negativo per indicare lo spostamento indietro nel tempo. Un negativoTimeSpan
non indica un'ora specifica del giorno.- Se
TimeSpan
viene usato come ora del giorno, esiste il rischio che possa essere modificato in un valore al di fuori del giorno di 24 ore.TimeOnly
non ha questo rischio. Ad esempio, se il turno di lavoro di un dipendente inizia alle 18:00 e dura 8 ore, aggiungendo 8 ore allaTimeOnly
struttura passa a 2:00. - L'uso
DateTime
di per un'ora del giorno richiede che una data arbitraria sia associata all'ora e quindi ignorata in un secondo momento. È prassi comune scegliereDateTime.MinValue
(0001-01-01) come data, tuttavia, se le ore vengono sottratte dalDateTime
valore, potrebbe verificarsi un'eccezioneOutOfRange
.TimeOnly
non presenta questo problema perché il tempo scorre avanti e indietro intorno all'intervallo di tempo di 24 ore. - La serializzazione di una
DateTime
struttura include il componente data, che può nascondere la finalità dei dati.TimeOnly
Serializza anche meno dati.
Per altre informazioni su TimeOnly
, vedere Come usare le strutture DateOnly e TimeOnly.
Importante
TimeOnly
non è disponibile in .NET Framework.
Classe TimeZoneInfo
La classe TimeZoneInfo class represents any of the Earth's time zones, and enables the conversion of any date and time in one time zone to its equivalent in another time zone. La classe TimeZoneInfo permette di usare date e ore in modo che qualsiasi valore di data e ora identifichi un singolo momento senza ambiguità. La classe TimeZoneInfo può anche essere estesa. Benché dipenda dalle informazioni sul fuso orario fornite per i sistemi Windows e definite nel Registro di sistema, questa classe supporta la creazione di fusi orari personalizzati. Supporta anche la serializzazione e la deserializzazione delle informazioni sul fuso orario.
In alcuni casi, per sfruttare tutti i vantaggi della classe TimeZoneInfo possono essere necessarie attività aggiuntive di sviluppo. Se i valori di data e ora non sono strettamente associati ai fusi orari a cui appartengono, è necessario eseguire ulteriori operazioni. A meno che l'applicazione non fornisca un meccanismo per collegare una data e un'ora al fuso orario associato, è facile che un determinato valore di data e ora diventi disassociato dal fuso orario. Un metodo per collegare queste informazioni consiste nel definire una classe o una struttura che contiene sia i valori di data e ora sia l'oggetto fuso orario associato.
Per sfruttare il supporto del fuso orario in .NET, è necessario conoscere il fuso orario a cui appartiene un valore di data e ora quando viene creata un'istanza dell'oggetto data e ora. Il fuso orario spesso non è noto, in particolare nelle app Web o di rete.
Vedi anche
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: nel corso del 2024 verranno dismessi i problemi di GitHub come meccanismo di feedback per il contenuto e verranno sostituiti con un nuovo sistema di feedback. Per altre informazioni, vedere:Invia e visualizza il feedback per