Lernprogramm: Aktualisieren eines Plug-Ins

Dieses Tutorial ist das dritte in einer Reihe, die zeigt, wie Sie mit Plug-ins arbeiten.

• Lernprogramm: Schreiben und Registrieren eines Plugins
• Lernprogramm: Debuggen eines Plug-Ins
• Lernprogramm: Aktualisieren eines Plug-Ins (Dieses Lernprogramm)

Eine ausführliche Erläuterung der unterstützenden Konzepte und technischen Details finden Sie unter:

• Verwenden von Plug-Ins zur Erweiterung von Geschäftsprozessen
• Schreiben eines Plug-Ins
• Registrieren eines Plug-Ins
• Debuggen von Plug-Ins

Ziel

In diesem Lernprogramm werden allgemeine Aufgaben beschrieben, die Sie mit Plug-Ins ausführen. In diesem Lernprogramm:

• Eine Plug-In-Assembly aktualisieren.
• Ein synchrones Plug-In erstellen und registrieren
• Konfigurationsdaten im Plug-In verwenden
• Einen Fehler auslösen, der dem Benutzer angezeigt wird
• Ein Vor-Entitätsbild in Ihrem Code konfigurieren und verwenden
• Aufheben der Registrierung einer Assembly, eines Plug-Ins oder eines Schritts

Das Ziel dieses Tutorials ist:

• Erstellen Sie ein synchrones Plug-In, das auf der Vorvalidierungsstufe der Nachricht „Update“ der Kontentabelle registriert ist.
• Werten Sie einen Satz von Zeichenfolgenwerten aus, die als Konfigurationsdaten übergeben werden, wenn das Plug-In registriert ist.
• Wenn der Name des Kontos in einen dieser Werte geändert wird und der vorherige Wert den neuen Namen nicht enthielt, brechen Sie den Vorgang ab und senden Sie eine Fehlermeldung an den Benutzer zurück.

Voraussetzungen

• Vollständiges Lernprogramm: Schreiben und Registrieren eines Plug-Ins.
• Lernprogramm: Debuggen eines Plug-In wird empfohlen, ist aber nicht erforderlich.

Erstellen einer neuen Plug-In-Klasse

1. Fügen Sie in Visual Studio dem BasicPlugin-Projekt eine neue Klasse mit dem Namen hinzuValidateAccountName.cs.

   Anmerkung

   Wenn Sie eine erhebliche Änderung an einer Assembly vornehmen, aktualisieren Sie die Assemblyversion. Dieser Schritt ist besonders wichtig, wenn Sie beabsichtigen, eine Assembly zu aktualisieren, die Teil einer verwalteten Lösung ist. Die Version ist Teil des vollqualifizierten Namens der Assembly, der als eindeutiger Bezeichner der Assembly dient. Der Lösungsaktualisierungsprozess erkennt möglicherweise nicht, dass sich die Assembly geändert hat, wenn sich der vollqualifizierte Name der Assembly nicht ändert.

2. Fügen Sie der Klasse den folgenden Code hinzu, und erstellen Sie die Assembly neu.

using Microsoft.Xrm.Sdk;
using System;
using System.Collections.Generic;
using System.Linq;

namespace BasicPlugin
{
  public class ValidateAccountName : IPlugin
  {
    //Invalid names from unsecure configuration
    private List<string> invalidNames = new List<string>();

    // Constructor to capture the unsecure configuration
    public ValidateAccountName(string unsecure)
    {
      // Parse the configuration data and set invalidNames
      if (!string.IsNullOrWhiteSpace(unsecure))
        unsecure.Split(',').ToList().ForEach(s =>
        {
          invalidNames.Add(s.Trim());
        });
    }
    public void Execute(IServiceProvider serviceProvider)
    {

      // Obtain the tracing service
      ITracingService tracingService =
      (ITracingService)serviceProvider.GetService(typeof(ITracingService));
      try
      {

        // Obtain the execution context from the service provider.  
        IPluginExecutionContext context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

        // Verify all the requirements for the step registration
        if (context.InputParameters.Contains("Target") && //Is a message with Target
            context.InputParameters["Target"] is Entity && //Target is an entity
            ((Entity)context.InputParameters["Target"]).LogicalName.Equals("account") && //Target is an account
            ((Entity)context.InputParameters["Target"])["name"] != null && //account name is passed
            context.MessageName.Equals("Update") && //Message is Update
            context.PreEntityImages["a"] != null && //PreEntityImage with alias 'a' included with step
            context.PreEntityImages["a"]["name"] != null) //account name included with PreEntityImage with step
        {
          // Obtain the target entity from the input parameters.  
          var entity = (Entity)context.InputParameters["Target"];
          var newAccountName = (string)entity["name"];
          var oldAccountName = (string)context.PreEntityImages["a"]["name"];

          if (invalidNames.Count > 0)
          {
            tracingService.Trace("ValidateAccountName: Testing for {0} invalid names:", invalidNames.Count);

            if (invalidNames.Contains(newAccountName.ToLower().Trim()))
            {
              tracingService.Trace("ValidateAccountName: new name '{0}' found in invalid names.", newAccountName);

              // Test whether the old name contained the new name
              if (!oldAccountName.ToLower().Contains(newAccountName.ToLower().Trim()))
              {
                tracingService.Trace("ValidateAccountName: new name '{0}' not found in '{1}'.", newAccountName, oldAccountName);

                string message = string.Format("You can't change the name of this account from '{0}' to '{1}'.", oldAccountName, newAccountName);

                throw new InvalidPluginExecutionException(message);
              }

              tracingService.Trace("ValidateAccountName: new name '{0}' found in old name '{1}'.", newAccountName, oldAccountName);
            }

            tracingService.Trace("ValidateAccountName: new name '{0}' not found in invalidNames.", newAccountName);
          }
          else
          {
            tracingService.Trace("ValidateAccountName: No invalid names passed in configuration.");
          }
        }
        else
        {
          tracingService.Trace("ValidateAccountName: The step for this plug-in is not configured correctly.");
        }
      }
      catch (Exception ex)
      {
        tracingService.Trace("BasicPlugin: {0}", ex.ToString());
        throw;
      }
    }
  }
}

Infos zum Code

• Diese Klasse enthält einen Konstruktor, um die unsichere Konfiguration zu erfassen, die Sie beim Konfigurieren eines Schritts festgelegt haben.
• Diese Klasse benötigt bestimmte Schrittkonfiguration, um ordnungsgemäß zu funktionieren:
  • Aktualisierungsnachricht
  • In der Kontotabelle
  • Mit dem in den Attributen enthaltenen Kontonamen
  • Mit PreEntityImage mit dem spezifischen Alias „a“
  • Mit PreEntityImage einschließlich der Spalten für die Namen.
• Wenn die Schrittkonfiguration nicht korrekt ist, schreibt das Plug-in in die Ablaufverfolgung, dass es nicht korrekt konfiguriert ist.
• Wenn Sie in der Konfiguration keine ungültigen Namen festlegen, schreibt das Plug-In in die Ablaufverfolgung, dass keine ungültigen Namen an die Konfiguration übergeben wurden.
• Wenn der neue Name mit einem der ungültigen Namen übereinstimmt, die Sie mithilfe der Konfiguration festgelegt haben und der ursprüngliche Name nicht den neuen Namen enthält, löst das Plug-In eine InvalidPluginExecutionException Meldung aus, dass dieser Vorgang nicht zulässig ist.

Plug-In-Assembly-Registrierung aktualisieren

Sie haben die vorhandene Assembly bereits im Lernprogramm registriert: Schreiben und Registrieren eines Plug-Ins. Um das neue ValidateAccountName-Plug-In hinzuzufügen, ohne die Registrierung der vorhandenen Assembly aufzuheben, aktualisieren Sie es.

1. Wählen Sie das (Assembly) Basis-Plug-In aus und wählen Sie Aktualisieren aus.

   

2. Geben Sie im Dialogfeld „Assembly aktualisieren: Basis-Plug-In“ den Speicherort der Assembly an, indem Sie die Ellipsen (…) auswählen. Die Baugruppe wird geladen.

   

3. Vergewissern Sie sich, dass die Assembly und beide Plug-Ins ausgewählt sind, und wählen Sie "Ausgewählte Plug-Ins aktualisieren" aus.

Einen neuen Schritt konfigurieren

Konfigurieren Sie das ValidateAccountName-Plug-in mit diesen Einstellungen:

Bild hinzufügen

1. Klicken Sie mit der rechten Maustaste auf den Schritt, den Sie soeben registriert haben, und wählen Sie Neues Bild registrieren aus.

   

2. Konfigurieren Sie im Dialogfeld Neues Image registrieren das Image mit diesen Einstellungen:

   Einstellung	Wert
   Bildtyp	Vorheriges Bild
   Name	Konto
   Alias der Entität	a
   Parameter	Name

   

3. Wenn Sie das Bild registrieren, wird es im Plug-In-Registrierungstool angezeigt.

   

Plug-In testen

1. Öffnen Sie die Anwendung und versuchen Sie, einen vorhandenen Firmennamen auf test, foooder bar zu aktualisieren.

2. Wenn Sie versuchen, zu speichern, sollte die folgende Fehlermeldung angezeigt werden:

   

3. Wenn Sie ein vorhandenes Konto mit einem Namen aktualisieren, der test, foo oder bar enthält, und dann das Konto auf test, foo oder bar aktualisieren, sollte die Meldung nicht angezeigt werden.

Die Registrierung einer Assembly, eines Plug-Ins und eines Schritts aufheben

Verwenden Sie das Plug-In-Registrierungstool, um die Registrierung aller Assemblys, Plug-Ins oder Schritte aufzuheben (löschen). Beim Löschen einer Assembly werden alle Plug-Ins und Schritte für diese Assembly gelöscht.