Comportement et format de l’attribut Date et heure

Article
03/22/2023

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. La classe DateTimeAttributeMetadata (DateTimeAttributeMetadata Entity Type ou DateTimeAttributeMetadata) est utilisée pour définir et gérer les attributs de type DateTime dans Dynamics 365 Customer Engagement (on-premises). Utilisez la propriété DateTimeBehavior (pour le service d’organisation, voir DateTimeAttributeMetadata.DateTimeBehavior) pour définir s’il faut stocker les valeurs de date et d’heure avec ou sans fuseau horaire, et utilisez la propriété DateTimeAttributeMetadata.Format pour spécifier le format d’affichage de ces attributs.

Vous pouvez également utiliser la zone de personnalisation de Customer Engagement pour définir le comportement et le format des attributs de date et d’heure. Informations complémentaires : Comportement et format du champ de date et d’heure.

Note

Tous les attributs de date et d’heure dans CRM Online 2015 Update 1 et Dynamics CRM 2016 (on-premises) ou ultérieur prennent désormais en charge toutes les valeurs à partir du 1/1/1753 minuit.

Pour les versions Dynamics 365 Customer Engagement (on-premises) antérieures à CRM Online 2015 Update 1 et Dynamics CRM 2016 (on-premises), vous ne pouvez pas définir le comportement des valeurs de date et d’heure. Par défaut, les valeurs de date et d’heure sont stockées en tant que comportement UserLocal comme décrit plus loin dans cette rubrique.

Spécifier le comportement d’un attribut de date et heure

Vous pouvez utiliser la classe DateTimeBehavior (DateTimeBehavior ComplexType ouDateTimeBehavior) pour spécifier une valeur pour la propriété DateTimeAttributeMetadata EntityType.DateTimeBehavior. 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, l’attribut est exposé en tant que DateTimeOffset. - Ce comportement est utilisé pour les attributs système comme `CreatedOn` et `ModifiedOn`, et ne peut pas être modifié. Vous devez utiliser ce comportement pour les attributs personnalisés où vous souhaitez stocker les valeurs de date et d’heure avec les informations de fuseau horaire.
`DateOnly`	- Stocke dans le système la valeur de date finale avec la valeur d’heure, par exemple, minuit (00:00:00). - Pour les opérations de récupération et de mise à jour, aucune conversion de fuseau horaire n’est effectuée, et la valeur de l’heure correspond toujours à minuit (00:00:00). - La récupération de la valeur mise en forme affiche la valeur de date sans aucune conversion de fuseau horaire. - Pour l’API web, l’attribut est exposé en tant que Date. - Ce comportement doit être utilisé pour les attributs personnalisés 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, l’attribut est exposé en tant que DateTimeOffset. - Ce comportement doit être utilisé pour les attributs 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 un nouvel attribut de date et heure :



// Create a date time attribute for the Account entity
// with the UserLocal behavior
dtAttribute = new DateTimeAttributeMetadata
{                             
    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 = DateTimeFormat.DateAndTime,
    ImeMode = ImeMode.Disabled
};

CreateAttributeRequest createAttributeRequest = new CreateAttributeRequest
{
    EntityName = Account.EntityLogicalName,
    Attribute = dtAttribute
};
_serviceProxy.Execute(createAttributeRequest);
Console.WriteLine("Created attribute '{0}' with UserLocal behavior\nfor the Account entity.\n", 
                            dtAttribute.SchemaName);

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 un attribut de date et heure, l’attribut est créé avec le comportement UserLocal par défaut. Pour obtenir un exemple de code complet, voir Exemple : convertir les valeurs de date et d’heure.

Important

Après avoir créé un attribut de date et heure avec le comportement défini sur DateOnly ou TimeZoneIndependent, vous ne pourrez plus modifier le comportement de l’attribut. Pour plus d’informations : Modifier le comportement d’un attribut de type datetime
- Les attributs 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 n’inclut pas les nouveaux comportements et ne les traite pas différemment de UserLocal (comportement existant dans les versions Dynamics 365 Customer Engagement (on-premises) antérieures aux applications CRM Online 2015 Update 1 ou Dynamics 365 (online), version 8.2 (en local)). Aucun attribut de date ni d’heure n’est converti en nouveaux comportements lors de la mise à niveau, donc la meilleure pratique ici sera de mettre à niveau tous les clients Dynamics 365 for Outlook dans la dernière version avant qu’un personnalisateur adopte un des nouveaux comportements. Une fois en ligne, la modification des données des champs avec les nouveaux comportements fonctionne également parfaitement.
Les clients Dynamics 365 for Outlook plus anciens ne comprendront pas non plus les dates antérieures au 01/01/1900 (valeur la plus antérieure prise en charge pour les types de date et d’heure dans d’autres versions de Dynamics 365 Customer Engagement (on-premises) antérieures à CRM Online 2015 Update 1 et Dynamics 365 (online), version 8.2 (en local)). Les utilisateurs ne pourront pas ouvrir les enregistrements avec des dates antérieures au 01/01/1900 en mode hors connexion. Toutefois, tout fonctionnera également parfaitement lorsqu’ils seront en ligne. Vous devez effectuer une mise à niveau vers la dernière version des clients Dynamics 365 for Outlook pour utiliser les attributs avec des dates à partir du 01/01/1753 minuit en mode hors connexion également.
- Si vous utilisez un code personnalisé pour implémenter le comportement de date et d’heure dans votre instance des applications Dynamics 365 Customer Engagement (on-premises), il ne pourra pas fonctionner correctement dans CRM Online 2015 Update 1 et Dynamics 365 (online), version 8.2 (en local) en raison du nouveau comportement.

Spécifier le format de l’attribut de date et heure

Utilisez la propriété Format. pour spécifier le format d’affichage de date/heure de l’attribut indépendamment de la façon dont il est stocké dans le système. Vous pouvez utiliser l’DateTimeFormaténumération (DateTimeFormat EnumType ou DateTimeFormaténumération) 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.FormatDateAndTime.

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

Pour plus d’informations : Opérateurs de requête de date et d’heure dans FetchXML

Modifier le comportement d’un attribut de date et heure

Vous pouvez mettre un attribut de date et heure à jour pour modifier son comportement si vous détenez le rôle de personnalisateur de système dans votre instance Dynamics 365 Customer Engagement (on-premises) et si la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior pour l’attribut de date et heure est définie sur True.

Avertissement

Avant de modifier le comportement d’un attribut de date et heure, vous devez examiner toutes les dépendances de l’attribut, telles que les règles métier, les workflows et les attributs calculés ou cumulatifs, pour éviter de générer des problèmes. Les personnalisateurs de système peuvent limiter la modification du comportement des attributs 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’un attribut de date et heure, vous devez ouvrir chaque enregistrement de règle métier, de workflow, d’attribut calculé et d’attribut cumulatif qui dépend de l’attribut de date et heure modifié, vous devez lire les informations, puis enregistrer l’enregistrement pour garantir que le dernier comportement et la dernière valeur d’attribut sont utilisés.

Après avoir modifié le comportement de date et d’heure d’un attribut calculé ou cumulatif, ouvrez l’éditeur de définition de champ cumulatif ou calculé, puis enregistrez la définition du champ pour vérifier que l’attribut est encore valide après modification du comportement. Les personnalisateurs de système peuvent ouvrir l’éditeur de définition du champ pour l’attribut calculé ou cumulatif en cliquant sur Modifier en regard de Type de champ dans la zone de personnalisation dans Dynamics 365 Customer Engagement (on-premises). Pour plus d’informations : Définir les champs calculés et Définir les champs cumulatifs

Le comportement des attributs CreatedOn et ModifiedOn pour les entités 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 attributs. Bien que les utilisateurs puissent modifier la valeur de la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior de ces attributs pour les entités personnalisées, ils ne peuvent toujours pas modifier le comportement des attributs.
Pour les nouveaux attributs 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’un attribut de date et heure personnalisé UserLocal par DateOnly ou TimeZoneIndependent ; aucune autre transition de comportement n’est autorisée.

Pour les attributs de date et d’heure personnalisés faisant partie d’une organisation des applications Dynamics 365 Customer Engagement (on-premises) qui est mise à niveau vers CRM Online 2016 Update ou Dynamics 365 (online), version 8.2 (local), la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur True, sauf si l’attribut ou l’entité parente n’est pas personnalisable.

Note

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

Les attributs de date et d’heure prédéfinis suivants dans CRM Online 2015 Update 1 et Dynamics 365 (online), version 8.2 (en local) sont définis par défaut sur DateOnly et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior est définie sur False pour ces attributs, ce qui implique que vous ne pouvez pas modifier le comportement de ces attributs :

Attribut Date et heure	Entité parente
anniversary	Contact
birthdate	Contact
duedate	Facture
estimatedclosedate	Prospect
actualclosedate	Opportunité
estimatedclosedate	Opportunité
finaldecisiondate	Opportunité
validfromdate	Produit
validtodate	Produit
closedon	Devis
expireson	Devis

Toutefois, si ces attributs de date et d’heure prédéfinis appartiennent à une organisation qui est mise à niveau vers Dynamics CRM Online 2016 Update ou Dynamics 365 (online), version 8.2 (en local), le comportement de ces attributs sera défini sur UserLocal et la propriété gérée DateTimeAttributeMetadata.CanChangeDateTimeBehavior sur True dans l’organisation mise à niveau ; vous pouvez modifier le comportement de ces attributs sur DateOnly uniquement. Aucune autre transition de comportement n’est autorisée.

Après la mise à jour du comportement d’un attribut, vous devez publier les personnalisations pour que la modification soit effective. La mise à jour du comportement d’un attribut de date et heure garantit que toutes les valeurs entrées/mises à jour après la mise à jour du comportement d’attribut, 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 l’attribut. Par exemple, si vous avez remplacé le comportement d’un attribut personnalisé 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’afficheront 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’un attribut de date et heure :



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

Console.WriteLine("Retrieved the attribute '{0}'.",
                attributeResponse.AttributeMetadata.SchemaName);

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

// Update the attribute with the modified value
UpdateAttributeRequest updateRequest = new UpdateAttributeRequest
{
    Attribute = retrievedAttributeMetadata,
    EntityName = Account.EntityLogicalName,
    MergeLabels = false
};
_serviceProxy.Execute(updateRequest);
Console.WriteLine("Updated the behavior and format of '{0}' to DateOnly.",
    retrievedAttributeMetadata.SchemaName);

// Publish customizations to the account entity
PublishXmlRequest pxReq = new PublishXmlRequest
{
    ParameterXml = String.Format("<importexportxml><entities><entity>account</entity></entities></importexportxml>")
};
_serviceProxy.Execute(pxReq);
Console.WriteLine("Published customizations to the Account entity.\n");

Pour obtenir un exemple de code complet, voir Exemple : convertir les valeurs de date et d’heure.

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

Lorsque vous mettez à jour un attribut de date et heure pour remplacer son comportement UserLocal en DateOnly ou TimeZoneIndependent, il ne convertit pas automatiquement les valeurs d’attributs existantes dans la base de données. Le changement de comportement affecte uniquement ces valeurs qui seront entrées ou mises à jour dans l’attribut après la modification du comportement. Les valeurs de date et heure dans le système restent au format UTC et affichées par Dynamics 365 Customer Engagement (on-premises) 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 attributs 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 service d’organisation, voir 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 Dynamics 365 Customer Engagement (on-premises) spécifié. Dans ce cas, vous devez spécifier une valeur pour le paramètre 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 le paramètre ConversionRule.

Note

Le message ConvertDateAndTimeBehavior n’est disponible que si vous utilisez CRM Online 2015 Update 1 ou Dynamics 365 (online), version 8.2 (en local). Il est indisponible pour les versions antérieures de Dynamics 365 Customer Engagement (on-premises).
- Vous devez disposer du rôle administrateur système dans votre instance Dynamics 365 Customer Engagement (on-premises) pour exécuter le message ConvertDateAndTimeBehaviorRequest.

Lorsque vous exécutez ConvertDateAndTimeBehavior (si vous utilisez le service d’organisation, voir le message ConvertDateAndTimeBehaviorRequest), une tâche système (opération asynchrone) est créée pour exécuter la demande de conversion. L’attribut 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.

Note

Nous vous recommandons de regrouper la conversion de plusieurs attributs 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 Customer Engagement lors de l’exécution du message, comme importer une solution ou supprimer une entité d’attribut ou 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écuteront pas les workflows ni les plug-ins.

Les mises à jour apportées au système suite à l’exécution du message ne modifieront pas la valeur « dernière modification le » pour les attributs, mais seront auditées pour aider les administrateurs à déterminer la période de la conversion et les valeurs d’origine/modifiées pour un attribut.

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



ConvertDateAndTimeBehaviorRequest request = new ConvertDateAndTimeBehaviorRequest()
{
    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 CRM
    AutoConvert = false // Conversion must be done using ConversionRule
};

// Execute the request
ConvertDateAndTimeBehaviorResponse response = (ConvertDateAndTimeBehaviorResponse)_serviceProxy.Execute(request);

Pour obtenir un exemple de code complet, voir Exemple : convertir les valeurs de date et d’heure

Voir aussi

Exemple : convertir les valeurs de date et d’heure
Comportement et format du champ de date et d’heure
Personnaliser les métadonnées d’attribut d’entité
ConvertDateAndTimeBehaviorRequest
DateTimeAttributeMetadata

Partager via

Comportement et format de l’attribut Date et heure

Spécifier le comportement d’un attribut de date et heure

Spécifier le format de l’attribut de date et heure

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

Modifier le comportement d’un attribut de date et heure

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

Voir aussi

Commentaires

Ressources supplémentaires