Freigeben über

Schreiben eines Plug-Ins

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Plug-Ins sind benutzerdefinierte Klassen, die die IPlugin-Schnittstelle implementieren. Sie können in jeder .NET Framework 4.5.2-CLR-kompatiblen Sprache wie Microsoft Visual C# und Microsoft Visual Basic .NET ein Plug-In schreiben. Um in der Lage zu sein, Plug-In-Code zu erstellen, müssen Sie Microsoft.Crm.Sdk.Proxy.dll- und Microsoft.Xrm.Sdk.dll-Assemblyverweise dem Projekt hinzufügen. Diese Assemblys finden Sie im SDK\Bin-Ordner des SDK.Laden Sie das Microsoft Dynamics CRM SDK-Paket herunter.

In diesem Thema

Plug-In-Entwurf

Schreiben eines einfachen Plug-Ins

Schreiben eines Plug-In-Konstruktors

Unterstützung der Offlineausführung

Webzugriff für isolierte Plug-Ins (im Sandkasten)

Verwenden von Typen mit früher Bindung

Plug-In-Assemblys

Plug-In-Entwurf

Ihr Plug-In-Entwurf sollte die Webanwendungsfunktion automatisch speichern berücksichtigen, die in Microsoft Dynamics 365 (online und lokal) eingeführt wurde. Das Automatische Speichern ist standardmäßig aktiviert, kann jedoch auf einer Organisationsebene deaktiviert werden. Wenn das automatische Speichern aktiviert ist, gibt es keine Schaltfläche Speichern. Die Webanwendung speichert Daten im Formular automatisch 30 Sekunden nach der letzten nicht gespeicherten Änderung. Sie können Formularskripts anwenden, um das automatische Speicherverhalten auf Formularebene zu deaktivieren. Je nachdem, wie Sie das Plug-In registriert haben, kann das automatische Speichern dazu führen, dass das Plug-In häufiger für einzelne Feldänderungen aufgerufen wird, anstelle eines Plug-In-Aufrufs für alle Änderungen. Sie sollten annehmen, dass jeder Benutzer jeden Datensatz jederzeit speichern kann, mithilfe von Ctrl+S, durch eine Speichernschaltfläche oder automatisch durch die automatische Speicherfunktion.

Es ist eine bewährte Methode, um das Plug-In oder den Workflow für Entitäten und besondere Felder zu registrieren. Vermeiden Sie es, einen Workflow oder ein Plug-In für Änderungen an allen Entitätsfeldern zu registrieren. Wenn Sie ein vorhandenes Plug-In oder einen vorhandenen Workflow haben, der implementiert wurde, bevor die automatische Speicherfunktion verfügbar war, sollten Sie diesen Code erneut testen, um die ordnungsgemäße Funktion zu überprüfen. Weitere Informationen finden Sie unter TechNet: Verwalten der automatischen Speicherung.

Schreiben eines einfachen Plug-Ins

Das folgende Beispiel zeigt allgemeinen Code, den Sie häufig in einem Plug-In finden. In diesem Beispiel enthält der Code keine angepasste Geschäftslogik, durch die die beabsichtigte Aufgabe des Plug-Ins ausgeführt wird. Der Code zeigt aber eine Plug-In-Klasse, die die IPlugin-Schnittstelle und die erforderliche Execute-Methode implementiert.

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

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        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"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference 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 MyPlug-in.", ex);
            }

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

Der IServiceProvider-Parameter der Execute-Methode ist ein nützlicher Container für mehrere nützliche Serviceobjekte, auf die innerhalb eines Plug-Ins zugegriffen werden kann. Der Dienstanbieter enthält Instanzverweise auf den Ausführungskontext IOrganizationServiceFactory, ITracingService und mehr. Der Beispielcode demonstriert das Abrufen von Verweisen auf den Ausführungskontext IOrganizationService und ITracingService vom Dienstanbieterparameter. Weitere Informationen zum Suchdienst finden Sie unter Debuggen Sie ein Plug-In.

Der Ausführungskontext enthält zahlreiche Informationen zum Ereignis, das dazu geführt hat, dass das Plug-In ausgeführt wird und die Daten in der Nachricht aktuell von der Pipeline bearbeitet werden. Weitere Informationen zum Datenkontext finden Sie unter Nachvollziehen des Datenkontexts, der an einem Plug-In übergeben wird.

Die Plattform bietet die korrekten Webdienst-URLs und Netzwerkanmeldeinformationen, wenn Sie den Webdienstverweis der Organisation vom Dienstanbieter abrufen. Das Instanziieren Ihres eigenen Webdienstproxys wird nicht unterstützt, da es zu Deadlock- und Authentifizierungsproblemen führt. Nachdem Sie die Organisationsservicereferenz haben, können Sie sie verwenden, um Methodenaufrufe an den Webdienst der Organisation durchzuführen. Sie können Geschäftsdaten in einer einzelnen Microsoft Dynamics 365-Organisation abrufen oder ändern, indem Sie eine oder mehrere Nachrichtenanforderungen für den Webdienst ausstellen. Weitere Informationen zu Nachrichtenanforderungen finden Sie unter Verwendung von Nachrichten (Anforderungs- und Antwortklassen) mit der Ausführensmethode.

Ein typisches Plug-In sollte auf die Informationen im Kontext zugreifen, die erforderlichen Geschäftsvorgänge ausführen und Ausnahmen verarbeiten. Weitere Informationen zu Verarbeitungsausnahmen in ein Plug-In finden Sie unter Behandlung von Ausnahmen in Plug-ins. Ein Beispiel für ein komplexeres Plug-In finden Sie im Thema Beispiel: Erstellen eines grundlegenden Plug-Ins.

Wichtig

Für verbesserte Leistung werden Plug-In-Instanzen von Microsoft Dynamics 365 zwischengespeichert. Die Execute-Methode des Plug-Ins sollte keinen Status aufweisen, da der Konstruktor nicht für jeden Aufruf des Plug-Ins aufgerufen wird. Außerdem könnten mehreren Systemsthreads das Plug-In gleichzeitig ausführen. Alle aufrufbasierten Statusinformationen werden im Kontext gespeichert. Daher sollten Sie keine globalen Variablen verwenden oder versuchen, Daten in Elementvariablen zur Verwendung während des nächsten Plug-In-Aufrufs zu speichern, es sei denn, Daten wurden aus den Konfigurationsparameter abgerufen, der dem Konstruktor bereitgestellt wurde. Änderungen an einer Plug-In-Registrierung führen dazu, dass das Plug-In erneut initialisiert wird.

Schreiben eines Plug-In-Konstruktors

Die Microsoft Dynamics 365-Plattform unterstützt einen optionalen ein Plug-In-Konstruktor, der einen oder zwei Zeichenfolgenparameter akzeptiert. Beim Schreiben eines Konstruktors auf diese Weise, können Sie alle Zeichenfolgen mit Informationen zur Laufzeit an das Plug-In übergeben.

Im folgenden Beispiel wird das Format des Konstruktors gezeigt. In diesem Beispiel wird die Plug-In-Klasse SamplePlugin benannt.

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

Der erste Zeichenfolgenparameter des Konstruktors enthält öffentliche (unsichere) Informationen. Der zweite Zeichenfolgenparameter enthält nicht öffentliche (sichere) Informationen. In dieser Diskussion bezieht sich sicher auf einen verschlüsselten Wert, während sich unsicher auf einen unverschlüsselten Wert bezieht. Beim Verwenden von Microsoft Dynamics 365 für Microsoft Office Outlook mit Offlinezugriff wird die sichere nicht ein ein ausgeführtes Plug-In übergeben, während Dynamics 365 für Outlook offline ist.

Die Informationen, um die an den Plug-In-Konstruktor in diesen Zeichenfolgen übergeben werden, werden angegeben, wenn das Plug-In bei Microsoft Dynamics 365 registriert wird. Wenn Sie das Plug-In-Registrierungstool verwenden, um ein Plug-In zu registrieren, können Sie sichere und unsichere Informationen in die Felder Sichere Konfiguration und Unsichere Konfiguration eingeben, die im Formular Neuen Schritt registrieren bereitgestellt werden. Wenn Sie ein Plug-In programmgesteuert mithilfe von Microsoft Dynamics 365 SDK registrieren, enthält SdkMessageProcessingStep.Configuration den unsicheren Wert, und SdkMessageProcessingStep.SecureConfigId bezieht sich auf einen SdkMessageProcessingStepSecureConfig-Datensatz, der den sicheren Wert enthält.

Unterstützung der Offlineausführung

Sie können Plug-Ins so registrieren, dass sie im Onlinemodus, im Offlinemodus oder in beiden Modi ausgeführt werden. Der Offlinemodus wird nur in Microsoft Dynamics 365 für Microsoft Office Outlook mit Offlinezugriff unterstützt. Der Plug-In-Code kann überprüfen, ob er im Offlinemodus ausgeführt wird, indem er die IsExecutingOffline-Eigenschaft überprüft.

Wenn Sie ein Plug-In entwerfen, das für die Online- und Offlineausführung registriert wird, denken Sie daran, dass das Plug-In zweimal ausgeführt werden kann. Das erste Mal, während Microsoft Dynamics 365 für Microsoft Office Outlook mit Offlinezugriff offline ist. Das Plug-In wird erneut ausgeführt, wenn Dynamics 365 für Outlook online geht und die Synchronisierung zwischen Dynamics 365 für Outlook und dem Microsoft Dynamics 365-Server stattfindet. Sie können die IsOfflinePlayback-Eigenschaft überprüfen, um zu ermitteln, ob das Plug-In aufgrund der Synchronisierung ausgeführt wird.

Webzugriff für isolierte Plug-Ins (im Sandkasten)

Wenn Sie das Plug-In im Sandkasten registrieren möchten, können Sie trotzdem auf Webadressen vom Plug-In-Code aus zugreifen. Sie können eine beliebige .NET Framework-Klasse im Plug-In-Code verwenden, der Internetzugang innerhalb der Internetzugriffsbeschränkungen, die in Plug-In-Isolation, Vertrauensstellungen und Statistiken erläutert werden, bereitstellt. Der folgende Plug-In-Code lädt beispielsweise eine Webseite herunter.


// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);
System_CAPS_security Sicherheit Hinweis

Damit Sandkasten-Plugins auf externe Webdienste zugreifen können, muss der Server, auf dem die Sandbox Processing Service-Rolle installiert ist, über Internetzugang verfügen, und das Konto, unter dem der Sandkastendienst ausgeführt wird, muss über Internetzugang verfügen. Es sind nur ausgehende Verbindungen über die Ports 80 und 443 erforderlich. Eingehender Verbindungszugriff ist nicht notwendig. Verwenden Sie die Windows-Firewall-Systemsteuerung, um ausgehende Verbindungen für die Microsoft.Crm.Sandbox.WorkerProcess-Anwendung, die sich auf dem Server im Ordner "%PROGRAMFILES%\Microsoft Dynamics 365\Server\bin" befindet, zu ermöglichen.

Verwenden von Typen mit früher Bindung

Wenn Sie Microsoft Dynamics 365-Typen mit früher Bindung im Plug-In-Code verwenden möchten, schließen Sie einfach die Typendatei ein, die mit dem CrmSvcUtil-Programm im Microsoft Visual Studio-Plug-In-Projekt generiert wurde.

Die Konvertierung einer Entität mit später Bindung in eine Entität mit früher Bindung wird folgendermaßen verarbeitet:

Account acct = entity.ToEntity<Account>();

In der vorherigen Codezeile ist die acct-Variable ein Typ mit früher Bindung. Alle IPluginExecutionContext-Werte, die Entity zugewiesen sind, müssen Typen mit später Bindung sein. Wenn ein Typ mit früher Bindung dem Kontext zugewiesen wird, tritt eine SerializationException auf. Weitere Informationen finden Sie unter Nachvollziehen des Datenkontexts, der an einem Plug-In übergeben wird. Stellen Sie sicher, dass Sie nicht die Typen vermischen und einen Typ mit früher Bindung verwenden, wenn ein Typ mit später Bindung, wie im folgenden Code gezeigt, erforderlich ist.

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

Im Beispiel oben sollten Sie keine Instanz mit früher Bindung an der Stelle im Plug-In-Kontext speichern, an der eine Instanz mit später Bindung stehen sollte. Auf diese Weise vermeiden Sie das Konvertieren der Plattform zwischen Typen mit früher und später Bindung vor dem Aufruf eines Plug-Ins und bei der Rückkehr vom Plug-In zur Plattform.

Plug-In-Assemblys

In einer Assembly kann es einen oder mehrere Plug-In-Typen geben. Nachdem die Plug-In-Assembly registriert und bereitgestellt wurde, können Plug-Ins ihren geplanten Vorgang als Reaktion auf ein Microsoft Dynamics 365-Laufzeitereignis ausführen.

System_CAPS_security Sicherheit Hinweis

In Microsoft Dynamics 365 müssen Plug-In-Assemblys für alle lesbar sein, um ordnungsgemäß zu funktionieren. Daher ist es eine bewährte Sicherheitsmethode, Plug-In-Code zu entwickeln, der keine Systemanmeldeinformationen, vertrauliche Informationen oder Unternehmensgeschäftsgeheimnisse enthält.

Jede Plug-In-Assembly muss entweder mithilfe der Registerkarte Signieren des Eigenschaftenblattes des Projekts Microsoft Visual Studio oder Mithilfe des Tools für starke Namen signiert werden, bevor sie auf Microsoft Dynamics 365 registriert und bereitgestellt wird. Weitere Informationen zum Tool für starke Namen erhalten Sie durch Ausführen des Programms "sn.exe" ohne Argumente von einem Microsoft Visual Studio-Eingabeaufforderungsfenster aus.

Wenn Ihre Assembly ein Plug-In enthält, das ausgeführt werden kann, während Dynamics 365 für Outlook offline ist, gibt es zusätzliche Sicherheit, die die Microsoft Dynamics 365-Plattform für Assemblys anwendet. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Assemblysicherheit für ein Offline-Plug-In konfigurieren.

Siehe auch

Plug-In-Entwicklung
Nachvollziehen des Datenkontexts, der an einem Plug-In übergeben wird
Schreiben eines benutzerdefinierten Azure-Plug-Ins
Registrieren und Bereitstellen von Plug-Ins
Behandlung von Ausnahmen in Plug-ins
Beispiel: Erstellen eines grundlegenden Plug-Ins
Beispiel: Webzugriff über ein Sandkasten-Plug-In
Ausführen des Codegenerierungstools
Blog: Verwenden von Plug-Ins zum Ändern von Ansichten

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright