Exécuter plusieurs requêtes à l’aide du SDK pour .NET

Article
03/08/2023

Le but principal d’exécuter plusieurs requêtes consiste à améliorer les performances dans des environnements de haut latence en réduisant le volume total des données qui sont transmises via le réseau.

Vous pouvez utiliser le message ExecuteMultipleRequest pour prendre en charge les scénarios de transmission de messages en nombre d’un débit supérieur dans Microsoft Dataverse. ExecuteMultipleRequest accepte une collection d’entrée de messages Requests, exécute chacune des demandes de message dans l’ordre dans lequel elles apparaissent dans la collection d’entrée et renvoie en option un ensemble de Responses contenant la réponse de chaque message ou l’erreur qui s’est produite. Chaque demande de message dans la collection d’entrée est traitée dans une transaction de base de données distincte. ExecuteMultipleRequest est exécuté à l’aide de la méthode IOrganizationService.Execute .

En général, ExecuteMultipleRequest se comporte comme si vous exécutiez séparément chaque demande de message de la collection de demandes en entrée, si ce n’est avec des performances optimisées. L’utilisation du paramètre CallerId du proxy de service est honorée et s’applique à l’exécution de chaque message de la collection de demandes en entrée. Les plug-ins et les activités de workflow sont exécutés comme prévu pour chaque message traité.

Les plug-ins et les activités de workflow personnalisées ne sont pas empêchés d’utiliser ExecuteMultipleRequest. Toutefois, ce n’est pas recommandé. Tout échec de l’étape synchrone doit annuler toutes les opérations sur les données pour maintenir l’intégrité des données. Chaque opération effectuée dans ExecuteMultiple doit être annulé. ExecuteMultiple provoque également des problèmes lorsque les opérations dépassent la durée maximale du délai d’expiration du plug-in.

En savoir plus : N’utilisez pas les types de demandes par lots dans les plug-ins et les activités de workflow

Exemple

L’exemple de code suivant illustre un simple ExecuteMultipleRequest qui effectue plusieurs opérations de création. Les options d’exécution du runtime appelées Paramètres permettent de contrôler le traitement de la demande et les résultats renvoyés. Ces options à l’exécution sont décrites dans la section suivante.


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

Pour plus d’informations : Exemple : Exécuter plusieurs requêtes

Spécifier les options d’exécution à l’exécution

Le paramètre Settings de ExecuteMultipleRequest s’applique à toutes les demandes de la collection de demandes contrôlant le comportement à l’exécution et les résultats retournés. Intéressons-nous à ces options plus en détail.

Membre ExecuteMultipleSettings Description

ContinueOnError Lorsque la valeur est true, continuez à traiter la demande suivante de la collection même si une erreur a été renvoyée lors du traitement de la demande en cours de la collection. Lorsque la valeur est false, ne poursuivez pas le traitement de la demande suivante.

ReturnResponses Lorsque la valeur est true, les réponses de retour de chaque demande de message sont traitées. Lorsque la valeur est false, ne renvoyez pas les réponses.

Si la valeur est true et qu’une demande ne renvoie pas une réponse, parce qu’elle est ainsi conçue, l’élément ExecuteMultipleResponseItem de cette requête a la valeur null.

Cependant, même si la valeur est false, la collection Responses n’est pas vide si des erreurs sont retournées. Si des erreurs sont retournées, un seul élément de réponse de la collection de chaque demande traitée ayant renvoyé une erreur et Fault sera défini sur l’erreur réelle qui s’est produite.

Membre ExecuteMultipleSettings	Description
ContinueOnError	Lorsque la valeur est `true`, continuez à traiter la demande suivante de la collection même si une erreur a été renvoyée lors du traitement de la demande en cours de la collection. Lorsque la valeur est `false`, ne poursuivez pas le traitement de la demande suivante.
ReturnResponses	Lorsque la valeur est `true`, les réponses de retour de chaque demande de message sont traitées. Lorsque la valeur est `false`, ne renvoyez pas les réponses. Si la valeur est `true` et qu’une demande ne renvoie pas une réponse, parce qu’elle est ainsi conçue, l’élément ExecuteMultipleResponseItem de cette requête a la valeur `null`. Cependant, même si la valeur est `false`, la collection Responses n’est pas vide si des erreurs sont retournées. Si des erreurs sont retournées, un seul élément de réponse de la collection de chaque demande traitée ayant renvoyé une erreur et Fault sera défini sur l’erreur réelle qui s’est produite.

Par exemple, dans un ensemble contenant six demandes où les erreurs retournées concernent la troisième et la cinquième demande, le tableau suivant indique ce que la collection Responses doit contenir.

Paramètres	Contenu de la collection de réponses
ContinueOnError=true, ReturnResponses=true	6 éléments de réponse : 2 avec la propriété Fault définie sur une valeur.
ContinueOnError=false, ReturnResponses=true	3 éléments de réponse : 1 avec la propriété Fault définie sur une valeur.
ContinueOnError=true, ReturnResponses=false	2 éléments de réponse : 2 avec la propriété Fault définie sur une valeur.
ContinueOnError=false, ReturnResponses=false	1 éléments de réponse : 1 avec la propriété Fault définie sur une valeur.

Un paramètre RequestIndex de l’élément de réponse indique le numéro de séquence, à partir de zéro, de la demande à laquelle la réponse est associée. Dans l’exemple précédent, la troisième demande a un index de demande égal à 2.

Limitations à l’exécution

Il existe plusieurs contraintes liées à l’utilisation de ExecuteMultipleRequest comme décrit dans la liste suivante.

Aucune récursivité n’est autorisée ExecuteMultipleRequest ne peut pas appeler ExecuteMultipleRequest. ExecuteMultipleRequest trouvé dans la collection de demandes génère une erreur pour cet élément de demande.
Taille de lot maximale : il existe une limite au nombre de demandes qui peuvent être ajoutées à une collection de demandes. Si cette limite est dépassée, une erreur est levée avant que la première demande ne soit même exécutée. Une limite de 1 000 requêtes est habituelle, bien que ce montant maximal puisse être défini pour le déploiement de Dataverse.

Notes

Il y avait une fois une limite au nombre de requêtes ExecuteMultiple simultanées. La limite était de 2. Cela a été supprimé car les limites de protection des services la rendaient inutile. Pour plus d’information : Limites de l’API de protection des services.

Gérer une erreur de taille de lot

Que devez-vous faire lorsque votre collection de demandes d’entrée dépasse la taille de lot maximale ? Votre code ne peut pas directement interroger la taille de lot maximale via le service Web de déploiement, à moins qu’il ne soit exécuté sous un compte disposant du rôle d’administrateur du déploiement.

Heureusement, il existe une autre méthode que vous pouvez utiliser. Lorsque le nombre de demandes de la collection Requests d’entrées dépasse la taille de lot maximale autorisée pour une organisation, une erreur est renvoyée par l’appel ExecuteMultipleRequest. La taille de lot maximale est retournée dans l’erreur. Votre code peut contrôler cette valeur, redimensionner la collection de demandes en entrée dans la limite indiquée et renvoyer ExecuteMultipleRequest. L’extrait de code suivant illustre une partie de cette logique.

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

Voir aussi

Utiliser les messages avec le SDK pour .NET
Utiliser ExecuteAsync
Utiliser ExecuteTransaction

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Partager via