Elección entre DateTime, DateOnly, DateTimeOffset, TimeSpan, TimeOnly y TimeZoneInfo
Las aplicaciones de .NET pueden usar la información de fecha y hora de varias maneras. Los usos más comunes de la información de fecha y hora incluyen:
- Reflejar solo la fecha (la información de hora no es importante).
- Reflejar solo la hora (la información de fecha no es importante).
- Reflejar una fecha y una hora abstractas que no estén asociadas a una hora ni a un lugar concretos (por ejemplo, la mayoría de tiendas de una cadena internacional abren los días laborables a las 09:00).
- Recuperar la información de fecha y hora de orígenes situados fuera de .NET en los que normalmente esta se almacena en un tipo de datos simple.
- Identificar de forma exclusiva e inequívoca un solo punto en el tiempo. Algunas aplicaciones requieren que una fecha y hora sea inequívoca solo en el sistema host. Otras aplicaciones requieren que sea inequívoca entre sistemas (es decir, que una fecha serializada en un sistema se pueda deserializar y usar con sentido en otro sistema en cualquier lugar en el mundo).
- Para conservar varias horas relacionadas (como la hora local del solicitante y la hora de recepción del servidor para una solicitud web).
- Realizar operaciones aritméticas de fecha y hora, posiblemente con un resultado que identifica de forma exclusiva e inequívoca un único punto en el tiempo.
.NET incluye los tipos DateTime, DateOnly, DateTimeOffset, TimeSpan, TimeOnly y TimeZoneInfo, que pueden usarse para compilar aplicaciones que funcionan con fechas y horas.
Nota
En este artículo no se habla de TimeZone porque su funcionalidad está incorporada casi por completo en la clase TimeZoneInfo. Siempre que sea posible, use la clase TimeZoneInfo en lugar de la clase TimeZone.
DateTimeOffset (estructura)
La estructura DateTimeOffset representa un valor de fecha y hora, junto con un desplazamiento que indica la diferencia de ese valor con respecto a la hora UTC. Por lo tanto, el valor identifica siempre de forma inequívoca un único punto en el tiempo.
El tipo DateTimeOffset incluye toda la funcionalidad del tipo DateTime junto con la zona horaria. Esto lo hace adecuado para aplicaciones que hacen lo siguiente:
- Identificar de forma exclusiva e inequívoca un solo punto en el tiempo. El tipo DateTimeOffset puede usarse para definir inequívocamente el significado de “ahora”, para registrar los tiempos de transacción, para registrar la hora de eventos del sistema o de aplicaciones, y para registrar los tiempos de creación y modificación de archivos.
- Realizar operaciones aritméticas generales de fecha y hora.
- Conservar varias horas relacionadas, siempre que esas horas se almacenen como dos valores independientes o como dos miembros de una estructura.
Nota
Estos usos de valores DateTimeOffset son mucho más comunes que los de valores DateTime . Por tanto, considere DateTimeOffset como el tipo de fecha y hora predeterminado para el desarrollo de aplicaciones.
Un valor DateTimeOffset no está asociado a una zona horaria determinada, pero puede originarse en distintas zonas horarias. En el ejemplo siguiente se enumeran las zonas horarias a las que pueden pertenecer varios valores DateTimeOffset (incluida una Hora estándar del Pacífico local).
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
La salida muestra que cada valor de fecha y hora de este ejemplo puede pertenecer al menos a tres zonas horarias diferentes. El valor DateTimeOffset de 6/10/2007 muestra que si un valor de fecha y hora representa un horario de verano, su diferencia horaria con UTC no se corresponde necesariamente con la diferencia horaria con UTC base de la zona horaria de origen ni con la diferencia horaria con UTC que se encuentra en su nombre para mostrar. Dado que un solo valor DateTimeOffset no está asociado estrechamente con su zona horaria, no puede reflejar un cambio de zona horaria con respecto al horario de verano. Esto puede ser problemático cuando se usan operaciones aritméticas de fecha y hora para manipular un valor DateTimeOffset. Para obtener información sobre cómo realizar operaciones aritméticas de fecha y hora teniendo en cuenta las reglas de ajuste de una zona horaria, consulte Efectuar operaciones aritméticas con fechas y horas.
DateTime (estructura)
Un valor DateTime define una fecha y hora concretas. Incluye una propiedad Kind que proporciona información limitada sobre la zona horaria a la que pertenece esa fecha y hora. El valor DateTimeKind devuelto por la propiedad Kind indica si el valor DateTime representa la hora local (DateTimeKind.Local), la hora universal coordinada (UTC) (DateTimeKind.Utc) o una hora no especificada (DateTimeKind.Unspecified).
La estructura DateTime es adecuada para aplicaciones con una o varias de las siguientes características:
- Trabajar con fechas y horas abstractas.
- Trabajar con fechas y horas cuya información de zona horaria no esté disponible.
- Trabajar solo con fechas y horas UTC.
- Realizar operaciones aritméticas de fecha y hora, pero con interés por los resultados generales. Por ejemplo, en una operación que suma seis meses a una determinada fecha y hora, a menudo no resulta importante si el resultado se ajusta al horario de verano.
A menos que un determinado valor DateTime represente la hora UTC, ese valor de fecha y hora suele ser ambiguo o limitado en su movilidad. Por ejemplo, si un valor DateTime representa la hora local, entonces se puede mover en la zona horaria local (es decir, si el valor se deserializa en otro sistema de la misma zona horaria, dicho valor sigue identificando inequívocamente un único punto en el tiempo). Fuera de la zona horaria local, ese valor DateTime puede tener varias interpretaciones. Si la propiedad Kind del valor es DateTimeKind.Unspecified, es aún menos móvil: ahora es ambiguo dentro de la misma zona horaria y posiblemente incluso en el mismo sistema en el que se serializó por primera vez. Solo si un valor DateTime representa la hora UTC, ese valor identificará inequívocamente un único punto con independencia del sistema o la zona horaria en los que se usa el valor.
Importante
Al guardar o compartir datos DateTime, use UTC y establezca la propiedad Kind del valor DateTime en DateTimeKind.Utc.
Estructura DateOnly
La estructura DateOnly representa una fecha específica, sin hora. Como no tiene ningún componente de hora, representa una fecha desde el inicio hasta el final del día. Esta estructura es ideal para almacenar fechas específicas, como una fecha de nacimiento, una fecha de aniversario, un día festivo o una fecha relacionada con la empresa.
Aunque puede usar DateTime y omitir el componente de hora, hay algunas ventajas al usar DateOnly en vez de DateTime:
- La estructura
DateTimepuede pasar al día anterior o al día siguiente si se desplaza por una zona horaria.DateOnlyno se puede desplazar por una zona horaria y siempre representa la fecha establecida. - Serializar una estructura
DateTimeincluye el componente de hora, que puede ocultar la intención de los datos. Además,DateOnlyserializa menos datos. - Cuando el código interactúa con una base de datos, como SQL Server, las fechas completas se almacenan generalmente como el tipo de datos
date, que no incluye una hora.DateOnlycoincide mejor con el tipo de base de datos.
Para obtener más información sobre DateOnly, consulte Cómo usar las estructuras DateOnly y TimeOnly.
Importante
DateOnly no está disponible en .NET Framework.
TimeSpan (estructura)
La estructura TimeSpan representa un intervalo de tiempo. Sus dos usos típicos son:
- Reflejar el intervalo de tiempo entre dos valores de fecha y hora. Por ejemplo, restar un valor DateTime de otro devuelve un valor TimeSpan .
- Medir el tiempo transcurrido. Por ejemplo, la propiedad Stopwatch.Elapsed devuelve un valor TimeSpan que refleja el intervalo de tiempo transcurrido desde la llamada a uno de los métodos Stopwatch que empieza a medir el tiempo transcurrido.
Un valor TimeSpan también puede usarse como sustituto de un valor DateTime cuando ese valor refleja una hora sin referencia a un día determinado. Este uso es similar a las propiedades DateTime.TimeOfDay y DateTimeOffset.TimeOfDay, que devuelven un valor TimeSpan que representa la hora sin referencia a una fecha. Por ejemplo, la estructura TimeSpan puede usarse para reflejar la hora diaria de apertura o cierre de una tienda, o puede usarse para representar la hora en que se produce cualquier evento habitual.
En el ejemplo siguiente se define una estructura StoreInfo que incluye objetos TimeSpan para las horas de apertura y cierre de la tienda, así como un objeto TimeZoneInfo que representa la zona horaria de la tienda. La estructura también incluye dos métodos, IsOpenNow e IsOpenAt, que indican si la tienda está abierta en el momento especificado por el usuario, quien se supone que está en la zona horaria local.
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 estructura StoreInfo puede usarla un código de cliente como este.
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: True
// Store is open at 04:59:00: False
// Store is open at 18:31:00: True
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
Estructura TimeOnly
La estructura TimeOnly representa un valor de momento del día, como un reloj de alarma diario o la hora de comer cada día. TimeOnly se limita al intervalo de 00:00:00.0000000 - 23:59:59.9999999, una hora específica del día.
Antes de introducir el tipo TimeOnly, los programadores solían usar el tipo DateTime o el TimeSpan para representar una hora específica. Pero el uso de estas estructuras para simular una hora sin una fecha puede presentar algunos problemas, que TimeOnly resuelve:
TimeSpanrepresenta el tiempo transcurrido, como el tiempo medido con un cronómetro. El rango superior es de más de 29 000 años, y su valor puede ser negativo para indicar que se mueve hacia atrás. UnTimeSpannegativo no indica una hora específica del día.- Si
TimeSpanse usa como hora del día, existe el riesgo de que se pueda manipular en un valor fuera del día de 24 horas.TimeOnlyno tiene este riesgo. Por ejemplo, si el turno de trabajo de un empleado comienza a las 18:00 y dura 8 horas, la adición de 8 horas a la estructuraTimeOnlypasa a las 2:00 - El uso de
DateTimepara una hora del día requiere que se asocie una fecha arbitraria a la hora y se omita más adelante. Es habitual elegirDateTime.MinValue(0001-01-01-01) como fecha, pero si las horas se restan del valorDateTime, podría producirse una excepciónOutOfRange.TimeOnlyno tiene este problema, ya que el tiempo se avanza y retrocede alrededor del marco de tiempo de 24 horas. - Serializar una estructura
DateTimeincluye el componente de fecha, que puede ocultar la intención de los datos. Además,TimeOnlyserializa menos datos.
Para obtener más información sobre TimeOnly, consulte Cómo usar las estructuras DateOnly y TimeOnly.
Importante
TimeOnly no está disponible en .NET Framework.
TimeZoneInfo (clase)
La clase 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 clase TimeZoneInfo permite trabajar con valores de fecha y hora de forma que cada uno de esos valores identifique de forma inequívoca un único punto en el tiempo. La clase TimeZoneInfo también es extensible. Aunque depende de la información de zona horaria proporcionada para los sistemas Windows y definida en el Registro, admite la creación de zonas horarias personalizadas. También admite la serialización y deserialización de la información de zona horaria.
En algunos casos, si desea aprovechar al máximo la clase TimeZoneInfo puede que tenga que desarrollar aún más. Si los valores de fecha y hora no están asociados estrechamente con las zonas horarias a las que pertenecen, hay que hacer más cosas. A menos que la aplicación proporcione algún mecanismo para vincular una fecha y hora con su zona horaria asociada, es fácil que un determinado valor de fecha y hora se desasocie de su zona horaria. Un método para vincular esta información es definir una clase o estructura que contenga el valor de fecha y hora, y su objeto de zona horaria asociada.
Para aprovechar la compatibilidad de zona horaria en .NET, debe conocer la zona horaria a la que pertenece un valor de fecha y hora cuando se crea una instancia de ese objeto de fecha y hora. La zona horaria a menudo no se conoce, especialmente en aplicaciones web o de red.
