Lernprogramm: Aktualisieren eines Plug-Ins

Dieses Lernprogramm ist das dritte in der Serie, in der Ihnen gezeigt wird, 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 detaillierte 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 zusätzliche allgemeinen Optionen beschrieben, die Sie mit Plug-Ins ausführen können. In diesem Lernprogramm werden Sie:

• 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
• Die Registrierung einer Assembly, eines Plug-Ins oder Schritts aufheben

Ziel des Lernprogramms ist:

• Erstellen Sie ein synchrones Plug-In, das auf der Vorvalidierungsstufe der Nachricht „Update“ der Kontentabelle registriert ist.
• Das Plug-In wertet eine Reihe von String-Werten aus, die bei der Registrierung des Plug-Ins als Konfigurationsdaten übergeben wurden.
• Wenn der Name der Firma zu einem dieser Werte geändert wurde und der vorherige Wert den neuen Namen nicht enthielt, brechen Sie den Vorgang ab und senden Sie eine Fehlermeldung an den Benutzer.

Voraussetzungen

• Schließen Sie Lernprogramm: Schreiben und Registrieren eines Plugins ab
• Lernprogramm: Debuggen eines Plug-In wird empfohlen, ist aber nicht erforderlich.

Hinweis

Da viele grundlegender Schritte in Lernprogramm: Schreiben und Sie ein Plug-In registrieren detailliert beschrieben wurden, werden dieselben Schritte in diesem Lernprogramm nicht so ausführlich behandelt.

Erstellen einer neuen Plug-In-Klasse

1. Fügen Sie in Visual Studio dem BasicPlugin-Projekt eine neue Klasse namens ValidateAccountName.cs hinzu.

   Hinweis

   Wenn Sie eine wesentliche Änderung an einer Assembly vornehmen, sollten Sie die Assembly-Version aktualisieren. Dies ist besonders wichtig, wenn Sie eine Assembly aktualisieren wollen, die Teil einer verwalteten Lösung ist. Die Version ist Teil des vollqualifizierten Namens der Assembly, der ein eindeutiger Bezeichner der Assembly ist. Der Aktualisierungsprozess der Lösung erkennt möglicherweise nicht, dass sich die Assembly geändert hat, wenn sich der vollständig qualifizierte Name der Assembly nicht geändert hat.

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 umfasst einen Konstruktor, um die unsichere Konfiguration zu erfassen, die festgelegt wird, wenn ein Schritt konfiguriert wird.
• Diese Klasse benötigt bestimmte Schrittkonfiguration, um ordnungsgemäß zu funktionieren:
  • Aktualisierungsnachricht
  • In der Kontentabelle
  • Beim Firmenname, der in den Attributen enthalten ist
  • Bei PreEntityImage bei Verwendung des bestimmten Alias "a"
  • Mit PreEntityImage einschließlich der Namensspalten.
• Wenn die Schrittkonfiguration nicht korrekt ist, schreibt das Plug-In nur in die Ablaufverfolgung, dass es nicht korrekt konfiguriert ist
• Wenn keine ungültigen Namen in der Konfiguration festgelegt wurden, schreibt das Plug-In nur in die Ablaufverfolgung, dass keine ungültigen Namen an die Konfiguration übergeben wurden
• Wenn der neue Name einem der ungültigen Namen entspricht, die mit der Konfiguration festgelegt wurden UND der Originalname den neuen Namen nicht enthält, wird eine InvalidPluginExecutionException ausgelöst und dem Benutzer wird die Meldung ausgegeben, dass der Vorgang nicht zulässig ist.

Plug-In-Assembly-Registrierung aktualisieren

Die vorhandene Assembly aus Lernprogramm: Schreiben und Registrieren eines Plug-Ins sollte bereits registriert sein. Um das neue ValidateAccountName-Plug-In hinzuzufügen, ohne die Registrierung der vorhandene Assembly aufzuheben, müssen Sie es aktualisieren.

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

   

2. Im Dialog Update-Assembly: Grundlegendes Plug-In geben Sie den Speicherort der Assemblys an, indem Sie auf die Auslassungspunkte (…) klicken, und die Assembly wird geladen.

   

3. Vergewissern Sie sich, dass die Assembly und beide Plug-Ins ausgewählt sind und klicken Sie auf Ausgewählte Plug-Ins aktualisieren.

Einen neuen Schritt konfigurieren

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

Einstellung	Wert
Nachricht	Update
Primäre Entität	account
Filterattribute	Name
Ereignis-Pipeline-Phase der Ausführung	PreValidation
Ausführungsmodus	Synchron
Unsichere Konfiguration	test, foo, bar

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 das Bild mit diesen Einstellungen Neues Bild registrieren-Dialogfeld:

   Einstellung	Value
   Bildtyp	Vorbild
   Name	Konto
   Alias der Entität	v
   Parameter	Name

   

3. Wenn das Bild registriert ist, sehen Sie es im Plug-In-Registrierungstool.

   

Wichtig

Das Standardverhalten beim Erstellen eines Entitätsbilds besteht darin, alle Spalten auszuwählen. Dies kann jedoch zu einer verringerten Webdienstleistung führen. Entwickler sollten nur die erforderlichen Spalten einbeziehen.

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 eine vorhandene Firma mit einem Namen aktualisiert, der test, foo oder bar enthält, dann die Firma auf test, foo oder bar aktualisieren, sollten keine Nachricht angezeigt werden.

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

Verwenden Sie das Tool „Plug-in-Registrierung“, um eine Assembly, ein Plug-in oder einen Schritt zu de-registrieren (löschen). Das löschen einer Assembly löscht alle Plug-Ins und Schritte für diese Assembly.

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).