Evento OnSave de formulario (referencia de API de cliente) en aplicaciones basadas en modelos

El evento de formulario OnSave en aplicaciones controladas por modelos permite ejecutar lógica, validar datos o cancelar un guardado antes de guardar un registro. El evento OnSave se produce cuando:

  • El usuario selecciona el botón Guardar o Actualizar de la barra de comandos, incluso cuando no hay datos modificados para guardar.
  • El código ejecuta el método formContext.data.entity.save , incluso cuando no hay datos modificados para guardar.
  • El usuario navega fuera del formulario y hay datos sin guardar en el formulario.
  • La opción Autoguardado está habilitada, 30 segundos después de que los datos han cambiado y hay datos sin guardar en el formulario.
  • El código ejecuta el método formContext.data.save y hay datos sin guardar en el formulario.
  • El código ejecuta el método formContext.data.refresh que pasa un valor true al primer parámetro y hay datos sin guardar en el formulario.

Nota

El OnSave evento de cita, cita periódica o registros de actividad del servicio cancela la operación de guardado y usa el Book mensaje para guardar el cambio en lugar de Create o Update. Debido a este comportamiento, OnSave y PostSave los controladores de eventos para estas tablas no funcionan.

Para determinar en qué botón se ha hecho clic para realizar la acción de guardar, use el método getSaveMode.

Puede cancelar la acción de guardar mediante el método preventDefault dentro del objeto de argumentos de evento. El preventDefault método es accesible mediante el método getEventArgs que forma parte del contexto de ejecución. El contexto de ejecución se transfiere automáticamente al controlador de eventos del formulario.

Compatibilidad con el controlador de eventos asincrónico

El evento OnSave tiene la capacidad de esperar a que se resuelvan las promesas devueltas por los controladores de eventos antes de guardar, lo que permite al evento OnSave ser asincrónico ("async").

El evento OnSave se vuelve asíncrono cuando el controlador de eventos OnSave devuelve una promesa. El guardado del registro ocurre cuando se resuelve cada promesa devuelta por un controlador. Para las promesas que se devuelven, hay un límite de 10 segundos para cada promesa, después de eso, la plataforma considera que las promesas están vencidas. Este tiempo de espera se aplica según la promesa. Por ejemplo, si tenemos cinco promesas devueltas, el tiempo total de espera es de 50 segundos.

Si la promesa se rechaza o se agota el tiempo de espera, la operación de guardado continúa comportándose de manera similar a los errores de secuencia de comandos actuales. Use el método preventDefault dentro del objeto de argumentos de evento en ese controlador en particular si desea evitar que suceda el evento de guardado si hay un error de secuencia de comandos / promesa rechazada o tiempo de espera del controlador.

También puede cancelar la operación de guardado independientemente del error en el controlador o de no usar el método preventDefault dentro del objeto de argumentos de evento. Si se llama a este método, el evento Async OnSave espera a que se resuelvan todas las promesas, pero no se guardará. Al llamar a este método la lógica dentro de .then() & .catch() se ejecutará.

El evento OnSave espera a que se devuelva una promesa por controlador. Si se requieren varias promesas, se recomienda encapsular todas las promesas en el método Promise.all() y devolver la única promesa resultante. Para varios controladores que devuelven una promesa, le recomendamos que cree un controlador que llame a todos los eventos y devuelva una única promesa que encapsule todas las promesas requeridas. Esta práctica es para minimizar los tiempos de espera causados por el tiempo de espera.

Ejemplo: Cuándo usar controladores onSave asincrónicos

Considere la posibilidad de crear una tarea de servicio de pedido de trabajo en la que necesite validar que el recurso de cliente seleccionado tiene la misma cuenta que aparece en el Pedido de trabajo. Capturar la cuenta en el pedido de trabajo y el recurso de cliente son procesos asincrónicos y debe completar ambos antes de poder validarlo.

En este escenario, dado que hay varios procesos asincrónicos y ambas llamadas devuelven una única promesa, encapsulan ambos en el Promise.all() método .

Nota

Solo puede usar el preventDefault método de forma sincrónica.

Por ejemplo: 

 function myHandler() {
    return Promise.all([getWorkOrderPromise, getCustomerAssetPromise]).then((values) => {
        var workOrder = values[0];
        var customerAsset = values[1];
        // Perform validation
        if (isValid(workOrder, customerAsset)) {
            return Promise.resolve();
        }
        return Promise.reject(new Error("Validation failed for the work order and customer asset"));
   });
 }

Habilitación de controladores onSave asincrónicos mediante una configuración de aplicación

Para usar controladores async onSave, active la característica a través de una configuración de aplicación:

  1. Vaya a https://make.powerapps.com.

  2. Asegúrese de seleccionar el entorno correcto.

  3. Seleccione Aplicaciones en el panel de navegación izquierdo.

  4. Seleccione la aplicación, seleccione ... (puntos suspensivos) y, a continuación, seleccione Editar.

  5. Seleccione Configuración en la barra de comandos.

  6. Cuando se abra el cuadro de diálogo, seleccione Características.

  7. Active Controlador onSave asincrónico.

  8. Seleccione Guardar.

    Captura de pantalla de la configuración de características del controlador Async onSave activada en el cuadro de diálogo Configuración de la aplicación.

Deshabilitación de los tiempos de espera del controlador de onSave asincrónicos

Cuando usa un controlador asíncrono OnSave, el formulario espera a que se devuelva la promesa desde el controlador. Para asegurarse de que el formulario se guarda de forma oportuna, el controlador produce una excepción de tiempo de espera después de 10 segundos para que sepa ajustar el controlador asincrónico OnSave para mejorar el rendimiento.

Hay escenarios en los que es necesario pausar el controlador OnSave durante más de 10 segundos. Un ejemplo es abrir un diálogo y esperar la entrada del usuario antes de guardar. Para asegurarse de que la operación asincrónica espera a que se resuelva la promesa, use el método disableAsyncTimeout .

Nota

Debe llamar a disableAsyncTimeout antes de cualquier declaración de espera o llamada asíncrona.

Por ejemplo: 

async function myHandler(context) {  
     context.getEventArgs().disableAsyncTimeout();
     // The 10000ms time out will not be disabled if the above line does not come before all async awaits
     await Xrm.Navigation.openConfirmDialog({ text: "Are you sure you want to save?" });
 }

Al llamar a disableAsyncTimeout, no se aplica el tiempo de espera de ese controlador. Continúa esperando que se cumpla la promesa de ese manejador.

Este patrón puede afectar al rendimiento del guardado del formulario.

Evento OnSave de cuadrícula
Eventos (referencia de la API de cliente)
Eventos en formularios y cuadrículas en aplicaciones basadas en modelos

  • Se actualizó por última vez el