Configurar o comportamento e o formato da coluna de data e hora usando o código

Se você tiver usuários e escritórios em todo o mundo, é importante representar corretamente valores de data e hora em vários fusos horários. Use o DateTimeAttributeMetadata (tipo de entidade DateTimeAttributeMetadata ou Classe DateTimeAttributeMetadata) para definir e gerenciar colunas de tipo DateTime no Microsoft Dataverse. Use a propriedade DateTimeBehavior (para o SDK para .NET, consulte DateTimeBehavior Property) para definir se os valores de data e hora devem ser armazenados com ou sem informações de fuso horário. Use a Propriedade DateTimeAttributeMetadata.Format para especificar o formato de exibição para essas colunas.

Você também pode usar a área de personalização no Dataverse para definir o comportamento e o formato das colunas de data e hora. Para obter mais informações, consulte Comportamento e formato da coluna Data e Hora.

Observação

Todas as colunas de data e hora no Dataverse dão suporte a valores tão cedo quanto 1/1/1753 12:00 AM.

Se o campo Data Somente ou Data e Hora estiver em uma solução, você só poderá alterar o comportamento de um campo gerenciado existente se for o publicador. Para fazer uma alteração nesses campos, você deve atualizar a solução que adicionou a coluna Date Only ou Date Time. Para obter mais informações, consulte Fazer upgrade ou atualizar uma solução.

Especificar o comportamento de uma coluna de data e hora

Use o DateTimeBehavior (tipo complexo DateTimeBehavior ou Classe DateTimeBehavior) para especificar um valor para o tipo de entidade DateTimeAttributeMetadata. Propriedade DateTimeBehavior. DateTimeBehavior contém os membros a seguir. 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 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 de fuso horário do usuário atual e armazena o valor atualizado como está 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 está. Caso contrário, o valor equivalente a UTC será armazenado. – Recuperar o valor formatado converte de UTC para o fuso horário atual do usuário com base no fuso horário e na configuração de localidade do usuário. - Para a API Web, a coluna é exposta como DateTimeOffset. - Esse comportamento é usado para colunas do sistema, como `CreatedOn` e `ModifiedOn`, e não pode ser alterado. Use esse comportamento para colunas personalizadas em que você deseja armazenar valores de data e hora com as informações de fuso horário.
`DateOnly`	- Armazena o valor de data real sem nenhum valor de hora. – A recuperação do valor formatado exibe o valor da data. - Para a API Web, a coluna é apresentada como Data. – Use esse comportamento para colunas personalizadas que armazenam aniversários e datas comemorativas, onde a informação de tempo não é necessária.
`TimeZoneIndependent`	- Armazena os valores reais de data e hora no sistema, independentemente do fuso horário do usuário. - Para as operações de recuperação e atualização, nenhuma conversão de fuso horário é executada e os valores reais de data e hora são retornados e atualizados respectivamente no sistema, independentemente do fuso horário do usuário. - A recuperação do valor formatado exibe o valor de data e hora (sem nenhuma conversão de fuso horário) com base no formato especificado pelo fuso horário e configuração de localidade do usuário atual. - Para a API Web, a coluna é exposta como DateTimeOffset. – Use esse comportamento para colunas que armazenam informações como horário de check-in e check-out em hotéis.

O código de exemplo a seguir demonstra como definir um UserLocal comportamento para uma nova coluna de data e hora:

/// <summary>
/// Create a new DateTime column for the Account table with UserLocal behavior
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void CreateUserLocalDateTimeColumn(IOrganizationService service) {

   int _languageCode = 1033; //English

   DateTimeAttributeMetadata dtAttribute = new()
   {
       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 = Microsoft.Xrm.Sdk.Metadata.DateTimeFormat.DateAndTime,
       ImeMode = ImeMode.Disabled
   };

   CreateAttributeRequest request = new()
   {
       EntityName = Account.EntityLogicalName,
       Attribute = dtAttribute
   };

   service.Execute(request);
}

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

Se você não especificar o comportamento ao criar uma coluna de data e hora, a coluna será criada com o UserLocal comportamento por padrão.

Importante

Depois de criar uma coluna de data e hora com o comportamento definido como DateOnly ou TimeZoneIndependent, você não poderá alterar o comportamento da coluna. Para obter mais informações, consulte Alterar o comportamento de uma coluna DateTime.
As colunas de data e hora com o comportamento DateOnly ou TimeZoneIndependent são tratadas como se tivessem o comportamento UserLocal quando editadas em uma versão anterior do cliente do Dynamics 365 para o Outlook no modo offline. Essa limitação existe porque o cliente não entende os novos comportamentos e não os trata de forma diferente.UserLocal Nenhuma coluna de data e hora é convertida para os novos comportamentos durante a atualização. Para evitar essa limitação, atualize todos os clientes do Dataverse para a versão mais recente antes que um personalizador adote um dos novos comportamentos. Quando online, a edição de dados para colunas com os novos comportamentos funciona bem.

Especificar o formato da coluna de data e hora

Use a Format propriedade para especificar o formato de exibição de data/hora da coluna, independentemente de como o sistema a armazena. Use a DateTimeFormat enumeração (tipo de enumeração DateTimeFormat ou DateTimeFormat Enum) para especificar o formato de exibição: DateAndTime ou DateOnly.

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

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

Não há suporte para o comportamento de DateOnly por operadores de consulta relacionados ao tempo. Além dos operadores de consulta específicos ao tempo listados aqui, todos os outros operadores de consulta têm suporte.

Anterior a X Minutos
Anterior a X Horas
Últimas X Horas
Próximas X Horas

Mais informações: operadores de dados DateTime

Usando APIs OData para enviar valores de data e hora local do usuário

No Microsoft Power Platform, quando um usuário envia uma data e hora no fuso horário específico do usuário por meio da interface do usuário, um cálculo automático define os dados como a data e a hora corretas. Ele executa uma análise para alterar qualquer data enviada para o valor UTC correspondente com base nas configurações de coluna e interface do usuário. Quando você envia um valor de data e hora usando a operação da API Web, o cálculo não ocorre, o que resulta em exibições de dados inexplicáveis. Por exemplo, se você estiver no fuso horário do Pacífico e enviar 4/4/2021 12:00, o seguinte acontecerá:

Original: 4/4/2021 12:00 o remetente está no fuso horário do Pacífico.
Enviado pela interface do usuário e recuperado como usuário local: 4/4/2021 12:00
Enviado por meio da API e recuperado como usuário local: 4/4/2021 04:00

Enviando por meio da UI

A interface do usuário configura o valor como local do usuário, e a coluna é configurada como local do usuário.

Valor Original: 4/4/2021 12:00 no fuso horário do Pacífico.
Valor calculado para UTC e armazenado no Dataverse: 4/4/2021 12:00 + 8:00 = 4/4/2021T20:00:00Z . Esse valor ocorre porque o PST é -8:00 de UTC, portanto+ 8 é adicionado ao valor armazenado.
Valor quando exibido na interface do usuário por um usuário no fuso horário do Pacífico: 4/4/2021 12:00. A interface do usuário aplica o cálculo de deslocamento UTC -8:00 a 4/4/2021T20:00:00Z para o valor correto.

Enviando por meio da API

A IU define o valor como 'local do usuário' e a coluna é definida como 'local do usuário'.

Valor original: 4/4/2021T12:00:00 ou 4/4/2021T12:00:00Z – nenhum deslocamento ou indicador UTC fornecido. O remetente está no fuso horário do Pacífico.
Valor calculado para UTC e armazenado no Dataverse: Nenhum cálculo de interface do usuário é feito no envio de APIs OData, portanto, o valor é armazenado como 4/4/2021T12:00:00Z.
Valor quando exibido na interface do usuário por um usuário no fuso horário do Pacífico: 4/4/2021 4:00. A IU aplica o cálculo de fuso horário -8:00 UTC ao valor no Dataverse.

Para evitar esse problema ao usar chamadas de API para inserir dados em colunas locais do usuário, calcule o deslocamento do usuário ao enviar os dados e depois aplique o deslocamento calculado.

Usando o exemplo anterior: 4/4/2021 12:00 precisa ser enviado por meio da API como 4/4/2021T12:00:00-08:00. A data e hora originais incluem o cálculo de ajuste do fuso horário do usuário atual. Como alternativa, o enviador pode executar o cálculo antes do envio e enviar 4/4/2021T20:00:00Z.

Se você optar por incluir o cálculo de deslocamento, não inclua o Zindicador UTC, pois o Dataverse não o aceita.

Alterar o comportamento de uma coluna de data e hora

Você pode atualizar uma coluna de data e hora para alterar seu comportamento se tiver a função de Personalizador do Sistema em sua instância do Dataverse e a DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriedade gerenciada para a coluna de data e hora estiver definida como True.

Cuidado

Antes de alterar o comportamento de uma coluna de data e hora, revise todas as dependências da coluna, como regras de negócios, fluxos de trabalho e colunas calculadas ou de agregação, para garantir que não haja problemas como resultado da alteração do comportamento. Os Personalizadores do Sistema podem restringir a modificação do comportamento das colunas de data e hora existentes usando a DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriedade gerenciada.

No mínimo, depois de alterar o comportamento de uma coluna de data e hora, abra cada regra de negócios, fluxo de trabalho, coluna calculada e registro de coluna cumulativo que depende da coluna de data e hora alterada, examine as informações e salve o registro para garantir que o comportamento e o valor da coluna mais recente sejam usados.

Depois de alterar o comportamento de data e hora de uma coluna calculada ou agregada, abra o editor de definição de coluna calculada ou agregada e salve a definição da coluna para garantir que ela ainda seja válida após a alteração de comportamento. Os personalizadores do sistema podem abrir o editor de definição de coluna para a coluna calculada ou cumulativa selecionando Editar ao lado de Tipo de Campo na área de personalização no Dataverse. Para obter mais informações, consulte Definir colunas calculadas para automatizar cálculos e Definir colunas cumulativas que agregam valores.

O comportamento da coluna CreatedOn e ModifiedOn para as tabelas prontas e personalizadas é definido como UserLocal por padrão, e a propriedade gerenciada é definida como DateTimeAttributeMetadata.CanChangeDateTimeBehavior, o que significa que False você não pode alterar o comportamento dessas colunas. Embora os usuários possam alterar o valor da DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriedade gerenciada dessas colunas para tabelas personalizadas, eles ainda não podem alterar o comportamento das colunas.
Para novas colunas de data e hora personalizadas, a DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriedade gerenciada é definida como True. Essa configuração significa que você pode alterar o comportamento de uma coluna de data e hora personalizada de UserLocal para DateOnly ou TimeZoneIndependent; nenhuma outra transição de comportamento é permitida.

Para colunas de data e hora personalizadas que fazem parte de uma organização do Dataverse, a DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriedade gerenciada é definida como True , a menos que a coluna ou a tabela pai não seja personalizável.

Observação

Quando você atualizar DateTimeAttributeMetadata.DateTimeBehavior a propriedade de uma coluna de UserLocal para DateOnly, certifique-se de que você também altere aDateTimeAttributeMetadata.Format propriedade de DateAndTime para DateOnly. Caso contrário, ocorrerá uma exceção.

As seguintes colunas de data e hora pré-configuradas no Dataverse são definidas DateOnly como por padrão e a DateTimeAttributeMetadata.CanChangeDateTimeBehavior propriedade gerenciada é definida como False, o que significa que você não pode alterar o comportamento dessas colunas:

Coluna de data e hora	Tabela pai
`anniversary`	Contato
`birthdate`	Contato
`duedate`	Invoice
`estimatedclosedate`	Cliente Potencial
`actualclosedate`	Oportunidade
`estimatedclosedate`	Oportunidade
`finaldecisiondate`	Oportunidade
`validfromdate`	Product
`validtodate`	Product
`closedon`	Citação
`expireson`	Citação

O comportamento dessas colunas é definido como UserLocal, e a propriedade gerenciada DateTimeAttributeMetadata.CanChangeDateTimeBehavior como True, e você pode alterar o comportamento dessas colunas apenas para DateOnly. Nenhuma outra transição de comportamento é permitida.

Depois de atualizar o comportamento de uma coluna, você deve publicar as personalizações para que a alteração entre em vigor. Atualizar o comportamento de uma coluna de data e hora garante que todos os valores inseridos ou atualizados após a alteração do comportamento da coluna sejam armazenados no sistema de acordo com o novo comportamento. Essa alteração não afeta os valores que já estão armazenados no banco de dados e continuam sendo armazenados como valores UTC. No entanto, quando você recupera os valores existentes usando o SDK ou o exibe na interface do usuário, os valores existentes são exibidos de acordo com o novo comportamento da coluna. Por exemplo, se você alterar o comportamento de uma coluna personalizada em uma 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 pela hora como 00h (00:00:00). Da mesma forma, para a alteração de comportamento de UserLocal para TimeZoneIndependent, o valor real no banco de dados é exibido como está sem nenhuma conversão de fuso horário.

O código de exemplo a seguir demonstra como atualizar o comportamento de uma coluna de data e hora:

/// <summary>
/// Update the behavior of a DateTime column
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void UpdateBehaviorOfDateTimeColumn(IOrganizationService service) {

    // Retrieve the attribute to update its behavior and format
    RetrieveAttributeRequest retrieveColumnRequest = new()
    {
        EntityLogicalName = Account.EntityLogicalName,
        LogicalName = "new_sampledatetimeattribute",
        RetrieveAsIfPublished = false
    };
    // Execute the request
    RetrieveAttributeResponse attributeResponse =
                    (RetrieveAttributeResponse)service.Execute(retrieveColumnRequest);

    // Modify the values of the retrieved attribute
    DateTimeAttributeMetadata retrievedAttributeMetadata =
                    (DateTimeAttributeMetadata)attributeResponse.AttributeMetadata;

    retrievedAttributeMetadata.DateTimeBehavior = DateTimeBehavior.DateOnly;
    retrievedAttributeMetadata.Format = Microsoft.Xrm.Sdk.Metadata.DateTimeFormat.DateOnly;

    // Update the attribute with the modified value
    UpdateAttributeRequest updateRequest = new()
    {
        Attribute = retrievedAttributeMetadata,
        EntityName = Account.EntityLogicalName,
        MergeLabels = false
    };
    service.Execute(updateRequest);


    // Publish customizations to the account 
    PublishXmlRequest pxReq = new()
    {
        ParameterXml = "<importexportxml><entities><entity>account</entity></entities></importexportxml>"
    };
    service.Execute(pxReq);
}

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

Quando você atualiza uma coluna de data e hora para alterar seu comportamento de UserLocal para DateOnly ou TimeZoneIndependent, os valores existentes da coluna no banco de dados não são convertidos automaticamente. A alteração de comportamento afeta somente os valores que você insere ou atualiza na coluna depois de alterar o comportamento. Os valores de data e hora existentes no sistema permanecem em UTC. O Dataverse exibe esses valores de acordo com o novo comportamento ao recuperá-los por meio do SDK ou da interface do usuário, conforme explicado na seção anterior. Para colunas cujo comportamento muda de UserLocal para DateOnly, você pode converter os valores UTC existentes no banco de dados para o valor apropriado DateOnly para evitar anomalias de dados usando a ConvertDateAndTimeBehavior mensagem.

Essa mensagem permite especificar uma regra de conversão (se você estiver trabalhando com o SDK para .NET, consulte a propriedade ConvertDateAndTimeBehaviorRequest.ConversionRule) para selecionar o fuso horário a ser usado para conversão dos valores de UTC para DateOnly. Você pode especificar uma das seguintes regras de conversão:

SpecificTimeZone: converte o valor UTC em um valor DateOnly de acordo com o código de fuso horário do Dataverse especificado. Nesse caso, você também precisa especificar um valor para a propriedade ConvertDateAndTimeBehaviorRequest.TimeZoneCode.
CreatedByTimeZone: converte o valor UTC em um valor DateOnly que o usuário que criou o registro vê na interface do usuário.
OwnerTimeZone: converte o valor UTC em um valor DateOnly que o usuário que possui o registro vê na interface do usuário.
LastUpdatedByTimeZone: converte o valor UTC em um valor DateOnly que o usuário que atualizou o registro pela última vez vê na interface do usuário.

Use um dos quatro membros da classe DateTimeBehaviorConversionRule para especificar um valor válido para a propriedade ConversionRule.

Observação

Você deve ter a função administrador do sistema em sua instância do Dataverse para executar a classe ConvertDateAndTimeBehaviorRequest.

Ao executar o ConvertDateAndTimeBehavior (se você estiver trabalhando com o SDK para .NET, consulte a mensagem ConvertDateAndTimeBehaviorRequest), você cria um trabalho de sistema (operação assíncrona) para executar a solicitação de conversão. A ConvertDateAndTimeBehaviorResponse.JobId coluna na resposta da mensagem exibe a ID do trabalho do sistema que a solicitação de conversão cria. Após a conclusão do trabalho do sistema, verifique os detalhes do trabalho (AsyncOperation.Message) para exibir detalhes ou erros de conversão, se houver.

Observação

Agrupar a conversão de várias colunas em um único trabalho de conversão e executar um único trabalho de conversão de cada vez para garantir que não haja conflitos na conversão e para o desempenho ideal do sistema.

Considere os seguintes pontos ao usar a ConvertDateAndTimeBehavior mensagem:

Evite alterações importantes nas soluções no Dataverse durante a execução da mensagem, como importar uma solução ou excluir uma coluna ou tabela pai. Pode ocorrer um comportamento inesperado. No entanto, nenhuma perda de dados ocorre.
As atualizações feitas no sistema como resultado da execução da mensagem não executam fluxos de trabalho e plug-ins.
As atualizações feitas no sistema como resultado da execução da mensagem não alteram o valor "última modificação em" para as colunas. No entanto, as atualizações são auditadas para ajudar os administradores a determinar a hora da conversão e os valores originais e alterados para uma coluna.

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

/// <summary>
/// Demonstrates use of the ConvertDateAndTimeBehavior message
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void ConvertDateAndTimeBehavior(IOrganizationService service)
{

    ConvertDateAndTimeBehaviorRequest request = new()
    {
        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 Dataverse
        AutoConvert = false // Conversion must be done using ConversionRule
    };

    // Execute the request
    var response = (ConvertDateAndTimeBehaviorResponse)service.Execute(request);

    Console.WriteLine($"Asynchronous Job ID: {response.JobId}");
}

O Cliente Web manipula a conversão de fuso horário de forma diferente da Interface Unificada

O Cliente Web foi descontinuado em 2019. Se você estiver migrando scripts de cliente para seu sucessor, a Interface Unificada, observe a diferença na forma como os dois clientes lidam com a conversão de fuso horário para colunas Locais do Usuário.

No Cliente Web, o servidor manipula a conversão de fuso horário. Se um usuário entrar 2018-10-15 07:30 em um formulário de Cliente Web, a API Xrm.Page.getAttribute(<column name>).getValue() do Cliente retornará 2018-10-15 07:30. Esse valor é enviado para o servidor e os ajustes de fuso horário ocorrem lá ao salvar o valor.

No Unified Client, o cliente manipula a conversão de fuso horário. Se um usuário no fuso horário UTC+8 entrar 2018-10-15 07:30 em um formulário de Cliente Unificado, a API formContext.getAttribute(<column name>).getValue() do Cliente retornará o valor 2018-10-14T23:30:00Zajustado. O servidor aceita o valor como está e não executa mais ajustes de fuso horário.

Para considerar essa diferença, você pode:

Obtenha o deslocamento de fuso horário do usuário com o método UserSettings.getTimeZoneOffsetMinutes do Component Framework ou o método Xrm.Utility.getGlobalContext().userSettings.getTimeZoneOffsetMinutes e modifique seus scripts para contabilá-lo.
Altere o comportamento da coluna de UserLocal para TimeZoneIndependent para que os horários inseridos não sejam ajustados. Essa alteração só será possível se os fusos horários não forem aplicáveis à coluna.

Consulte também

Comportamento e formato da coluna de Data e Hora
Solucionar problemas de data e hora em aplicativos baseados em modelo
Visão Geral das Colunas
ConvertDateAndTimeBehaviorRequest class
Classe DateTimeAttributeMetadata
Blog: Importa como você envia dados de data e hora?

Feedback

Esta página foi útil?

Last updated on 2026-02-12

Partilhar via

Configurar o comportamento e o formato da coluna de data e hora usando o código

Especificar o comportamento de uma coluna de data e hora

Especificar o formato da coluna de data e hora

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

Usando APIs OData para enviar valores de data e hora local do usuário

Enviando por meio da UI

Enviando por meio da API

Alterar o comportamento de uma coluna de data e hora

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

O Cliente Web manipula a conversão de fuso horário de forma diferente da Interface Unificada

Consulte também

Feedback

Recursos adicionais