Lernprogramm: Schreiben und Registrieren eines Plugins

Dieses Tutorial führt Sie durch das Schreiben eines Plug-Ins und dessen Registrierung bei Microsoft Dataverse. Sie sollten zunächst den Artikel Plug-In schreiben lesen, um sich mit dem Schreiben eines Plug-Ins vertraut zu machen.

Sie finden hier die kompletten Plug-In-Lösungsdateien für dieses Tutorial: Beispiel: Erstellen eines grundlegenden Plug-Ins.

Ziel

Erstellen Sie ein asynchrones Plug-In, das für die Nachricht „Create“ der Tabelle „Konto“ registriert ist. Das Plug-In erstellt eine Aufgabenaktivität, die den Ersteller des Kontos erinnert, eine Woche später eine Nachverfolgung durchzuführen.

Anforderungen

• Ein Systembenutzerkonto mit der Rolle „Administrator“ oder „Systemanpasser“ in der Zielumgebung von Microsoft Dataverse.
• Eine modellbasierte App, die die Tabellen „Konto“ und „Aufgabe“ enthält.
  • Wenn Sie über keine modellgesteuerte App verfügen, die diese Tabellen enthält, finden Sie Schritte zum Neuerstellen Ihrer ersten modellgesteuerten App in nur wenigen Minuten.
• Visual Studio 2019 (oder spätere Version).
• Kenntnisse der Programmiersprache Visual C#.
• Auf dem Entwicklungscomputer installiertes Plug-In-Registrierungstool. Siehe Dataverse-Entwicklungstools.

Plug-In-Projekt erstellen

In diesem Artikel wird die Verwendung von Visual Studio zum Schreiben des Plug-Ins und zum Erstellen der Assembly veranschaulicht. Sie können jedoch Ihren bevorzugten Editor zum Codieren verwenden und MSBuild zum Erstellen der Assembly verwenden. In beiden Fällen müssen Sie das Plug-In-Registrierungstool verwenden, um das Plug-In bei Dataverse zu registrieren.

Alternativ können Sie Power Platform CLI verwenden, um mit dem Befehl pac plugin init schnell ein neues Projekt mit Boilerplate-Plug-In-Code zu erstellen. Sie verwenden weiterhin das Plug-In-Registrierungstool, um das Plug-In bei Dataverse zu registrieren.

Eine weitere Alternative ist die Verwendung der Power Platform Tools-Erweiterung wie hier beschrieben: Erstellen und registrieren Sie ein Plug-In-Paket mit Visual Studio. In diesem Fall kann die Erweiterung das Plug-In erstellen und registrieren, sodass das Plug-In-Registrierungstool nicht erforderlich ist.

Erstellen Sie ein Visual Studio-Projekt für das Plug-In

1. Öffnen Sie in Visual Studio ein neues Klassenbibliotheksprojekt (.NET Framework), das auf eine unterstützte Frameworkversion ausgerichtet ist.

   

   Der Name, der für das Projekt verwendet wird, ist auch der Name der Assembly. Dieses Tutorial verwendet den Namen BasicPlugin.

2. Klicken Sie im Lösungs-Explorer mit der rechten Maustaste auf das von Ihnen erstellte Projekt und wählen Sie im Kontextmenü NuGet-Pakete verwalten... aus.

   

3. Wählen Sie Durchsuchen aus und suchen Sie nach Microsoft.CrmSdk.CoreAssemblies und installieren Sie die aktuelle Version.

   

4. Sie müssen Ich stimme zu im Dialogfeld Lizenz-Abnahme auswählen.

   Anmerkung

   Durch das Hinzufügen des Microsoft.CrmSdk.CoreAssemblies NuGet-Pakets sind diese Assemblys im Build-Ordner für Ihre Assemblys enthalten, Sie laden diese Assemblys jedoch nicht mit der Assembly hoch, die Ihre Logik enthält. Diese Assemblys sind bereits in der Sandbox-Laufzeit vorhanden.

   Stellen Sie sicher, dass sich nur Assemblys im Buildordner befinden, auf die direkt vom Projekt oder über NuGet Abhängigkeitsketten verwiesen wird. Sie können keine anderen Assemblies einbeziehen, wenn Sie das Assembly in Ihrer Logik registrieren. Sie können nicht davon ausgehen, dass die Assemblys, die nicht im Paket Microsoft.CrmSdk.CoreAssemblies NuGet enthalten sind, auf dem Server vorhanden und mit Ihrem Code kompatibel sind.

5. Klicken Sie im Lösungsexplorer mit der rechten Maustaste auf die Datei Class1.cs und wählen Sie im Kontextmenü Umbenennen aus.

   

6. Benennen Sie die Datei Class1.cs in FollowupPlugin.cs um.

7. Wenn Sie dazu aufgefordert werden, erlauben Sie Visual Studio, die Klasse umzubenennen, damit der Dateiname übereinstimmt.

   

Bearbeiten Sie die Klassendatei, um ein Plug-In zu definieren

1. Fügen Sie die folgenden using-Ausdrücke am Anfang der FollowupPlugin.cs-Datei hinzu.

   using System.ServiceModel;  
   using Microsoft.Xrm.Sdk;
   

2. Implementieren Sie die Schnittstelle IPlugin, indem Sie die Klasse bearbeiten.

   Anmerkung

   Wenn Sie nach dem Klassennamen nur : IPlugin eingeben, schlägt Visual Studio automatisch die Implementierung einer Kurzversion für die Ausführen-Methode vor.

   public class FollowupPlugin : IPlugin
   {
       public void Execute(IServiceProvider serviceProvider)
       {
           throw new NotImplementedException();
       }
   }
   

3. Ersetzen Sie die Inhalte der Execute-Methode durch den folgenden Code.

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

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

// The InputParameters collection contains all the data passed in the message request.  
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.  
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the IOrganizationService instance which you will need for  
    // web service calls.  
    IOrganizationServiceFactory serviceFactory =
        (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
    IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

    try
    {
        // Plug-in business logic goes here.  
    }

    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw new InvalidPluginExecutionException("An error occurred in FollowUpPlugin.", ex);
    }

    catch (Exception ex)
    {
        tracingService.Trace("FollowUpPlugin: {0}", ex.ToString());
        throw;
    }
}

Infos zum Code

• Das ITracingService ermöglicht Schreibzugriffe auf das Tracingprotokoll. Im abschließenden catch-Block sehen Sie ein Beispiel. Weitere Informationen: Tracing verwenden
• IPluginExecutionContext bietet Zugriff auf den Kontext für das Ereignis, das das Plug-In ausgeführt hat. Mehr Informationen: Verstehen Sie den Kontext der Ausführung.
• Der Code überprüft, dass der Kontext InputParameters die erwarteten Parameter für CreateRequest enthält, für das dieses Plug-In registriert wird. Wenn die Eigenschaft Target vorhanden ist, wird das an die Anfrage übergebene Entity bereitgestellt.
• Die IOrganizationServiceFactory-Schnittstelle bietet Zugriff auf eine Servicevariable, die die IOrganizationService-Benutzeroberfläche implementiert, die die Methoden bereitstellt, die Sie verwenden, um mit dem Service zu interagieren, um die Aufgabe zu erstellen.

Geschäftslogik hinzufügen

Das Plug-In erstellt eine Aufgabenaktivität, die den Ersteller des Kontos erinnert, eine Woche später eine Nachverfolgung durchzuführen.

Fügen Sie folgenden Code dem try-Block hinzu. Ersetzen Sie den Kommentar // Plug-in business logic goes here durch den folgenden Code.

// Create a task activity to follow up with the account customer in 7 days. 
Entity followup = new Entity("task");

followup["subject"] = "Send e-mail to the new customer.";
followup["description"] =
    "Follow up with the customer. Check if there are any new issues that need resolution.";
followup["scheduledstart"] = DateTime.Now.AddDays(7);
followup["scheduledend"] = DateTime.Now.AddDays(7);
followup["category"] = context.PrimaryEntityName;

// Refer to the account in the task activity.
if (context.OutputParameters.Contains("id"))
{
    Guid regardingobjectid = new Guid(context.OutputParameters["id"].ToString());
    string regardingobjectidType = "account";

    followup["regardingobjectid"] =
    new EntityReference(regardingobjectidType, regardingobjectid);
}

// Create the task in Microsoft Dynamics CRM.
tracingService.Trace("FollowupPlugin: Creating the task activity.");
service.Create(followup);

Infos zum Code

• Dieser Code verwendet den Stil der späten Bindung, um eine Aufgabe zu erstellen und sie dem Konto zuzuordnen, das gerade erstellt wird. Weitere Informationen: Tabellen mit dem SDK für .NET erstellen
• Früh gebundene Klassen können verwendet werden, aber für deren Verwendung müssen die Klassen für die Tabellen generiert und die Datei, die diese Klassen definiert, in das Assembly-Projekt aufgenommen werden. Die Verwendung früh gebundener Klassen ist größtenteils eine persönliche Vorliebe, daher werden diese Schritte zugunsten der Kürze aus diesem Lernprogramm weg gelassen. Weitere Informationen: Programmierung mit später und früher Bindung mithilfe des SDK für .NET
• Die Id des zu erstellenden Kontos wird im Kontext OutputParameters gefunden und als Lookup-Spalte regardingobjectid für die Aufgabe festgelegt.

Plug-In erstellen

In Visual Studio drücken Sie F6, um die Assembly zu erstellen. Überprüfen Sie, dass die Kompilierung fehlerfrei erfolgt.

Signieren des Plug-ins

1. Klicken Sie im Lösungsexplorer mit der rechten Maustaste auf das BasicPlugin-Projekt, und wählen Sie im Kontextmenü Eigenschaften aus.

   

2. Wählen Sie in den Projekteigenschaften die Registerkarte Signierung aus, und aktivieren Sie das Kontrollkästchen Assembly signieren.

   

3. Im Dropdown eine Schlüsseldatei mit starkem Namen auswählen: wählen Sie <Neu...> aus.

4. Geben Sie im Dialogfeld Schlüssel mit starkem Namen erstellen einen Schlüsseldateinamen ein, und deaktivieren Sie das Kontrollkästchen Meine Schlüsseldatei mit einem Kennwort schützen.

5. Wählen Sie OK aus, um das Dialogfeld Schlüssel mit starkem Namen erstellen zu schließen.

6. Überprüfen Sie in der Registerkarte Build der Projekteigenschaften, dass die Konfiguration auf Debuggen festgelegt ist.

7. Drücken Sie F6, um das Plug-In erneut zu erstellen.

8. Verwenden Sie den Windows-Explorer, um unter \bin\Debug\BasicPlugin.dll nach dem erstellten Plug-In zu suchen.

Plug-In registrieren

Um ein Plug-in zu registrieren, benötigen Sie das Plug-in Registration Tool.

Verbindung mithilfe des Plugin Registration Tool herstellen

1. Öffnen Sie das Plug-In-Registrierungstool, indem Sie den PAC-CLI pac tool prt Befehl ausführen.

2. Wählen Sie +Neue Verbindung erstellen, um Ihre Dataverse-Umgebung zu verbinden.

3. Stellen Sie sicher, dass Office 365 ausgewählt ist.

4. Wenn Sie die Verbindung mit einem anderen Microsoft-Konto als dem derzeit verwendeten herstellen, wählen Sie Erweitert anzeigen und geben Sie Ihre Zugangsdaten ein. Ansonsten lassen Sie Melden Sie sich als aktueller Benutzer an ausgewählt.

   Anmerkung

   Wenn Ihr Benutzerkonto die Multifaktorauthentifizierung (MFA) verwendet, stellen Sie sicher, dass das Kontrollkästchen Erweitert anzeigen nicht aktiviert ist.

5. Wenn Ihr Microsoft-Konto Zugriff auf mehrere Umgebungen bietet, wählen Sie Liste der verfügbaren Organisationen anzeigen aus.

   

6. Wählen Sie Anmelden aus.

7. Wenn Sie Liste verfügbarer Organisationen anzeigen ausgewählt haben, wählen Sie die Organisation aus, die Sie verbinden möchten und wählen Sie Anmeldung.

8. Nachdem Sie verbunden sind, sehen Sie alle vorhandenen registrierten Plug-Ins, benutzerdefinierten Workflow-Aktivitäten und die Datenanbieter.

   

Registrieren Sie Ihre Assembly

1. Wählen Sie im Dropdown Registrieren die Option Neue Assembly aus.

   

2. Wählen Sie im Dialogfeld Neue Assembly registrieren die Schaltfläche mit den Auslassungspunkten (…) aus, und wechseln Sie zu der Assembly, die Sie im vorherigen Schritt erstellt haben.

   

3. Vergewissern Sie sich für Microsoft 365-Benutzer, dass der Isolationsmodus auf Sandkasten und der Speicherort für die Assembly auf Datenbank eingestellt ist.

   Anmerkung

   Weitere Optionen für Isolationsmodus und Speicherort gelten für lokale Dynamics 365-Bereitstellungen. Als Standort können Sie die Datenbank des D365-Servers, den lokalen Speicher (Festplatte) des Servers oder den Cache für die globale Assembly des Servers angeben. Weitere Informationen finden Sie unter Plug-In-Speicher.

4. Klicken Sie auf Ausgewählte Plug-ins registrieren.

5. Sie sehen ein Bestätigungsdialogfeld Registrierte Plug-Ins.

   

6. Wählen Sie OK aus, um das Dialogfeld zu schließen, und schließen Sie den Dialog Neue Assembly registrieren.

7. Sie sollten nun die (Assembly) BasicPlugin-Assembly sehen, die Sie erweitern können, um das (Plugin) BasicPlugin.FollowUpPlugin-Plug-In anzuzeigen.

   

Einen neuen Schritt registrieren

1. Klicken Sie mit der rechten Maustaste auf (Plug-In) BasicPlugin.FollowUpPlugin, und wählen Sie Neuen Schritt registrieren aus.

   

2. Legen Sie im Dialogfeld Neuen Schritt registrieren die folgenden Felder fest.

   Einstellungen	Wert
   Nachricht	Erzeugen
   Primäre Entität	Konto
   Phase der Ereignis-Pipeline-Ausführung	Nach der Operation
   Ausführungsmodus	Asynchron

   

3. Wählen Sie Neuen Schritt registrieren aus, um die Registrierung abzuschließen, und schließen Sie das Dialogfeld Neuen Schritt registrieren.

4. Sie können den registrierten Schritt jetzt sehen.

   

Plug-In testen

1. Öffnen Sie eine modellbasierte App und erstellen Sie eine Kontotabelle.

2. Nach kurzer Zeit öffnen Sie das Konto, und Sie können überprüfen, ob die Aufgabe erstellt wurde.

   

Was, wenn die Aufgabe nicht erstellt wurde?

Da wir mit einem asynchronen Plug-In arbeiten, wird der Vorgang zum Erstellen der Aufgabe erst nach dem Erstellen des Kontos ausgeführt. Normalerweise erfolgt die Aufgabenerstellung sofort, aber wenn dies nicht der Fall ist, können Sie den Systemauftrag möglicherweise weiterhin in der Warteschlange sehen, wo er auf seine Ausführung wartet. Diese Schrittregistrierung verwendete die Option AsyncOperation löschen, wenn StatusCode = Erfolgreich, was eine bewährte Methode ist. Das bedeutet, dass Sie, sobald der Systemauftrag erfolgreich abgeschlossen ist, die Daten des Systemauftrags nicht mehr anzeigen können, es sei denn, Sie registrieren das Plug-In erneut, wobei die Option Delete AsyncOperation if StatusCode = Successful deaktiviert ist.

Wenn jedoch ein Fehler aufgetreten ist, können Sie den Systemauftrag aufrufen, um die Fehlermeldung anzuzeigen.

Anzeigen von Systemaufträgen

Verwenden Sie die angepasste Dynamics 365-App, um Systemaufträge anzuzeigen.

1. Navigieren Sie in Ihrer modellbasierten App zur App.

   

2. In der angepassten Dynamics 365-App navigieren Sie zu Einstellungen>System>Systemaufträge.

   

3. Beim Anzeigen von Systemaufgaben können Sie nach Tabelle (Entität) filtern. Wählen Sie Konto aus.

   

4. Wenn der Auftrag fehlgeschlagen ist, sollte ein Datensatz mit dem Namen BasicPlugin.FollowupPlugin: Erstellen eines Kontos angezeigt werden.

   

5. Wenn Sie den Systemauftrag öffnen, können Sie den Bereich Details erweitern, um die im Trace protokollierten Informationen und Details zum Fehler anzuzeigen.

   

Systemaufträge abfragen

Sie können die folgende Web-API-Abfrage verwenden, um fehlgeschlagene Systemjobs für asynchrone Plug-ins zurückzugeben.

GET <your org uri>/api/data/v9.0/asyncoperations?$filter=operationtype eq 1 and statuscode eq 31&$select=name,message

Weitere Informationen: Abfrage von Daten über die Web-API

Oder Sie verwenden das folgende FetchXml:

<fetch top='50' >
  <entity name='asyncoperation' >
    <attribute name='message' />
    <attribute name='name' />
    <filter type='and' >
      <condition attribute='operationtype' operator='eq' value='1' />
      <condition attribute='statuscode' operator='eq' value='31' />
    </filter>
  </entity>
</fetch>

Weitere Informationen: Verwendung von FetchXML mit FetchExpression

Traceprotokolle anzeigen

Der Beispielcode schrieb eine Nachricht in das Ablaufverfolgungsprotokoll. Diese nächsten Schritte beschreiben, wie die Protokolle angezeigt werden.

Standardmäßig sind Ablaufverfolgungsprotokolle von Plug-Ins nicht aktiviert.

Verwenden Sie die folgenden Schritte, um sie in einer modellgesteuerten App zu aktivieren.

1. Öffnen Sie die angepasste Dynamics 365-App.

   

2. Navigieren Sie zu Einstellungen>System>Administration.

   

3. Wählen Sie unter Administration die Option Systemeinstellungen aus.

4. Im Dialog Systemeinstellungen in der Registerkarte Anpassung legen Sie Protokollierung im Plug-In-Ablaufverfolgungsprotokoll aktivieren auf Alle fest.

   

   Anmerkung

   Sie sollten die Protokollierung deaktivieren, nachdem Sie das Testen Ihres Plug-In beendet haben, oder es mindestens auf Ausnahme anstelle von Alle festlegen.

5. Wählen Sie OK aus, um das Dialogfeld Systemeinstellungen zu schließen.

6. Wiederholen Sie die Schritte, um Ihr Plug-in zu testen, indem Sie ein neues Konto erstellen.

7. In der angepassten Dynamics 365-App navigieren Sie zu Einstellungen>Anpassung>Plug-In-Ablaufverfolgungsprotokoll.

8. Sie sollten feststellen, dass ein neuer Eintrag im Plug-In-Ablaufverfolgungsprotokoll erstellt wird.

   

9. Wenn Sie den Datensatz öffnen, könnten Sie erwarten, dass er die Informationen enthält, die Sie in Ihrer Nachverfolgung festgelegt haben, doch das tut er nicht. Es wird nur überprüft, dass die Ablaufverfolgung erfolgt ist.

10. Um die Details anzuzeigen, ist es einfacher, diese Daten mithilfe der Web API in Ihrem Browser abzufragen. Nutzen Sie dazu die folgende Abfrage mit dem plugintracelog EntityType mithilfe der Eigenschaft typename, um die Ergebnisse in der messageblock Eigenschaft anhand des Namens der Plug-In-Klasse zu filtern.

    GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=typename eq 'BasicPlugin.FollowUpPlugin'

11. Sie können erwarten, dass diese JSON-formatierten Informationen mit der Web-API-Abfrage zurückgegeben werden.

    {
        "@odata.context": "<your org uri>/api/data/v9.0/$metadata#plugintracelogs(messageblock)",
        "value": [{
            "messageblock": "FollowupPlugin: Creating the task activity.",
            "plugintracelogid": "f0c221d1-7f84-4f89-acdb-bbf8f7ce9f6c"
        }]
    }
    

Nächste Schritte,

In diesem Lernprogramm haben Sie ein einfaches Plug-In erstellt und es registriert. Schließen Sie Lernprogramm: Debuggen eines Plug-Ins ab, um zu erfahren, wie Sie dieses Plug-In debuggen.

Siehe auch

Lernprogramm: Aktualisieren eines Plug-Ins
Schreiben eines Plug-Ins
Registrieren eines Plug-Ins
Debuggen von Plug-Ins.