Freigeben über

Verwenden von "ExecuteMultiple" zur Verbesserung der Leistung bei Massendatenlast

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Sie können die ExecuteMultipleRequest-Nachricht verwenden, um einen höheren Durchsatz für Massennachricht-Szenarien in Microsoft Dynamics 365 (online und lokal)zu unterstützen (vor allem bei Microsoft Dynamics 365 (online), bei dem die Internet-Latenz der größte einschränkende Faktor sein kann).ExecuteMultipleRequest nimmt eine Eingang-Collection der Requests-Nachricht entgegen, führt jede Nachrichtenanforderung in der Reihenfolge in der Collection aus, und gibt optional eine Collection von Responses mit jeder Reaktion auf die Nachricht oder dem aufgetretenen Fehler zurück. Jede Messageanforderung in der Eingabesammlung wird in einer separaten Datenbanktransaktion verarbeitet.ExecuteMultipleRequest wird über die Methode IOrganizationService.Execute ausgeführt.

Generell verhält sich ExecuteMultipleRequest genauso, als ob Sie jede Messageanforderung separat in der Eingabeanforderungssammlung ausführen, nur mit besserer Leistung. Die Verwendung der CallerId-Parameter des Serviceproxys wird berücksichtigt und wird bei der Ausführung jeder Message in der Eingabeanforderungssammlung angewendet. Plug-Ins und Workflowaktivitäten werden ausgeführt, wie es für jede verarbeitete Message zu erwarten ist.

Benutzerdefinierter Code in Form von Plug-Ins und benutzerdefinierter Workflowaktivitäten kann sogar ExecuteMultipleRequest ausführen. Allerdings gibt es mehrere wichtige Punkte zu beachten. Eine Ausnahme, die von einem synchronen, registrierten Plug-In ausgelöst wird, wird, wird im Fault-Parameter des Antwortsammlungselements zurückgegeben. Falls ein Plug-In innerhalb einer Datenbanktransaktion ausgeführt wird, führt das Plug-In ExecuteMultipleRequest aus, und ein Transaktionsrollback wird gestartet. In diesem Rollback sind alle Daten enthalten, die von Anforderungen stammen, die von ExecuteMultipleRequest ausgeführt werden.

In diesem Thema

Beispiel

Angeben von Laufzeitausführungsoptionen

Laufzeitbeschränkungen

Behandeln eines Batchgrößenfehlers

Beispiel

Im folgenden Beispielcode wird ein einzelnes ExecuteMultipleRequest dargestellt, das mehrere Erstellen-Vorgänge ausführt. Die Laufzeitausführungsoptionen namens Einstellungen werden zur Steuerung der Anforderungsverarbeitung und der zurückgegebenen Ergebnisse verwendet. Diese Laufzeitoptionen werden im nächsten Abschnitt näher erläutert.


// 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

Eine Ansicht des vollständigen Beispiels finden Sie unter Beispiel: Ausführen mehrerer Anforderungen.

Angeben von Laufzeitausführungsoptionen

Der Settings-Parameter von ExecuteMultipleRequest gilt für alle Anforderungen in der Anforderungssammlung, die das Ausführungsverhalten und die zurückgegebenen Ergebnisse steuert. Es folgt eine ausführlichere Betrachtung dieser Optionen.

ExecuteMultipleSettings-Member

Beschreibung

ContinueOnError

Wenn true, setzen Sie die Verarbeitung der folgenden Anforderung in der Sammlung fort, selbst wenn bei der Verarbeitung der aktuellen Anforderung ein Fehler in der Sammlung zurückgegeben wurde. Wenn false, setzen Sie die Verarbeitung folgenden Anforderung nicht fort.

ReturnResponses

Wenn true, geben Sie Antworten von jeder verarbeiteten Messageanforderung zurück. Wenn false, geben Sie keine Antworten zurück.

Wenn es auf true festgelegt ist, und eine Anforderung keine Antwort zurückgibt, da es so entworfen wurde, wird ExecuteMultipleResponseItem für diese Anforderungen auf null festgelegt.

Doch auch wenn es false ist, wird die Responses-Sammlung nicht leer sein, falls Fehler zurückgegeben werden. Wenn Fehler zurückgegeben werden, gibt es für jede verarbeitete Anforderung, die einen Fehler zurückgab ein Antwortelement in der Sammlung und Fault wird auf den aktuellen Fehler festgelegt, der aufgetreten ist.

Geben in einer Anforderungssammlung mit sechs Anforderungen die dritte und fünfte Anforderung beispielsweise Fehler zurück, zeigt die folgenden Tabelle was die Responses-Sammlung enthalten würde.

Einstellungen

Inhalte der Antwortsammlung

ContinueOnError=true, ReturnResponses=true

6 Antwortelemente: bei 2 wurde Fault auf einen Wert festgelegt.

ContinueOnError=false, ReturnResponses=true

3 Antwortelemente: bei 1 wurde Fault auf einen Wert festgelegt.

ContinueOnError=true, ReturnResponses=false

2 Antwortelemente: bei 2 wurde Fault auf einen Wert festgelegt.

ContinueOnError=false, ReturnResponses=false

1 Antwortelement: bei 1 wurde Fault auf einen Wert festgelegt.

Ein RequestIndex-Parameter im Antwortelement gibt, beginnend bei null, die Sequenznummer der Anforderung an, der die Anforderung zugeordnet ist. Im vorherigen Beispiel verfügt die dritte Anforderung beispielsweise über einen Anforderungsindex von 2.

Laufzeitbeschränkungen

Es gibt mehrere Beschränkungen, die zur mit der Verwendung von ExecuteMultipleRequest in Beziehung stehen, wie in der folgenden Liste beschrieben.

  • Keine Rekursion zulässig - ExecuteMultipleRequest kann ExecuteMultipleRequest nicht aufrufen. Ein ExecuteMultipleRequest-Element, das in der Anforderungssammlung gefunden wird, verursacht einen Fehler für das Anforderungselement.

  • Maximale Batchgröße - es gibt eine Beschränkung bei der Anzahl von Anforderungen, die einer Anforderungssammlung hinzugefügt werden können. Wird dieser Grenzwert überschritten, wird ein Fehler ausgelöst, bevor die erste Anforderung ausgeführt wird. Eine Limit von 1000 Anforderungen ist typisch, obwohl die maximale Menge für die Microsoft Dynamics 365-Bereitstellung festgelegt werden kann. Die Bereitstellungseinstellung für diesen Grenzwert ist BatchSize.

  • Einschränkung der gleichzeitigen für Aufrufe - bei Microsoft Dynamics 365 (online) gibt es eine Beschränkung von 2 gleichzeitig ausgeführten ExecuteMultipleRequest-Elementen pro Organisation. Wird dieser Grenzwert überschritten, wird ein "Server Ausgelastet"-Fehler ausgelöst, bevor die erste Anforderung ausgeführt wird. Bei einer lokalen Bereitstellung ist Einschränkung standardmäßig nicht aktiviert. Die Bereitstellungseinstellung für diesen Grenzwert ist ExecuteAsyncPerOrgMaxConnectionsPerServer.

    Tipp

    Für jede mögliche Dynamics 365-Bereitstellung kann ein Bereitstellungsadministrator den Einschränkungsgrenzwert festlegen oder ändern.

Behandeln eines Batchgrößenfehlers

Was kann getan werden, wenn die Eingabeanforderungssammlung die maximale Batchgröße überschreitet? Ihr Code kann die maximale Batchgröße nicht direkt durch den Bereitstellungswebdienst abfragen, sofern er nicht unter einem Konto mit der Rolle "Bereitstellungsadministrator" ausgeführt wird.

Glücklicherweise gibt es eine andere Möglichkeit, die Sie verwenden können. Wenn die Anzahl der Anforderungen in der Requests-Eingabesammlung die maximale Batchgröße überschreitet, die für eine Organisation zulässig ist, wird vom ExecuteMultipleRequest-Aufruf ein Fehler zurückgegeben. Die maximale Batchgröße wird im Fehler zurückgegeben. Ihr Code kann nach diesen Wert prüfen, die Größe der Eingabeanforderungssammlung anpassen, um innerhalb des angegebenen Grenzwerts zu liegen, und ExecuteMultipleRequest erneut senden. Der folgende Codeausschnitt stellt einen Teil dieser Logik dar.


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

Siehe auch

Execute
OrganizationRequest
OrganizationResponse
Verwenden des Organisationsdienstes, um Daten oder Metadaten zu lesen und zu schreiben
xRM-Meldungen im Organisationsservice
Meldungen im Suchdienst
Dynamics 365-Meldungen im Organisationsdienst
Daten importieren

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright