DateTime, structure

Vous pouvez créer une valeur DateTime de l'une des manières suivantes :

• En appelant l'une des surcharges du constructeur DateTime qui vous permettent de spécifier des éléments spécifiques de la valeur de date et d'heure (tel que l'année, le mois et le jour, ou le nombre de graduations). L'instruction suivante illustre un appel à l'un des constructeurs DateTime pour créer une date avec une année, un mois, un jour, une heure, des minutes et des secondes spécifiques.

  C#

  VB

  Copier

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

• En utilisant toute syntaxe spécifique au compilateur pour déclarer des valeurs de date et d'heure. Par exemple, l'instruction Visual Basic suivante initialise une nouvelle valeur DateTime.

  VB

  Copier

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

• En assignant à l'objet DateTime une valeur de date et d'heure retournée par une propriété et une méthode. L'exemple suivant assigne la date et l'heure actuelles, la date et l'heure UTC (coordinated universal time) et la date actuelle aux trois nouvelles variables DateTime.

  C#

  VB

  Copier

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

• En analysant la représentation sous forme de chaîne d'une valeur de date et d'heure. Les méthodes Parse, ParseExact, TryParse et TryParseExact convertissent une chaîne en sa valeur équivalente de date et d'heure. L'exemple suivant utilise la méthode Parse pour analyser une chaîne et la convertir en une valeur DateTime.

  C#

  VB

  Copier

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

  Notez que les méthodes TryParse et TryParseExact indiquent si une chaîne particulière contient une représentation valide d'une valeur DateTime en plus d'exécuter la conversion.

• En appelant le constructeur par défaut implicite de la structure DateTime. (Pour plus d'informations sur le constructeur par défaut implicite d'un type valeur, consultez Types valeur (référence C#).) Un équivalent approximatif, pour les compilateurs qui le prennent en charge, déclare une valeur DateTime sans lui assigner explicitement une valeur de date et d'heure. L'exemple suivant illustre un appel au constructeur par défaut implicite DateTime en C# et en Visual Basic, ainsi qu'une déclaration de variable DateTime sans assignation dans Visual Basic.

  C#

  VB

  Copier

  
  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));
  
  
  

En interne, toutes les valeurs DateTime sont représentées comme le nombre de graduations (nombre d'intervalles de 100 nanosecondes) qui se sont écoulés depuis 12:00:00 minuit, le 1er janvier 0001. La valeur DateTime réelle est indépendante de la façon dont cette valeur apparaît en cas d'affichage dans un élément d'interface utilisateur ou en cas d'écriture dans un fichier. L'apparence d'une valeur DateTime est le résultat d'une opération de mise en forme. La mise en forme est le processus qui consiste à convertir une valeur en une représentation sous forme de chaîne.

L'apparence des valeurs de date et d'heure étant dépendants de facteurs tels que la culture, les normes internationales, les spécifications d'application et les préférences personnelles, la structure DateTime offre une grande souplesse pour la mise en forme des valeurs de date et d'heure via les surcharges de sa méthode ToString. La méthode DateTime.ToString() par défaut retourne la représentation sous forme de chaîne d'une valeur de date et d'heure à l'aide du modèle de date courte et d'heure longue de la culture actuelle. L'exemple suivant utilise la méthode DateTime.ToString() par défaut pour afficher la date et l'heure selon le modèle de date courte et d'heure longue de la culture en-US, culture actuelle de l'ordinateur sur lequel cet exemple a été exécuté.

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

La méthode DateTime.ToString(IFormatProvider) retourne la représentation sous forme de chaîne d'une valeur de date et d'heure selon le modèle de date courte et d'heure longue d'une culture spécifique. L'exemple suivant utilise la méthode DateTime.ToString(IFormatProvider) pour afficher la date et l'heure selon le modèle de date courte et d'heure longue pour la culture 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

La méthode DateTime.ToString(String) retourne la représentation sous forme de chaîne de la date et de l'heure dans un format défini par un spécificateur de format standard ou personnalisé et selon les conventions de mise en forme de la culture actuelle. L'exemple suivant utilise la méthode DateTime.ToString(String) pour afficher le modèle de date et d'heure complètes pour la culture en-US, culture actuelle de l'ordinateur sur lequel cet exemple a été exécuté.

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

La méthode DateTime.ToString(String, IFormatProvider) retourne la représentation sous forme de chaîne de la date et de l'heure dans un format défini par un spécificateur de format spécifique et selon les conventions de mise en forme d'une culture spécifique. L'exemple suivant utilise la méthode DateTime.ToString(String, IFormatProvider) pour afficher le modèle de date et heure complètes pour la culture 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

Dans les versions antérieures du .NET Framework version 2.0, la structure DateTime contient un champ 64 bits composé d'un champ de 2 bits inutilisé concaténé avec un champ Ticks privé qui est un champ non signé de 62 bits qui contient le nombre de graduations qui représentent la date et heure. La valeur du champ Ticks peut être obtenue avec la propriété Ticks.

ہ partir du .NET Framework version 2.0, la structure DateTime contient un champ de 64 bits composé d'un champ Kind privé concaténé avec le champ Ticks. Le champ Kind est un champ de 2 bits qui indique si la structure DateTime représente une heure locale, un temps universel (UTC, Universal Time Coordinated) ou l'heure dans un fuseau horaire non spécifié. Le champ Kind est utilisé lors de l'exécution de conversions d'heure entre des fuseaux horaires, mais pas pour les comparaisons d'heure ou l'arithmétique. La valeur du champ Kind peut être obtenue avec la propriété Kind.

Remarque

Une alternative à la structure DateTime pour l'utilisation de valeurs de date et d'heure dans des fuseaux horaires particuliers est la structure DateTimeOffset. La structure DateTimeOffset stocke des informations d'horodatage dans un champ DateTime privé et le nombre de minutes par lesquelles ces date et heure diffèrent d'UTC dans un champ Int16 privé. Cela permet à une valeur DateTimeOffset de répercuter l'heure dans un fuseau horaire particulier, alors qu'une valeur DateTime ne peut refléter clairement que le fuseau horaire UTC et le fuseau horaire local. Pour plus d'informations sur l'utilisation appropriée de la structure DateTime ou de la structure DateTimeOffset lorsque vous travaillez avec des valeurs de date et d'heure, consultez Choix entre DateTime, DateTimeOffset et TimeZoneInfo.

Dans le type DateTime, les valeurs d'heure sont souvent exprimées en temps universel coordonné (UTC), précédemment connu sous le nom d'heure de Greenwich (GMT). Le temps universel coordonné est l'heure mesurée à la longitude zéro, le point de départ de l'UTC. L'heure d'été ne s'applique pas à l'UTC.

L'heure locale est relative à un fuseau horaire particulier. Un fuseau horaire est associé à un décalage horaire, qui est le décalage du fuseau horaire mesuré en heures par rapport au point de départ UTC. De plus, l'heure locale peut en option être affectée par l'heure d'été, qui ajoute ou soustrait une heure de la journée. Par conséquent, l'heure locale est calculée en ajoutant l'offset de fuseau horaire à l'UTC et en réglant l'heure d'été si nécessaire. Le décalage horaire au point de départ de l'UTC est nul.

L'heure UTC est appropriée pour les calculs, les comparaisons et l'enregistrement des dates et heures dans les fichiers. L'heure locale est appropriée pour l'affichage dans les interfaces utilisateur des applications de bureau. Les applications prenant en charge les fuseaux horaires (telles que de nombreuses applications Web) doivent également utiliser plusieurs autres fuseaux horaires.

Si la propriété Kind d'un objet DateTime est DateTimeKind.Unspecified, il n'est pas spécifié si l'heure représentée est l'heure locale, l'heure UTC ou une heure dans un autre fuseau horaire.

Un calcul effectué à l'aide d'une structure DateTime, telle que Add ou Subtract, ne modifie pas la valeur de la structure. En revanche, l'opération retourne une nouvelle structure DateTime dont la valeur est égale au résultat du calcul.

Les opérations de conversion entre des fuseaux horaires (tel qu'entre l'heure UTC et l'heure locale ou entre un fuseau horaire et un autre) prennent l'heure d'été en considération, mais l'arithmétique et les opérations de comparaison ne le font pas.

La structure DateTime elle-même offre un support limité pour la conversion d'un fuseau horaire en un autre. Vous pouvez utiliser la méthode ToLocalTime pour convertir l'UTC en heure locale, ou la méthode ToUniversalTime pour convertir l'heure locale en UTC. Toutefois, un jeu complet de méthodes de conversion de fuseau horaire est disponible dans la classe TimeZoneInfo. À l'aide de ces méthodes, vous pouvez convertir l'heure de l'un des fuseaux horaires du monde en l'heure de tout autre fuseau horaire.

Les calculs et les comparaisons d'objets DateTime n'ont de signification que si les objets représentent les heures dans le même fuseau horaire. Vous pouvez utiliser un objet TimeZoneInfo pour représenter un fuseau horaire de valeur DateTime, bien que les deux soient associés vaguement. (Autrement dit, un objet DateTime n'a pas de propriété qui retourne un objet qui représente le fuseau horaire de cette valeur de date et d'heure autre que la propriété Kind.) Pour cette raison, dans une application prenant en charge les fuseaux horaires, vous devez compter sur un mécanisme externe pour déterminer le fuseau horaire dans lequel un objet DateTime a été créé. Par exemple, vous pouvez utiliser une structure qui encapsule à la fois la valeur DateTime et l'objet TimeZoneInfo qui représente le fuseau horaire de valeur DateTime. Pour plus d'informations sur l'utilisation d'UTC dans les calculs et les comparaisons avec les valeurs DateTime, consultez Exécution d'opérations arithmétiques avec des dates et heures.

Lors de l'opération, chaque membre DateTime utilise implicitement le calendrier grégorien, à l'exception des constructeurs qui spécifient un calendrier, et des méthodes avec un paramètre dérivé de IFormatProvider, par exemple System.Globalization.DateTimeFormatInfo, qui spécifie implicitement un calendrier.

Les opérations effectuées par les membres du type DateTime prennent en considération des éléments tels que les années bissextiles et le nombre de jours d'un mois.

Les types valeur DateTime et TimeSpan se distinguent par le fait que DateTime représente un instant, tandis que TimeSpan représente un intervalle de temps. Cela signifie, par exemple, que vous pouvez soustraire une instance de DateTime d'une autre pour obtenir un objet TimeSpan qui représente l'intervalle de temps les séparant. De la même façon, vous pouvez ajouter un TimeSpan positif au DateTime actuel pour obtenir une valeur DateTime qui représente une date ultérieure.

Vous pouvez ajouter ou soustraire un intervalle de temps d'un objet DateTime. Les intervalles de temps peuvent être négatifs ou positifs ; ils peuvent être exprimés en unités telles que les graduations ou les secondes ou comme un objet TimeSpan.

On dit d'une valeur DateTime qui est transférée à une application COM, puis transférée de nouveau à une application managée, qu'elle effectue un aller-retour. Toutefois, une valeur DateTime qui ne spécifie qu'une heure n'effectue pas un aller-retour, comme vous vous en doutez.

Si vous effectuez uniquement un aller-retour d'une heure, telle que 3 heures de l'après-midi, la date et l'heure finale est le 30 décembre 1899 (ère commune). à 15 heures, au lieu du 1er janvier 0001 (notre ère) à 15 heures. Cela s'explique par le fait que le .NET Framework et COM adoptent une date par défaut lorsque seule une heure est spécifiée. Toutefois, le système COM suppose une date de base au 30 décembre, 1899, notre ère. Alors que le .NET Framework suppose une date de base au 1er janvier 0001, notre ère.

Lorsque seule une heure est passée du .NET Framework à COM, un traitement spécial qui convertit l'heure au format utilisé par COM est exécuté. Lorsque seule une heure est passée de COM au .NET Framework, aucun traitement spécial n'est exécuté parce que cela altérerait les dates et heures légitimes égales ou antérieures au 30 décembre 1899. Cela signifie également que si une date démarre son aller-retour à partir de COM, le .NET Framework et COM conservent cette date.

Le comportement du .NET Framework et de COM signifie que si votre application réalise un aller-retour de DateTime qui spécifie uniquement une heure, elle doit veiller à modifier ou à ignorer la date erronée du dernier objet DateTime.