Teilen über

Debuggen Sie ein Plug-In

  • Artikel

 

Veröffentlicht: Januar 2017

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

Im Folgenden wird beschrieben, wie ein Plug-In bei Microsoft Dynamics 365 (lokal) debuggt wird. Um ein Plug-In im Sandkasten zu debuggen, das unter Microsoft Dynamics 365 (online) ausgeführt wird, müssen Sie die Ablaufverfolgung, wie weiter unten in diesem Thema beschrieben, verwenden.

In diesem Thema

Debug a plug-in

Debuggen Sie ein Sandkasten-Plug-In

Protokollierung und Ablaufverfolgung

Debuggen Sie ein Plug-In

  1. Registrieren Sie die Plug-In-Assembly und stellen Sie sie bereit.

    Liegt eine weitere Kopie der Assembly am gleichen Ort vor und kann die Kopie nicht überschrieben werden, da sie von Microsoft Dynamics 365 ausgeführt wird, müssen Sie den Serviceprozess, in dem das Plug-In ausgeführt wurde, neu starten. Informationen zum richtigen Serviceprozess finden Sie in der unten aufgeführten Tabelle.Weitere Informationen: Registrieren und Bereitstellen von Plug-Ins

  2. Konfigurieren Sie den Debugger.

    Fügen Sie den Debugger zum Prozess auf dem Microsoft Dynamics 365-Server an, auf dem das Plug-In ausgeführt wird. Informationen zum Identifizieren des Prozesses finden Sie in der nachfolgenden Tabelle.

    Konfigurieren der Plug-In-Registrierung

    Dienstprozess

    online

    w3wp.exe

    offline

    Microsoft.Crm.Application.Hoster.exe

    asynchrone registrierte Plug-Ins (oder benutzerdefinierte Workflow-Assemblys)

    CrmAsyncService.exe

    Sandkasten (Isolationsmodus)

    Microsoft.Crm.Sandbox.WorkerProcess.exe

    Wird die ausführbare Datei von mehreren Prozessen ausgeführt, z. B. mehreren w3wp.exe-Prozessen, fügen Sie den Debugger an alle Instanzen des ausgeführten ausführbaren Prozesses an. Legen Sie anschließend mindestens einen Haltepunkt in Ihrem Plug-In-Code fest.

  3. Testen Sie das Plug-In.

    Führen Sie die Microsoft Dynamics 365-Anwendung oder eine andere benutzerdefinierte Anwendung, die das SDK verwendet, aus, und führen Sie die Aktion aus, die zum Ausführen des Plug-Ins erforderlich ist. Wenn z. B. ein Plug-In für ein Firmenerstellungsereignis registriert ist, erstellen Sie eine neue Firma.

  4. Debuggen Sie den Plug-In-Code.

    Nehmen Sie alle erforderlichen Änderungen an dem Code vor, damit er wie gewünscht ausgeführt wird. Wenn der Code geändert wird, kompilieren Sie den Code in eine Assembly und wiederholen Sie die Schritte 1 bis 4 dieser Vorgehensweise (falls erforderlich). Wenn Sie die Haupt- oder Nebenversionsnummern der Plug-In-Assembly ändern, müssen Sie die Registrierung der Vorversion der Assembly aufheben und die neue Version registrieren.Weitere Informationen: Registrieren und Bereitstellen von Plug-Ins

  5. Registrieren Sie das Plug-In in der Datenbank.

    Nachdem der Bearbeitungs-/Kompilierungs-/Bereitstellungs-/Test-/Debugzyklus abgeschlossen wurde, heben Sie die Registrierung für die Plug-In-Assembly (auf Datenträger) auf registrieren Sie das Plug-In dann erneut in der Microsoft Dynamics 365-Datenbank.Weitere Informationen: Registrieren und Bereitstellen von Plug-Ins

Tipp

Es ist möglich, ein in der Datenbank bereitgestelltes Plug-In zu debuggen. Die Symboldatei (.pdb) der kompilierten Plug-In-Assembly muss in den Ordner crm-root>\Server\bin\assembly des Servers kopiert werden und Internetinformationsdienste (IIS) muss dann neu gestartet werden. Nachdem das Debuggen abgeschlossen wurde, müssen Sie die Symboldatei entfernen und IIS zurücksetzen, damit der Vorgang, der das Plug-In ausgeführt hat, keinen zusätzlichen Arbeitsspeichers verbraucht.

Weitere Informationen über das Debuggen von Plug-Ins mithilfe eines Plug-In-Profilertools finden Sie unter Analysieren von Plug-In-Leistung.

Debuggen Sie ein Sandkasten-Plug-In

Es ist wichtig, diese Schritte vor der ersten Ausführung eines Sandkasten-Plug-Ins auszuführen. Wenn das Plug-In bereits ausgeführt wurde, ändern Sie entweder den Code der Assembly, sodass sich der Hash der Assembly auf dem Server ändert, oder starten Sie den Microsoft Dynamics 365 Sandbox Processing Service auf dem Sandkastenserver neu.

Konfigurieren Sie den Server

Der Sandkastenhostprozess überwacht den Sandkastenarbeitsprozess, in dem das Plug-In ausgeführt wird. Die Hostprozess überprüft, ob das Plug-In nicht mehr reagiert, Arbeitsspeicherschwellenwerte überschreitet, usw. Wenn der Arbeitsprozess 30 Sekunden nicht reagiert, wird er heruntergefahren. Um ein Sandkasten-Plug-in zu debuggen, müssen Sie diese Herunterfahrfunktion deaktivieren. Um die Herunterfahrfunktion zu deaktivieren, müssen Sie den folgenden Registrierungsschlüssel auf 1 festlegen (DWORD):

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins

Plug-In debuggen

Führen Sie die folgenden Schritte aus, um ein Sandkasten-Plug-in zu debuggen.

  1. Registrieren Sie das Plug-In im Sandkasten (Isolationsmodus) und stellen Sie es für die Microsoft Dynamics 365-Serverdatenbank bereit.

  2. Kopieren Sie die Symboldatei (.pdb) der kompilierten Plug-In-Assembly in den server\bin\assembly-Ordner auf dem Server, auf dem der Sandkastenarbeitsprozess Microsoft.Crm.Sandbox.WorkerProcess.exe ausgeführt wird. Dies ist der Server, auf dem die Sandbox Processing Service-Rolle gehostet wird.

  3. Befolgen Sie die Anweisungen in den Schritten 2 bis 4, die am Anfang dieses Themas gezeigt wurden.

Weitere Informationen über das Debuggen von Plug-Ins mithilfe eines Plug-In-Profilertools finden Sie unter Analysieren von Plug-In-Leistung.

Protokollierung und Ablaufverfolgung

Eine alternative Methode, Probleme bei einem Plug-In oder einer benutzerdefinierten Workflowaktion (benutzerdefinierter Code) zu beheben, verglichen mit Debugging in Microsoft Visual Studio, ist das Verwenden der Ablaufverfolgung. Die Ablaufverfolgung unterstützt Entwickler durch die Aufzeichnung von benutzerdefinierten Informationen zur Laufzeit als Hilfe bei der Ursachendiagnose für Codefehler. Die Ablaufverfolgung ist besonders hilfreich bei der Problembehebung von registriertem benutzerdefiniertem Code von Microsoft Dynamics 365 (online), da dies die einzige unterstützte Problembehebungsmethode für dieses Szenario ist. Ablaufverfolgung wird für Sandkasten- (mit teilweiser Vertrauenswürdigkeit) und registrierten benutzerdefinierten Code mit voller Vertrauenswürdigkeit und beim synchronen oder asynchronen Ausführen unterstützt. Ablaufverfolgung wird nicht unterstützt für benutzerdefinierten Code, der in Microsoft Dynamics 365 für Outlook oder einem anderen Mobil-Client ausgeführt wird.

Die Aufzeichnung von Ablaufverfolgungsinformationen zur Laufzeit für Microsoft Dynamics 365 wird von einem Dienst namens ITracingService bereitgestellt. Die Informationen, die für diesen Dienst durch benutzerdefinierten Code bereitgestellt werden, können an drei verschiedenen Orten erfasst werden, wie hier identifiziert.

  • Ablaufverfolgungsprotokoll

    Ablaufverfolgungsprotokoll-Datensätze vom Typ PluginTraceLog können in der Webanwendung gefunden werden, indem Sie zu Einstellungen navigieren und die Kachel Plug-In-Ablaufverfolgungsprotokoll auswählen. Die Kachel ist nur sichtbar, wenn Sie über Zugriff auf die Ablaufverfolgungsprotokoll-Entitätsdatensätze in Ihrer zugewiesenen Sicherheitsrolle verfügen. Das Schreiben dieser Datensätze wird über die Ablaufverfolgungseinstellungen gesteuert, die im nächsten Abschnitt beschrieben werden. Weitere Informationen zu den erforderlichen Rechten für die PluginTraceLog-Entität finden Sie unter Rechte nach Entität.

    Hinweis

    Die Ablaufverfolgungsprotokollierung erfordert Organisationsspeicherplatz, insbesondere wenn viele Ablaufverfolgungen und Ausnahmen generiert werden. Sie sollten die Ablaufverfolgungsprotokollierung nur für das Debugging und die Problembehandlung aktivieren, und deaktivieren, wenn die Überprüfung abgeschlossen ist.

  • Fehlerdialogfeld

    Ein synchrones registriertes Plug-In oder eine benutzerdefinierte Workflowaktion, die eine Ausnahme an die Plattform zurückgibt, führt zu einem Fehlerdialogfeld in der Webanwendung, die dem angemeldeten Benutzer angezeigt wird. Der Benutzer kann die Schaltfläche Protokolldatei herunterladen im Dialogfeld auswählen, um das Protokoll mit der Ausnahme und der Ablaufverfolgungsausgabe anzuzeigen.

  • Systemauftrag

    Bei asynchronen registrierten Plug-Ins oder benutzerdefinierten Workflowaktionen, die eine Ausnahme zurückgeben, werden die Ablaufverfolgungsinformationen im Bereich Details des Systemauftrag-Formulars in der Webanwendung angezeigt.

Ablaufverfolgungsprotokollierung aktivieren

Um die Ablaufverfolgungsprotokollierung in einer Organisation zu aktivieren, die diese Funktion unterstützt, navigieren Sie in der Webanwendung zu Einstellungen > Verwaltung > Systemeinstellungen. Auf der Registerkarte Anpassung suchen Sie das Dropdownmenü namens Protokollierung in Plug-in-Ablaufverfolgungsprotokoll aktivieren und wählen Sie eine der verfügbaren Optionen aus.

Option

Beschreibung

Aus

Das Schreiben in das Ablaufverfolgungsprotokoll ist deaktiviert. Es werden keine PluginTraceLog-Datensätze erstellt. Allerdings kann benutzerdefinierter Code weiter die Trace-Methode aufrufen, auch wenn noch kein Protokoll geschrieben wurde.

Ausnahmen

Ablaufverfolgungsinformationen werden in das Protokoll geschrieben, wenn eine Ausnahme wieder an die Plattform von benutzerdefiniertem Code zurückgegeben wird.

Alle

Ablaufverfolgungsinformationen werden bei Fertigstellung von Code in das Protokoll geschrieben, oder wenn eine Ausnahme wieder an die Plattform von benutzerdefiniertem Code zurückgegeben wird.

Wenn die Ablaufverfolgungsprotokollierungs-Einstellung auf Ausnahme gesetzt ist und benutzerdefinierter Code eine Ausnahme wieder zur Plattform zurückgibt, wird ein Ablaufverfolgungsprotokolldatensatz erstellt und Ablaufverfolgungsinformationen werden zudem an einen anderen Ort geschrieben. Bei benutzerdefiniertem Code, der synchron ausgeführt wird, werden die Informationen in einem Fehlerdialogfeld dem Benutzer angezeigt; andernfalls, für asynchronen Code, werden die Informationen in den verknüpften Systemauftrag geschrieben.

Standardmäßig weisen die Rollen "Systemadministrator" und "Systemanpasser" die erforderlichen Berechtigungen auf, um die Ablaufverfolgungsprotokollierungs-Einstellung zu ändern, die in einem TraceSettings-Entitätsdatensatz gespeichert wird. Ablaufverfolgungseinstellungen haben einen Organisationsbereich.

Schreiben in den Ablaufverfolgungsdienst

Bevor Sie in den Ablaufverfolgungsdienst schreiben, müssen Sie erst das Ablaufverfolgungsdienstobjekt aus dem übergebenen Ausführungskontext extrahieren. Danach fügen Sie ggf. einfach Trace-Aufrufe benutzerdefiniertem Code hinzu, wobei alle relevanten Diagnoseinformationen in diesem Methodenaufruf übergeben werden.


//Extract the tracing service for use in debugging sandboxed plug-ins.
ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

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

// For this sample, execute the plug-in code only while the client is online. 
tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");
if (context.IsExecutingOffline || context.IsOfflinePlayback)
    return;

// 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.
    tracingService.Trace
        ("AdvancedPlugin: Getting the target entity from Input Parameters.");
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the image entity from the Pre Entity Images.
    tracingService.Trace
        ("AdvancedPlugin: Getting image entity from PreEntityImages.");
    Entity image = (Entity)context.PreEntityImages["Target"];

Entwickeln Sie anschließend das Plug-In oder die benutzerdefinierte Workflowaktion und stellen Sie diese(s) bereit. Während der Ausführung von benutzerdefiniertem Code wird die Information, die in den Trace-Methodenaufrufen bereitgestellt wird, in einen Ablaufverfolgungsprotokoll-Entitätsdatensatz von ITracingService geschrieben, wenn dies von Ihrer Organisation unterstützt wird und aktiviert ist, und kann auch dem Benutzer in einem Web-Dialog oder Systemauftrag bereitgestellt werden, wie im vorherigen Abschnitt beschrieben. Die Ablaufverfolgungsinformationen, die in das Ablaufverfolgungsprotokoll geschrieben werden, werden in den Ablaufverfolgungseinstellungen konfiguriert. Weitere Informationen finden Sie unter Ablaufverfolgungsprotokollierung aktivieren.

Hinweis

Wenn benutzerdefinierter Code in einer Datenbanktransaktion ausgeführt wird und eine Ausnahme auftritt, die ein Transaktionsrollback verursacht, werden alle Entitätsdatenänderungen durch Code rückgängig gemacht. Die PluginTraceLog-Datensätze bleiben jedoch bis zum Fertigstellen des Rollbacks vorhanden.

Informationen zum Ablaufverfolgungsdienst

ITracingService verarbeitet stapelweise die Informationen, die dafür über die Trace-Methode bereitgestellt werden. Die Informationen werden in einen neuen PluginTraceLog-Datensatz geschrieben, wenn benutzerdefinierter Code erfolgreich zum Abschluss ausgeführt oder eine Ausnahme ausgelöst wurde.

PluginTraceLog-Datensätze haben eine begrenzte Gültigkeitsdauer. Ein Massenlöschungs-Hintergrundauftrag wird einmal täglich ausgeführt, um Datensätze zu löschen, die älter als 24 Stunden seit der Erstellung sind. Dieser Auftrag kann bei Bedarf deaktiviert werden.

Siehe auch

Plug-In-Entwicklung
Analysieren von Plug-In-Leistung
Registrieren und Bereitstellen von Plug-Ins
Ereignisausführungspipeline
Schreiben eines Plug-Ins
Plug-In-Isolation, Vertrauensstellungen und Statistiken
PluginTraceLog-Entitätsmeldungen und -methoden

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright