Compartilhar via

Comportamento e formato do atributo de data e hora

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Se você tiver usuários e escritórios ao redor do mundo, é importante representar corretamente os valores de data e hora em vários fusos horários. A classe DateTimeAttributeMetadata é usada para definir e gerenciar atributos do tipo DateTime no Dynamics 365. Use a propriedade DateTimeAttributeMetadata.DateTimeBehavior para definir se os valores de data e hora devem ser armazenados com ou sem informações de fuso horário, e use a propriedade DateTimeAttributeMetadata.Format para especificar o formato de exibição desses atributos.

Você também pode usar a área personalização no Dynamics 365 para definir o comportamento e o formato dos atributos de data e hora.Para obter mais informações:TechNet: comportamento e formato do campo de data e hora

Observação

A propriedade DateTimeAttributeMetadata.DateTimeBehavior está disponível somente quando você está usando o Atualização 1 do Microsoft Dynamics CRM Online 2015 ou o Microsoft Dynamics 365 (local). Além disso, todos os atributos de data e hora no CRM Online 2015 Atualização 1 e Dynamics 365 (local) agora dão suporte a valores a partir de 1/1/1753 12:00 AM.

Em versões do Dynamics 365 anteriores ao CRM Online 2015 Atualização 1 e Dynamics 365 (local), não é possível definir o comportamento dos valores de data e hora. Por padrão, os valores de data e hora são armazenados como o comportamento UserLocal, conforme descrito mais adiante neste tópico.

Neste tópico

Especificar o comportamento de um atributo de data e hora

Especificar o formato do atributo de data e hora

Operadores de consulta de data e hora sem suporte para o comportamento DateOnly

Alterar o comportamento de um atributo de data e hora

Converter o comportamento de valores existentes de data e hora no banco de dados

Especificar o comportamento de um atributo de data e hora

Você pode usar a classe DateTimeBehavior para especificar um valor para a propriedade DateTimeAttributeMetadata.DateTimeBehavior. A classe DateTimeBehavior contém os seguintes membros; cada membro retorna uma cadeia de caracteres com o mesmo valor que o nome do membro:

Nome e valor do membro

Descrição

UserLocal

  • Armazena o valor de data e hora como o valor UTC no sistema.

  • A operação de recuperação retorna o valor UTC.

  • A operação de atualização converte o valor UTC no valor atual de fuso horário do usuário, e armazena o valor atualizado como tal ou como o valor UTC equivalente, dependendo do tipo (DateTimeKind) do valor especificado para atualização. Se o valor especificado for do tipo UTC, ele será armazenado como tal. Caso contrário, o valor equivalente a UTC será armazenado.

  • A recuperação do valor formatado converte do UTC para o fuso horário atual do usuário com base no fuso horário e na configuração local do usuário.

  • Para o ponto de extremidade OData, o atributo é exposto como DateTimeOffset.

  • Esse comportamento é usado para atributos do sistema como CreatedOn e ModifiedOn, e não pode ser alterado. Use esse comportamento para os atributos personalizados onde você deseja armazenar valores de data e hora com as informações de fuso horário.

DateOnly

  • Armazena o valor de data real com o valor de hora como 12:00 AM (00:00:00) no sistema.

  • Para as operações de recuperação e atualização, nenhuma conversão de fuso horário é realizada, e o valor de hora é sempre 12 AM (00:00: 00).

  • Recuperar o valor formatado exibe o valor de data sem conversão de fuso horário.

  • Para o ponto de extremidade OData, o atributo é exposto como DateTimeOffset.

  • Esse comportamento deve ser usado com os atributos personalizados que armazenam aniversários e datas especiais, onde as informações de hora não são necessárias.

TimeZoneIndependent

  • Armazena os valores de data e hora no sistema, seja qual for o fuso horário do usuário.

  • Para as operações de recuperação e atualização, nenhuma conversão de fuso horário é realizada, e os valores reais de data e hora são retornados e atualizados, respectivamente, no sistema, seja qual for o fuso horário do usuário.

  • Recuperar o valor formatado exibe o valor de data e hora (sem conversão de fuso horário) com base no formato, conforme especificado pelo fuso horário e pela configuração local do usuário atual.

  • Para o ponto de extremidade OData, o atributo é exposto como DateTimeOffset.

  • Esse comportamento deve ser usado para os atributos que armazenam informações, como as horas de check-in e check-out em hotéis.

O seguinte código de exemplo demonstra como definir um comportamento UserLocal para um novo atributo de data e hora:


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

No código de exemplo, você também pode definir o valor da propriedade DateTimeBehavior especificando diretamente o valor da cadeia de caracteres: DateTimeBehavior = "UserLocal"

Se você não especificar o comportamento ao criar um atributo de data e hora, o atributo será criado com o comportamento UserLocal por padrão. Para o código de exemplo completo, consulte Exemplo: converter comportamento de data e hora.

Importante

  • Depois de criar um atributo de data e hora com o comportamento definido como DateOnly ou TimeZoneIndependent, você não poderá alterar o comportamento do atributo.Para obter mais informações:Alterar o comportamento de um atributo de data e hora

  • Os atributos de data e hora com o comportamento DateOnly ou TimeZoneIndependent serão tratados como apresentando o comportamento UserLocal quando editados em uma versão anterior do cliente Dynamics 365 para Outlook no modo offline. Isso acontece porque o cliente não compreende os novos comportamentos e não os tratará de maneira diferente do UserLocal (comportamento existente em outras versões do Dynamics 365 anteriores ao CRM Online 2015 Atualização 1 ou Dynamics 365 (local)). Nenhum atributo de data e hora é convertido em novos comportamentos na atualização; então, a prática recomendada aqui seria atualizar todos os clientes Dynamics 365 para Outlook para a versão mais recente antes de um personalizador adotar um dos novos comportamentos. Online, a edição de dados para campos com os novos comportamentos funcionará bem.

    Os clientes do Dynamics 365 para Outlook mais antigos também não compreenderão as datas anteriores a 1/1/1900 (o valor mais antigo do suporte para os tipos de data e hora em versões do Dynamics 365 anteriores ao CRM Online 2015 Atualização 1 e Dynamics 365 (local)). Os usuários não poderão abrir registros com datas anteriores a 1/1/1900 quando estiverem offline. Entretanto, tudo funcionará bem quando eles estiverem online. Você deve atualizar para a versão mais recente dos clientes do Dynamics 365 para Outlook para trabalhar com atributos com datas a partir de 1/1/1753 12:00 AM também no modo offline.

  • Se você usar o código personalizado para implementar o comportamento de data e hora na instância do Dynamics 365, talvez isso não funcione conforme o esperado no CRM Online 2015 Atualização 1 e Dynamics 365 (local) devido ao novo comportamento.

Especificar o formato do atributo de data e hora

Use a propriedade DateTimeAttributeMetadata.Format para especificar o formato de exibição de data/hora do atributo, independentemente de como ele é armazenado no sistema. Você pode usar a enumeração DateTimeFormat para especificar o formato de exibição: DateAndTime ou DateOnly.

Se a propriedade DateTimeBehavior estiver definida como DateOnly, você não poderá definir ou alterar o valor de propriedade Format para DateAndTime.

Operadores de consulta de data e hora sem suporte para o comportamento DateOnly

Os operadores de consulta relacionados a hora não têm suporte no comportamento DateOnly. Além dos operadores de consulta específicos de hora listados aqui, todos os demais operadores de consulta têm suporte.

  • Anterior a X Minutos

  • Anterior a X Horas

  • Últimas X Horas

  • Próximas X Horas

Para obter mais informações:Operadores de consulta de data fiscal e de data/hora "mais antigo do que" no FetchXML

Alterar o comportamento de um atributo de data e hora

Você pode atualizar o atributo de data e hora para alterar o comportamento se tiver a função Personalizador de Sistema na instância do Dynamics 365 e a propriedade gerenciada CanChangeDateTimeBehavior para o atributo de data e hora é definida como True.

Cuidado

Antes de alterar o comportamento de um atributo de data e hora, você deve examinar todas as dependências do atributo, como regras de negócios, fluxos de trabalho, e atributos calculados ou cumulativos, para garantir que não haja problemas como resultado da alteração do comportamento. Personalizadores de sistema podem restringir a modificação no comportamento dos atributos existentes de data e hora usando a propriedade gerenciada CanChangeDateTimeBehavior.

No mínimo, após alterar o comportamento de um atributo de data e hora, você deve abrir cada regra de negócios, fluxo de trabalho, atributo calculado e registro de atributo cumulativo que é dependente do atributo de data e hora alterado, examinar as informações e salvar o registro para garantir que sejam usados o comportamento e o valor do atributo mais recente.

Depois de alterar o comportamento de data e hora de um atributo calculado ou acumulado, abra o editor de definição do campo calculado ou acumulado, e salve a definição do campo para garantir que o atributo ainda seja válido para após a alteração de comportamento. Personalizadores de sistema podem abrir o editor de definição do campo para o atributo calculado ou acumulado, clicando em Editar ao lado de Tipo de Campo na área de personalização do Dynamics 365.Para obter mais informações:Definir campos calculados e Definir campos cumulativos

  • O comportamento dos atributos CreatedOn e ModifiedOn para as entidades integradas e personalizadas é definido como UserLocal por padrão, e a propriedade gerenciada CanChangeDateTimeBehavior é definida como False, que implica que você não pode alterar o comportamento desses atributos. Embora os usuários possam alterar o valor da propriedade gerenciada CanChangeDateTimeBehavior desses atributos para entidades personalizadas, eles ainda não podem alterar o comportamento dos atributos.

  • Para novos atributos personalizados de data e hora, a propriedade gerenciada CanChangeDateTimeBehavior é definida como True. Isso implica que você pode modificar o comportamento de um atributo personalizado de data e hora de UserLocal para DateOnly ou TimeZoneIndependent; nenhuma outra transição de comportamento é permitida.

    Para atributos personalizados de data e hora que fazem parte de uma organização do Dynamics 365 que foi atualizada para o Atualização do CRM Online 2016 ou Dynamics 365 (local), a propriedade gerenciada CanChangeDateTimeBehavior está definida como True, a menos que o atributo ou a entidade principal não seja personalizável.

    Observação

    Quando atualizar a propriedade DateTimeBehavior de um atributo de UserLocal para DateOnly, verifique se você também alterou a propriedade Format de DateAndTime para DateOnly. Caso contrário, ocorrerá uma exceção.

  • Os seguintes atributos integrados de data e hora no CRM Online 2015 Atualização 1 e Dynamics 365 (local) são definidos por padrão como DateOnly e a propriedade gerenciada CanChangeDateTimeBehavior é definida como False desses atributos, o que significa que você não pode alterar o comportamento desses atributos:

    Atributo de data e hora

    Entidade principal

    anniversary

    Contact

    birthdate

    Contact

    duedate

    Invoice

    estimatedclosedate

    Lead

    actualclosedate

    Opportunity

    estimatedclosedate

    Opportunity

    finaldecisiondate

    Opportunity

    validfromdate

    Product

    validtodate

    Product

    closedon

    Quote

    expireson

    Quote

    Entretanto, se esses atributos de data e hora integrados pertencerem a uma organização que está atualizada para Atualização do Microsoft Dynamics CRM Online 2016 ou Dynamics 365 (local), o comportamento desses atributos será definido como UserLocal e a propriedade gerenciada CanChangeDateTimeBehavior como True na organização atualizada. Você pode alterar o comportamento desses atributos somente para DateOnly. Nenhuma outra transição de comportamento é permitida.

Após atualizar o comportamento de um atributo, você deve publicar as personalizações para que a alteração tenha efeito. A atualização do comportamento de um atributo de data e hora garante que todos os valores inseridos/atualizados após a alteração do comportamento do atributo sejam armazenados no sistema de acordo com o novo comportamento. Isso não afeta os valores que já estão armazenados no banco de dados, e eles continuam a ser armazenados como valores UTC. No entanto, quando você recupera os valores existentes usando o SDK ou exibe-os na interface do usuário, os valores existentes são exibidos conforme o novo comportamento do atributo. Por exemplo, se você tiver alterado o comportamento de um atributo personalizado em uma entidade da conta de UserLocal para DateOnly e recuperar um registro de conta existente usando o SDK, a data e a hora serão exibidas como <Data> seguida da hora como 12 AM (00:00:00). Da mesma forma, para que o comportamento mude de UserLocal para TimeZoneIndependent, o valor real no banco de dados será exibido como tal, sem conversões de fuso horário.

O seguinte código de exemplo demonstra como atualizar o comportamento de um atributo de data e hora:


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

Para o código de exemplo completo, consulte Exemplo: converter comportamento de data e hora.

Converter o comportamento de valores existentes de data e hora no banco de dados

Quando você atualiza um atributo de data e hora para alterar seu comportamento de UserLocal para DateOnly ou TimeZoneIndependent, ele não converte automaticamente os valores existentes do atributo no banco de dados. A alteração de comportamento afeta somente os valores que serão inseridos ou atualizados no atributo após o comportamento ser alterado. Os valores de data e hora existentes no sistema permanecem no UTC, e são exibidos pelo Dynamics 365 de acordo com o novo comportamento quando recuperados através do SDK ou na interface do usuário, conforme explicado na seção anterior. Para atributos cujo comportamento foi alterado de UserLocal para DateOnly, você pode converter os valores de UTC existentes do banco de dados no valor DateOnly apropriado para evitar anomalias de dados usando a mensagem ConvertDateAndTimeBehaviorRequest.

A mensagem permite especificar uma regra de conversão(ConversionRule) para selecionar o fuso horário a ser usado na conversão dos valores de UTC em DateOnly. É possível especificar uma das seguintes regras de conversão:

  • SpecificTimeZone: converte o valor de UTC em um valor DateOnly conforme o código de fuso horário do Dynamics 365 especificado. Nesse caso, você também precisa especificar um valor para o parâmetro TimeZoneCode.

  • CreatedByTimeZone: converte o valor de UTC em um valor DateOnly que usuário que criou o registro poderia ver na interface do usuário.

  • OwnerTimeZone: converte o valor de UTC em um valor DateOnly que o usuário dono do registro veria na interface do usuário.

  • LastUpdatedByTimeZone: converte o valor de UTC em um valor DateOnly que o usuário que atualizou o registro pela última vez poderia ver na interface do usuário.

Use um dos quatro membros da classe DateTimeBehaviorConversionRule para especificar um valor válido para o parâmetro ConversionRule.

Observação

  • A mensagem ConvertDateAndTimeBehaviorRequest está disponível somente quando você está usando o CRM Online 2015 Atualização 1 or Dynamics 365 (local). Não está disponível para versões anteriores do Dynamics 365.

  • Você precisa ter a função Administrador do Sistema na instância do Dynamics 365 para executar a mensagem ConvertDateAndTimeBehaviorRequest.

Quando você executa a mensagem ConvertDateAndTimeBehaviorRequest, um trabalho do sistema (operação assíncrona) é criado para executar a solicitação de conversão. O atributo ConvertDateAndTimeBehaviorResponse.JobId na resposta da mensagem exibe a ID do trabalho do sistema que é criado como resultado da solicitação de conversão. Quando o trabalho do sistema for concluído, verifique os detalhes do trabalho (AsyncOperation.Message) para exibir detalhes ou erros de conversão, caso existam.

Observação

É recomendável agrupar a conversão de vários atributos em um único trabalho de conversão, e executar um único trabalho de conversão de cada vez para garantir que não existam conflitos na conversão e para atingir o desempenho ideal do sistema.

Alguns aspectos importantes a serem considerados ao usar a mensagem ConvertDateAndTimeBehaviorRequest:

  • Você deve evitar todas as alterações em grande escala nas soluções do Dynamics 365 durante a execução da mensagem, como importar uma solução ou excluir um atributo ou entidade principal. Isso pode resultar em um comportamento inesperado; contudo, não haverá perda de dados.

  • As atualizações feitas no sistema como resultado da execução da mensagem não executarão fluxos de trabalho e plug-ins.

  • As atualizações feitas no sistema como resultado da execução da mensagem não alterarão o valor de “última modificação em“ para os atributos, mas serão auditadas para ajudar os administradores a determinarem o momento da conversão e os valores originais/alterados de um atributo.

O seguinte código de exemplo mostra como usar a mensagem:


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

Para o código de exemplo completo, consulte Exemplo: converter comportamento de data e hora

Confira Também

Exemplo: converter comportamento de data e hora
TechNet: comportamento e formato do campo de data e hora
Personalizar metadados do atributo de entidades

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais