Comportamento e formato do atributo de data e hora

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

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:

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.

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.

• 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.

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.

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