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 DateTimeDateOnly 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 negativo TimeSpan 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 alla TimeOnly 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 scegliere DateTime.MinValue (0001-01-01) come data, tuttavia, se le ore vengono sottratte dal DateTime valore, potrebbe verificarsi un'eccezione OutOfRange . 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