Ausführen mehrerer Anforderungen mithilfe des SDK für .NET

Der Hauptzweck der Ausführung mehrerer Anforderungen besteht darin, die Leistung in Umgebungen mit hoher Latenz zu verbessern, indem die Gesamtmenge der über das Netzwerk übertragenen Daten reduziert wird.

Sie können die ExecuteMultipleRequest-Nachricht verwenden, um höheren Durchsatz bei Massen-Nachrichten in Microsoft Dataverse zu unterstützen. ExecuteMultipleRequest nimmt eine Eingabesammlung der Requests-Nachricht entgegen, führt jede Nachrichtenanforderung in der Reihenfolge in der Sammlung aus, und gibt optional eine Sammlung 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. Verwenden Sie die IOrganizationService.Execute-Methode , um auszuführen ExecuteMultipleRequest.

Generell verhält sich ExecuteMultipleRequest genauso, als ob Sie jede Messageanforderung separat in der Eingabeanforderungssammlung ausführen, nur mit besserer Leistung. Der Dienstproxy berücksichtigt die Verwendung des CallerId Parameters und wendet ihn auf die Ausführung jeder Nachricht in der Eingabeanforderungssammlung an. Plug-Ins und Workflowaktivitäten werden für jede verarbeitete Nachricht erwartungsgemäß ausgeführt.

Plug-Ins und benutzerdefinierte Workflowaktivitäten können ExecuteMultipleRequest verwenden. Dieser Ansatz wird jedoch nicht empfohlen. Bei Fehlern im synchronen Schritt muss ein Rollback für alle Datenvorgänge ausgeführt werden, um die Datenintegrität aufrechtzuerhalten. Jeder Vorgang, der in von ExecuteMultiple durchgeführt wird, muss zurückgesetzt werden muss. ExecuteMultiple verursacht auch Probleme, wenn die Vorgänge die maximale Plug-In-Zeitüberschreitungsdauer überschreiten.

Weitere Informationen: Verwenden Sie keine Batchanforderungstypen in Plug-Ins und Workflowaktivitäten

Beispiel

Im folgenden Beispielcode wird ein einzelnes ExecuteMultipleRequest dargestellt, das mehrere Erstellen-Vorgänge ausführt. Laufzeitausführungsoptionen namens "Einstellungen" steuern die Anforderungsverarbeitung und die zurückgegebenen Ergebnisse. Im nächsten Abschnitt werden diese Laufzeitoptionen erläutert.

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

Weitere Informationen: Beispiel: Mehrere Anforderungen in einer Transaktion ausführen

Angeben von Laufzeitausführungsoptionen

Der Settings Parameter von ExecuteMultipleRequest gilt für alle Anforderungen in der Anforderungssammlung und steuert das Ausführungsverhalten sowie die zurückgegebenen Ergebnisse.

ExecuteMultipleSettings-Member	Beschreibung
ContinueOnError	Wenn true ist, 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

Die folgende Liste beschreibt Einschränkungen im Zusammenhang mit der Verwendung der ExecuteMultipleRequest.

• Keine Rekursion Ein ExecuteMultipleRequest kann kein anderes ExecuteMultipleRequest aufrufen. Enthält die Anforderungsauflistung eine ExecuteMultipleRequest, generiert sie einen Fehler für dieses Anforderungselement.
• Maximale Batchgröße Sie können einer Anforderungssammlung nur eine begrenzte Anzahl von Anforderungen hinzufügen. Wenn Sie diesen Grenzwert überschreiten, löst das System einen Fehler aus, bevor die erste Anforderung ausgeführt wird. Ein Grenzwert von 1.000 Anforderungen ist typisch, Aber Sie können diese maximale Menge für Ihre Dataverse-Bereitstellung festlegen.

Notiz

Die Anzahl der gleichzeitigen ExecuteMultiple-Anforderungen war bisher begrenzt. Das Limit war 2. Microsoft diesen Grenzwert entfernt, da Dienstschutzgrenzwerte es unnötig machten. Weitere Informationen finden Sie unter Dienstschutz-API-Grenzwerte.

Behandeln eines Batchgrößenfehlers

Was sollten Sie tun, wenn ihre Eingabeanforderungsauflistung die maximale Batchgröße überschreitet? Ihr Code kann die maximale Batchgröße nicht direkt über den Bereitstellungswebdienst abfragen, es sei denn, er wird unter einem Konto ausgeführt, das über die Rolle des Bereitstellungsadministrators verfügt.

Glücklicherweise gibt es eine andere Möglichkeit, die Sie verwenden können. Wenn die Anzahl der Anforderungen in der Eingabeauflistung Requests die für eine Organisation zulässige maximale Batchgröße überschreitet, gibt der ExecuteMultipleRequest Aufruf einen Fehler zurück. Der Fehler beinhaltet die maximale Batchgröße. 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
    // 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;
}

Siehe auch

Nachrichten mit dem SDK für .NET verwenden
Verwenden von ExecuteAsync
Verwenden von ExecuteTransaction