DateTime (Estructura)

Puede crear un nuevo valor de DateTime de cualquiera de las maneras siguientes:

• Mediante una llamada a cualquiera de las sobrecargas del constructor DateTime que permiten especificar elementos concretos del valor de fecha y hora (como el año, el mes y el día o el número de pasos). En la instrucción siguiente se muestra una llamada a uno de los constructores DateTime para crear una fecha con un año, mes, día, hora, minuto y segundo concretos.

  C#

  VB

  Copiar

  
  DateTime date1 = new DateTime(2008, 5, 1, 8, 30, 52);
  
  
  

• Mediante cualquier sintaxis específica del compilador para declarar los valores de fecha y hora. Por ejemplo, la siguiente instrucción de Visual Basic inicializa un nuevo valor de DateTime.

  VB

  Copiar

  
  Dim date1 As Date = #5/1/2008 8:30:52AM#
  
  
  

• Mediante la asignación al objeto DateTime de un valor de fecha y hora devuelto por una propiedad o un método. En el ejemplo siguiente se asignan la fecha y hora actuales, la fecha y hora de la hora universal coordinada (hora UTC) y la fecha actual a tres nuevas variables DateTime.

  C#

  VB

  Copiar

  
  DateTime date1 = DateTime.Now;
  DateTime date2 = DateTime.UtcNow;
  DateTime date3 = DateTime.Today;
  
  
  

• Mediante el análisis de la representación de cadena de un valor de fecha y hora. Los métodos Parse, ParseExact, TryParseExact y TryParse convierten una cadena en su valor de fecha y hora equivalente. En el ejemplo siguiente se utiliza el método Parse para analizar una cadena y convertirla en un valor de DateTime.

  C#

  VB

  Copiar

  
  string dateString = "5/1/2008 8:30:52 AM";
  DateTime date1 = DateTime.Parse(dateString, 
                            System.Globalization.CultureInfo.InvariantCulture); 
  
  
  

  Observe que los métodos TryParseExact y TryParse indican si una cadena determinada contiene una representación válida de un valor de DateTime a la vez que realiza la conversión.

• Mediante una llamada al constructor predeterminado implícito de la estructura DateTime. (Para obtener información detallada sobre el constructor predeterminado implícito de un tipo de valor, vea Tipos de valor (Referencia de C#).) Un equivalente aproximado, para los compiladores que lo admiten, se declara un valor DateTime sin explícitamente la asignación de una fecha y hora él. En el ejemplo siguiente se muestra una llamada al constructor predeterminado implícito de DateTime en C# y Visual Basic, así como una declaración de variable DateTime sin asignación en Visual Basic.

  C#

  VB

  Copiar

  
  DateTime dat1 = new DateTime();
  // The following method call displays 1/1/0001 12:00:00 AM.
  Console.WriteLine(dat1.ToString(System.Globalization.CultureInfo.InvariantCulture));
  // The following method call displays True.
  Console.WriteLine(dat1.Equals(DateTime.MinValue));
  
  
  

Internamente, todos los valores DateTime se representan como el número de pasos (el número de intervalos de 100 nanosegundos) transcurridos desde la medianoche (00:00:00) del 1 de enero de 0001. El valor DateTime real es independiente de la manera en la que ese valor aparece cuando se mostró en un elemento de la interfaz de usuario o cuando se escribe en un archivo. La apariencia de un valor de DateTime es el resultado de una operación de formato. Dar formato es el proceso de convertir un valor en su representación de cadena.

Como la apariencia de los valores de fecha y hora depende de factores como la referencia cultural, normas internacionales, requisitos de aplicación y preferencias personales, la estructura DateTime ofrece una gran flexibilidad para dar formato a los valores de fecha y hora a través de las sobrecargas de su método ToString. El método DateTime.ToString() predeterminado devuelve la representación de cadena de un valor de fecha y hora utilizando la fecha corta de la referencia cultural actual y el modelo horario largo. En el ejemplo siguiente se utiliza el método DateTime.ToString() predeterminado para mostrar la fecha y hora utilizando la fecha corta y el modelo horario largo para la referencia cultural en-US, que era la referencia cultural actual del equipo en el que se ejecutó el ejemplo.

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
Console.WriteLine(date1.ToString());
// For en-US culture, displays 3/1/2008 7:00:00 AM

El método DateTime.ToString(IFormatProvider) devuelve la representación de cadena de un valor de fecha y hora utilizando la fecha corta y el modelo horario largo de una referencia cultural concreta. En el ejemplo siguiente se utiliza el método DateTime.ToString(IFormatProvider) para mostrar la fecha y hora utilizando la fecha corta y el modelo horario largo para la referencia cultural fr-FR.

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
Console.WriteLine(date1.ToString(System.Globalization.CultureInfo.CreateSpecificCulture("fr-FR")));
// Displays 01/03/2008 07:00:00

El método DateTime.ToString(String) devuelve la representación de cadena de la fecha y hora en un formato definido por un especificador de formato estándar o personalizado, utilizando las convenciones de formato de la referencia cultural actual. En el ejemplo siguiente se utiliza el método DateTime.ToString(String) para mostrar el modelo completo de fecha y hora para la referencia cultural en-US, que era la referencia cultural actual del equipo en el que se ejecutó el ejemplo.

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
Console.WriteLine(date1.ToString("F"));
// Displays Saturday, March 01, 2008 7:00:00 AM

El método DateTime.ToString(String, IFormatProvider) devuelve la representación de cadena de la fecha y hora en un formato definido por un especificador de formato concreto, utilizando las convenciones de formato de una referencia cultural concreta. En el ejemplo siguiente se utiliza el método DateTime.ToString(String, IFormatProvider) para mostrar el modelo completo de fecha y hora utilizando la fecha corta y el modelo horario largo para la referencia cultural fr-FR.

DateTime date1 = new DateTime(2008, 3, 1, 7, 0, 0);
Console.WriteLine(date1.ToString("F", new System.Globalization.CultureInfo("fr-FR")));
// Displays samedi 1 mars 2008 07:00:00

En las versiones anteriores a la versión 2.0 de .NET Framework, la estructura DateTime contiene un campo de 64 bits formado por un campo de 2 bits no utilizados concatenado a un campo privado Ticks, que es un campo sin firma de 62 bits que contiene el número de pasos que representan la fecha y la hora. El valor del campo Ticks se puede obtener con la propiedad Ticks.

A partir de la versión 2.0 de .NET Framework, la estructura DateTime contiene un campo de 64 bits formado por un campo Kind privado concatenado al campo Ticks. El campo Kind es un campo de 2 bits que indica si la estructura DateTime representa una hora local, una hora universal coordinada (UTC) o la hora en una zona horaria no especificada. Este campo se utiliza cuando se realizan conversiones de horas entre zonas horarias, pero no para realizar operaciones aritméticas o de comparación de horas. El valor del campo Kind se puede obtener con la propiedad Kind.

Nota

Una alternativa a la estructura DateTime para trabajar en particular con valores de fecha y hora en zonas horarias concretas es la estructura DateTimeOffset. La estructura DateTimeOffset almacena información de fecha y hora en un campo DateTime privado y el número de minutos en que esa fecha y hora difiere de la hora UTC en un campo Int16 privado. Esto permite que un valor de DateTimeOffset refleje la hora en una zona horaria determinada, mientras que un valor de DateTime puede reflejar inequívocamente solo la hora UTC y la hora de la zona horaria local. Para obtener una explicación de cuándo se debe utilizar la estructura DateTime o la estructura DateTimeOffset al trabajar con valores de fecha y hora, vea Elegir entre DateTime, DateTimeOffset y TimeZoneInfo.

Las descripciones de los valores de hora del tipo DateTime se suelen expresar utilizando el estándar de hora universal coordinada (UTC), que es el nombre con el que se conoce internacionalmente a la hora media de Greenwich (GMT). La hora universal coordinada es la hora que se mide en la longitud cero grados, punto de origen de UTC. El horario de verano no se aplica a UTC.

La hora local está relacionada con una zona horaria determinada. Una zona horaria se asocia a un desplazamiento de zona horaria, que es la diferencia medida en horas entre la zona horaria y el punto de origen de UTC. Además, a la hora local le afecta opcionalmente el horario de verano, que agrega o resta una hora a la duración del día. Por consiguiente, la hora local se calcula agregando el desplazamiento de zona horaria a la hora UTC y haciendo los ajustes oportunos por el horario de verano, en caso necesario. El desplazamiento de zona horaria en el punto de origen de UTC es cero.

La hora UTC es adecuada para los cálculos, las comparaciones y el almacenamiento de fechas y horas en los archivos. La hora local es apropiada para la presentación en las interfaces de usuario de aplicaciones de escritorio. Las aplicaciones que tienen en cuenta la zona horaria (como muchas aplicaciones web) también necesitan trabajar con otras zonas horarias.

Si la propiedad Kind de un objeto DateTime es DateTimeKind.Unspecified, no se especifica si la hora representada es la hora local, la hora UTC o una hora de otra zona horaria.

Un cálculo utilizando una estructura DateTime, como Add o Subtract, no modifica el valor de la estructura. En su lugar, el cálculo devuelve una nueva estructura DateTime cuyo valor es el resultado del cálculo.

Las operaciones de conversión entre zonas horarias (como entre la hora UTC y la hora local, o entre una zona horaria y otra) tienen en cuenta el horario de verano, aunque las operaciones aritméticas y de comparación no lo hacen.

La propia estructura DateTime proporciona compatibilidad limitada para la conversión de una zona horaria a otra. Puede utilizar el método ToLocalTime para convertir de hora UTC a hora local, o el método ToUniversalTime para convertir de hora local a hora UTC. No obstante, existe un conjunto completo de métodos de conversión de zonas horarias en la clase TimeZoneInfo. Con estos métodos, puede convertir la hora de cualquiera de las zonas horarias del mundo en la hora de cualquier otra zona horaria.

Los cálculos y las comparaciones de objetos DateTime solo tienen significado si los objetos representan horas de la misma zona horaria. Puede utilizar un objeto TimeZoneInfo para representar la zona horaria de un valor de DateTime, aunque tengan una correspondencia imprecisa. Es decir, un objeto DateTime no tiene una propiedad que devuelva un objeto que represente la zona horaria de ese valor de fecha y hora salvo la propiedad Kind. Por esta razón, en una aplicación que tenga en cuenta la zona horaria, debe basarse en algún mecanismo externo para determinar la zona horaria en que se creó un objeto DateTime. Por ejemplo, puede utilizar una estructura que incluya el valor de DateTime y el objeto TimeZoneInfo que representa la zona horaria del valor de DateTime. Para obtener información detallada sobre el uso de la hora UTC en cálculos y comparaciones con valores DateTime, vea Efectuar operaciones aritméticas con fechas y horas.

Cada miembro de DateTime usa de forma implícita el calendario gregoriano para realizar sus operaciones, excepto los constructores que especifican un calendario y los métodos con un parámetro derivado de IFormatProvider, como System.Globalization.DateTimeFormatInfo, que indican implícitamente un calendario.

Las operaciones que realizan los miembros del tipo DateTime tienen en cuenta una serie de detalles, como los años bisiestos y el número de días de un mes.

Los tipos de valor de DateTime y TimeSpan se diferencian en que DateTime representa un instante de tiempo, mientras que TimeSpan representa un intervalo de tiempo. Por ejemplo, esto significa que puede restar una instancia de DateTime de otra para obtener un objeto TimeSpan que representa el intervalo de tiempo entre ellas. O bien, podría sumar un valor de TimeSpan positivo al valor de DateTime actual para obtener un valor de DateTime que representa una fecha futura.

Se puede agregar o restar un intervalo de tiempo a un objeto DateTime. Los intervalos de tiempo pueden ser negativos o positivos y se pueden expresar en unidades como pasos o segundos, o como objetos TimeSpan.

Se dice que un valor DateTime es de ida y vuelta cuando se transfiere a una aplicación COM y, a continuación, se vuelve a transferir a una aplicación administrada. Sin embargo, la acción de ida y vuelta de un valor de DateTime que especifique sólo una hora no tendrá el resultado que cabría esperar.

Si la operación de ida y vuelta sólo una hora, como 3 P.M..., la fecha y hora final es el 30 de diciembre de 1899 C.E. a las 3:00 P.M..., en lugar de enero, 1, 0001 C.E. a las 3:00 P.M... Esto se debe a que .NET Framework y COM suponen una fecha predeterminada en que sólo especifica una hora. Sin embargo, el sistema COM supone como fecha base el 30 de diciembre de 1899 de la Era Cristiana. mientras que .NET Framework supone que la fecha base es el 1 de enero de 0001 de la Era Cristiana.

Cuando sólo se pasa una hora de .NET Framework a COM, se realiza un proceso especial que convierte la hora al formato utilizado por COM. Cuando sólo una vez se pasa de COM a .NET Framework, no se realiza ningún procesamiento especial debido a que podrían dañar las fechas y horas legítimas durante o antes del 30 de diciembre de 1899. Esto también significa que si una fecha comienza una acción de ida y vuelta empezando en COM, .NET Framework y COM conservan la fecha.

El comportamiento de .NET Framework y COM supone que si la aplicación ejecuta una acción de ida y vuelta respecto de un objeto DateTime que sólo especifica una hora, la aplicación no puede olvidarse de modificar u omitir los datos erróneos provenientes del objeto DateTime final.