Comportement et format de l'attribut Date et heure

Article
07/06/2017

Date de publication : novembre 2016

S’applique à : Dynamics CRM 2015

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 est utilisée pour définir et gérer les attributs de type DateTime dans CRM. Utilisez la propriété 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 Dynamics 365 pour définir le comportement et le format des attributs de date et d'heure.Pour plus d'informations :TechNet : Behavior and format of the Date and Time field (Comportement et format du champ Date et heure)

Notes

La propriété DateTimeAttributeMetadata.DateTimeBehavior est disponible uniquement si vous utilisez CRM Online, et que vous avez actualisé votre instance de Mise à jour 1 de Microsoft Dynamics CRM Online 2015. En outre, les attributs de date et d'heure dans Mise à jour 1 de Microsoft Dynamics CRM Online 2015 prennent désormais en charge toutes les valeurs à partir du 1/1/1753 12:00 AM.

Dans les autres versions CRM, 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.

Contenu de la rubrique

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

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

Vous pouvez utiliser la classe DateTimeBehavior pour spécifier une valeur pour la propriété DateTimeAttributeMetadata.DateTimeBehavior. La classe 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 en une 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 en fuseau horaire actuel de l'utilisateur en fonction du paramètre fuseau horaire et paramètres régionaux de l'utilisateur. Pour le point de terminaison OData, 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 le point de terminaison OData, l'attribut est exposé en tant que DateTimeOffset. 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 le point de terminaison OData, 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 l’exemple de code complet, voir Exemple : Convertir le comportement 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 date et heure
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 CRM pour 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 d'autres versions CRM, sauf Mise à jour 1 de Microsoft Dynamics CRM Online 2015). 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 CRM pour 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 CRM pour 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 CRM, sauf Mise à jour 1 de Microsoft Dynamics CRM Online 2015). 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 CRM pour 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 de CRM, il ne pourra pas fonctionner correctement dans Mise à jour 1 de Microsoft Dynamics CRM Online 2015 qui appartient à la nouvelle fonctionnalité de comportement.

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

Utilisez la propriété DateTimeAttributeMetadata.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'énumération DateTimeFormat pour spécifier le format d'affichage : DateAndTime ou DateOnly.

Si la propriété DateTimeBehavior est définie sur DateOnly, vous ne pourrez pas définir ni modifier la valeur de la propriété 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/heure "Plus de" et date d'exercice 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 CRM et que la propriété gérée 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 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 CRM.Pour plus d'informations :Définition des champs calculés et Définition des 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 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 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 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 CRM qui est mise à niveau vers Mise à jour 1 de Microsoft Dynamics CRM Online 2015, la propriété gérée CanChangeDateTimeBehavior est définie sur True sauf si l'attribut ou l'entité parente n'est pas personnalisable.

Notes

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

Les attributs de date et d'heure prédéfinis suivants dans Mise à jour 1 de Microsoft Dynamics CRM Online 2015 sont définis par défaut sur DateOnly et la propriété gérée 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	Invoice
estimatedclosedate	Lead
actualclosedate	Opportunity
estimatedclosedate	Opportunity
finaldecisiondate	Opportunity
validfromdate	Product
validtodate	Product
closedon	Quote
expireson	Quote

Toutefois, si ces attributs de date et d'heure prédéfinis appartiennent à une organisation qui est mise à niveau vers Mise à jour 1 de Microsoft Dynamics CRM Online 2015, le comportement de ces attributs sera défini sur UserLocal et la propriété gérée 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 l’exemple de code complet, voir Exemple : Convertir le comportement 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 CRM 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 ConvertDateAndTimeBehaviorRequest .

Le message vous permet de spécifier une règle de conversion (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 CRM 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.

Notes

Le message ConvertDateAndTimeBehaviorRequest est disponible uniquement si vous utilisez CRM Online, et que vous avez actualisé votre instance vers Mise à jour 1 de Microsoft Dynamics CRM Online 2015. Il n'est pas disponible pour Microsoft Dynamics CRM (local).
Vous devez disposer du rôle administrateur système dans votre instance CRM pour exécuter le message ConvertDateAndTimeBehaviorRequest.

Lorsque vous exécutez 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 de 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 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 ConvertDateAndTimeBehaviorRequest :

Vous devez éviter les modifications majeures dans les solutions Dynamics 365 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 l'exemple de code complet, voir Exemple : Convertir le comportement de date et d'heure

Voir aussi

Exemple : Convertir le comportement de date et d'heure
TechNet : Comportement et format du champ Date et heure
Personnaliser les métadonnées d’attribut d’entité

Share via

Comportement et format de l'attribut Date et heure

Contenu de la rubrique

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

Ressources supplémentaires