Freigeben über

Plug-Ins für „CreateMultiple“ und „UpdateMultiple“ schreiben

Hinweis

Die CreateMultiple und UpdateMultiple Nachrichten werden bereitgestellt. Alle Tabellen, die Create und Update unterstützen, werden schließlich auch CreateMultiple und UpdateMultiple unterstützen, aber einige Tabellen unterstützen sie möglicherweise noch nicht. Lernen Sie mehr über Nachrichten für Massenvorgänge

Sie sollten Plug-Ins für die CreateMultiple und UpdateMultiple Nachrichten mit Tabellen schreiben, in denen Datensätze möglicherweise massenhaft erstellt oder aktualisiert werden müssen, oder wenn eine hohe Leistung beim Erstellen und Aktualisieren zahlreicher Datensätze wichtig ist. Ungefähr jede Tabelle, in der Geschäftsdaten gespeichert werden, müssen möglicherweise in Massen erstellt oder aktualisiert werden.

Wenn Sie über vorhandene Plug-Ins für die Nachrichten Create und Update für Tabellen wie diese verfügen, sollten Sie diese migrieren, um stattdessen CreateMultiple und UpdateMultiple zu verwenden.

Ist das Aktualisieren von Plug-Ins erforderlich?

Sie müssen Ihre Plug-Ins nicht migrieren, um CreateMultiple anstelle von Create und UpdateMultiple anstelle von Update zu verwenden. Ihre Logik wird weiterhin angewendet, wenn Anwendungen verwenden CreateMultiple oder UpdateMultiple. Es ist nicht erforderlich, Ihre Plug-Ins zu migrieren, da die Dataverse-Nachrichtenverarbeitungspipeline die Logik für Plug-Ins zusammenführt , die entweder für die einzelne oder mehrere Versionen dieser Nachrichten geschrieben wurden.

Allerdings erhalten nur Plug-Ins, die für die mehrfache Version dieser Nachrichten geschrieben wurden, eine erhebliche Leistungssteigerung. Im Laufe der Zeit, wenn mehr Entwickler sich entscheiden, die Leistung durch die Verwendung der CreateMultiple und UpdateMultiple-Nachrichten zu optimieren, erwarten wir, dass das Schreiben von Plug-ins für mehrere Vorgänge zum Standard wird. Plug-Ins, die für einzelne Vorgänge geschrieben wurden, sind die Ausnahme.

Was ist anders?

Im Folgenden sind einige der Unterschiede aufgeführt, die Sie verwalten müssen, wenn Sie Ihre Plug-Ins zu den CreateMultiple und UpdateMultiple den Nachrichten migrieren.

Ziele anstelle von Ziel

Die mehrfache Version dieser Nachrichten hat einen Targets Parameter, der eine EntityCollection ist, anstatt eines Target Parameters, der eine einzelne Entität ist. Ihr Plug-In-Code muss die Entitäten in der Auflistung durchlaufen und logik auf jede anwenden.

Entitätsbilder

Entitätsbilder, die in der Schrittregistrierung für Ihre Plug-ins konfiguriert werden, sind ein Array von EntityImageCollection. Diese Entitätsimages sind nur verfügbar, wenn Sie die IPluginExecutionContext4-Schnittstelle verwenden, die die Eigenschaften PreEntityImagesCollection und PostEntityImagesCollection bereitstellt. Diese Arrays bieten Zugriff auf dieselben Entitätsbilder in einem Array, das mit der EntityCollection synchronisiert wird.

Wenn Sie die PluginBase Klasse verwenden, die beim Initialisieren von Plug-In-Projekten mit Power Platform-Tools der Standard ist, sollten Sie in der PluginBase.cs Datei alle Instanzen von IPluginExecutionContext mit IPluginExecutionContext4 ersetzen, damit diese Sammlungen von Entitätsbildern für Ihr Plug-In verfügbar sind.

Von Bedeutung

Wenn Sie Bilder von Entitäten für die Plug-in-Schritte für CreateMultiple und UpdateMultiple konfigurieren, ist es wichtig, dass Sie sorgfältig auswählen, welche Spaltendaten aufgenommen werden sollen. Wählen Sie nicht die Standardoption aller Spalten aus. Diese Daten werden mit der Anzahl der Entitäten multipliziert, die im Parameter Targets übergeben werden, und tragen zur Gesamtgröße der Nachricht bei, die an die Sandbox gesendet wird. Möglicherweise erreichen Sie den Grenzwert für die Nachrichtengröße.

Attributfilter

Für ein Plug-In, das auf Update oder UpdateMultiple registriert ist, können Sie Filterattribute in der Schrittregistrierung angeben.

  • Mit Update, das Plug-In wird nur ausgeführt, wenn eines der ausgewählten Attribute in der Target Entität enthalten ist, die aktualisiert wird.
  • Mit UpdateMultiple, das Plug-In wird ausgeführt, wenn eines der ausgewählten Attribute in einer der Entitäten im Targets Parameter enthalten ist.

Von Bedeutung

Bei UpdateMultiple können Sie nicht davon ausgehen, dass jede Entität im Parameter Targets Attribute enthält, die in einem Filter verwendet werden.

Example

Die folgenden Beispiele, eines mit einer grundlegenden Logik für Update und ein anderes mit Logik für UpdateMultiple, greifen auf Entitätsbilder zu, die mit dem Schritt registriert sind.

In diesem Beispiel wird das sample_description Attribut mit Informationen darüber aktualisiert, ob sich der sample_name Wert geändert hat. Es bezieht sich auf ein Entitätsbild mit dem Namen example_preimage , das beim Schritt registriert wurde.

// Verify input parameters
if (context.InputParameters.Contains("Target") && context.InputParameters["Target"] is Entity entity)
{

   // Verify expected entity image from step registration
   if (context.PreEntityImages.TryGetValue("example_preimage", out Entity preImage))
   {

      bool entityContainsSampleName = entity.Contains("sample_name");
      bool entityImageContainsSampleName = preImage.Contains("sample_name");
      bool entityImageContainsSampleDescription = preImage.Contains("sample_description");

      if (entityContainsSampleName && entityImageContainsSampleName && entityImageContainsSampleDescription)
      {
            // Verify that the entity 'sample_name' values are different
            if (entity["sample_name"] != preImage["sample_name"])
            {
               string newName = (string)entity["sample_name"];
               string oldName = (string)preImage["sample_name"];
               string message = $"\\r\\n - 'sample_name' changed from '{oldName}' to '{newName}'.";

               // If the 'sample_description' is included in the update, do not overwrite it, just append to it.
               if (entity.Contains("sample_description"))
               {

                  entity["sample_description"] = entity["sample_description"] += message;

               }
               else // The sample description is not included in the update, overwrite with current value + addition.
               {
                  entity["sample_description"] = preImage["sample_description"] += message;
               }

               // Success:
               localPluginContext.Trace($"Appended to 'sample_description': \"{message}\" ");
            }
            else
            {
               localPluginContext.Trace($"Expected entity and preImage 'sample_name' values to be different. Both are {entity["sample_name"]}");
            }
      }
      else
      {
            if (!entityContainsSampleName)
               localPluginContext.Trace("Expected entity sample_name attribute not found.");
            if (!entityImageContainsSampleName)
               localPluginContext.Trace("Expected preImage entity sample_name attribute not found.");
            if (!entityImageContainsSampleDescription)
               localPluginContext.Trace("Expected preImage entity sample_description attribute not found.");
      }
   }
   else
   {
      localPluginContext.Trace($"Expected PreEntityImage: 'example_preimage' not found.");
   }
}
else
{
   if (!context.InputParameters.Contains("Target"))
      localPluginContext.Trace($"Expected InputParameter: 'Target' not found.");
   if (!(context.InputParameters["Target"] is Entity))
      localPluginContext.Trace($"Expected InputParameter: 'Target' is not Entity.");
}

Behandeln von Ausnahmen

Alle Fehler, die in Ihren Plug-Ins auftreten, sollten mit InvalidPluginExecutionException zurückgegeben werden. Wenn Ihr Plug-In eine Ausnahme für die Schritte auslöst, die für die CreateMultiple und UpdateMultiple Nachrichten registriert sind, sollte es identifizieren, welcher Datensatz zu dem Ausfall des Plug-Ins führte. Verwenden Sie einen der folgenden Konstruktoren, um diese Informationen zu erfassen:

Mit diesen Konstruktoren können Sie der InvalidPluginExecutionException.ExceptionDetails-Eigenschaft Werte hinzufügen, die nicht direkt festgelegt werden können.

Verwenden Sie den Parameter Dictionary<String,String>exceptionDetails des Konstruktors, um Informationen über den fehlgeschlagenen Datensatz und andere relevante Informationen anzugeben.

Festlegen von Ausnahmedetails

Für die UpdateMultiple Nachricht durchläuft der Code die EntityCollectionTargets-Eigenschaft und wendet auf jede Entität Logik an. Wenn ein Fehler auftritt, können Sie die ID des Datensatzes wie folgt an den InvalidPluginExecutionException Konstruktor übergeben:

// in plugin code
foreach (Entity entity in Targets)
{
   // [...] When an error occurs:
   var exceptionDetails = new Dictionary<string, string>();
   exceptionDetails.Add("failedRecordId", (string)entity.Id);
   throw new InvalidPluginExecutionException("This is an error message.", exceptionDetails);
}

Fügen Sie alle anderen Informationen, die für den Fehler relevant sind, als Zeichenfolge-Schlüssel-Wert-Paare zum Parameter exceptionDetails hinzu.

Für CreateMultiple empfehlen wir, den Primärschlüsselwert für jeden Datensatz nicht zu vergeben. In den meisten Fällen sollten Sie es dem System ermöglichen, den Primärschlüsselwert für Sie festzulegen, da die vom System generierten Werte für eine optimale Leistung optimiert sind.

In Fällen, in denen der Primärschlüsselwert nicht festgelegt ist, wenn kein anderer eindeutiger Bezeichner vorhanden ist, müssen Sie möglicherweise den Index des fehlgeschlagenen Datensatzes im EntityCollection-ParameterTargets oder eine Kombination von Werten zurückgeben, die den datensatz eindeutig identifizieren, der fehlschlägt. Zum Beispiel kann ein Schlüssel mit dem Namen failedRecordIndex, der den Platz des Datensatzes in EntityCollection angibt, oder ein anderer nützlicher eindeutiger Bezeichner zu exceptionDetails hinzugefügt werden, um die Fehlersuche zu erleichtern.

Abrufen von Ausnahmedetails

Wenn Sie Details zum fehlerhaften Vorgang in die InvalidPluginExecutionException.ExceptionDetails-Eigenschaft einfügen, kann die Clientanwendung diese über die FaultException<OrganizationServiceFault>.Detail-Eigenschaft von der OrganizationServiceFault.ErrorDetails-Eigenschaft abrufen. Der folgende Code zeigt, wie:


try
{
   // xMultiple request that triggers your plugin
}
catch (FaultException<OrganizationServiceFault> ex)
{
   ex.Detail.ErrorDetails.TryGetValue("failedRecordId", out object failedRecordId);
}

Wenn die Clientanwendung die Web-API verwendet, kann sie weitere Details zu Fehlern erhalten , indem Sie den Anforderungsheader Prefer: odata.include-annotations="*" festlegen.

Einzelne Operations-Plugins in Lösungen ersetzen

Wenn Sie Plug-In-Schritt-Registrierungen in Lösungen bereitstellen, gibt es keine Möglichkeit, die Deaktivierung oder Löschung einer Schrittregistrierung zu erzwingen. Das Ersetzen der Logik aus einer einzelnen Operation durch ein Plug-In mit mehreren Operationen stellt eine Herausforderung dar.

Wenn Sie einen neuen Plug-In-Schritt in einer Lösung für CreateMultiple oder UpdateMultiple implementieren, der einen Plug-In-Schritt für Create oder Update ersetzt, möchten Sie die Zeitspanne verringern, in der keine Logik oder redundante Logik angewendet wird. Sie können die Schritte für Create oder Update vor oder nach der Installation der Lösung manuell deaktivieren. Wenn Sie vorher deaktivieren, gibt es einen Punkt, in dem keine Logik angewendet wird. Wenn Sie danach deaktivieren, gibt es einen Punkt, in dem doppelte Logik angewendet wird. In beiden Fällen erfordert die Organisation möglicherweise geplante Ausfallzeiten, um sicherzustellen, dass logik konsistent angewendet wird.

Um die Dauer einer dieser Bedingungen zu minimieren, empfehlen wir Ihnen, Logik zum Deaktivieren aller Schritte einzuschließen, die durch die Bereitstellung der neuen Plug-Ins mit Package Deployer ersetzt werden. Package Deployer bietet die Möglichkeit, benutzerdefinierten Code vor, während und nach dem Importieren des Pakets in eine Umgebung auszuführen. Verwenden Sie diesen Code, um die vorhandenen Schrittregistrierungen zu deaktivieren.

Siehe auch

Beispiel: „CreateMultiple“- und „UpdateMultiple“-Plug-Ins
Nachrichten zu Massenoperationen
Beispiel: SDK für .Net Massenvorgänge nutzen
Leistung für Massenvorgänge optimieren

  • Last updated on