Utiliser ExecuteMultiple pour améliorer les performances du chargement en bloc des données

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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 Dynamics 365 (Online et local), notamment dans le cas de Microsoft Dynamics 365 (Online) où la latence Internet peut être le plus gros facteur de limitation.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é.

Le code personnalisé du formulaire des plug-ins et des activités de workflow personnalisé peut même exécuter ExecuteMultipleRequest. Toutefois, certains points clés sont à ne pas oublier. Une exception levée par un plug-in inscrit synchrone est retournée dans le paramètre Fault de l’élément de collection de la réponse. Si un plug-in s’exécute dans une transaction de base de données, que le plug-in exécute ExecuteMultipleRequest et qu’une restauration des transactions est initialisée, la restauration inclut toutes les modifications de données résultant des demandes exécutés par ExecuteMultipleRequest.

Contenu de la rubrique

Exemple

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

Limitations à l’exécution

Gérer une erreur de taille de lot

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.

// Get a reference to the organization service.
using (_serviceProxy = new OrganizationServiceProxy(serverConfig.OrganizationUri, serverConfig.HomeRealmUri,serverConfig.Credentials, serverConfig.DeviceCredentials))
{
    // Enable early-bound type support to add/update entity records required for this sample.
    _serviceProxy.EnableProxyTypes();

    #region Execute Multiple with Results
    // Create an ExecuteMultipleRequest object.
    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)_serviceProxy.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);
    }

' Get a reference to the organization service.
_serviceProxy = ServerConnection.GetOrganizationProxy(serverConfig)

Using _serviceProxy
    ' Enable early-bound type support to add/update entity records required for this sample.
    _serviceProxy.EnableProxyTypes()

    '#Region "Execute Multiple with Results"
    ' Create an ExecuteMultipleRequest object.
    ' Assign settings that define execution behavior: continue on error, return responses.
    ' Create an empty organization request collection.
    requestWithResults = New ExecuteMultipleRequest() With
        {
            .Settings = New ExecuteMultipleSettings() With
                        {
                            .ContinueOnError = False,
                            .ReturnResponses = True
                        },
            .Requests = New OrganizationRequestCollection()
        }

    ' Create several (local, in memory) entities in a collection. 
    Dim input As EntityCollection = GetCollectionOfEntitiesToCreate()

    ' Add a CreateRequest for each entity to the request collection.
    For Each entity In input.Entities
        Dim createRequest_Renamed As CreateRequest = New CreateRequest With {.Target = entity}
        requestWithResults.Requests.Add(createRequest_Renamed)
    Next entity

    ' Execute all the requests in the request collection using a single web method call.
    Dim responseWithResults As ExecuteMultipleResponse =
        CType(_serviceProxy.Execute(requestWithResults), ExecuteMultipleResponse)

    ' Display the results returned in the responses.
    For Each responseItem In responseWithResults.Responses

        If responseItem.Response IsNot Nothing Then
            ' A valid response.
            DisplayResponse(requestWithResults.Requests(responseItem.RequestIndex),
                            responseItem.Response)

        ElseIf responseItem.Fault IsNot Nothing Then
            ' An error has occurred.
            DisplayFault(requestWithResults.Requests(responseItem.RequestIndex),
                         responseItem.RequestIndex, responseItem.Fault)
        End If
    Next responseItem

Pour afficher l’exemple complet, voir Exemple : Exécuter plusieurs demandes.

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.

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.

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 Microsoft Dynamics 365. Le paramètre de déploiement pour cette limite est BatchSize.

• Limitation des appels simultanés – pour Microsoft Dynamics 365 (Online), il existe une limite de 2 exécutions simultanées de ExecuteMultipleRequest par organisation. Si cette limite est dépassée, une erreur « Serveur occupé » est levée avant que la première demande ne soit même exécutée. Pour un déploiement local, la limitation n’est pas activée par défaut. Le paramètre de déploiement pour cette limite est ExecuteAsyncPerOrgMaxConnectionsPerServer.

  Conseil

  Pour tout déploiement Dynamics 365, un administrateur de déploiement peut définir ou modifier la limite de limitation.

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

Catch fault As FaultException(Of OrganizationServiceFault)

    ' Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if it
    ' the input request collection count exceeds the maximum batch size.
    If fault.Detail.ErrorDetails.Contains("MaxBatchSize") Then

        Dim maxBatchSize As Integer = Convert.ToInt32(fault.Detail.ErrorDetails("MaxBatchSize"))
        If maxBatchSize < requestWithResults.Requests.Count Then
            ' 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)
        End If
    End If
    ' Re-throw so Main() can process the fault.
    Throw
End Try

Voir aussi

Execute
OrganizationRequest
OrganizationResponse
Utilisez le service Organization pour lire et écrire des données ou des métadonnées.
Messages xRM dans le service d’organisation
Messages dans le service de découverte
Messages Dynamics 365 dans le service d’organisation
Importer les données

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright