Condividi tramite

Comportamento e formato dell'attributo di data e ora

  • Articolo

 

Data di pubblicazione: novembre 2016

Si applica a: Dynamics CRM 2015

Se hai utenti e uffici dislocati in tutto il mondo, è importante rappresentare correttamente i valori di data e ora in più fusi orari. La classe DateTimeAttributeMetadata è utilizzata per definire e gestire gli attributi di tipo DateTime in CRM. Utilizza la proprietà DateTimeAttributeMetadata.DateTimeBehavior per definire se archiviare o meno i valori di data e ora con le informazioni sul fuso orario e utilizzare la proprietà DateTimeAttributeMetadata.Format per specificare il formato di visualizzazione degli attributi.

Puoi utilizzare anche l'area di personalizzazione di Dynamics 365 per definire il comportamento e il formato degli attributi di data e ora.Ulteriori informazioni:TechNet: Comportamento e formato del campo di data e ora

Nota

La proprietà DateTimeAttributeMetadata.DateTimeBehavior è disponibile solo se utilizzi CRM Online e hai aggiornato l'istanza in uso a Aggiornamento 1 di Microsoft Dynamics CRM Online 2015. Inoltre, gli attributi di data e ora in Aggiornamento 1 di Microsoft Dynamics CRM Online 2015 ora supportano valori precedenti fino a 1/1/1753 12:00 AM.

Nelle altre versioni di CRM non puoi definire il comportamento dei valori di data e ora. Per impostazione predefinita, i valori di data e ora sono archiviati come comportamento UserLocal come descritto più avanti in questo argomento.

In questo argomento

Specificare il comportamento di un attributo di data e ora

Specificare il formato dell'attributo di data e ora

Gli operatori di query di data e ora non sono supportati per il comportamento DateOnly

Modificare il comportamento di un attributo di data e ora

Convertire il comportamento dei valori esistenti di data e ora nel database

Specificare il comportamento di un attributo di data e ora

Puoi utilizzare la classe DateTimeBehavior per specificare un valore per la proprietà DateTimeAttributeMetadata.DateTimeBehavior. La classe DateTimeBehavior contiene i seguenti membri; ogni membro restituisce una stringa con lo stesso valore del nome membro:

Nome membro e valore

Descrizione

UserLocal

  • Archivia il valore di data e ora come valore UTC nel sistema.

  • L'operazione di recupero restituisce il valore UTC.

  • L'operazione di aggiornamento converte il valore UTC nel valore del fuso orario dell'utente corrente e quindi archivia il valore aggiornato così com'è o come valore UTC equivalente a seconda del tipo (DateTimeKind) del valore specificato per l'aggiornamento. Se il valore specificato è di tipo UTC, viene archiviato così com'è. In caso contrario, viene archiviato il valore UTC equivalente.

  • Il valore formattato recuperato viene convertito da UTC in fuso orario dell'utente corrente sulla base delle impostazioni locali e del fuso orario dell'utente.

  • Per l'endpoint OData, l'attributo è esposto come DateTimeOffset.

  • Questo comportamento è utilizzato per gli attributi di sistema come CreatedOn e ModifiedOn e non può essere modificato. Devi utilizzare questo comportamento per gli attributi personalizzati per cui desideri archiviare i valori di data e ora con le informazioni sul fuso orario.

DateOnly

  • Archivia nel sistema il valore della data effettiva con il valore dell'ora nel formato 12:00 AM (00:00:00).

  • Per le operazioni di aggiornamento e recupero, la conversione del fuso orario non viene eseguita e il valore dell'ora è sempre 12:00 AM (00:00:00).

  • Il recupero del valore formattato visualizza il valore della data senza la conversione del fuso orario.

  • Per l'endpoint OData, l'attributo è esposto come DateTimeOffset.

  • Questo comportamento deve essere utilizzato per gli attributi personalizzati che archiviano compleanni e anniversari, per cui le informazioni sull'ora non sono richieste.

TimeZoneIndependent

  • Archivia i valori di data e ora effettivi nel sistema indipendentemente dal fuso orario dell'utente.

  • Per le operazioni di aggiornamento e recupero, non viene eseguita la conversione del fuso orario e i valori di data e ora effettivi vengono restituiti e aggiornati rispettivamente nel sistema, indipendentemente dal fuso orario dell'utente.

  • Il recupero del valore formattato visualizza il valore di data e ora (senza la conversione del fuso orario) sulla base del formato specificato dalle impostazioni locali e dal fuso orario dell'utente corrente.

  • Per l'endpoint OData, l'attributo è esposto come DateTimeOffset.

  • Questo comportamento deve essere utilizzato per gli attributi che archiviano informazioni quali l'ora del check-in e del check-out per gli hotel.

Il seguente codice di esempio illustra come impostare un comportamento UserLocal per un nuovo attributo di data e ora:


// 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);

Nel codice di esempio, puoi anche impostare il valore della proprietà DateTimeBehavior specificando direttamente il valore stringa: DateTimeBehavior = "UserLocal"

Se non specifichi il comportamento per la creazione di un attributo di data e ora, l'attributo viene creato con il comportamento UserLocal per impostazione predefinita. Per il codice di esempio completo, vedere Esempio: Convertire il comportamento di data e ora.

Importante

  • Dopo aver creato un attributo di data e ora con il comportamento impostato su DateOnly o TimeZoneIndependent, non puoi modificare il comportamento dell'attributo.Ulteriori informazioni:Modificare il comportamento di un attributo di data e ora

  • Gli attributi di data e ora con il comportamento TimeZoneIndependent o DateOnly verranno elaborati come avessero il comportamento UserLocal se vengono modificati in una versione precedente del client di Dynamics CRM per Outlook in modalità offline. Ciò avviene perché il client non riconosce i nuovi comportamenti e non li tratterà in modo diverso da UserLocal (comportamento esistente in altre versioni di CRM, ad eccezione di Aggiornamento 1 di Microsoft Dynamics CRM Online 2015). Nessun attributo di data e ora viene convertito nei nuovi comportamenti in fase di aggiornamento e quindi la procedura consigliata sarà quella di aggiornare tutti i client di Dynamics CRM per Outlook all'ultima versione prima che un'operazione di personalizzazione adotti uno dei nuovi comportamenti. In modalità online, la modifica dei dati per i campi con i nuovi comportamenti viene eseguita correttamente.

    Anche i client di Dynamics CRM per Outlook meno recenti non riconoscono le date precedenti a 1/1/1900 (il valore meno recente supportato per i tipi di data e ora in altre versioni di CRM, ad eccezione di Aggiornamento 1 di Microsoft Dynamics CRM Online 2015). Gli utenti non possono aprire i record con date precedenti a 1/1/1900 in modalità offline. Tuttavia, in modalità online l'operazione viene eseguita correttamente. Devi eseguire l'aggiornamento alla versione più recente dei client di Dynamics CRM per Outlook per utilizzare gli attributi con date precedenti fino a 1/1/1753 12:00 AM anche in modalità offline.

  • Se utilizzi un codice personalizzato per implementare un comportamento di data e ora nell'istanza di CRM in uso, è possibile che il codice non funzioni come previsto in Aggiornamento 1 di Microsoft Dynamics CRM Online 2015 a causa della nuova funzionalità di comportamento.

Specificare il formato dell'attributo di data e ora

Utilizza la proprietà DateTimeAttributeMetadata.Format per specificare il formato di visualizzazione della data e dell'ora dell'attributo indipendentemente da come viene archiviato nel sistema. Puoi utilizzare l'enumerazione DateTimeFormat per specificare il formato di visualizzazione: DateAndTime o DateOnly.

Se la proprietà DateTimeBehavior è impostata su DateOnly, non puoi impostare o modificare il valore della proprietà Format su DateAndTime.

Gli operatori di query di data e ora non sono supportati per il comportamento DateOnly

Gli operatori di query relativi al tempo non sono supportati per il comportamento DateOnly. Sono supportati tutti gli operatori di query, ad eccezione di quelli specificati di seguito.

  • Oltre X minuti fa

  • Oltre X ore fa

  • Ultime X ore

  • Prossime X ore

Ulteriori informazioni:Operatori di query "oltre" data/ora e data fiscale in FetchXML

Modificare il comportamento di un attributo di data e ora

Puoi aggiornare un attributo di data e ora per modificarne il comportamento se disponi del ruolo Addetto personalizzazione sistema nell'istanza di CRM e la proprietà gestita CanChangeDateTimeBehavior per l'attributo di data e ora è impostata su True.

Attenzione

Prima di modificare il comportamento di un attributo di data e ora, devi controllare tutte le dipendenze dell'attributo, ad esempio le regole di business, i flussi di lavoro e gli attributi calcolati o di rollup, per assicurarti che non si verifichino problemi a seguito della modifica del comportamento. Gli addetti alla personalizzazione del sistema possono limitare la modifica del comportamento degli attributi esistenti di data e ora utilizzando la proprietà gestita CanChangeDateTimeBehavior.

Dopo aver modificato il comportamento di un attributo di data e ora, devi almeno aprire ogni regola di business, flusso di lavoro, attributo calcolato e record di attributo di rollup che dipende dall'attributo di data e ora modificato, controllare le informazioni e salvare il record in modo da garantire che vengano utilizzati il comportamento e il valore dell'attributo più recenti.

Dopo aver modificato il comportamento della data e dell'ora di un attributo calcolato o di rollup, apri l'editor delle definizioni dei campi calcolati o di rollup e salva la definizione del campo in modo che l'attributo sia valido anche dopo la modifica del comportamento. Gli addetti alla personalizzazione del sistema possono aprire l'editor delle definizioni dei campi per l'attributo calcolato o di rollup facendo clic su Modifica accanto a Tipo di campo nell'area di personalizzazione in CRM.Ulteriori informazioni:Definire campi calcolati e Definire i campi di rollup

  • Il comportamento degli attributi CreatedOn e ModifiedOn per le entità predefinite e personalizzate è impostato su UserLocal per impostazione predefinita e la proprietà gestita CanChangeDateTimeBehavior è impostata su False a indicare che non puoi modificare il comportamento di tali attributi. Sebbene gli utenti possano modificare il valore della proprietà gestita CanChangeDateTimeBehavior di questi attributi per le entità personalizzate, non possono comunque modificare il comportamento degli attributi.

  • Per i nuovi attributi personalizzati di data e ora, la proprietà gestita CanChangeDateTimeBehavior è impostata su True. Questo implica che puoi modificare il comportamento di un attributo personalizzato di data e ora da UserLocal in DateOnly o TimeZoneIndependent; non sono consentite altre transizioni di comportamento.

    Per gli attributi personalizzati di data e ora che fanno parte dell'organizzazione CRM che viene aggiornata a Aggiornamento 1 di Microsoft Dynamics CRM Online 2015, la proprietà gestita CanChangeDateTimeBehavior è impostata su True a meno che l'attributo o l'entità padre non sia personalizzabile.

    Nota

    Quando aggiorni la proprietà DateTimeBehavior di un attributo da UserLocal a DateOnly, assicurati di modificare anche la proprietà Format da DateAndTime a DateOnly. In caso contrario, si verifica un'eccezione.

  • I seguenti attributi di data e ora predefiniti in Aggiornamento 1 di Microsoft Dynamics CRM Online 2015 sono per impostazione predefinita impostati su DateOnly e la proprietà gestita CanChangeDateTimeBehavior è impostata su False per questi attributi a indicare che non puoi cambiare il comportamento degli attributi:

    Attributo di data e ora

    Entità padre

    anniversary

    Contact

    birthdate

    Contact

    duedate

    Invoice

    estimatedclosedate

    Lead

    actualclosedate

    Opportunity

    estimatedclosedate

    Opportunity

    finaldecisiondate

    Opportunity

    validfromdate

    Product

    validtodate

    Product

    closedon

    Quote

    expireson

    Quote

    Tuttavia, se questi attributi predefiniti di data e ora appartengono a un'organizzazione che viene aggiornata a Aggiornamento 1 di Microsoft Dynamics CRM Online 2015, il comportamento di questi attributi viene impostato su UserLocal e la proprietà gestita CanChangeDateTimeBehavior viene impostata su True nell'organizzazione aggiornata e quindi puoi modificare il comportamento di tali attributi solo su DateOnly. Non sono consentite altre transizioni di comportamento.

Dopo aver aggiornato il comportamento di un attributo, devi pubblicare le personalizzazioni per rendere effettiva la modifica. L'aggiornamento del comportamento di un attributo di data e ora garantisce che tutti i valori immessi o aggiornati dopo la modifica del comportamento dell'attributo vengano archiviati nel sistema in base al nuovo comportamento. Ciò non riguarda i valori già memorizzati nel database che continuano ad essere archiviati come valori UTC. Tuttavia, quando recuperi i valori esistenti con l'SDK o li visualizzi nell'interfaccia utente, i valori esistenti vengono visualizzati in base al nuovo comportamento dell'attributo. Ad esempio, se hai modificato il comportamento di un attributo personalizzato in un'entità account da UserLocal a DateOnly e recuperi un record di account esistente utilizzando l'SDK, la data e l'ora vengono visualizzate come <Date> seguita dall'ora come 12:00 AM (00:00:00). Analogamente, per la modifica del comportamento da UserLocal a TimeZoneIndependent, il valore effettivo nel database viene visualizzato così com'è, senza alcuna conversione di fuso orario.

Il seguente codice di esempio illustra come aggiornare il comportamento di un attributo di data e ora:


// 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");

Per il codice di esempio completo, vedere Esempio: Convertire il comportamento di data e ora.

Convertire il comportamento dei valori esistenti di data e ora nel database

Quando aggiorni un attributo di data e ora per modificarne il comportamento da UserLocal a DateOnly o TimeZoneIndependent, i valori di attributo esistenti nel database non vengono convertiti automaticamente. La modifica del comportamento riguarda solo i valori che verranno immessi o aggiornati nell'attributo dopo aver modificato il comportamento. I valori di data e ora esistenti nel sistema continuano a essere nel formato UTC e vengono visualizzati da CRM in base al nuovo comportamento quando recuperati tramite l'SDK o nell'interfaccia utente come descritto nella sezione precedente. Per gli attributi il cui comportamento è stato modificato da UserLocal a DateOnly, puoi convertire i valori UTC esistenti nel database nel valore DateOnly appropriato per evitare anomalie sui dati, utilizzando il messaggio ConvertDateAndTimeBehaviorRequest.

Il messaggio ti consente di specificare una regola di conversione (ConversionRule) per selezionare il fuso orario da utilizzare nella conversione dei valori da UTC a DateOnly. Puoi specificare una delle seguenti regole di conversione:

  • SpecificTimeZone: converte il valore UTC in un valore DateOnly in base al codice specificato per il fuso orario di CRM. In questo caso, devi inoltre specificare un valore per il parametro TimeZoneCode.

  • CreatedByTimeZone: converte il valore UTC in un valore DateOnly che viene visualizzato nell'interfaccia dell'utente che ha creato il record.

  • OwnerTimeZone: converte il valore UTC in un valore DateOnly che viene visualizzato nell'interfaccia dell'utente proprietario del record.

  • LastUpdatedByTimeZone: converte il valore UTC in un valore DateOnly che viene visualizzato nell'interfaccia dell'utente che ha eseguito l'ultimo aggiornamento del record.

Puoi utilizzare uno dei quattro membri della classe DateTimeBehaviorConversionRule per specificare un valore valido per il parametro ConversionRule.

Nota

  • Il messaggio ConvertDateAndTimeBehaviorRequest è disponibile solo se utilizzi CRM Online e hai aggiornato l'istanza in uso a Aggiornamento 1 di Microsoft Dynamics CRM Online 2015. Non è disponibile per Microsoft Dynamics CRM (locale).

  • Per eseguire il messaggio ConvertDateAndTimeBehaviorRequest, devi disporre del ruolo di amministratore di sistema per l'istanza di CRM.

Quando esegui il messaggio ConvertDateAndTimeBehaviorRequest, viene creato un processo di sistema (operazione asincrona) per eseguire la richiesta di conversione. L'attributo ConvertDateAndTimeBehaviorResponse.JobId nella risposta del messaggio visualizza l'ID del processo di sistema creato in seguito alla richiesta di conversione. Al termine del processo di sistema, controlla i dettagli del processo (AsyncOperation.Message) per visualizzare i dettagli o gli errori della conversione, se presenti.

Nota

È consigliabile raggruppare la conversione di più attributi in un singolo processo di conversione ed eseguire un singolo processo di conversione alla volta per assicurare che non vi siano conflitti nella conversione e per le prestazioni ottimali del sistema.

Alcuni aspetti importanti da considerare quando si utilizza il messaggio ConvertDateAndTimeBehaviorRequest:

  • Devi evitare di applicare modifiche sostanziali alle soluzioni in Dynamics 365 durante l'esecuzione del messaggio, come importare una soluzione o eliminare un'entità padre o un attributo. In caso contrario, si potrebbe verificare un comportamento imprevisto, sebbene senza perdita di dati.

  • Gli aggiornamenti effettuati nel sistema in seguito all'esecuzione del messaggio non eseguiranno i flussi di lavoro e i plug-in.

  • Gli aggiornamenti effettuati nel sistema in seguito all'esecuzione del messaggio non modificheranno il valore dell'ultima modifica per gli attributi, ma saranno controllati per assistere gli amministratori nella determinazione dell'ora della conversione e dei valori originali/modificati di un attributo.

Nell'esempio di codice seguente viene illustrato come utilizzare il messaggio:


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);

Per il codice di esempio completo, vedi Esempio: Convertire il comportamento di data e ora

Vedere anche

Esempio: Convertire il comportamento di data e ora
TechNet: Comportamento e formato del campo di data e ora
Personalizzare i metadati degli attributi di entità

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright