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

Artikel
08/17/2023

Hinweis

Die Nachrichten CreateMultiple und UpdateMultiple werden bereitgestellt. Alle Tabellen, die Create und Update unterstützen, werden irgendwann 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 in großen Mengen erstellt oder aktualisiert werden müssen, oder wenn die Leistung beim Erstellen und Aktualisieren einer großen Anzahl von Datensätzen wichtig ist. So ziemlich jede Tabelle, die Geschäftsdaten speichert, muss möglicherweise im Bulk erstellt oder aktualisiert werden.

Wenn Sie bereits Plug-Ins für die Create- und Update-Nachrichten bei Tabellen wie diesen haben, sollten Sie sie migrieren, damit bei ihnen stattdessen CreateMultiple und UpdateMultiple verwendet wird.

Ist eine Aktualisierung der Plug-Ins erforderlich?

Sie müssen Ihre Plug-ins nicht umstellen, um CreateMultiple und UpdateMultiple anstelle von Create und Update zu verwenden. Ihre Logik wird weiterhin angewendet, wenn Anwendungen CreateMultiple oder UpdateMultiple verwenden. Es besteht keine Notwendigkeit, Ihre Plugins zu migrieren, da die Dataverse Pipeline zur Verarbeitung von Nachrichten die Logik für Plugins, die entweder für die Einzel- oder die Mehrfachversion dieser Nachrichten geschrieben wurden, zusammenfasst.

Allerdings erhalten nur Plug-ins, die für die Mehrfachversion dieser Nachrichten geschrieben wurden, einen deutlichen Leistungsvorschub. Im Laufe der Zeit, wenn sich mehr Entwickler dafür entscheiden, die Leistung durch Verwendung der Nachrichten CreateMultiple und UpdateMultiple 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, bilden die Ausnahme.

Was ist anders?

Im Folgenden finden Sie einige der Unterschiede, die Sie bei der Migration Ihrer Plug-ins auf die Nachrichten CreateMultiple und UpdateMultiple beachten müssen.

Ziele statt Ziel

Die Mehrfachversion dieser Nachrichten hat einen Targets-Parameter, der eine EntityCollection ist, anstatt eines Target-Parameters, der eine einzelne Entity ist. Ihr Plugin-Code muss die Entitäten in der Sammlung in einer Schleife durchlaufen und auf jede Entität eine Logik anwenden.

Entitätsbilder

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

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

Wichtig

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 für alle Spalten. Diese Daten werden mit der Anzahl der im Parameter Targets übergebenen Entitäten multipliziert und tragen zur Gesamtgröße der Nachricht bei, die an die Sandbox gesendet wird. Möglicherweise stoßen Sie an das Limit für die Größe von Nachrichten.

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

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

Wichtig

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

Beispiel

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

Unverheiratet
Mehrere

Dieses Beispiel aktualisiert das Attribut sample_description mit der Information, ob sich der Wert sample_name geändert hat. Er bezieht sich auf ein Entitätsbild mit dem Namen example_preimage, das mit dem 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.");
}

In diesem Beispiel wird dieselbe Logik angewendet wie in der Einzel-Version, außer dass die Entity und die EntityImageCollection über eine count-Variable mit einer foreach-Schleife durch die EntityCollection synchronisiert werden. Es schließt auch die count ein, wenn Sie die localPluginContext.Trace-Methode verwenden, und ist weniger ausführlich. Traces werden nur dann angezeigt, wenn Fehlerbedingungen auftreten. Die Datenmenge, die Sie in die Ablaufverfolgungsprotokoll-Tabelle schreiben können, ist begrenzt. Sie sollten daher versuchen, das Schreiben von Ablaufverfolgungen für jede Iteration zu vermeiden.

// Verify input parameters
if (context.InputParameters.Contains("Targets") && context.InputParameters["Targets"] is EntityCollection entityCollection)
{
   // Verify expected entity images from step registration
   if (context.PreEntityImagesCollection.Length == entityCollection.Entities.Count)
   {
      int count = 0;
      foreach (Entity entity in entityCollection.Entities)
      {
            EntityImageCollection entityImages = context.PreEntityImagesCollection[count];

            // Verify expected entity image from step registration
            if (entityImages.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;
                        }

                        // Not tracing Success for brevity. There is a limit to what tracelog can display.
                        // localPluginContext.Trace($"Appended to 'sample_description': \"{message}\" for item {count} ");
                  }
                  else
                  {
                        localPluginContext.Trace($"Expected entity and preImage 'sample_name' values to be different. Both are {entity["sample_name"]} for item {count}");
                  }
               }
               else
               {
                  if (!entityContainsSampleName)
                        localPluginContext.Trace($"Expected entity sample_name attribute not found for item {count}.");
                  if (!entityImageContainsSampleName)
                        localPluginContext.Trace($"Expected preImage entity sample_name attribute not found for item {count}.");
                  if (!entityImageContainsSampleDescription)
                        localPluginContext.Trace($"Expected preImage entity sample_description attribute not found for item {count}.");
               }
            }
            else
            {
               localPluginContext.Trace($"Expected PreEntityImage: 'example_preimage' not found for item {count}.");
            }

            count++;
      }
   }
   else
   {
      localPluginContext.Trace($"Expected PreEntityImagesCollection to contain Entity images for each Entity.");
   }
}
else
{
   if (!context.InputParameters.Contains("Targets"))
      localPluginContext.Trace($"Expected InputParameter: 'Targets' not found.");
   if (!(context.InputParameters["Targets"] is EntityCollection))
      localPluginContext.Trace($"Expected InputParameter: 'Targets' is not EntityCollection.");
}

Ausnahmen behandeln

Alle Fehler, die in Ihren Plug-ins auftreten, sollten mit InvalidPluginExecutionException zurückgegeben werden. Wenn Ihr Plug-in eine Ausnahme für Schritte auslöst, die auf den Nachrichten CreateMultiple und UpdateMultiple registriert sind, sollte es angeben, welcher Datensatz den Fehler des Plug-ins verursacht hat. Um diese Informationen zu erfassen, verwenden Sie einen der folgenden Konstruktoren:

Diese Konstruktoren lassen zu, dass Sie der Eigenschaft InvalidPluginExecutionException.ExceptionDetails, die nicht direkt festgelegt werden kann, Werte hinzufügen.

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

Details der Ausnahme festlegen

Für die Nachricht UpdateMultiple iteriert Ihr Code durch die Eigenschaft EntityCollection Targets und wendet die Logik auf jede Entity an. Wenn ein Fehler auftritt, können Sie die Id des Datensatzes auf folgende Weise 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 Ihnen, den Wert des Primärschlüssels nicht für jeden Datensatz festzulegen. In den meisten Fällen sollten Sie zulassen, dass das System den Primärschlüsselwert für Sie festlegt, da die vom System generierten Werte für die beste Leistung optimiert sind.

In Fällen, in denen der Wert des Primärschlüssels nicht festgelegt ist, wenn es keinen anderen eindeutigen Bezeichner gibt, müssen Sie möglicherweise den Index des ausgefallenen Datensatzes im Parameter EntityCollection Targets oder eine Kombination von Werten zurückgeben, die den ausgefallenen Datensatz eindeutig identifizieren. 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.

Details zur Ausnahme abrufen

Wenn Sie Details über den fehlgeschlagenen Vorgang in die Eigenschaft InvalidPluginExecutionException.ExceptionDetails aufnehmen, kann der Client-Antragsteller diese über die Eigenschaft OrganizationServiceFault.ErrorDetails und die Eigenschaft FaultException <OrganizationServiceFault >.Detail erhalten. Der folgende Code zeigt, wie das geht:


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

Wenn die Client-Anwendung die Web-API verwendet, kann sie mehr Details zu Fehlern abrufen, indem sie den Prefer: odata.include-annotations="*" Anfrage-Header setzt.

Ersetzen von Plug-ins für einzelne Vorgänge in Lösungen

Wenn Sie Plug-in-Schrittregistrierungen in Lösungen bereitstellen, gibt es keine Möglichkeit, die Deaktivierung oder Löschung einer Schrittregistrierung zu erzwingen. Das macht das Ersetzen der Logik eines einzelnen Vorgangs in einem Plug-in mit mehreren Vorgängen zu einer Herausforderung.

Wenn Sie einen neuen Plug-in-Schritt in einer Lösung für CreateMultiple oder UpdateMultiple bereitstellen, der einen Plug-in-Schritt für Create oder Update ersetzt, möchten Sie die Zeit reduzieren, in der keine Logik oder doppelte Logik angewendet wird. Sie können die Schritte für Create oder Update manuell deaktivieren, bevor oder nachdem Sie die Lösung installieren. Wenn Sie vorher deaktivieren, gibt es einen Zeitraum, in dem keine Logik angewandt wird. Wenn Sie nachher deaktivieren, gibt es einen Zeitraum, in dem die doppelte Logik angewendet wird. In beiden Fällen benötigt die Organisation möglicherweise eine geplante Downtime, um sicherzustellen, dass die Logik konsistent angewendet wird.

Um die Dauer eines dieser Zustände zu minimieren, empfehlen wir Ihnen, eine Logik zur Deaktivierung aller Schritte einzubauen, die durch das Bereitstellen der neuen Plug-ins mit Package Deployer ersetzt werden. Package Deployer bietet die Funktionalität, angepassten Code auszuführen, bevor, während und nachdem das Paket in eine Umgebung importiert wird. Verwenden Sie diesen Code, um die vorhandenen Schrittregistrierungen zu deaktivieren.

Siehe auch

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