Mehrere Anforderungen mit dem SDK für .NET ausführen

  • Artikel

Hauptzweck des Ausführens von mehreren Anforderungen ist es, die Leistung in der Hochwartezeitumgebung zu verbessern, indem Sie den gesamten Datenbestand reduzieren, der über das Netzwerk gesendet wird.

Sie können die ExecuteMultipleRequest Nachricht verwenden, um höheren Durchsatz bei Massen-Nachrichten in Microsoft Dataverse zu unterstützen. 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 IOrganizationService.Execute ausgeführt. Methode.

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.

Die Verwendung von ExecuteMultipleRequest durch Plug-Ins und benutzerdefinierte Workflowaktivitäten ist nicht gesperrt. Dies wird jedoch nicht empfohlen. Alle Fehler im synchronen Schritt müssen alle Datenvorgänge zurückgesetzt 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-Dauer überschreiten.

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

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.


// 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, 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. Ein Grenzwert von 1.000 Anforderungen ist typisch, obwohl diese maximale Menge für die Dataverse-Bereitstellung festgelegt werden kann.

Hinweis

Die Anzahl der gleichzeitigen ExecuteMultiple-Anforderungen war bisher begrenzt. Das Limit war 2. Dies wurde entfernt, da Serviceschutzbeschränkungen dies unnötig machten. Für weitere Informationen: API-Grenzwerte für den Serviceschutz.

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

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).