Partager via

Configurer le comportement et le format de la colonne de date et d’heure à l’aide du code

Si vous avez des utilisateurs et des bureaux partout dans le monde, il est important de représenter correctement les valeurs de date et d’heure sous la forme de plusieurs fuseaux horaires. Utilisez le DateTimeAttributeMetadata (type d’entité DateTimeAttributeMetadata ou Classe DateTimeAttributeMetadata) pour définir et gérer des colonnes de type DateTime dans Microsoft Dataverse. Utilisez la propriété DateTimeBehavior(pour le kit de développement logiciel (SDK) pour .NET, consultez la propriété DateTimeBehavior) pour définir s’il faut stocker les valeurs de date et d’heure avec ou sans informations de fuseau horaire. Utilisez la propriété DateTimeAttributeMetadata.Format pour spécifier le format d’affichage de ces colonnes.

Vous pouvez également utiliser la zone de personnalisation dans Dataverse pour définir le comportement et le format des colonnes de date et d’heure. Pour plus d’informations, consultez Comportement et format de la colonne Date et Heure.

Note

Toutes les colonnes de date et d’heure dans Dataverse prennent en charge toutes les valeurs à partir du 01/01/1753 minuit.

Si votre champ Date uniquement ou Heure de date se trouve dans une solution, vous ne pouvez modifier le comportement d’un champ managé existant que si vous êtes l’éditeur. Pour apporter une modification à ces champs, vous devez mettre à niveau la solution qui a ajouté la colonne Date uniquement ou Date Heure. Pour plus d’informations, consultez Mettre à niveau ou mettre à jour une solution.

Spécifier le comportement d’une colonne de date et heure

Utilisez le DateTimeBehavior (type complexe DateTimeBehavior ou Classe DateTimeBehavior) pour spécifier une valeur pour le type d’entité DateTimeAttributeMetadata.Propriété DateTimeBehavior. Le DateTimeBehavior contient les membres suivants. Chaque membre retourne une chaîne avec la même valeur que le nom du membre :

Nom et valeur du membre Description
UserLocal - Stocke la valeur de date et d’heure comme valeur UTC dans le système.
- L’opération de récupération retourne la valeur UTC.
- Le processus de mise à jour convertit la valeur UTC dans la valeur du fuseau horaire de l'utilisateur actuel, puis stocke la valeur mise à jour telle quelle ou en tant que valeur UTC équivalente en fonction du type (DateTimeKind) de la valeur spécifiée pour la mise à jour. Si la valeur spécifiée est de type UTC, elle sera stockée telle quelle. Sinon, la valeur équivalente à UTC sera stockée.
- La récupération de la valeur mise en forme convertit la valeur UTC dans le fuseau horaire actuel de l’utilisateur en fonction du fuseau horaire et des paramètres régionaux de l’utilisateur.
- Pour l’API web, la colonne est exposée en tant que DateTimeOffset.
- Ce comportement est utilisé pour les colonnes système comme CreatedOn et ModifiedOn, et ne peut pas être modifié. Utilisez ce comportement pour les colonnes personnalisées où vous souhaitez stocker les valeurs de date et d’heure avec les informations de fuseau horaire.
DateOnly - Stocke la valeur de date réelle sans aucune valeur de temps.
- Récupérer la valeur formatée affiche la date.
- Pour l’API web, la colonne est exposée en tant que Date.
- Utilisez ce comportement pour les colonnes personnalisées qui stockent les anniversaires et les fêtes d'anniversaire, où les informations temporelles ne sont pas nécessaires.
TimeZoneIndependent - Stocke les valeurs de date et d’heure réelles dans le système quel que soit le fuseau horaire de l’utilisateur.
- Pour les opérations de récupération et de mise à jour, aucune conversion de fuseau horaire n’est effectuée, et les valeurs de date et d’heure réelles sont retournées et mises à jour respectivement dans le système quel que soit le fuseau horaire de l’utilisateur.
- La récupération de la valeur mise en forme affiche la valeur de date et d’heure (sans aucune conversion du fuseau horaire) selon le format spécifié par le fuseau horaire et les paramètres régionaux de l’utilisateur actuel.
- Pour l’API web, la colonne est exposée en tant que DateTimeOffset.
- Utilisez ce comportement pour les colonnes qui stockent des informations telles que les heures d’enregistrement et de départ pour les hôtels.

L’exemple de code suivant montre comment définir un comportement UserLocal pour une nouvelle colonne de date et heure :

/// <summary>
/// Create a new DateTime column for the Account table with UserLocal behavior
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void CreateUserLocalDateTimeColumn(IOrganizationService service) {

   int _languageCode = 1033; //English

   DateTimeAttributeMetadata dtAttribute = new()
   {
       SchemaName = "new_SampleDateTimeAttribute",
       DisplayName = new Label("Sample Date Time Attribute", _languageCode),
       RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
       Description = new Label("Created by SDK Sample", _languageCode),
       DateTimeBehavior = DateTimeBehavior.UserLocal,
       Format = Microsoft.Xrm.Sdk.Metadata.DateTimeFormat.DateAndTime,
       ImeMode = ImeMode.Disabled
   };

   CreateAttributeRequest request = new()
   {
       EntityName = Account.EntityLogicalName,
       Attribute = dtAttribute
   };

   service.Execute(request);
}

Dans l’exemple de code, vous pouvez également définir la valeur de la propriété DateTimeBehavior en spécifiant directement la valeur de chaîne : DateTimeBehavior = "UserLocal"

Si vous ne spécifiez pas le comportement en créant une colonne de date et heure, la colonne est créée avec le comportement UserLocal par défaut.

Important

  • Une fois que vous avez créé une colonne de date et d’heure avec le comportement défini sur DateOnly ou TimeZoneIndependent, vous ne pouvez pas modifier le comportement de la colonne. Pour plus d’informations, consultez Modifier le comportement d’une colonne DateTime.
  • Les colonnes de date et d’heure avec le comportement DateOnly ou TimeZoneIndependent sont traitées comme si elles avaient le comportement UserLocal lorsqu’elles sont modifiées dans une version antérieure du client Dynamics 365 pour Outlook en mode hors connexion. Cette limitation existe, car le client ne comprend pas les nouveaux comportements et ne les traite pas différemment.UserLocal Aucune colonne de date et d’heure n’est convertie en nouveaux comportements lors de la mise à niveau. Pour éviter cette limitation, mettez à niveau tous les clients Dataverse vers la dernière version avant qu’un personnalisateur adopte l’un des nouveaux comportements. Lorsque vous êtes en ligne, la modification de données pour les colonnes avec les nouveaux comportements fonctionne correctement.

Spécifier le format de la colonne de date et heure

Utilisez la Format propriété pour spécifier le format d’affichage de date/heure de la colonne, quel que soit le mode de stockage du système. Utilisez l’énumération DateTimeFormat (type d’énumération DateTimeFormat ou DateTimeFormat Enum) pour spécifier le format d’affichage : DateAndTime ou DateOnly.

Si vous définissez la propriété DateTimeAttributeMetadata.DateTimeBehavior sur DateOnly, vous ne pouvez pas définir ou modifier la valeur de la propriété DateTimeAttributeMetadata.Format sur DateAndTime.

Opérateurs de requête de date et d’heure non pris en charge pour le comportement DateOnly

Les opérateurs de requête relatifs au temps ne sont pas pris en charge pour le comportement DateOnly. Hormis les opérateurs de requête spécifiques au temps mentionnés ici, tous les autres opérateurs de requête sont pris en charge.

  • Plus ancien que X minutes
  • Depuis plus de X heures
  • X dernières heures
  • X prochaines heures

Plus d’informations : Opérateurs de données de date et d’heure

Utilisation des API OData pour soumettre les valeurs de date et d’heure locales de l’utilisateur

Dans Microsoft Power Platform, lorsqu’un utilisateur soumet une date et une heure du fuseau horaire spécifique à l’utilisateur via l’interface utilisateur, un calcul automatique définit les données sur la date et l’heure correctes. Une analyse est effectuée pour remplacer toute date soumise par la valeur UTC correspondante en fonction de la colonne et des paramètres de l’interface utilisateur. Lorsque vous envoyez une valeur de date et d’heure à l’aide de l’opération d’API web, le calcul ne se produit pas, ce qui entraîne des affichages de données non expliquées. Par exemple, si vous êtes dans le fuseau horaire du Pacifique et que vous envoyez le 4/4/2021 12:00, ce qui suit se produit :

  • Valeur d’origine : 4/4/2021 12:00 ; l’utilisateur se trouve dans le fuseau horaire du Pacifique.
  • Soumise via l’interface utilisateur et récupérée en tant qu’heure locale de l’utilisateur : 4/4/2021 12:00
  • Soumise via l’API et récupérée en tant qu’heure locale de l’utilisateur : 4/4/2021 04:00

Soumission via l’interface utilisateur

L’interface utilisateur définit la valeur locale de l’utilisateur et la colonne est définie sur utilisateur local.

  • Valeur d’origine : 4/4/2021 12:00 ; fuseau horaire du Pacifique.
  • Valeur calculée en UTC et stockée dans Dataverse : 4/4/2021 12:00 + 8:00 = 4/4/2021T20:00:00Z. Cette valeur est due au fait que PST est de -8:00 à partir d’UTC, donc +8 est ajouté à la valeur stockée.
  • Valeur lorsqu’elle est affichée dans l’interface utilisateur par un utilisateur dans le fuseau horaire du Pacifique : 4/4/2021 12:00. L’interface utilisateur applique le calcul de décalage de -8:00 UTC à 04/04/2021T20:00:00Z pour obtenir la valeur correcte.

Soumission via l’API

L’interface utilisateur définit la valeur à locale de l'utilisateur, et la colonne est définie sur locale de l'utilisateur.

  • Valeur d’origine: 4/4/2021T12:00:00 ou 4/4/2021T12:00:00Z - aucun décalage ou indicateur UTC fourni. L’utilisateur se trouve dans le fuseau horaire du Pacifique.
  • Valeur calculée en UTC et stockée dans Dataverse : Aucun calcul d’interface utilisateur n’est effectué lors de la soumission à partir des API OData, la valeur est donc stockée sous la forme 4/4/2021T12:00:00Z.
  • Valeur lorsqu’elle est affichée dans l’interface utilisateur par un utilisateur dans le fuseau horaire du Pacifique : 4/4/2021 4:00. L’interface utilisateur applique le calcul de décalage UTC de -8:00 à la valeur dans Dataverse.

Pour éviter ce problème lors de l’utilisation d’appels API pour saisir des données dans les colonnes locales de l’utilisateur, calculez le décalage de l’utilisateur qui soumet les données et appliquez ce décalage.

À l’aide de l’exemple précédent : 4/4/2021 12:00 doit être envoyé via l’API en tant que 4/4/2021T12:00:00-08:00. L’heure et la date d’origine incluent le calcul du décalage du fuseau horaire de l’utilisateur actuel. Sinon, l’utilisateur peut effectuer le calcul avant la soumission, puis soumettre 04/04/2021T20:00:00Z.

Si vous choisissez d’inclure le calcul de décalage, n’incluez pas l’indicateur ZUTC, car Dataverse ne l’accepte pas.

Modifier le comportement d’une colonne de date et heure

Vous pouvez mettre une colonne de date et heure à jour pour modifier son comportement si vous détenez le rôle de personnalisateur de système dans votre instance des applications Dataverse et que la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior pour la colonne de date et heure est définie sur True.

Avertissement

Avant de modifier le comportement d’une colonne de date et d’heure, passez en revue toutes les dépendances de la colonne, telles que les règles d’entreprise, les flux de travail et les colonnes de cumul, pour vous assurer qu’il n’y a aucun problème en raison de la modification du comportement. Les personnalisateurs système peuvent restreindre la modification du comportement des colonnes de date et d’heure existantes à l’aide de la DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriété gérée.

Au minimum, après avoir modifié le comportement d’une colonne de date et d’heure, ouvrez chaque règle métier, flux de travail, colonne calculée et enregistrement de colonne de cumul qui dépend de la colonne de date et d’heure modifiée, passez en revue les informations et enregistrez l’enregistrement pour vous assurer que le comportement et la valeur de colonne les plus récents sont utilisés.

Après avoir modifié le comportement de date et d’heure d’une colonne calculée ou cumulative, ouvrez l’éditeur de définition de colonne cumulative ou calculée, puis enregistrez la définition de la colonne pour vérifier que la colonne est encore valide après modification du comportement. Les personnalisateurs système peuvent ouvrir l’éditeur de définition de colonne pour la colonne calculée ou rollup en sélectionnant Modifier en regard du type de champ dans la zone de personnalisation de Dataverse. Pour plus d’informations, consultez Définir des colonnes calculées pour automatiser les calculs et définir des colonnes de cumul qui agrègent des valeurs.

  • Le comportement des colonnes CreatedOn et ModifiedOn pour les tables prêtes à l'emploi et personnalisées est défini à UserLocal par défaut, et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie à False, ce qui signifie que vous ne pouvez pas modifier le comportement de ces colonnes. Bien que les utilisateurs puissent modifier la valeur de la DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriété managée de ces colonnes pour les tables personnalisées, ils ne peuvent toujours pas modifier le comportement des colonnes.

  • Pour les nouvelles colonnes de date et d’heure, la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur True. Ce paramètre signifie que vous pouvez modifier le comportement d’une colonne de date et d’heure personnalisée à partir de l’une ou l’autre UserLocalDateOnly ou TimeZoneIndependent; aucune autre transition de comportement n’est autorisée.

    Pour les colonnes de date et d’heure personnalisées qui font partie d’une organisation Dataverse, la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur True sauf si la colonne ou la table parente ne sont pas personnalisables.

    Note

    Lorsque vous mettez à jour la propriété DateTimeAttributeMetadata.DateTimeBehavior d’une colonne UserLocalDateOnly, vérifiez que vous remplacez également la propriété DateTimeAttributeMetadata.FormatDateAndTime par DateOnly. Sinon, une exception se produit.

  • Les colonnes de date et d’heure prêtes à l’emploi DateOnly suivantes dans Dataverse sont définies par défaut sur DateOnly, et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur False, ce qui signifie que vous ne pouvez pas modifier le comportement pour ces colonnes :

    Colonne de date et heure Table parente
    anniversary Contact
    birthdate Contact
    duedate Facture
    estimatedclosedate Prospect
    actualclosedate Opportunité
    estimatedclosedate Opportunité
    finaldecisiondate Opportunité
    validfromdate Produit
    validtodate Produit
    closedon Devis
    expireson Devis

    Le comportement de ces colonnes est défini sur UserLocal et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior sur True, et vous pouvez modifier le comportement de ces colonnes sur DateOnly uniquement. Aucune autre transition de comportement n’est autorisée.

Après la mise à jour du comportement d’une colonne, vous devez publier les personnalisations pour que la modification soit effective. La mise à jour du comportement d’une colonne de date et d’heure garantit que toutes les valeurs entrées ou mises à jour après la modification du comportement de colonne sont stockées dans le système en fonction du nouveau comportement. Cette modification n’affecte pas les valeurs déjà stockées dans la base de données, et elles continuent d’être stockées en tant que valeurs UTC. Toutefois, lorsque vous récupérez les valeurs existantes à l’aide du Kit de développement logiciel (SDK) ou que vous l’affichez dans l’interface utilisateur, les valeurs existantes sont affichées conformément au nouveau comportement de la colonne. Par exemple, si vous modifiez le comportement d’une colonne personnalisée sur un compte de UserLocal à DateOnly et que vous récupérez un enregistrement de compte existant à l'aide du Kit de développement logiciel (SDK), la date et l'heure s’affichent en tant que <Date> suivies de l'heure minuit (00:00:00). De même, pour le changement de comportement de UserLocal à TimeZoneIndependent, la valeur réelle dans la base de données est affichée comme sans aucune conversion de fuseau horaire.

L’exemple de code suivant montre comment mettre à jour le comportement d’une colonne de date et heure :

/// <summary>
/// Update the behavior of a DateTime column
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void UpdateBehaviorOfDateTimeColumn(IOrganizationService service) {

    // Retrieve the attribute to update its behavior and format
    RetrieveAttributeRequest retrieveColumnRequest = new()
    {
        EntityLogicalName = Account.EntityLogicalName,
        LogicalName = "new_sampledatetimeattribute",
        RetrieveAsIfPublished = false
    };
    // Execute the request
    RetrieveAttributeResponse attributeResponse =
                    (RetrieveAttributeResponse)service.Execute(retrieveColumnRequest);

    // Modify the values of the retrieved attribute
    DateTimeAttributeMetadata retrievedAttributeMetadata =
                    (DateTimeAttributeMetadata)attributeResponse.AttributeMetadata;

    retrievedAttributeMetadata.DateTimeBehavior = DateTimeBehavior.DateOnly;
    retrievedAttributeMetadata.Format = Microsoft.Xrm.Sdk.Metadata.DateTimeFormat.DateOnly;

    // Update the attribute with the modified value
    UpdateAttributeRequest updateRequest = new()
    {
        Attribute = retrievedAttributeMetadata,
        EntityName = Account.EntityLogicalName,
        MergeLabels = false
    };
    service.Execute(updateRequest);


    // Publish customizations to the account 
    PublishXmlRequest pxReq = new()
    {
        ParameterXml = "<importexportxml><entities><entity>account</entity></entities></importexportxml>"
    };
    service.Execute(pxReq);
}

Modifier le comportement des valeurs de date et d'heure existantes dans la base de données

Lorsque vous modifiez le comportement d'une colonne de date et d’heure de UserLocal vers DateOnly ou TimeZoneIndependent, les valeurs de colonne existantes dans la base de données ne se convertissent pas automatiquement. Le changement de comportement affecte uniquement les valeurs que vous entrez ou mettez à jour dans la colonne après avoir modifié le comportement. Les valeurs de date et d’heure existantes dans le système restent au format UTC. Dataverse affiche ces valeurs en fonction du nouveau comportement lorsque vous les récupérez via le Kit de développement logiciel (SDK) ou dans l’interface utilisateur, comme expliqué dans la section précédente. Pour les colonnes dont le comportement passe UserLocal à DateOnly, vous pouvez convertir les valeurs UTC existantes dans la base de données en valeur appropriée DateOnly pour éviter toute anomalie des données à l’aide du ConvertDateAndTimeBehavior message.

Ce message vous permet de spécifier une règle de conversion (si vous utilisez le Kit de développement logiciel (SDK) pour .NET, consultez la propriété ConvertDateAndTimeBehaviorRequest.ConversionRule) pour sélectionner le fuseau horaire à utiliser pour la conversion des valeurs UTC vers DateOnly. Vous pouvez spécifier l’une des règles de conversion suivantes :

  • SpecificTimeZone : convertit une valeur UTC en valeur DateOnly en fonction du code du fuseau horaire de Dataverse spécifié. Dans ce cas, vous devez spécifier une valeur pour la Propriété ConvertDateAndTimeBehaviorRequest.TimeZoneCode.
  • CreatedByTimeZone: convertit la valeur UTC en valeur DateOnly que l’utilisateur qui a créé l’enregistrement voit dans l’interface utilisateur.
  • OwnerTimeZone: convertit la valeur UTC en valeur DateOnly que l’utilisateur propriétaire de l’enregistrement voit dans l’interface utilisateur.
  • LastUpdatedByTimeZone: convertit la valeur UTC en une valeur DateOnly telle qu'elle apparaît dans l'interface utilisateur à l'utilisateur qui a mis à jour l'enregistrement pour la dernière fois.

Utilisez l’un des quatre membres de la classe DateTimeBehaviorConversionRule pour spécifier une valeur valide pour la propriété ConversionRule.

Note

Vous devez disposer du rôle administrateur système dans votre instance Dataverse pour exécuter la Classe ConvertDateAndTimeBehaviorRequest.

Lorsque vous exécutez le ConvertDateAndTimeBehavior (si vous utilisez le Kit de développement logiciel (SDK) pour .NET, voir ConvertDateAndTimeBehaviorRequest le message), vous créez un travail système (opération asynchrone) pour exécuter la demande de conversion. La ConvertDateAndTimeBehaviorResponse.JobId colonne de la réponse du message affiche l’ID du travail système que la demande de conversion crée. Une fois la tâche système effectuée, consultez les informations relatives à la tâche (AsyncOperation.Message) pour afficher les détails ou les erreurs de conversion éventuelles.

Note

Regroupez la conversion de plusieurs colonnes en un seul travail de conversion et exécutez un travail de conversion unique à la fois pour vous assurer qu’il n’y a aucun conflit dans la conversion et pour optimiser les performances du système.

Tenez compte des points suivants lors de l’utilisation du ConvertDateAndTimeBehavior message :

  • Évitez les modifications majeures apportées aux solutions dans Dataverse pendant l’exécution du message, telles que l’importation d’une solution ou la suppression d’une colonne ou d’une table parente. Un comportement inattendu peut se produire. Toutefois, aucune perte de données ne se produit.
  • Les mises à jour apportées au système suite à l’exécution du message n’exécutent pas les workflows ni les plug-ins.
  • Les mises à jour effectuées dans le système suite à l’exécution du message ne modifient pas la valeur « dernière modification sur » pour les colonnes. Toutefois, les mises à jour sont auditées pour aider les administrateurs à déterminer l’heure de la conversion et les valeurs d’origine et modifiées d’une colonne.

L’exemple de code suivant montre comment utiliser le message :

/// <summary>
/// Demonstrates use of the ConvertDateAndTimeBehavior message
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void ConvertDateAndTimeBehavior(IOrganizationService service)
{

    ConvertDateAndTimeBehaviorRequest request = new()
    {
        Attributes = new EntityAttributeCollection()
        {
            new KeyValuePair<string, StringCollection>("account", new StringCollection()
            { "new_sampledatetimeattribute" })
        },
        ConversionRule = DateTimeBehaviorConversionRule.SpecificTimeZone.Value,
        TimeZoneCode = 190, // Time zone code for India Standard Time (IST) in Dataverse
        AutoConvert = false // Conversion must be done using ConversionRule
    };

    // Execute the request
    var response = (ConvertDateAndTimeBehaviorResponse)service.Execute(request);

    Console.WriteLine($"Asynchronous Job ID: {response.JobId}");
}

Le client Web gère la conversion de fuseau horaire différemment de Unified Interface

Le client Web a été déconseillé en 2019. Si vous migrez des scripts clients vers son successeur, Unified Interface, notez la différence dans la façon dont les deux clients gèrent la conversion des fuseaux horaires pour les colonnes Heure locale de l’utilisateur.

Dans le client web, le serveur gère la conversion de fuseau horaire. Si un utilisateur entre 2018-10-15 07:30 dans un formulaire client web, l’API Xrm.Page.getAttribute(<column name>).getValue() cliente retourne 2018-10-15 07:30. Cette valeur est envoyée au serveur et les ajustements de fuseau horaire s’y produisent lors de l’enregistrement de la valeur.

Dans Unified Client, le client gère la conversion de fuseau horaire. Si un utilisateur dans le fuseau horaire UTC+8 entre 2018-10-15 07:30 dans un formulaire Unified Client, l’API client formContext.getAttribute(<column name>).getValue() renvoie la valeur ajustée 2018-10-14T23:30:00Z. Le serveur accepte la valeur telle quelle et n’effectue pas d’ajustements de fuseau horaire supplémentaires.

Pour tenir compte de cette différence, vous pouvez :

Voir aussi

Comportement et format de la colonne Date et heure
Résoudre les problèmes de date et d’heure dans les applications pilotées par modèle
Vue d’ensemble des colonnes
Classe ConvertDateAndTimeBehaviorRequest
Classe DateTimeAttributeMetadata
Blog : La manière de soumettre les données de date et d’heure est-elle importante ?

  • Last updated on