Compartir a través de

Comportamiento y formato del atributo de fecha y hora

  • Artículo

 

Publicado: noviembre de 2016

Se aplica a: Dynamics CRM 2015

Si tiene usuarios y oficinas en todo el mundo, es importante representar correctamente valores de fecha y hora en varias zonas horarias. La clase DateTimeAttributeMetadata se usa para definir y administrar atributos del tipo DateTime en CRM. Use la propiedad DateTimeAttributeMetadata. 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 estos atributos.

También puede usar el área personalización en Dynamics 365 para definir el comportamiento y el formato de los atributos de fecha y hora.Más información:TechNet: Comportamiento y formato del campo de fecha y hora

Nota

La propiedad DateTimeAttributeMetadata.DateTimeBehavior se encuentra disponible solo si usa CRM Online y ha actualizado la instancia a Actualización 1 de Microsoft Dynamics CRM Online 2015. Además, todos los atributos de fecha y hora en Actualización 1 de Microsoft Dynamics CRM Online 2015 admiten ahora valores de hasta 1/1/1753 12:00 AM.

Para otras versiones de CRM, no puede definir el comportamiento de los valores de fecha y hora. De forma predeterminada, los valores de fecha y hora se almacenan como comportamiento de UserLocal según lo descrito más adelante en este tema.

En este tema

Especifique el comportamiento de un atributo de fecha y hora

Especificar el formato del atributo de fecha y hora

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

Cambiar el comportamiento de un atributo de fecha y hora

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

Especifique el comportamiento de un atributo de fecha y hora

Puede usar la clase DateTimeBehavior para especificar un valor para la propiedad DateTimeAttributeMetadata.DateTimeBehavior. La clase 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 el extremo de OData, el atributo se expone como DateTimeOffset.

  • Este comportamiento se usa para atributos del sistema como CreatedOn y ModifiedOn, y no se puede cambiar. Debe usar este comportamiento para atributos personalizados donde desee almacenar valores de fecha y hora con la información de la zona horaria.

DateOnly

  • Almacena el valor de fecha real con el valor de hora como 12:00 AM (00:00:00) en el sistema.

  • Para operaciones de recuperación y actualización, no se realiza conversión de zona horaria, y el valor de hora siempre es 12 AM (00:00:00).

  • La recuperación del valor con formato muestra el valor de fecha sin ninguna conversión de zona horaria.

  • Para el extremo de OData, el atributo se expone como DateTimeOffset.

  • Este comportamiento se debe usar para atributos personalizados 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 el extremo de OData, el atributo se expone como DateTimeOffset.

  • Este comportamiento se debe usar para atributos 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 un nuevo atributo de fecha y 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);

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 un atributo de fecha y hora, el atributo se crea con el comportamiento UserLocal de forma predeterminada. Para ver el código de ejemplo completo, consulte Ejemplo: Convertir el comportamiento de fecha y hora.

Importante

  • Una vez que cree un atributo de fecha y hora con el comportamiento establecido como DateOnly o TimeZoneIndependent, no puede cambiar el comportamiento del atributo.Más información:Cambiar el comportamiento de un atributo de fecha y hora

  • Los atributos 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 CRM para Outlook en modo sin conexión. Esto se debe a que el cliente no entiende los nuevos comportamientos y no los tratará de forma distinta de UserLocal (comportamiento existente en otras versiones de CRM, excepto Actualización 1 de Microsoft Dynamics CRM Online 2015). Ningún atributo 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 Dynamics CRM para Outlook 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 los campos con los nuevos comportamientos funcionará bien.

    Los clientes de Dynamics CRM para Outlook más antiguos tampoco entenderán las fechas anteriores de 1/1/1900 (el valor más antiguo que admiten los tipos de fecha y hora en otras versiones de CRM, excepto Actualización 1 de Microsoft Dynamics CRM Online 2015). Los usuarios no podrán abrir registros con fechas anteriores a 1/1/1900 sin conexión. Sin embargo, todo funcionará bien cuando están conectados. Deberá actualizar la versión más reciente de los clientes de Dynamics CRM para Outlook para trabajar también con atributos con fechas de 1/1/1753 12:00 AM en modo sin conexión.

  • Si usa código personalizado para implementar comportamiento de fecha y hora en su instancia de CRM, puede que no funcione como se espera en Actualización 1 de Microsoft Dynamics CRM Online 2015 debido a la característica del nuevo comportamiento.

Especificar el formato del atributo de fecha y hora

Use la propiedad DateTimeAttributeMetadata.Format para especificar el formato de visualización de la fecha y hora del atributo con independencia de cómo se almacena en el sistema. Puede usar la enumeración de DateTimeFormat para especificar el formato de visualización: DateAndTime o DateOnly.

Si la propiedad DateTimeBehavior se establece en DateOnly, no puede establecer o cambiar el valor de la propiedad Format 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

  • Más antiguo de X horas

  • Últimas X horas

  • Próximas X horas

Más información:Fecha fiscal y operadores de consultas de fecha y hora "más antiguo que" en FetchXML

Cambiar el comportamiento de un atributo de fecha y hora

Puede actualizar un atributo de fecha y hora para cambiar su comportamiento si tiene el rol Personalizador del sistema en su instancia de CRM y la propiedad administrada CanChangeDateTimeBehavior para el atributo de fecha y hora se establece en True.

Precaución

Antes de modificar el comportamiento de un atributo de fecha y hora, debe comprobar todas las dependencias del atributo, como reglas de negocio, flujos de trabajo, atributos calculados o consolidados, 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 los atributos existentes de fecha y hora usando la propiedad administrada CanChangeDateTimeBehavior.

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

Después de modificar el comportamiento de los datos y el tiempo de un atributo calculado o consolidado, abra el editor de definición de campos calculados o consolidados y guarde la definición del campo para asegurarse de que el atributo sigue siendo válido después del cambio de comportamiento. Los personalizadores del sistema pueden abrir el editor de definición del atributo calculado o consolidado haciendo clic en Editar junto a Tipo de campo en el área personalización en CRM.Más información:Definir campos calculados y Definir campos consolidados

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

  • Para nuevos atributos de fecha y hora personalizados, la propiedad administrada CanChangeDateTimeBehavior se establece en True. Esto implica que puede cambiar el comportamiento de un atributo personalizado de fecha y hora de UserLocal a DateOnly o TimeZoneIndependent; no se permite ninguna otra transición de comportamiento.

    Para los atributos de fecha y hora que forman parte de una organización de CRM que se actualiza a Actualización 1 de Microsoft Dynamics CRM Online 2015, la propiedad administrada CanChangeDateTimeBehavior se establece en True a menos que el atributo o la entidad principal no se puede personalizar.

    Nota

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

  • Los siguientes atributos de fecha y hora predefinidos de Actualización 1 de Microsoft Dynamics CRM Online 2015 se establecen de forma predeterminado en DateOnly y la propiedad administrada CanChangeDateTimeBehavior se establece en False de estos atributos, lo que implica que no puede modificar el comportamiento de estos atributos:

    Atributo de fecha y hora

    Entidad primaria

    anniversary

    Contact

    birthdate

    Contact

    duedate

    Invoice

    estimatedclosedate

    Lead

    actualclosedate

    Opportunity

    estimatedclosedate

    Opportunity

    finaldecisiondate

    Opportunity

    validfromdate

    Product

    validtodate

    Product

    closedon

    Quote

    expireson

    Quote

    Sin embargo, si estos atributos de fecha y hora predefinidos pertenecen a una organización que se actualiza a Actualización 1 de Microsoft Dynamics CRM Online 2015, el comportamiento de estos atributos se establece en UserLocal y la propiedad administrada CanChangeDateTimeBehavior en True en la organización actualizada, y puede cambiar el comportamiento de estos atributos a DateOnly solo. No se permite ninguna otra transición de comportamiento.

Después de actualizar el comportamiento de un atributo, debe publicar las personalizaciones para que el cambio surta efecto. Actualizar el comportamiento de un atributo de fecha y hora garantiza que todos los valores especificados o actualizados después de cambiar el comportamiento del atributo, 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 del atributo. Por ejemplo, si cambió el comportamiento de un atributo personalizado 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> seguida de la hora como 12 AM (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 un atributo de fecha y 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 ver el código de ejemplo completo, consulte Ejemplo: Convertir el comportamiento de fecha y hora.

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

Cuando se actualiza un atributo de fecha y hora para cambiar su comportamiento de UserLocal a DateOnly o TimeZoneIndependent, no convierte automáticamente los valores del atributo existente en la base de datos. El cambio de comportamiento sólo afecta a los valores que se introducirán o actualizarán en el atributo después de que haya cambiado el comportamiento. Los valores de fecha y hora existentes del sistema continúan estando en UTC y CRM 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 los atributos 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 ConvertDateAndTimeBehaviorRequest.

El mensaje le permite especificar una regla de conversión (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 CRM especificado. En este caso, también debe especificar un valor para el parámetro 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 posee el 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 el parámetro ConversionRule.

Nota

  • El mensaje ConvertDateAndTimeBehaviorRequest se encuentra disponible solo si usa CRM Online y ha actualizado la instancia a Actualización 1 de Microsoft Dynamics CRM Online 2015. No está disponible para Microsoft Dynamics CRM (local).

  • Debe tener el rol de administrador del sistema en su instancia de CRM para ejecutar el mensaje ConvertDateAndTimeBehaviorRequest.

Cuando ejecute el mensaje ConvertDateAndTimeBehaviorRequest, se crea un trabajo del sistema (operación asincrónica) para ejecutar la solicitud de conversión. El atributo ConvertDateAndTimeBehaviorResponse.JobId en la respuesta del mensaje muestra el Id. de trabajo del sistema que se crea como resultado de la solicitud de la 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 varios atributos 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 ConvertDateAndTimeBehaviorRequest:

  • Debe evitar cualquier cambio importante en las soluciones en Dynamics 365 durante la ejecución del mensaje, como importar una solución o eliminar un entidad o el atributo principal. 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 los atributos, pero serán auditadas para ayudar a los administradores a determinar el tiempo de la conversión y los valores original/cambiado de un atributo.

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


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 ver el código de ejemplo completo, consulte Ejemplo: Convertir el comportamiento de fecha y hora

Ver también

Ejemplo: Convertir el comportamiento de fecha y hora
TechNet: Comportamiento y formato del campo de fecha y hora
Personalizar metadatos de atributos de entidad

© 2017 Microsoft. Todos los derechos reservados. Copyright