Debuggen des Add-Ins mit Laufzeitprotokollierung

  • Artikel

Sie können die Laufzeitprotokollierung zum Debuggen des Manifests Ihres Add-Ins und verschiedener Installationsfehler verwenden. Mit dieser Funktion können Sie Fehler mit Ihrem Manifest, die von der XSD-Schemaüberprüfung nicht erkannt wurden, identifizieren und beheben, beispielsweise ein Konflikt zwischen den Ressourcen-IDs. Die Laufzeitprotokollierung ist besonders nützlich für das Debuggen von Add-Ins, die Add-In-Befehle und benutzerdefinierte Excel-Funktionen implementieren.

Hinweis

Die Laufzeitprotokollierungsfunktion ist derzeit für Office 2016 oder höher auf dem Desktop verfügbar.

Wichtig

Protokollierung zur Laufzeit wirkt sich auf die Leistung aus. Aktivieren Sie sie nur zum Debuggen von Problemen mit Ihrem Add-In-Manifest.

Verwenden der Protokollierung zur Laufzeit über die Befehlszeile

Das Aktivieren der Protokollierung zur Laufzeit über die Befehlszeile ist die schnellste Möglichkeit, dieses Protokollierungstool zu verwenden. Dabei wird NPX verwendet, das standardmäßig als Bestandteil von NPM@5.2.0 + bereitgestellt wird. Wenn Sie über eine frühere Version von NPM verfügen, sehen Sie sich die Anweisungen unter Protokollierung zur Laufzeit unter Windows oder Protokollierung zur Laufzeit unter Mac oder Installieren von NPX an.

Wichtig

Das Tool office-addin-dev-settings wird unter Mac nicht unterstützt.

  • Aktivieren der Protokollierung zur Laufzeit:

    npx office-addin-dev-settings runtime-log --enable

  • Wenn Sie die Protokollierung zur Laufzeit nur für eine bestimmte Datei aktivieren möchten, verwenden Sie denselben Befehl mit einem Dateinamen:

    npx office-addin-dev-settings runtime-log --enable [filename.txt]

  • Deaktivieren der Protokollierung zur Laufzeit:

    npx office-addin-dev-settings runtime-log --disable

  • So zeigen Sie an, ob die Protokollierung zur Laufzeit aktiviert ist:

    npx office-addin-dev-settings runtime-log

  • So zeigen Sie die Hilfe in der Befehlszeile für die Protokollierung zur Laufzeit an:

    npx office-addin-dev-settings runtime-log --help

Protokollierung zur Laufzeit unter Windows

  1. Stellen Sie sicher, dass Sie Office 2016 Desktop mit Build 16.0.7019 oder höher verwenden.

  2. Fügen Sie den Registrierungsschlüssel RuntimeLogging unter HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\Developer\ hinzu.

    Hinweis

    Wenn der Developer Schlüssel (Ordner) noch nicht unter HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\vorhanden ist, führen Sie die folgenden Schritte aus, um ihn zu erstellen.

    1. Klicken Sie mit der rechten Maustaste auf den WEF-Schlüssel (Ordner), und wählen Sie Neuer>Schlüsselaus.
    2. Nennen Sie den neuen Schlüssel Entwickler.

  3. Legen Sie den Standardwert für den RuntimeLogging-Schlüssel auf den vollständigen Pfad der Datei fest, in die das Protokoll geschrieben werden soll. Im folgenden Beispiel, das in einer .reg Datei ausgeführt wird, wird die Protokollierung auf den C:\ClientLogs\log.txt Ordner festgelegt.

    [HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\RuntimeLogging]
@="C:\\ClientLogs\\log.txt"`

    Hinweis

    Das Verzeichnis, in das die Protokolldatei geschrieben wird, muss bereits vorhanden sein, und Sie benötigen Schreibberechtigungen dafür.

Die folgende Abbildung zeigt, wie die Registrierung aussehen sollte. Entfernen Sie zum Deaktivieren der Funktion den RuntimeLogging-Schlüssel aus der Registrierung.

Der Registrierungs-Editor mit einem RuntimeLogging-Registrierungsschlüssel.

Protokollierung zur Laufzeit unter Mac

  1. Stellen Sie sicher, dass Sie Office 2016-Desktopbuild 16.27.19071500 oder höher ausführen.

  2. Öffnen Sie Terminal, und legen Sie mithilfe des defaults-Befehls eine Einstellung für die Protokollierung zur Laufzeit fest:

    defaults write <bundle id> CEFRuntimeLoggingFile -string <file_name>

    <bundle id> identifiziert den Host, für den die Protokollierung zur Laufzeit aktiviert werden soll. <file_name> gibt den Namen der Textdatei an, in die das Protokoll geschrieben wird.

    Legen Sie <bundle id> auf einen der folgenden Werte fest, um die Laufzeitprotokollierung für die entsprechende Anwendung zu aktivieren.

    • com.microsoft.Word
    • com.microsoft.Excel
    • com.microsoft.Powerpoint
    • com.microsoft.Outlook

Im folgenden Beispiel wird die Laufzeitprotokollierung für Word aktiviert und dann die Protokolldatei geöffnet.

defaults write com.microsoft.Word CEFRuntimeLoggingFile -string "runtime_logs.txt"
open ~/library/Containers/com.microsoft.Word/Data/runtime_logs.txt

Hinweis

Sie müssen Office nach dem Ausführen des defaults-Befehls zum Aktivieren der Protokollierung zur Laufzeit neu starten.

Verwenden Sie den Befehl defaults delete, um die Lauf Protokollierung zur Laufzeit zu deaktivieren:

defaults delete <bundle id> CEFRuntimeLoggingFile

Im folgenden Beispiel wird die Laufzeitprotokollierung für Word deaktiviert.

defaults delete com.microsoft.Word CEFRuntimeLoggingFile

Verwenden der Laufzeitprotokollierung für die Behebung von Problemen mit dem Manifest

So verwenden Sie die Protokollierung zur Laufzeit für die Behebung von Problemen beim Laden eines Add-Ins:

  1. Laden Sie das Add-In zu Testzwecken quer.

    Hinweis

    Es wird empfohlen, nur das Add-In querzuladen, das Sie Testen, um die Anzahl der Nachrichten in der Protokolldatei zu minimieren.

  2. Wenn nichts geschieht und das Add-In nicht angezeigt wird (und nicht im Dialogfeld „Add-Ins“ erscheint), öffnen Sie die Protokolldatei.

  3. Suchen Sie in der Protokolldatei nach der ID Ihres Add-Ins, die Sie in Ihrem Manifest definiert haben. In der Protokolldatei heißt diese ID SolutionId.

Bekannte Probleme mit der Protokollierung zur Laufzeit

In der Protokolldatei sind möglicherweise Meldungen enthalten, die verwirrend oder nicht korrekt eingestuft sind. Beispiel:

  • Die Meldung Medium Current host not in add-in's host list gefolgt von Unexpected Parsed manifest targeting different host wird fälschlicherweise als Fehler behandelt.

  • Wenn die Meldung Unexpected Add-in is missing required manifest fields DisplayName ohne SolutionId angezeigt wird, steht dieser Fehler wahrscheinlich in keinem Bezug zu dem Add-In, das Sie debuggen.

  • Alle Monitorable Meldungen sind aus Systemsicht erwartete Fehler. Manchmal weisen sie auf ein Problem mit Ihrem Manifest hin, z. B. ein falsch geschriebenes Element, das übersprungen wurde, aber nicht dazu führte, dass das Manifest fehlschlägt.

Siehe auch