Übung – Das erste Plug-In schreiben

Abgeschlossen

In diesem Szenario muss eine Organisation sicherstellen, dass die Telefonnummerndaten in einem einheitlichen Format eingegeben werden. Zu diesem Zweck erstellen Sie ein Plug-In, das bei „create/update“ ausgeführt wird. Dabei werden alle nicht numerischen Zeichen einer Telefonnummer entfernt, bevor sie in Dataverse gespeichert wird. Anschließend erstellen Sie ein weiteres Plug-In, das bei „Contact retrieve/retrievemultiple“ ausgeführt wird, um die Telefonnummer neu zu formatieren, sodass sie Klammern und Bindestriche enthält, sofern die Daten existieren. 

Übung 1: Plug-In erstellen/aktualisieren

In dieser Übung erstellen Sie ein Plug-In, das beim Erstellen und Aktualisieren ausgeführt wird. Dieses Plug-In entfernt alle nicht numerischen Zeichen aus einer Telefonnummer.

Jede Übung besteht aus einem Szenario und Lernzielen. Das Szenario beschreibt dabei den Zweck der Übungen, während die Ziele aufgelistet sind und über Aufzählungspunkte verfügen.

Hinweis

Wenn Sie nicht über die Dynamics 365 SDK-Tools verfügen, finden Sie weitere Informationen unter Tools von NuGet herunterladen.

Aufgabe 1: Plug-In erstellen

1. Starten Sie Visual Studio 2022.

2. Wählen Sie Datei > Neu > Projekt aus.

3. Wählen Sie erst Klassenbibliothek (.NET Framework) und dann Weiter aus.

   

4. Geben Sie D365PackageProject für Projektname ein. Wählen Sie erst einen Ort zum Speichern des Projekts, danach .NET Framework 4.6.2 für Framework und abschließend Erstellen aus.

   

5. Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie NuGet-Pakete verwalten aus.

   

6. Wählen Sie die Registerkarte Durchsuchen aus, und suchen Sie nach microsoft.crmsdk.coreassemblies. Wählen Sie erst diese Option und dann Installieren aus.

   

7. Lesen Sie die Lizenzbedingungen, und wählen Sie dann Akzeptieren aus, wenn Sie zustimmen.

8. Schließen Sie den NuGet-Paket-Manager.

9. Klicken Sie mit der rechten Maustaste auf Class1.cs und Löschen.

10. Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie dann Hinzufügen > Klasse aus.

11. Nennen Sie die neue Klasse PreOperationFormatPhoneCreateUpdate, und wählen Sie dann Hinzufügen aus.

    

12. Fügen Sie der neuen Klasse die using-Anweisungen wie folgt hinzu:

     using Microsoft.Xrm.Sdk;
    
     using System.Text.RegularExpressions;
    

13. Veröffentlichen Sie die Klasse, und implementieren Sie die IPlugin-Schnittstelle.

    

14. Implementieren Sie das Schnittstellenelement.

    

    Ihre Klasse sollte nun wie im Bild unten aussehen.

    

Aufgabe 2: Eine Telefonnummer formatieren

1. Rufen Sie den Ausführungskontext vom Dienstanbieter ab. Ersetzen Sie die Ausnahme in der Execute-Methode durch den folgenden Codeausschnitt.

    IPluginExecutionContext context =
    (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
   

2. Überprüfen Sie den Eingabeparameter für das Ziel. Fügen Sie der Execute-Methode den folgenden Codeausschnitt hinzu.

    if (!context.InputParameters.ContainsKey("Target"))
   
    throw new InvalidPluginExecutionException("No target found");
   

3. Fügen Sie der Execute-Methode den folgenden Codeausschnitt hinzu. Dieser Codeausschnitt ruft die Zielentität vom Eingabeparameter ab und überprüft dann, ob die Attribute telephone1 (Telefon (geschäftlich) für Kontakte, Telefon für Firmen) enthalten.

    var entity = context.InputParameters["Target"] as Entity;
   
    if (!entity.Attributes.Contains("telephone1"))
   
    return;
   

4. Fügen Sie der Execute-Funktion den folgenden Codeausschnitt hinzu. Dieser Codeausschnitt entfernt alle nicht numerischen Zeichen der vom Benutzer angegebenen Telefonnummer.

    string phoneNumber = (string)entity["telephone1"];
   
    var formattedNumber = Regex.Replace(phoneNumber, @"[^\d]", "");
   

5. Legen Sie telephone1 auf die formatierte Telefonnummer fest. Fügen Sie der Execute-Methode den folgenden Codeausschnitt hinzu.

    entity["telephone1"] = formattedNumber;
   

   Die Execute-Methode sollte nun wie im Bild unten aussehen.

   

6. Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Eigenschaften aus.

   

7. Wählen Sie die Registerkarte Signieren aus, aktivieren Sie das Kontrollkästchen Assembly signieren, und klicken Sie dann auf Neue Schlüsseldatei.

   

8. Geben Sie contoso.snk im Feld Name der Schlüsseldatei ein, deaktivieren Sie das Kontrollkästchen Meine Schlüsseldatei durch ein Kennwort schützen, und wählen Sie dann OK aus.

   

9. Schließen Sie die Registerkarte Eigenschaften.

10. Erstellen Sie das Projekt, und stellen Sie sicher, dass der Build ausgeführt wird.

Aufgabe 3: Ein Plug-In und neue Schritte registrieren

Hinweis

Wenn Sie nicht über die Dynamics 365 SDK-Tools verfügen, finden Sie weitere Informationen unter Tools von NuGet herunterladen.

1. Starten Sie die Anwendung Plug-in Registration Tool.

2. Wählen Sie Neue Verbindung erstellen aus.

   

3. Wählen Sie Office 365 aus, aktivieren Sie das Kontrollkästchen Erweiterte anzeigen, geben Sie Ihre Anmeldeinformationen ein und wählen Sie dann Anmelden aus.

   

4. Wählen Sie erst Registrieren und dann Neue Assembly registrieren aus.

   

5. Wählen Sie Durchsuchen aus.

   

6. Navigieren Sie zum Ordner Bin > Debug der von Ihnen erstellten Klassenbibliothek. Wählen Sie erst D365PackageProject.dll und dann Öffnen aus.

   

7. Wählen Sie Ausgewählte Plug-Ins registrieren aus.

   

8. Wählen Sie OK aus.

9. Erweitern Sie die neu registrierte Assembly.

   

10. Klicken Sie mit der rechten Maustaste auf das Plug-In, und wählen Sie Neuen Schritt registrieren aus.

    

11. Wählen Sie erst Erstellen für Nachricht und dann Kontakt für Primäre Entität aus.

    

12. Wählen Sie erst PreOperation für Ereignis‑Pipeline-Ausführungsphase und dann Neuen Schritt registrieren aus.

    

13. Klicken Sie auf Schließen.

14. Klicken Sie mit der rechten Maustaste auf das Plug-In, und wählen Sie erneut Neuen Schritt registrieren aus.

    

15. Wählen Sie zuerst Aktualisieren für Nachricht, danach Kontakt für Primäre Entität und abschließend die Suchoption Attribute aus.

    

16. Deaktivieren Sie das Kontrollkästchen Alle auswählen, aktivieren Sie das Kontrollkästchen Telefon (geschäftlich), und wählen Sie dann OK aus.

    

17. Wählen Sie erst PreOperation für Ereignis‑Pipeline-Ausführungsphase und dann Neuen Schritt registrieren aus.

Aufgabe 4: Das Plug-In testen

1. Navigieren Sie zum Maker Portal, und stellen Sie sicher, dass Sie die richtige Umgebung ausgewählt haben.

2. Wählen Sie Apps aus, und starten Sie die Anwendung Spendenaktion.

   

3. Klicken Sie auf Dashboard, und öffnen Sie einen der Kontakte.

   

4. Wählen Sie + Neu aus.

   

5. Geben Sie erst Test für Vorname, danach Kontakt für Nachname und abschließend (123)-555-0100 für Telefon (geschäftlich) ein, und wählen Sie dann Speichern aus.

   

   Der Datensatz sollte gespeichert werden, und Telefon (geschäftlich) sollte nur die numerischen Werte anzeigen.

   

6. Ändern Sie das Telefon (geschäftlich) in 001-123-555-0100, und warten Sie einige Sekunden.

   Der Datensatz sollte aktualisiert werden, und Telefon (geschäftlich) sollte nur die numerischen Werte anzeigen.

   

Übung 2: Mehrere Plug-Ins erstellen/abrufen

In dieser Übung erstellen Sie ein Plug-In, das bei „retrieve“ und „retrieve multiple“ ausgeführt wird. Dieses Plug-In fügt den Telefonnummern Klammern und Bindestriche hinzu.

Jede Übung besteht aus einem Szenario und Lernzielen. Das Szenario beschreibt dabei den Zweck der Übungen, während die Ziele aufgelistet sind und über Aufzählungspunkte verfügen.

Aufgabe 1: Plug-In erstellen

1. Starten Sie Visual Studio.

2. Öffnen Sie das Projekt, das Sie in Übung 1 erstellt haben.

3. Klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Hinzufügen > Klasse aus.

   

4. Geben Sie im Feld Name für die Klasse PostOperationFormatPhoneOnRetrieveMultiple ein, und wählen Sie dann Hinzufügen aus.

5. Fügen Sie der neuen Klasse die using-Anweisungen wie folgt hinzu:

    using Microsoft.Xrm.Sdk;
   

6. Veröffentlichen Sie die Klasse, und implementieren Sie die IPlugin-Schnittstelle.

7. Implementieren Sie das Schnittstellenelement. Ihre Klasse sollte nun wie im Bild unten aussehen.

   

Aufgabe 2: Telefonnummer zum Abrufen formatieren

1. Rufen Sie den Ausführungskontext vom Dienstanbieter ab. Ersetzen Sie die Ausnahme in der Execute-Methode durch den folgenden Codeausschnitt.

    IPluginExecutionContext context =
    (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
   

2. Überprüfen Sie, ob der Name der Nachricht „Retrieve“ oder „RetrieveMultiple“ lautet. Fügen Sie der Execute-Methode den folgenden Codeausschnitt hinzu.

    if (context.MessageName.Equals("Retrieve"))	
    {
   
    }	
    else if(context.MessageName.Equals("RetrieveMultiple"))	
    {
   
    }
   

3. Überprüfen Sie, ob die Ausgabeparameter eine Geschäftsentität enthalten und ob es sich um einen Entitätstyp handelt. Fügen Sie den folgenden Codeausschnitt in die if retrieve-Bedingung ein.

    if (!context.OutputParameters.Contains("BusinessEntity") && context.OutputParameters["BusinessEntity"] is Entity)
    throw new InvalidPluginExecutionException("No business entity found");
   

4. Rufen Sie die Entität ab, und prüfen Sie, ob sie das Feld „telephone1“ enthält. Fügen Sie den folgenden Codeausschnitt in der if retrieve-Bedingung hinzu.

    var entity = (Entity)context.OutputParameters["BusinessEntity"];
   
    if (!entity.Attributes.Contains("telephone1"))	
        return;
   

5. Fügen Sie den folgenden Codeausschnitt der if retrieve-Bedingung hinzu. Dieser Codeausschnitt versucht, telephone1 als lang zu analysieren. Er wird zurückgegeben, wenn die Analyse nicht erfolgreich ist.

    if (!long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
   
    return;
   

6. Formatieren Sie die Telefonnummer, indem Sie Klammern und Bindestriche hinzufügen. Fügen Sie den folgenden Codeausschnitt in der if retrieve-Bedingung hinzu.

    var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
    entity["telephone1"] = formattedNumber;
   

Der Abruf-Teil der Execute-Methode sollte nun wie im Bild unten aussehen.

Aufgabe 3: Telefonnummer für „retrieve multiple“ formatieren

1. Fügen Sie den folgenden Codeausschnitt der retrieve multiple-Bedingung hinzu. Dieser Codeausschnitt prüft, ob die Ausgabeparameter BusinessEntityCollection enthalten und vom Typ EntityCollection sind.

    if(!context.OutputParameters.Contains("BusinessEntityCollection") && context.OutputParameters ["BusinessEntityCollection"] is EntityCollection)
        throw new InvalidPluginExecutionException("No business entity collection found");
   

2. Rufen Sie die Entitätssammlung von den Ausgabeparametern ab. Fügen Sie den folgenden Codeausschnitt in der retrieve multiple-Bedingung hinzu.

    var entityCollection = (EntityCollection)context.OutputParameters["BusinessEntityCollection"];
   

3. Durchlaufen Sie jede Entität in der Entitätssammlung.

    foreach (var entity in entityCollection.Entities)	
    {
   
    }
   

4. Fügen Sie den folgenden Codeausschnitt in der foreach-Bedingung hinzu. Dieser Codeausschnitt führt die gleichen Schritte aus wie die retrieve-Bedingung.

    if (entity.Attributes.Contains("telephone1") && entity["telephone1"] != null)
    {
       if (long.TryParse(entity["telephone1"].ToString(), out long phoneNumber))
       {
           var formattedNumber = String.Format("{0:(###) ###-####}", phoneNumber);
           entity["telephone1"] = formattedNumber;
       }
    }
   

   Der Teil retrieve multiple der Execute-Methode sollte nun wie im Bild unten aussehen.

   

5. Erstellen Sie das Projekt neu, und stellen Sie sicher, dass der Build erfolgreich ist.

Aufgabe 4: Eine Plug-In-Assembly aktualisieren und neue Schritte registrieren

1. Starten Sie das Plugin Registration Tool, und wählen Sie Neue Verbindung erstellen aus.

   

2. Wählen Sie Office 365 aus, aktivieren Sie Erweiterte anzeigen, geben Sie Ihre Anmeldeinformationen ein und wählen Sie dann Anmelden aus.

3. Wählen Sie die Assembly aus, die Sie in Übung 1 registriert haben, und wählen Sie dann Aktualisieren aus.

   

4. Wählen Sie Durchsuchen aus.

5. Navigieren Sie zum Debug-Ordner Ihres Projekts, und wählen Sie erst D365PackageProject.dll und dann Öffnen aus.

   

6. Wählen Sie erst die Plug-Ins und dann Ausgewählte Plug-Ins aktualisieren aus.

   

7. Wählen Sie OK aus.

8. Klicken Sie mit der rechten Maustaste auf das neue Plug-In, und wählen Sie Neuen Schritt registrieren aus.

9. Wählen Sie erst Retrieve für Nachricht, dann contact für Primäre Entität und abschließend PostOperation für Ereignis‑Pipeline-Ausführungsphase aus. Stellen Sie sicher, dass Synchron für Ausführungsmodus ausgewählt wurde, und wählen Sie dann Neuen Schritt registrieren aus.

   

10. Klicken Sie mit der rechten Maustaste auf das Plug-In, und wählen Sie erneut Neuen Schritt registrieren aus.

11. Wählen Sie erst RetrieveMultiple für Nachricht, dann contact für Primäre Entität und abschließend PostOperation für Ereignis‑Pipeline-Ausführungsphase aus. Stellen Sie sicher, dass Synchron für Ausführungsmodus ausgewählt wurde, und wählen Sie dann Neuen Schritt registrieren aus.

Aufgabe 5: Das Plug-In testen

1. Navigieren Sie zu Ihrem Maker Portal, und stellen Sie sicher, dass Sie sich in der richtigen Umgebung befinden.

2. Wählen Sie Apps aus. Wählen Sie dann die Anwendung Spendenaktion und dann Bearbeiten aus. Fügen Sie der Anwendung die Kontakttabelle hinzu.

   

3. Wählen Sie die Seite + Neu aus.

4. Wählen Sie Dataverse-Tabelle aus, und klicken Sie dann auf Weiter.

5. Wählen Sie Vorhandene Tabelle aus. Klicken Sie dann auf die Tabelle Kontakt, und wählen Sie dann Hinzufügen aus.

   

6. Wählen Sie Wiedergeben aus.

   

7. Wählen Sie Speichern und fortfahren aus.

8. Wählen Sie erneut Wiedergeben aus.

9. Wählen Sie Kontakte aus.

10. Die vorhandenen Datensätze, die nicht in dem neuen Format gespeichert wurden, werden nicht geändert. Wählen Sie + Neu aus.

    

11. Geben Sie die folgenden Informationen ein, und wählen Sie dann Speichern aus. Der Datensatz sollte gespeichert werden, und das Plug-In sollte das neue Format übernehmen.

12. Wählen Sie erneut Kontakte aus. Der von Ihnen erstellte Datensatz sollte das neue Format aufweisen.

    

13. Wählen Sie einen der vorhandenen Kontakte aus, um ihn zu öffnen.

    

14. Bearbeiten Sie Telefon (geschäftlich) folgendermaßen:

    

15. Wählen Sie Speichern aus. Es sollte dann das neue Format angewandt werden. Wählen Sie nochmals Kontakte aus.

    

Das bearbeitete Telefon hat das neue Format.