Partager via


Comportement et format de l'attribut Date et heure

 

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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 Dynamics 365. 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 n'est disponible que si vous utilisez Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou Microsoft Dynamics 365 (en local). En outre, les attributs de date et d'heure dans Mise à jour 1 de CRM Online 2015 et Dynamics 365 (en local) prennent désormais en charge toutes les valeurs à partir du 1/1/1753 12:00 AM.

Dans les versions Dynamics 365 antérieures à Mise à jour 1 de CRM Online 2015 et Dynamics 365 (en local), 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 365 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 les versions Dynamics 365 antérieures à Mise à jour 1 de CRM Online 2015 ou Dynamics 365 (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 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 365 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 Dynamics 365 antérieures à Mise à jour 1 de CRM Online 2015 et Dynamics 365 (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 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 Dynamics 365, il ne pourra pas fonctionner correctement dans Mise à jour 1 de CRM Online 2015 et Dynamics 365 (en local) appartenant à 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 Dynamics 365 et que la propriété gérée CanChangeDateTimeBehavior pour l'attribut de date et heure est définie sur True.

Attention

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 Dynamics 365.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 Dynamics 365 qui est mise à niveau vers Mise à jour de CRM Online 2016 ou Dynamics 365, 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 CRM Online 2015 et Dynamics 365 (en local) 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 de Microsoft Dynamics CRM Online 2016 ou Dynamics 365 (en local), 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 Dynamics 365 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 Dynamics 365 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 n'est disponible que si vous utilisez Mise à jour 1 de CRM Online 2015 ou Dynamics 365 (en local). Il est indisponible pour les versions antérieures de Dynamics 365.

  • Vous devez disposer du rôle administrateur système dans votre instance Dynamics 365 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é

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright