Partager via

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

  • Article

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. Le DateTimeAttributeMetadata (Type d’entité DateTimeAttributeMetadata ou la Classe DateTimeAttributeMetadata ) permet de définir et de gérer les colonnes de type DateTime dans Microsoft Dataverse. Utilisez la propriété DateTimeBehavior (pour le Kit de développement logiciel (SDK) pour .NET, voir Propriété DateTimeBehavior) pour définir s’il faut stocker les valeurs de date et d’heure avec ou sans informations de fuseau horaire, et 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. Informations complémentaires : Comportement et format de la colonne de date et d’heure.

Notes

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 Date et heure se trouve dans une solution, vous ne pouvez modifier le comportement d’un champ géré existant que si vous êtes l’éditeur. Afin d’apporter des modifications à ces champs, il est nécessaire de mettre à niveau la solution qui a ajouté la colonne Date uniquement ou Date et heure. Plus d’informations : Mettre à niveau ou mettre à jour une solution

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

Vous pouvez utiliser le DateTimeBehavior (Type complexe DateTimeBehavior ou la Classe DateTimeBehavior) pour spécifier une valeur pour le Type d’entité DateTimeAttributeMetadata.DateTimeBehavior propriété. DateTimeBehavior contient les membres suivants ; chaque membre renvoie 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 de fuseau horaire de l’utilisateur actuel, puis stocke la valeur mise à jour telle quelle ou sous la forme d’une 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 paramètre de 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é. Vous devez utiliser 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 actuelle sans valeur d’heure.
- La récupération de la valeur mise en forme affiche la valeur de la date.
- Pour l’API web, la colonne est exposée en tant que Date.
- Ce comportement doit être utilisé pour les colonnes personnalisées qui stockent les dates d’anniversaires, pour lesquelles les informations d’heure 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 conversion de fuseau horaire) selon le format spécifié par le paramètre de 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.
- Ce comportement doit être utilisé pour les colonnes qui stockent les informations telles que les arrivées et les départs dans 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

  • Après avoir créé une colonne de date et heure avec le comportement défini sur DateOnly ou TimeZoneIndependent, vous ne pourrez plus modifier le comportement de la colonne. Plus d’informations : Modifier le comportement d’une colonne DateTime
  • Les colonnes de date et d’heure avec le comportement DateOnly ou TimeZoneIndependent seront traités comme pour le comportement UserLocal lorsqu’il est modifié dans une version antérieure du client Dynamics 365 for Outlook en mode hors connexion. Cela est dû au fait que le client ne comprend pas les nouveaux comportements et ne les traitera pas différemment de UserLocal. Aucune colonne de date ni d’heure n’est convertie en nouveaux comportements lors de la mise à niveau, donc la meilleure pratique ici sera de mettre à niveau tous les clients Dataverse dans la dernière version avant qu’un personnalisateur adopte un des nouveaux comportements. Une fois en ligne, la modification des données des colonnes avec les nouveaux comportements fonctionne également parfaitement.

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

Utilisez la propriété Format. pour spécifier le format d’affichage de date/heure de la colonne indépendamment de la façon dont elle est stockée dans le système. Vous pouvez utiliser l’énumération DateTimeFormat (type d’énumération DateTimeFormat ou l’énumération DateTimeFormat) pour spécifier le format d’affichage : DateAndTime ou DateOnly.

Si la propriété DateTimeAttributeMetadata.DateTimeBehavior est définie sur DateOnly, vous ne pourrez pas définir ni modifier la valeur de la propriété DateTimeAttributeMetadata.Format 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 associés à l’heure ne sont pas pris en charge pour le comportement DateOnly. Hormis les opérateurs de requête spécifiques à l’heure répertoriés ici, tous les autres opérateurs de requête sont pris en charge.

  • Plus de X minutes
  • 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. Lors de la soumission d’une valeur de date et d’heure à l’aide de l’opération d’API web, le calcul n’a pas lieu, ce qui entraîne des affichages de données inexpliqués. Par exemple, si vous êtes dans le fuseau horaire du Pacifique et que vous soumettez 4/4/2021 12:00, voici ce qui se passe :

  • 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 est définie sur l’heure locale de l’utilisateur et la colonne est définie sur l’heure locale de l’utilisateur.

  • 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. C’est parce que le fuseau PST est à -8:00 du fuseau 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 est définie sur l’heure locale de l’utilisateur et la colonne est définie sur l’heure 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 en cas d’utilisation d’appels d’API pour entrer des données dans les colonnes locales de l’utilisateur, vous devez calculer le décalage en soumettant les données et en appliquant le décalage.

Utilisez l’exemple ci-dessus : 4/4/2021 12:00 devra être soumis via l’API comme 04/04/2021T12:00:00-08:00. L’heure et la date d’origine incluent le calcul de 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 du décalage, vous ne pouvez pas avoir de valeur Z, un indicateur UTC, car Dataverse ne l’acceptera 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.

Attention

Avant de modifier le comportement d’une colonne de date et heure, vous devez examiner toutes les dépendances de la colonne, telles que les règles métier, les workflows et les colonnes calculées ou cumulatives, pour éviter de générer des problèmes. Les personnalisateurs de système peuvent limiter la modification du comportement des colonnes de date et d’heure existants à l’aide de la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior.

Au minimum, après avoir modifié le comportement d’une colonne de date et heure, vous devez ouvrir chaque enregistrement de règle métier, de workflow, de colonne calculée et de colonne cumulative qui dépend de la colonne de date et heure modifiée, vous devez lire les informations, puis enregistrer l’enregistrement pour garantir que le dernier comportement et la dernière valeur de colonne 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 de système peuvent ouvrir l’éditeur de définition de la colonne pour la colonne calculée ou cumulative en cliquant sur Modifier en regard de Type de champ dans la zone de personnalisation dans les applications Dataverse. En savoir plus : Définir des colonnes calculées pour automatiser les calculs et Définir des colonnes de cumul qui agrègent les valeurs

  • Le comportement des colonnes CreatedOn et ModifiedOn pour les tables prédéfinies et personnalisées est défini sur UserLocal par défaut, et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur False, ce qui implique que vous ne pouvez pas modifier le comportement de ces colonnes. Bien que les utilisateurs puissent modifier la valeur de la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior 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. Cela implique que vous pouvez remplacer le comportement d’une colonne de date et heure personnalisé UserLocal par DateOnly 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.

    Notes

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

  • Les colonnes de date et d’heure prédéfinies suivantes dans Dataverse sont définis par défaut sur DateOnly et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur False pour ces colonnes, ce qui implique que vous ne pouvez pas modifier le comportement de 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 heure garantit que toutes les valeurs entrées/mises à jour après la mise à jour du comportement de colonne, sont stockées dans le système en fonction du nouveau comportement. Cela n’impacte pas les valeurs qui sont déjà stockées dans la base de données, elles restent enregistrées en tant que valeurs UTC. Toutefois, si vous récupérez les valeurs existantes dans le SDK ou les afficher dans l’interface utilisateur, les valeurs apparaîtront en fonction du nouveau comportement de la colonne. Par exemple, si vous avez remplacé le comportement d’une colonne personnalisée dans une entité compte UserLocal en DateOnly et que vous récupérez un enregistrement de compte existant en utilisant le SDK, la date et l’heure s’affichent sous la forme d’une <Date> suivie de 00:00:00 correspondant à minuit. De même, pour le changement de comportement UserLocal en TimeZoneIndependent, la valeur réelle dans la base de données apparaît 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);
}

Convertir le comportement des valeurs de date et heure dans la base de données

Lorsque vous mettez à jour une colonne de date et heure pour remplacer son comportement UserLocal en DateOnly ou TimeZoneIndependent, il ne convertit pas automatiquement les valeurs de colonnes existantes dans la base de données. Le changement de comportement affecte uniquement ces valeurs qui seront entrées ou mises à jour dans la colonne après la modification du comportement. Les valeurs de date et heure dans le système restent au format UTC et affichées par Dataverse en fonction du nouveau comportement lorsque récupérées via le SDK ou dans l’interface utilisateur comme décrit dans la section précédente. Pour les colonnes dont le comportement est passé de UserLocal à DateOnly, vous pouvez convertir les valeurs UTC existantes dans la base de données en valeur DateOnly appropriée pour éviter toute anomalie de données en utilisant le message ConvertDateAndTimeBehavior .

Le message vous permet de spécifier une règle de conversion (si vous utilisez le SDK pour .NET, voir Propriété ConvertDateAndTimeBehaviorRequest.ConversionRule) pour sélectionner le fuseau horaire à utiliser pour la conversion des valeurs UTC en 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 une valeur UTC en valeur DateOnly que l’utilisateur auteur de l’enregistrement verra dans l’interface utilisateur.
  • OwnerTimeZone : convertit une valeur UTC en valeur DateOnly que l’utilisateur propriétaire de l’enregistrement verra dans l’interface utilisateur.
  • LastUpdatedByTimeZone : convertit une valeur UTC en valeur DateOnly que l’utilisateur ayant récemment actualisé l’enregistrement verra dans l’interface utilisateur.

Vous pouvez utiliser un des quatre membres de la Classe DateTimeBehaviorConversionRule pour spécifier une valeur valide pour la Propriété ConversionRule.

Notes

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

Lorsque vous exécutez ConvertDateAndTimeBehavior (si vous utilisez le SDK pour .NET, voir le message ConvertDateAndTimeBehaviorRequest), une tâche système (opération asynchrone) est créée pour exécuter la demande de conversion. La colonne ConvertDateAndTimeBehaviorResponse.JobId dans la réponse du message affiche l’ID de la tâche système créée suite à la demande de conversion. 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.

Notes

Nous vous recommandons de regrouper la conversion de plusieurs colonnes en une tâche de conversion unique, et d’exécuter une tâche de conversion unique pour éviter tout conflit lors de l’opération et pour optimiser les performances système.

Quelques aspects importants à prendre en compte lors de l’utilisation du message ConvertDateAndTimeBehavior :

  • Vous devez éviter les modifications majeures dans les solutions des applications Dataverse lors de l’exécution du message, comme importer une solution ou supprimer une colonne ou une table parente. Cela peut produire un comportement inattendu ; 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 apportées au système suite à l’exécution du message ne modifient pas la valeur « Date de la dernière modification » pour les colonnes, mais seront auditées pour aider les administrateurs à déterminer la période de la conversion et les valeurs d’origine/modifiées pour 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, la conversion du fuseau horaire n’était pas effectuée côté client. Si un utilisateur entrait 2018-10-15 07:30 dans un formulaire de client Web, l’API client Xrm.Page.getAttribute(<column name>).getValue() renvoyait 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 le client Unified Interface, la conversion du fuseau horaire se fait côté client. 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 aucun ajustement supplémentaire du fuseau horaire.

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 ?

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).