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

  • Artículo

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.

Nota

Todas las columans de fecha y hora en Dataverse admiten valores de hasta 1/1/1753 12:00 a. m.

Si su campo Solo fecha o Fecha y hora está en una solución, solo puede cambiar el comportamiento de un campo existente administrado si es el editor. Para realizar un cambio en estos campos, se debe realizar una actualización a la solución que agregó la columna Solo fecha o Fecha y hora. Más información: Actualizar una solución

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:

Nombre y valor del miembro Descripción
UserLocal - Almacena el valor de fecha y hora como valor UTC en el sistema.
- La operación de recuperación devuelve el valor UTC.
- La operación de actualización convierte el valor UTC en el valor de zona horaria del usuario actual y, a continuación almacena el valor actualizado tal cual o como el valor UTC equivalente en función del tipo (DateTimeKind) del valor especificado para la actualización. Si el valor especificado es de tipo UTC, se almacena tal cual. En caso contrario, se almacena el valor equivalente de UTC.
- La recuperación del valor con formato convierte de UTC a la zona horaria actual del usuario en función de la zona horaria y la configuración regional del usuario.
- Para la API web, la columna se expone como DateTimeOffset.
- Este comportamiento se usa para columnas del sistema como CreatedOn y ModifiedOn, y no se puede cambiar. Debe usar este comportamiento para columnas personalizadas donde desee almacenar valores de fecha y hora con la información de la zona horaria.
DateOnly - Almacena el valor de fecha real sin valor de tiempo.
- Recuperar el valor formateado muestra el valor de la fecha.
- Para la API web, la columna se expone como Fecha.
- Este comportamiento se debe usar para columnas personalizadas que almacenan cumpleaños y aniversarios, donde la información de hora no es obligatoria.
TimeZoneIndependent - Almacena los valores reales de fecha y hora en el sistema independientemente de la zona horaria del usuario.
- Para operaciones de recuperación y de actualización, no se realiza conversión de zona horaria, y los valores reales de fecha y hora se devuelven y actualizan respectivamente en el sistema independientemente de la zona horaria del usuario.
- La recuperación del valor con formato muestra el valor de fecha y hora (sin ninguna conversión de zona horaria) basándose en el formato especificado por la configuración regional y de zona horaria del usuario actual.
- Para la API web, la columna se expone como DateTimeOffset.
- Este comportamiento se debe usar para columnas que almacenan información como hora de registro y salida en hoteles.

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.

Importante

  • Una vez que cree una columna de fecha y hora con el comportamiento establecido como DateOnly o TimeZoneIndependent, no puede cambiar el comportamiento de la columna. Más información: Cambiar el comportamiento de una columna DateTime
  • Las columnas de fecha y hora con el comportamiento DateOnly o TimeZoneIndependent se tratarán como si tuvieran el comportamiento UserLocal cuando se editen en una versión anterior del cliente de Dynamics 365 for Outlook en modo sin conexión. Esto se debe a que el cliente no comprende todos los nuevos comportamientos y no los tratará de forma distinta de UserLocal. Ninguna columna de fecha y hora se convierte a los nuevos comportamientos en la actualización, por lo que la recomendación aquí sería actualizar todos los clientes de Dataverse a la última versión antes de que un personalizador adopte uno de los comportamientos nuevos. Cuando está en línea, la modificación de los datos de las columnas con los nuevos comportamientos funcionará bien.

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.

Precaución

Antes de modificar el comportamiento de una columna de fecha y hora, debe comprobar todas las dependencias de la columna, como reglas de negocio, flujos de trabajo, columnas calculadas o consolidadas, para asegurarse de que no hay problemas como resultado de modificar el comportamiento. Los personalizadores del sistema pueden limitar la modificación del comportamiento de las columnas existentes de fecha y hora usando la propiedad administrada DateTimeAttributeMetadata.CanChangeDateTimeBehavior.

Como mínimo, después de modificar el comportamiento de una columna de fecha y hora, debe abrir cada regla de negocio, flujo de trabajo, columna calculada y columna consolidada dependiente de la columna de fecha y hora cambiado, revisar la información y guardar el registro, para asegurarse de que se usarán el comportamiento y el valor más recientes de la columna.

Después de modificar el comportamiento de los datos y el tiempo de una columna calculada o consolidada, abra el editor de definición de columna calculada o consolidada y guarde la definición de la columna para asegurarse de que la columna sigue siendo válida después del cambio de comportamiento. Los personalizadores del sistema pueden abrir el editor de definición de la columna calculada o consolidada haciendo clic en Editar junto a Tipo de campo en el área de personalización en Dataverse. Más información: Definir columnas calculadas para automatizar cálculos yDefinir columnas consolidadas que agreguen valores

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

Nota

Debe tener el rol de administrador del sistema en su instancia de Dataverse para ejecutar la clase ConvertDateAndTimeBehaviorRequest.

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.

Nota

Se recomienda agrupar la conversión de varias columnas en un solo trabajo de conversión, y ejecutar un solo trabajo de conversión al mismo tiempo para asegurarse de que no existen conflictos en la conversión y para un rendimiento óptimo del sistema.

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:

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?

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).