Ejemplo: ejecutar varias solicitudes usando SDK para .NET

Artigo
03/14/2023

El objetivo principal de ejecutar varias solicitudes es mejorar el rendimiento en entornos de latencia alta mediante la reducción de volumen de datos total que se transmite a través de la red.

Puede utilizar el mesaje ExecuteMultipleRequest para admitir un rendimiento superior de mensajes en masa que pasan entre escenarios de Microsoft Dataverse. ExecuteMultipleRequest acepta una colección de entrada de Requests de mensajes, ejecuta cada una de las solicitudes de mensajes en el orden que aparecen en la colección de entrada y opcionalmente devuelve una colección de Responses que contiene la respuesta de cada mensaje o el error que se han producido. Cada solicitud de mensaje en la colección de entrada se procesa en una transacción independiente de la base de datos. ExecuteMultipleRequest se ejecuta usando el método IOrganizationService.Execute .

En general, ExecuteMultipleRequest se comporta de la misma manera que si ejecutara cada solicitud de mensaje en la colección de solicitudes de entrada por separado, excepto que con mejor rendimiento. Se respeta el uso del parámetro CallerId del proxy de servicio y se aplicará a la ejecución de cada mensaje en la colección de solicitudes de entrada. Los complementos y las actividades de flujo de trabajo se ejecutan como se podría esperar para cada mensaje procesado.

No se bloquea el uso de complementos y actividades de flujo de trabajo personalizadas ExecuteMultipleRequest. No obstante, esto no se recomienda. Cualquier falla en el paso sincrónico debe revertir todas las operaciones de datos para mantener la integridad de los datos. Cada operación realizada dentro ExecuteMultiple debe revertirse. ExecuteMultiple también causa problemas cuando las operaciones superan la duración máxima del tiempo de espera del complemento.

Más información: No use los tipos de solicitud de lotes en las actividades de flujo de trabajo y los complementos.

Ejemplo

El siguiente código de ejemplo muestra un solo ExecuteMultipleRequest que realiza varias operaciones de creación. Se utilizan opciones de ejecución en tiempo de ejecución denominadas Configuración para controlar el procesamiento de la solicitud y los resultados obtenidos. Estas opciones de tiempo de ejecución se tratan en la sección siguiente.


// Create an ExecuteMultipleRequest object.
ExecuteMultipleRequest requestWithResults = new ExecuteMultipleRequest()
{
    // Assign settings that define execution behavior: continue on error, return responses. 
    Settings = new ExecuteMultipleSettings()
    {
        ContinueOnError = false,
        ReturnResponses = true
    },
    // Create an empty organization request collection.
    Requests = new OrganizationRequestCollection()
};

// Create several (local, in memory) entities in a collection. 
EntityCollection input = GetCollectionOfEntitiesToCreate();

// Add a CreateRequest for each entity to the request collection.
foreach (var entity in input.Entities)
{
    CreateRequest createRequest = new CreateRequest { Target = entity };
    requestWithResults.Requests.Add(createRequest);
}

// Execute all the requests in the request collection using a single web method call.
ExecuteMultipleResponse responseWithResults =
    (ExecuteMultipleResponse)service.Execute(requestWithResults);

// Display the results returned in the responses.
foreach (var responseItem in responseWithResults.Responses)
{
    // A valid response.
    if (responseItem.Response != null)
        DisplayResponse(requestWithResults.Requests[responseItem.RequestIndex], responseItem.Response);

    // An error has occurred.
    else if (responseItem.Fault != null)
        DisplayFault(requestWithResults.Requests[responseItem.RequestIndex], 
            responseItem.RequestIndex, responseItem.Fault);
}

Más información: Ejemplo: ejecutar varias solicitudes

Especificación de las opciones de ejecución en tiempo de ejecución

El parámetro Settings de ExecuteMultipleRequest se aplica a todas las solicitudes de la colección de solicitudes que controlan el comportamiento de ejecución y los resultados obtenidos. Analicemos estas opciones con mayor detalle.

Miembro de ExecuteMultipleSettings Descripción

ContinueOnError Si está establecida en true, siga procesando la siguiente solicitud de la colección aunque haya obtenido un error por procesar la solicitud actual en la colección. Si está establecida en false, no siga procesando la solicitud siguiente.

ReturnResponses Si está establecida en true, devuelve las respuestas de cada solicitud de mensaje procesada. Si está establecida en false, no devuelve respuestas.

Si está establecida en true y una solicitud no devuelve una respuesta, porque ese es el diseño, el parámetro ExecuteMultipleResponseItem de esa solicitud se establece en null.

Sin embargo, aunque esté establecida en false, la colección de Responses no estará vacía si se devuelven errores. Si se devuelven errores, habrá un elemento de respuesta en la colección de cada solicitud procesada que devolvió un error y Fault se establecerá en el error real que se produjo.

Miembro de ExecuteMultipleSettings	Descripción
ContinueOnError	Si está establecida en `true`, siga procesando la siguiente solicitud de la colección aunque haya obtenido un error por procesar la solicitud actual en la colección. Si está establecida en `false`, no siga procesando la solicitud siguiente.
ReturnResponses	Si está establecida en `true`, devuelve las respuestas de cada solicitud de mensaje procesada. Si está establecida en `false`, no devuelve respuestas. Si está establecida en `true` y una solicitud no devuelve una respuesta, porque ese es el diseño, el parámetro ExecuteMultipleResponseItem de esa solicitud se establece en `null`. Sin embargo, aunque esté establecida en `false`, la colección de Responses no estará vacía si se devuelven errores. Si se devuelven errores, habrá un elemento de respuesta en la colección de cada solicitud procesada que devolvió un error y Fault se establecerá en el error real que se produjo.

Por ejemplo, para una colección de solicitudes que contiene seis solicitudes en las que la tercera y la quinta solicitud devuelven errores, la siguiente tabla indica qué contendría la colección de Responses.

Configuración	Contenido de la colección de respuestas
ContinueOnError=true, ReturnResponses=true	6 elementos de respuesta: 2 tienen Fault establecido en un valor.
ContinueOnError=false, ReturnResponses=true	3 elementos de respuesta: 1 tiene Fault establecido en un valor.
ContinueOnError=true, ReturnResponses=false	2 elementos de respuesta: 2 tienen Fault establecido en un valor.
ContinueOnError=false, ReturnResponses=false	1 elemento de respuesta: 1 tiene Fault establecido en un valor.

Un parámetro RequestIndex en el elemento de respuesta indica el número de secuencia, a partir de cero, de la solicitud con la que está asociada la respuesta. En el ejemplo anterior, la tercera solicitud tiene un índice de solicitudes de 2.

Limitaciones al tiempo de ejecución

Existen varias restricciones relacionadas con el uso de ExecuteMultipleRequest tal como se describe en la siguiente lista.

No se permite la recursión: ExecuteMultipleRequest no puede invocar a ExecuteMultipleRequest. Un parámetro ExecuteMultipleRequest que se encuentre en la colección de solicitudes generará un error para ese elemento de la solicitud.
Tamaño de lote máximo: hay un límite en cuanto a la cantidad de solicitudes que se pueden agregar a una colección de solicitudes. Si se supera ese límite, se genera un error incluso antes de que se ejecute la primera solicitud. Un límite de 1000 solicitudes es típico aunque este cantidad máxima puede establecerse para la implementación de Dataverse.

Nota

Anteriormente había un límite en el número de solicitudes simultáneas de ExecuteMultiple. El límite era 2. Esto se eliminó porque los límites de protección del servicio lo hicieron innecesario. Para obtener más información: Límites de API de protección de servicios.

Cómo administrar un error de tamaño de lote

¿Qué debe hacer cuando la colección de solicitudes de entrada supera el tamaño de lote máximo? El código no puede consultar directamente el tamaño de lote máximo con el servicio web de implementación a menos que se ejecute con una cuenta que tiene el rol de administrador de implementaciones.

Afortunadamente, hay otro método que puede usar. Cuando el número de solicitudes en la colección Requests de entrada supera el tamaño de lote máximo permitido para una organización, la llamada ExecuteMultipleRequest devuelve un error. El tamaño de lote máximo se devuelve en el error. El código puede comprobar ese valor, cambiar el tamaño de la colección de solicitudes de entrada de que modo que esté dentro del límite indicado y volver a enviar ExecuteMultipleRequest. El siguiente fragmento de código muestra parte de esta lógica.

catch (FaultException<OrganizationServiceFault> fault)
{
    // Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if
    // the input request collection count exceeds the maximum batch size.
    if (fault.Detail.ErrorDetails.Contains("MaxBatchSize"))
    {
        int maxBatchSize = Convert.ToInt32(fault.Detail.ErrorDetails["MaxBatchSize"]);
        if (maxBatchSize < requestWithResults.Requests.Count)
        {
            // Here you could reduce the size of your request collection and re-submit the ExecuteMultiple request.
            // For this sample, that only issues a few requests per batch, we will just print out some info. However,
            // this code will never be executed because the default max batch size is 1000.
            Console.WriteLine("The input request collection contains %0 requests, which exceeds the maximum allowed (%1)",
                requestWithResults.Requests.Count, maxBatchSize);
        }
    }
    // Re-throw so Main() can process the fault.
    throw;
}

Consulte también

Use estos mensajes con el SDK para .NET
Uso de ExecuteAsync
Uso de ExecuteTransaction

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

Compartir por