Configurar el comportamiento y el formato de la columna de fecha y hora mediante código

Si tiene usuarios y oficinas en todo el mundo, es importante representar correctamente valores de fecha y hora en varias zonas horarias. DateTimeAttributeMetadata (tipo de entidad DateTimeAttributeMetadata o la clase DateTimeAttributeMetadata) se usa para definir y administrar atributos de tipo DateTime en Microsoft Dataverse. Use la propiedad DateTimeBehavior (para SDK para . NET, consulte Propiedad DateTimeBehavior.) para definir si almacenar valores de fecha y hora con o sin información de zona horaria, y use la propiedad DateTimeAttributeMetadata.Format para especificar el formato de visualización de estas columnas.

También puede utilizar el área de personalización de Dataverse para definir el comportamiento y el formato de las columnas de fecha y hora. Más información: Comportamiento y formato de la columna de fecha y hora.

Especificar el comportamiento de una columna de fecha y hora

Puede usar DateTimeBehavior (tipo de complejo DateTimeBehavior o la clase DateTimeBehavior ) para especificar un valor para el tipo de entidad DateTimeAttributeMetadata.DateTimeBehavior . El DateTimeBehavior contiene los siguientes miembros, cada uno de los cuales devuelve una cadena con el mismo valor que el nombre del miembro:

El siguiente código de ejemplo demuestra cómo establecer un comportamiento de UserLocal para una nueva columna de fecha y 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);
}

En el código de ejemplo, también puede establecer el valor de la propiedad DateTimeBehavior especificando directamente el valor de cadena: DateTimeBehavior = "UserLocal"

Si no especifica el comportamiento cuando crea una columna de fecha y hora, la columna se crea con el comportamiento UserLocal de forma predeterminada.

Especificar el formato de la columna de fecha y hora

Use Format property para especificar el formato de visualización de la fecha y hora de la columna con independencia de cómo se almacena en el sistema. Puede usar la enumeración de DateTimeFormat (tipo de enumeración DateTimeFormat o enumeración DateTimeFormat) para especificar el formato de visualización: DateAndTime o DateOnly.

Si DateTimeAttributeMetadata.DateTimeBehavior property se establece en DateOnly, no puede establecer o cambiar el valor de DateTimeAttributeMetadata.Format property a DateAndTime.

Operadores de consulta de fecha y hora no admitidos en el comportamiento Solo fecha

No se admite operadores de consulta relacionados con el tiempo para el comportamiento DateOnly. Aparte de los operadores de consulta específicos de tiempo que se muestran aquí, se admiten todos los demás operadores de consulta.

• Más antiguo de X minutos
• Anterior a X horas
• Últimas X horas
• Próximas X horas

Más información: Operadores de datos de fecha y hora

Uso de las API de OData para enviar valores de fecha y hora locales de usuario

En Microsoft Power Platform, cuando un usuario envía una fecha y hora en la zona horaria específica del usuario a través de la interfaz de usuario, un cálculo automático establece los datos en la fecha y hora correctas. Realiza un análisis para cambiar cualquier fecha enviada al valor UTC correspondiente según la columna y la configuración de la interfaz de usuario. Al enviar un valor de fecha y hora mediante la operación de la API Web, el cálculo no se produce, lo que genera una visualización de datos inexplicables. Por ejemplo, si se encuentra en la zona horaria del Pacífico y envía 4/4/2021 12:00, esto es lo que sucede:

• Original: 4/4/2021 12:00, el remitente se encuentra en la zona horaria del Pacífico.
• Enviado a través de la interfaz de usuario y recuperado como usuario local: 4/4/2021 12:00
• Enviado a través de la API y recuperado como usuario local: 4/4/2021 04:00

Enviar a través de la interfaz de usuario

La interfaz de usuario está configurada para el usuario local y la columna está configurada para el usuario local.

• Valor original: 4/4/2021 12:00 en la zona horaria del Pacífico.
• Valor calculado en UTC y almacenado en Dataverse: 4/4/2021 12:00 + 8:00 = 4/4/2021T20:00:00Z . Esto se debe a que PST es -8:00 de UTC, por lo que se agrega +8 al valor almacenado.
• Valor cuando un usuario lo muestra en la interfaz de usuario en la zona horaria del Pacífico: 4/4/2021 12:00. La interfaz de usuario aplica el cálculo de la diferencia horaria de UTC de -8: 00 UTC al 4/4/2021T20:00:00Z para obtener el valor correcto.

Enviar a través de la API

La interfaz de usuario está configurada para el usuario local y la columna está configurada para el usuario local.

• Valor original: 4/4/2021T12:00 00 o 4/4/2021T12:00:00Z, no se proporciona ningún indicador de cálculo de diferencia o UTC. El remitente se encuentra en la zona horaria del Pacífico.
• Valor calculado en UTC y almacenado en Dataverse: no se realiza ningún cálculo de IU en el envío desde las API de OData, por lo que el valor se almacena como 4/4/2021T12:00:00Z.
• Valor cuando un usuario lo muestra en la interfaz de usuario en la zona horaria del Pacífico: 4/4/2021 4:00. La interfaz de usuario aplica el cálculo de diferencia horaria de -8:00 UTC en el valor en Dataverse.

Para evitar este problema al usar llamadas a la API para introducir datos en las columnas locales del usuario, debe calcular el desplazamiento del usuario que envía los datos y aplicar el desplazamiento.

Usando el ejemplo anterior: 4/4/2021 12:00 debería enviarse a través de la API como 4/4/2021T12:00:00-08:00. La hora y fecha originales incluyen el cálculo de diferencia horaria de la zona horaria del usuario actual. Alternativamente, el remitente puede realizar el cálculo antes del envío y enviar 4/4/2021T20:00:00Z.

Si elige incluir el cálculo de compensación, no podrá tener el Z, un indicador UTC, porque Dataverse no lo aceptará.

Cambiar el comportamiento de una columna de fecha y hora

Puede actualizar una columna de fecha y hora para cambiar su comportamiento si tiene el rol Personalizador del sistema en su instancia de aplicaciones Dataverse y la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior para la columna de fecha y hora se establece en True.

• El comportamiento de las columnas CreatedOn y ModifiedOn para las tablas predefinidas y personalizadas se establece en UserLocal de forma predeterminada, y la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior se establece en False, lo que implica que no puede modificar el comportamiento de estas columnas. Aunque los usuarios pueden cambiar el valor de propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior de estas columnas para tablas personalizadas, aún no pueden modificar el comportamiento de las columnas.

• Para nuevas columnas de fecha y hora personalizadas, la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior se establece en True. Esto implica que puede cambiar el comportamiento de una columna personalizada de fecha y hora de UserLocal a DateOnly o TimeZoneIndependent; no se permite ninguna otra transición de comportamiento.

  Para columnas personalizadas de fecha y hora que forman parte de una organización de Dataverse, la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior se establece en True, a menos que la columna o la tabla principal no sea personalizable.

  Nota

  Cuando se actualiza la propiedad DateTimeAttributeMetadata.DateTimeBehavior de una columna de UserLocal a DateOnly, asegúrese de cambiar también la propiedad DateTimeAttributeMetadata.Format de DateAndTime a DateOnly. De lo contrario, aparecerá una excepción.

• Las siguientes columnas de fecha y hora predefinidos de Dataverse se establecen de forma predeterminada en DateOnly y la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior se establece en False de estas columnas, lo que implica que no puede modificar el comportamiento de estas columnas:

  Columna de fecha y hora	Tabla primaria
  anniversary	Contact
  birthdate	Contact
  duedate	Factura
  estimatedclosedate	Cliente potencial
  actualclosedate	Oportunidad
  estimatedclosedate	Oportunidad
  finaldecisiondate	Oportunidad
  validfromdate	Producto
  validtodate	Producto
  closedon	Oferta
  expireson	Oferta

  El comportamiento de estas columnas se establece en UserLocal y la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior en True, y puede cambiar el comportamiento de estas columnas solo para DateOnly. No se permite ninguna otra transición de comportamiento.

Después de actualizar el comportamiento de una columna, debe publicar las personalizaciones para que el cambio surta efecto. Actualizar el comportamiento de una columna de fecha y hora garantiza que todos los valores especificados o actualizados después de cambiar el comportamiento de la columna, se almacenan en el sistema de acuerdo con el nuevo comportamiento. Esto no afecta a los valores que ya están almacenados en la base de datos, y siguen estando almacenados como valores UTC. No obstante, cuando se recuperan los valores existentes mediante el SDK o se ven en la interfaz de usuario, los valores existentes se muestran de acuerdo con el nuevo comportamiento de la columna. Por ejemplo, si cambió el comportamiento de una columna personalizada en una entidad de cuenta de UserLocal a DateOnly y recupera un registro de cuenta existente mediante el SDK, la fecha y la hora se mostrarán como <Date> y luego la hora como 12 a. m. (00:00:00). De forma similar, para el cambio de comportamiento de UserLocal a TimeZoneIndependent, el valor real en la base de datos se mostrará como está sin conversiones de zona horaria.

El siguiente código de ejemplo demuestra cómo actualizar el comportamiento de una columna de fecha y 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);
}
 

Convertir el comportamiento de valores existentes de fecha y hora en la base de datos

Cuando se actualiza una columna de fecha y hora para cambiar su comportamiento de UserLocal a DateOnly o TimeZoneIndependent, no convierte automáticamente los valores de la columna existente en la base de datos. El cambio de comportamiento sólo afecta a los valores que se introducirán o actualizarán en la columna después de que haya cambiado el comportamiento. Los valores de fecha y hora existentes del sistema continúan estando en UTC y Dataverse los muestra de acuerdo con el nuevo comportamiento cuando se recuperan mediante el SDK o en la interfaz de usuario como se explica en la sección anterior. Para las columnas cuyo comportamiento ha cambiado de UserLocal a DateOnly, puede convertir los valores UTC existentes en la base de datos al valor DateOnly adecuado para evitar cualquier anomalía de datos mediante el mensaje ConvertDateAndTimeBehavior.

El mensaje le permite especificar una regla de conversión (Si trabaja con el SDK para .NET, consulte la propiedad ConvertDateAndTimeBehaviorRequest.ConversionRule) para seleccionar la zona horaria para usar en la conversión de los valores de UTC a DateOnly. Puede especificar una de las siguientes reglas de conversión:

• SpecificTimeZone: convierte el valor UTC a un valor DateOnly de acuerdo con el código de zona horaria de Dataverse especificado. En este caso, también debe especificar un valor para la propiedad ConvertDateAndTimeBehaviorRequest.TimeZoneCode.
• CreatedByTimeZone: Convierte un valor UTC en un valor DateOnly que el usuario que creó el registro vería en la interfaz de usuario.
• OwnerTimeZone: Convierte un valor UTC en un valor DateOnly que el usuario que es propietario del registro vería en la interfaz de usuario.
• LastUpdatedByTimeZone: Convierte un valor UTC en un valor DateOnly que el usuario que actualizó por última vez el registro vería en la interfaz de usuario.

Puede usar uno de los cuatro miembros de la clase DateTimeBehaviorConversionRule para especificar un valor válido para la propiedad ConversionRule.

Cuando ejecute el mensaje ConvertDateAndTimeBehavior (Si trabaja con SDK para .NET, consulte el mensaje ConvertDateAndTimeBehaviorRequest), se crea un trabajo del sistema (operación asincrónica) para ejecutar la solicitud de conversión. La columna ConvertDateAndTimeBehaviorResponse.JobId de la respuesta del mensaje muestra el id. de trabajo del sistema que se crea como resultado de la solicitud de conversión. Cuando finalice el trabajo del sistema, verifique los detalles del trabajo (AsyncOperation.Message) para ver detalles o errores de conversión, si los hay.

Algunos aspectos importantes que se deben tener en cuenta mientras usa el mensaje ConvertDateAndTimeBehavior:

• Debe evitar cualquier cambio importante en las soluciones en aplicaciones Dataverse durante la ejecución del mensaje, como importar una solución o eliminar una columna o tabla primaria. Si lo hace podría producirse un comportamiento inesperado; sin embargo, no se producirá pérdida de datos.
• Las actualizaciones realizadas en el sistema como resultado de ejecutar el mensaje no ejecutarán flujos de trabajo y complementos.
• Las actualizaciones realizadas en el sistema como resultado de ejecutar el mensaje no cambiarán el valor de "última modificación" para las columnas, pero se auditarán para ayudar a los administradores a determinar la hora de la conversión y los valores originales/cambiados de una columna.

El siguiente código de ejemplo muestra cómo usar el mensaje:

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

El cliente web gestiona la conversión de zona horaria de manera diferente a Interfaz unificada

Cliente web fue declarado en desuso en 2019. Si está migrando scripts de cliente a su sucesor, Interfaz unificada, observe la diferencia en cómo los dos clientes manejan la conversión de zona horaria para las columnas de usuario local.

En Cliente web, la conversión de zona horaria no se realizó en el lado del cliente. Si un usuario ingresaba 2018-10-15 07:30 en un formulario de Cliente web, la API del Cliente Xrm.Page.getAttribute(<column name>).getValue() devolvía 2018-10-15 07:30. Este valor se envía al servidor y allí se realizan ajustes de zona horaria al guardar el valor.

En Cliente unificado, la conversión de zona horaria se realiza en el lado del cliente. Si un usuario en la zona horaria UTC+8 ingresa 2018-10-15 07:30 en un formulario de Cliente unificado, la API del cliente formContext.getAttribute(<column name>).getValue() devuelve el valor ajustado 2018-10-14T23:30:00Z. El servidor acepta el valor tal como está y no realiza más ajustes de zona horaria.

Para tener en cuenta esta diferencia, puede:

• Ivteber el desplazamiento de la zona horaria del usuario con el método Component Framework UserSettings.getTimeZoneOffsetMinutes o método Xrm.Utility.getGlobalContext().userSettings.getTimeZoneOffsetMinutes y modifique sus scripts para tenerlo en cuenta.
• Cambie el comportamiento de la columna de UserLocal a TimeZoneIndependent para que los tiempos ingresados ​​no se ajusten. Esto solo es posible si las zonas horarias no son aplicables para la columna.

Consulte también

Comportamiento y formato de la columna Fecha y hora
Solucionar problemas de fecha y hora en aplicaciones basadas en modelos
Información general sobre las columnas
Clase ConvertDateAndTimeBehaviorRequest
Clase DateTimeAttributeMetadata
Blog: ¿Importa cómo se envían los datos de fecha y hora?