Execute várias solicitações usando o SDK para .NET

A principal finalidade da execução de várias solicitações é melhorar o desempenho em ambientes de alta latência, reduzindo o volume total de dados transmitidos pela rede.

Você pode usar a mensagem ExecuteMultipleRequest para oferecer suporte a cenários de envio de mensagens em massa com alta taxa de transferência no Microsoft Dataverse. ExecuteMultipleRequest aceita uma coleção de entrada de mensagens Requests, executa cada uma das solicitações de mensagens na ordem em que aparecem na coleção de entrada e, opcionalmente, retorna uma coleção contendo a resposta de Responses cada mensagem ou o erro que ocorreu. Cada solicitação de mensagem na coleção de entrada é processada em uma transação de banco de dados separada. Use o método IOrganizationService.Execute para executar ExecuteMultipleRequest.

Em geral, ExecuteMultipleRequest comporta-se da mesma forma como se você executasse cada solicitação de mensagem na coleção de solicitações de entrada separadamente, exceto com melhor desempenho. O proxy de serviço reconhece o uso do parâmetro CallerId e o aplica à execução de cada mensagem na coleção de solicitações de entrada. Os plug-ins e as atividades de fluxo de trabalho são executados conforme o esperado para cada mensagem processada.

Plugins e atividades de fluxo de trabalho personalizadas podem usar ExecuteMultipleRequest. No entanto, essa abordagem não é recomendada. Qualquer falha na etapa síncrona deve desfazer todas as operações de dados para manter a integridade dos dados. Cada operação executada dentro ExecuteMultiple deve ser revertida. ExecuteMultiple também causa problemas quando as operações excedem a duração máxima do tempo limite do plug-in.

Mais informações: Não use tipos de solicitação em lote em plug-ins e atividades de fluxo de trabalho

Example

O código de exemplo a seguir demonstra um único ExecuteMultipleRequest que executa várias operações de criação. As opções de execução em tempo de execução chamadas Configurações controlam o processamento da solicitação e os resultados retornados. A próxima seção discute essas opções de tempo de execução.


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

Mais informações: Exemplo: Executar várias solicitações

Especificar opções de execução de runtime

O Settings parâmetro de ExecuteMultipleRequest aplica-se a todas as solicitações na coleção de solicitações e controla o comportamento de execução e os resultados retornados.

Membro ExecuteMultipleSettings Description

ContinueOnError Quando true, continue a processar a próxima solicitação na coleção, mesmo que ocorra uma falha ao processar a solicitação atual da coleção. Quando false, não continue processando a próxima solicitação.

ReturnResponses Quando true, retorne as respostas de cada solicitação de mensagem processada. Quando false, não retorne respostas.

Se definido como true, e uma solicitação não retornar uma resposta, por design, o ExecuteMultipleResponseItem dessa solicitação será definido como null.

No entanto, mesmo quando false, a coleção Responses não ficará vazia se forem retornados erros. Quando os erros são retornados, há um item de resposta na coleção para cada solicitação processada que retorna uma falha e Fault é definido como a falha real que ocorreu.

Membro ExecuteMultipleSettings	Description
ContinueOnError	Quando `true`, continue a processar a próxima solicitação na coleção, mesmo que ocorra uma falha ao processar a solicitação atual da coleção. Quando `false`, não continue processando a próxima solicitação.
ReturnResponses	Quando `true`, retorne as respostas de cada solicitação de mensagem processada. Quando `false`, não retorne respostas. Se definido como `true`, e uma solicitação não retornar uma resposta, por design, o ExecuteMultipleResponseItem dessa solicitação será definido como `null`. No entanto, mesmo quando `false`, a coleção Responses não ficará vazia se forem retornados erros. Quando os erros são retornados, há um item de resposta na coleção para cada solicitação processada que retorna uma falha e Fault é definido como a falha real que ocorreu.

Por exemplo, em uma coleção de solicitações que contém seis solicitações em que a terceira e a quinta solicitação retornam falhas, a tabela a seguir indica o que a Responses coleção conteria.

Settings	Conteúdo da coleção de respostas
ContinueOnError=true, ReturnResponses=true	6 itens de resposta: 2 Fault foram definidos como um valor.
ContinueOnError=false, ReturnResponses=true	3 itens de resposta: 1 tem Fault definido com um valor.
ContinueOnError=true, ReturnResponses=false	2 itens de resposta: 2 têm Fault definidos com um valor.
ContinueOnError=false, ReturnResponses=false	1 item de resposta: 1 está com Fault definido para um valor.

Um RequestIndex parâmetro no item de resposta indica o número da sequência, começando em zero, da solicitação à qual a resposta está associada. No exemplo anterior, a terceira solicitação tem um índice de solicitação 2.

Limitações de tempo de execução

A lista a seguir descreve restrições relacionadas ao uso do ExecuteMultipleRequest.

Sem recursão Um ExecuteMultipleRequest não pode invocar outro ExecuteMultipleRequest. Se a coleção de solicitações contiver uma ExecuteMultipleRequest, ela gerará uma falha para esse item de solicitação.
Tamanho máximo do lote Você pode adicionar apenas um número limitado de solicitações a uma coleção de solicitações. Se você exceder esse limite, o sistema gerará uma falha antes de executar a primeira solicitação. Um limite de 1.000 solicitações é típico, mas você pode definir esse valor máximo para sua implantação do Dataverse.

Note

Houve uma vez um limite no número de solicitações ExecuteMultiple simultâneas. O limite era 2. Microsoft removido esse limite porque os limites de proteção de serviço o tornaram desnecessário. Para obter mais informações, consulte Limites da API de Proteção de Serviço.

Tratar um erro de tamanho de lote

O que você deve fazer se sua coleção de solicitações de entrada exceder o tamanho máximo do lote? Seu código não pode consultar diretamente o tamanho máximo do lote por meio do serviço Web de implantação, a menos que ele seja executado em uma conta que tenha a função de administrador de implantação.

Felizmente, há outro método que você pode usar. Quando o número de solicitações na coleção de entrada Requests excede o tamanho máximo do lote permitido para uma organização, a ExecuteMultipleRequest chamada retorna uma falha. A falha inclui o tamanho máximo do lote. Seu código pode verificar esse valor, redimensionar a coleção de solicitações de entrada para estar dentro do limite indicado e reenviar o ExecuteMultipleRequest. O snippet de código a seguir demonstra parte dessa 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 também

Use mensagens com o SDK para .NET
Usar ExecuteAsync
Use ExecuteTransaction

Comentários

Esta página foi útil?

Last updated on 2026-09-02