DateTimeOffset (Estructura)

La estructura DateTimeOffset incluye un valor DateTime, junto con una propiedad Offset que define la diferencia entre la fecha y hora de la instancia actual de DateTimeOffset y la hora universal coordinada (UTC). Dado que define exactamente una fecha y hora con respecto a la hora UTC, la estructura DateTimeOffset no incluye un miembro Kind, a diferencia de la estructura DateTime. Representa las fechas y horas con valores cuya hora UTC va de las 00:00:00 de la media noche del 1 de enero de 0001 d.C., a las 11:59:59 p.m. del 31 de diciembre de 9999 d.C. (Era cristiana).

El componente de hora de un valor DateTimeOffset se miden en unidades de 100 nanosegundos denominadas pasos, y una fecha concreta es el número de pasos transcurridos desde la medianoche (00:00) del 1 de enero de 0001 d.C. (C.E.) en el calendario GregorianCalendar. Un valor DateTimeOffset siempre se expresa en el contexto de un calendario explícito o predeterminado. Los pasos que son atribuibles a los segundos intercalados no se incluyen en el número de pasos total.

Nota

Si está trabajando con un valor de pasos que desea convertir en algún otro intervalo de hora, como minutos o segundos, debería utilizar las constantes TimeSpan.TicksPerDay, TimeSpan.TicksPerHour, TimeSpan.TicksPerMinute, TimeSpan.TicksPerSecond o TimeSpan.TicksPerMillisecond para la conversión. Por ejemplo, para sumar el número de segundos representado por un número especificado de pasos al componente Second de un valor DateTimeOffset, utilice la expresión dateValue.Second + nTicks/Timespan.TicksPerSecond.

Aunque un valor DateTimeOffset incluye un desplazamiento, no es una estructura de datos totalmente orientada a la zona horaria. Aunque un desplazamiento de hora UTC es una característica de una zona horaria, no identifica inequívocamente una zona horaria. No sólo varias zonas horarias comparten el mismo desplazamiento de hora UTC, además el desplazamiento de una misma zona horaria cambia si utiliza el horario de verano. Esto significa que, en cuanto un valor DateTimeOffset se desasocia de su zona horaria, ya no puede volver a vincularse inequívocamente a su zona horaria original.

Como DateTimeOffset es una estructura, un objeto DateTimeOffset que se ha declarado pero no se ha inicializado contiene valores predeterminados para cada uno de sus campos miembro. Esto significa que su propiedad DateTime se establece en DateTimeOffset.MinValue y su propiedad Offset se establece en TimeSpan.Zero.

Puede crear un nuevo valor DateTimeOffset llamando a cualquiera de las sobrecargas de su constructor, que son similares a los constructores sobrecargados para la estructura DateTime. También puede crear un nuevo valor DateTimeOffset asignándole un valor DateTime. Esta es una conversión implícita; no requiere un operador de conversión (en C#) ni llamar a un método de conversión (en Visual Basic). También puede inicializar un valor DateTimeOffset a partir de la representación de cadena de una fecha y hora llamando a varios métodos de análisis de cadenas estáticas, entre los que se incluyen Parse, ParseExact, TryParse y TryParseExact.

Los miembros de la estructura DateTimeOffset proporcionan funcionalidad en las áreas siguientes:

• Aritmética de fecha y hora.

  Puede sumar o restar intervalos de fecha u hora de un valor DateTimeOffset determinado. En las operaciones aritmética con valores DateTimeOffset, a diferencia de aquéllas con valores DateTime, se ajustan para las diferencias en los desplazamientos de hora al devolver un resultado. Por ejemplo, en el código siguiente se usan variables DateTime para restar la hora local actual de la hora UTC actual. A continuación, en el código se usan variables DateTimeOffset para realizar la misma operación. La resta con valores DateTime devuelve la diferencia entre la zona horaria local y la hora UTC, mientras la resta con valores DateTimeOffset devuelve TimeSpan.Zero.

  C#

  VB

  Copiar

  
  using System;
  
  public class DateArithmetic
  {
     public static void Main()
     {
        DateTime date1, date2;
        DateTimeOffset dateOffset1, dateOffset2;
        TimeSpan difference;
  
        // Find difference between Date.Now and Date.UtcNow
        date1 = DateTime.Now;
        date2 = DateTime.UtcNow;
        difference = date1 - date2;
        Console.WriteLine("{0} - {1} = {2}", date1, date2, difference);
  
        // Find difference between Now and UtcNow using DateTimeOffset
        dateOffset1 = DateTimeOffset.Now;
        dateOffset2 = DateTimeOffset.UtcNow;
        difference = dateOffset1 - dateOffset2;
        Console.WriteLine("{0} - {1} = {2}", 
                          dateOffset1, dateOffset2, difference);
        // If run in the Pacific Standard time zone on 4/2/2007, the example
        // displays the following output to the console:
        //    4/2/2007 7:23:57 PM - 4/3/2007 2:23:57 AM = -07:00:00
        //    4/2/2007 7:23:57 PM -07:00 - 4/3/2007 2:23:57 AM +00:00 = 00:00:00                        
     }
  }
  
  
  

• Operaciones de conversión de tipo.

  Los valores DateTimeOffset pueden convertirse en valores DateTime y viceversa.

• Operaciones de extracción y manipulación de la hora.

  Puede extraerse la fecha o la hora de un valor DateTimeOffset. También puede recuperarse el valor de un componente DateTimeOffset determinado, como el año o el mes.

• Conversión de fecha y hora.

  Cualquier valor DateTimeOffset puede convertirse en otro valor DateTimeOffset que representa el mismo momento en el tiempo en otra zona horaria. Sin embargo, las reglas de ajuste de una zona horaria sólo se aplican en el caso del método ToLocalTime, que convierte un valor DateTimeOffset en la fecha y hora de la zona del sistema local.

• Comparación de fecha y hora.

  Puede determinarse si cualquier valor DateTimeOffset determinado es anterior, igual o posterior a otro valor DateTimeOffset. Antes de realizar la comparación, todos los valores se convierten a la hora UTC.

.NET Framework

.NET Framework Client Profile

Biblioteca de clases portable

.NET para aplicaciones de la Tienda Windows

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (no se admite el rol Server Core), Windows Server 2008 R2 (se admite el rol Server Core con SP1 o versiones posteriores; no se admite Itanium)

Referencia

Otros recursos