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 auf die Nachricht „Create“ der Kontotabelle registriert ist. Das Plug-In erstellt eine Aufgabenaktivität, die den Ersteller des Kontos erinnert, eine Woche später eine Nachverfolgung durchzuführen.

Hinweis

Das Ziel kann mithilfe eines Workflows einfach erreicht werden, ohne Code zu schreiben. Wir verwenden dieses einfache Beispiel, damit wir uns auf den Vorgang der Erstellung und Bereitstellung eines Plug-Ins konzentrieren können.

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 Visual Studio und öffnen Sie ein neues Klassenbibliothek (.NET Framework)-Projekt mit .NET Framework 4.6.2

   

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

2. Klicken Sie im Lösungsexplorer mit der rechten Maustaste in das Projekt und wählen Sie NuGet-Pakete verwalten... aus dem Kontextmenü 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.

   Hinweis

   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.

   Fügen Sie dem Build-Ordner Ihres Projekts keine anderen NuGet-Pakete oder -Assemblys hinzu. Sie können diese Assemblys nicht einschließen, wenn Sie die Assembly bei 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.

   Hinweis

   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

• ITracingService ermöglicht das Schreiben in das Ablaufverfolgungsprotokoll. Sie können ein Beispiel im letzten catch-Block sehen. Weitere Informationen: Verwendung von Tracing
• 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 Target-Eigenschaft vorhanden ist, wird Entity, das der Anforderung übergeben wurde, verfügbar.
• 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 mit später Bindung, um eine Aufgabe zu erstellen und diese der Firma zuzuordnen, die 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.

Hinweis

Erstellen Sie die Assembly mit der Konfiguration Debug, da Sie den Plug-in Profiler in einem späteren Tutorial zum Debuggen verwenden werden. Bevor Sie ein Plug-In mit Ihrer Lösung einschließen, sollten Sie es mit der Versionskonfiguration erstellen.

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. Nachdem Sie das Plugin Registration Tool heruntergeladen haben, öffnen Sie es durch Klicken auf PluginRegistration.exe.

2. Stellen Sie mit Neue Verbindung erstellen eine Verbindung zu Ihrer Instanz her.

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, klicken Sie auf Erweitert anzeigen und geben Sie Ihre Zugangsdaten ein. Ansonsten lassen Sie Melden Sie sich als aktueller Benutzer an ausgewählt.

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

   

6. Klicken Sie auf Anmeldung.

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

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

   

Registrieren Ihrer Assembly

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

   

2. Wählen Sie im Dialogfeld Neue Assembly registrieren die Auslassungspunkte (…) aus, und navigieren Sie zur 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.

   Hinweis

   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. Die Assembly (Assembly) BasicPlugin sollte nun angezeigt werden, 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
   Ereignis-Pipeline-Phase der Ausführung	PostOperation
   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.

   

Hinweis

Zu diesem Zeitpunkt sind die Assembly und die Schritte Teil des Systems Standardlösung. Wenn Sie ein Produktions-Plug-in erstellen, fügen Sie diese in die nicht verwaltete Lösung ein, die Sie verteilen werden. Diese Schritte sind in diesem Lernprogramm nicht enthalten. Weitere Informationen finden Sie unter Fügen Sie Ihre Assembly zu einer Lösung hinzu und Fügen Sie Schritt zur Lösung hinzu .

Plug-In testen

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

2. Innerhalb kurzer Zeit öffnen Sie die Firma und Sie können die Erstellung der Aufgabe überprüfen.

   

Was, wenn die Aufgabe nicht erstellt wurde?

Da wir mit einem asynchronen Plug-In arbeiten, wird der Vorgang zur Erstellung der Aufgabe nach dem Erstellen der Firma durchgeführt. Normalerweise erfolgt die Aufgabenerstellung sofort, aber, falls nicht, können Sie den Systemauftrag weiterhin in der Warteschlange anzeigen, wo er auf seine Anwendung wartet. Diese Schrittregistrierung verwendete die Option AsyncOperation löschen, wenn StatusCode = Erfolgreich, was eine bewährte Methode ist. Das bedeutet, sobald der Systemauftrag erfolgreich abgeschlossen wird, können Sie die Systemauftragsdaten nicht anzeigen, es sei denn, Sie registrieren das Plug-In mit aufgehobener Auswahl der Option AsyncOperation löschen, wenn StatusCode = erfolgreich erneut.

Falls jedoch ein Fehler aufgetreten ist, können Sie den Systemauftrag anzeigen, 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 Firma aus.

   

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

   

5. Wenn Sie den Systemauftrag öffnen, können Sie den Bereich Details erweitern, um Informationen, die in die Ablaufverfolgung geschrieben wurden, 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: Datenabfragen mithilfe der 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 FetchXML mit FetchExpression

Ablaufverfolgungsprotokolle anzeigen

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

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

Tipp

WENN Sie es vorziehen, diese Einstellung im Code zu ändern: Diese Einstellung befindet sich in der Spalte Organisationstabelle PluginTraceLogSetting.

Die gültigen Werte sind:

Wert	Label
0	Aus
1	Ausnahme
2	Alle

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.

   

   Hinweis

   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 zum Testen Ihres Plug-Ins, indem Sie eine neue Firma erstellen.

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

8. Sie sollten feststellen, dass ein neuer Datensatz „Plug-In-Ablaufverfolgungsprotokoll“ erstellt wird.

   

9. Wenn Sie den Datensatz öffnen, erwarten Sie möglicherweise, dass die Informationen enthalten sind, die Sie im Ablaufprotokoll festgelegt haben. Dies ist aber nicht der Fall. 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 plugintracelog EntityType mithilfe der Eigenschaft typename, um die Ergebnisse in der Eigenschaft messageblock 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.

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