Debuggen von Office-Add-Ins in Visual Studio

  • Artikel

In diesem Artikel wird beschrieben, wie Sie clientseitigen Code in Office-Add-Ins debuggen, die mit einer der Office-Add-In-Projektvorlagen in Visual Studio 2022 erstellt werden. Informationen zum Debuggen von serverseitigem Code in Office-Add-Ins finden Sie unter Übersicht über das Debuggen von Office-Add-Ins – server- oder clientseitig?.

Hinweis

Sie können Visual Studio nicht zum Debuggen von Add-Ins in Office für Mac verwenden. Informationen zum Debuggen auf einem Mac finden Sie unter Debuggen von Office-Add-Ins auf einem Mac.

Überprüfen der Build- und Debugging-Eigenschaften

Bevor Sie mit dem Debuggen beginnen, überprüfen Sie die Eigenschaften der einzelnen Projekte, um sicherzustellen, dass Visual Studio die gewünschte Office-Anwendung öffnet und dass andere Build- und Debugeigenschaften entsprechend festgelegt sind.

Eigenschaften des Add-In-Projekts

Öffnen Sie das Fenster Eigenschaften für das Add-In-Projekt, um die Projekteigenschaften zu überprüfen.

  1. Wählen Sie im Projektmappen-Explorer das Add-In-Projekt (nicht das Webanwendungsprojekt) aus.

  2. Wählen Sie auf der Menüleiste Ansicht>Eigenschaftenfenster aus.

In der folgenden Tabelle werden die Eigenschaften des Add-In-Projekts beschrieben:

Eigenschaft Beschreibung
Startaktion Gibt den Debugmodus für Ihr Add-In an. Dies sollte auf Office Desktop Client festgelegt werden, wenn Sie in Microsoft 365 unter Windows debuggen möchten. Zum Debuggen in Microsoft 365 im Web sollte es auf Microsoft Edge festgelegt werden.
Startdokument
(nur Excel-, PowerPoint- und Word-Add-Ins)		 Gibt an, welches Dokument beim Starten des Projekts geöffnet werden soll. In einem neuen Projekt ist dies auf [Neue Excel-Arbeitsmappe], [Neues Word Dokument] oder [Neue PowerPoint-Präsentation] festgelegt. Um ein bestimmtes Dokument anzugeben, führen Sie die Schritte unter Verwenden eines vorhandenen Dokuments zum Debuggen des Add-Ins aus.
Webprojekt Gibt den Namen des Webprojekts an, das dem Add-In zugeordnet ist.
E-Mail-Adresse
(nur Outlook-Add-Ins)		 Gibt die E-Mail-Adresse des Benutzerkontos in Exchange Server oder Exchange Online an, mit dem Sie Ihr Outlook-Add-In testen möchten. Wenn sie leer gelassen wird, werden Sie beim Debuggen zur Eingabe der E-Mail-Adresse aufgefordert.
EWS-URL
(nur Outlook-Add-Ins)		 Gibt die Exchange-Webdienst-URL an (Beispiel: https://www.contoso.com/ews/exchange.aspx). Diese Eigenschaft kann leer gelassen werden.
OWA-URL
(nur Outlook-Add-Ins)		 Gibt die Outlook im Web-URL an (Beispiel: https://www.contoso.com/owa). Diese Eigenschaft kann leer gelassen werden.
Mehrstufige Authentifizierung verwenden
(nur Outlook-Add-Ins)		 Gibt den booleschen Wert an, der angibt, ob die mehrstufige Authentifizierung verwendet werden soll. Der Standardwert ist false, aber die Eigenschaft hat keine praktischen Auswirkungen. Wenn Sie normalerweise einen zweiten Faktor angeben müssen, um sich beim E-Mail-Konto anzumelden, werden Sie beim Debuggen dazu aufgefordert.
Benutzername
(nur Outlook-Add-Ins)		 Gibt den Namen des Benutzerkontos in Exchange Server oder Exchange Online an, mit dem Sie Ihr Outlook-Add-In testen möchten. Diese Eigenschaft kann leer gelassen werden.
Projektdatei Gibt den Namen der Datei mit den Build-, Konfigurations- und anderen Informationen zum Projekt an.
Projektordner Gibt den Speicherort der Projektdatei an.
Konfiguration der aktiven Bereitstellung
(nur beim Debuggen von Excel vorhanden,
PowerPoint oder Word im Web)		 Gibt die Bereitstellungskonfiguration an. Dies sollte auf Standard festgelegt werden.
Serververbindung
(nur beim Debuggen von Excel vorhanden,
PowerPoint oder Word im Web)		 Gibt an, ob das Projekt eine Verbindung mit dem SharePoint-Dienst herstellt, der in der Eigenschaft Website-URL angegeben ist. Dies sollte auf Online festgelegt werden.
Website-URL
(nur beim Debuggen von Excel vorhanden,
PowerPoint oder Word im Web)		 Gibt die vollständige, absolute URL des SharePoint-Mandanten an, den Sie beim Debuggen hosten möchten. Zum Beispiel https://mysite.sharepoint.com/

Hinweis

Für ein Outlook-Add-In können Sie werte für eine oder mehrere der Eigenschaften nur für Outlook-Add-Ins im Fenster Eigenschaften angeben, aber dies ist nicht erforderlich.

Eigenschaften des Webanwendungsprojekts

Öffnen Sie das Fenster Eigenschaften für das Webanwendungsprojekt, um die Projekteigenschaften zu überprüfen.

  1. Wählen Sie Projektmappen-Explorer das Webanwendungsprojekt aus.

  2. Wählen Sie auf der Menüleiste Ansicht>Eigenschaftenfenster aus.

In der folgenden Tabelle werden die Eigenschaften des Webanwendungsprojekts beschrieben, die für Office-Add-In-Projekte besonders relevant sind:

Eigenschaft Beschreibung
SSL-fähig Gibt an, ob SSL für die Website aktiviert ist. Diese Eigenschaft sollte bei Office-Add-In-Projekten auf True festgelegt sein.
SSL-URL Gibt die sichere HTTPS-URL für die Website an. Schreibgeschützt.
URL Gibt die HTTP-URL für die Website an. Schreibgeschützt.
Projektdatei Gibt den Namen der Datei mit den Build-, Konfigurations- und anderen Informationen zum Projekt an.
Projektordner Gibt den Speicherort der Projektdatei an. Schreibgeschützt. Die Manifestdatei, die Visual Studio zur Laufzeit generiert, wird an diesem Speicherort in den Ordner bin\Debug\OfficeAppManifests geschrieben.

Debuggen eines Add-In-Projekts auf dem Windows-Desktop

In diesem Abschnitt wird beschrieben, wie Sie ein Add-In in Office unter Windows desktop starten und debuggen. Das heißt, wenn die Startaktion-Eigenschaft des Add-In-Projekts auf Office-Desktopclient festgelegt ist.

Starten des Add-In-Projekts

Starten Sie das Projekt, indem Sie in der Menüleiste Debuggen>Debuggen starten auswählen oder F5 drücken. Visual Studio erstellt automatisch die Projektmappe und startet die Office-Hostanwendung.

Wenn Visual Studio das Projekt erstellt, führt es die folgenden Aufgaben aus:

  1. Erstellt eine Kopie der XML-Manifestdatei und fügt sie dem _ProjectName_\bin\Debug\OfficeAppManifests Verzeichnis hinzu. Die Office-Anwendung, die Ihr Add-In hostet, nutzt diese Kopie, wenn Sie Visual Studio starten und das Add-In debuggen.

  2. Erstellt eine Reihe von Registrierungseinträgen auf Ihrem Windows-Computer, mit denen das Add-In in der Office-Anwendung angezeigt werden kann.

  3. Erstellt das Webanwendungsprojekt und stellt es dann auf dem lokalen IIS-Webserver (https://localhost) bereit.

  4. Wenn dies das erste Add-In-Projekt ist, das Sie auf dem lokalen IIS-Webserver bereitgestellt haben, werden Sie möglicherweise aufgefordert, ein Self-Signed-Zertifikat im Speicher für vertrauenswürdige Stammzertifikate des aktuellen Benutzers zu installieren. Dies ist erforderlich, damit IIS Express den Inhalt Ihres Add-Ins richtig anzeigt.

Hinweis

Wenn Office das Edge Legacy-Webview-Steuerelement (EdgeHTML) verwendet, um Add-Ins auf Ihrem Windows-Computer auszuführen, werden Sie von Visual Studio möglicherweise aufgefordert, eine Lokale Netzwerk-Loopbackausnahme hinzuzufügen. Dies ist erforderlich, damit das Webview-Steuerelement auf die Website zugreifen kann, die auf dem lokalen IIS-Webserver bereitgestellt wird. Sie können diese Einstellung auch jederzeit in Visual Studio unter Tools>Optionen>Office-Tools (Web)>Debuggen von Web-Add-In ändern. Informationen dazu, welches Webview-Steuerelement auf Ihrem Windows-Computer verwendet wird, finden Sie unter Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden.

Danach führt Visual Studio folgende Aktionen aus:

  1. Ändert das SourceLocation-Element der XML-Manifestdatei (die in das _ProjectName_\bin\Debug\OfficeAppManifests Verzeichnis kopiert wurde), indem das ~remoteAppUrl Token durch die vollqualifizierte Adresse der Startseite ersetzt wird (z. B https://localhost:44302/Home.html. ).

  2. Das Webanwendungsprojekt wird in IIS Express gestartet.

  3. Überprüft das Manifest.

    Wichtig

    Wenn Sie Validierungsfehler für das Manifest erhalten, kann es sein, dass die Manifestschemadateien von Visual Studio nicht aktualisiert wurden, um die neuesten Features zu unterstützen. Der erste Schritt zur Problembehandlung sollte darin sein, eine oder mehrere dieser Dateien durch die neuesten Versionen zu ersetzen. Ausführliche Anweisungen finden Sie unter Manifestschemaüberprüfungsfehler in Visual Studio-Projekten.

  4. Öffnet die Office-Anwendung und überlädt das Add-In quer.

Debuggen des Add-Ins

Die beste Methode zum Debuggen eines Add-Ins in Visual Studio 2022 hängt davon ab, ob das Add-In in WebView2 ausgeführt wird, bei dem es sich um das Webview-Steuerelement handelt, das Microsoft Edge (Chromium) zugeordnet ist, oder ein älteres Webview-Steuerelement. Informationen dazu, welches Webview-Steuerelement verwendet wird, finden Sie unter Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden. Wenn Ihr Computer WebView2 verwendet, lesen Sie Verwenden des integrierten Visual Studio-Debuggers zum Debuggen auf dem Desktop. Informationen zu anderen Webview-Steuerelementen finden Sie unter Verwenden der Browserentwicklertools zum Debuggen auf dem Desktop.

Verwenden des integrierten Visual Studio-Debuggers zum Debuggen auf dem Desktop

  1. Legen Sie nach Bedarf Haltepunkte in den JavaScript- oder TypeScript-Quelldateien fest. Sie können dies entweder vor oder nach dem Starten des Add-Ins tun, wie im vorherigen Abschnitt Starten des Add-In-Projekts beschrieben. Wenn das Festlegen eines Haltepunkts dazu führt, dass der IIS-Server (Internetinformationsdienste) heruntergefahren wird, starten Sie das Debuggen neu, nachdem Sie Ihre Haltepunkte festgelegt haben.

  2. Wenn das Add-In ausgeführt wird, verwenden Sie die Benutzeroberfläche des Add-Ins, um den Code auszuführen, der Ihre Haltepunkte enthält.

Wichtig

Haltepunkte, die in Office.initialize festgelegt sind oder Office.onReady nicht erreicht werden. Informationen zum Debuggen dieser Methoden finden Sie unter Debuggen der Funktionen initialize und onReady.

Tipp

Wenn Probleme auftreten, finden Sie weitere Informationen unter Debuggen einer JavaScript- oder TypeScript-App in Visual Studio.

Verwenden der Browserentwicklertools zum Debuggen auf dem Desktop

  1. Führen Sie die Schritte im vorherigen Abschnitt Starten des Add-In-Projekts aus.

  2. Starten Sie das Add-In in der Office-Anwendung, falls es noch nicht geöffnet ist. Wenn es sich beispielsweise um ein Aufgabenbereich-Add-In handelt, wurde dem Menüband Start eine Schaltfläche hinzugefügt (z. B. eine Schaltfläche Aufgabenbereich anzeigen ). Wählen Sie die Schaltfläche im Menüband aus.

    Hinweis

    Wenn Ihr Add-In nicht von Visual Studio quergeladen wird, können Sie es manuell querladen. Befolgen Sie die Anweisungen zum Querladen eines Office-Add-Ins zum Testen für Ihre Plattform.

    Navigieren Sie in der Liste mit den verfügbaren Add-Ins zum Abschnitt Entwickler-Add-Ins, und wählen Sie Ihr Add-In aus, um es zu registrieren.

    Tipp

    Der Aufgabenbereich wird beim ersten Öffnen möglicherweise leer angezeigt. Wenn ja, sollte es ordnungsgemäß gerendert werden, wenn Sie die Debugtools in einem späteren Schritt starten.

  3. Öffnen Sie das Persönlichkeitsmenü , und wählen Sie dann Debugger anfügen aus. Dadurch werden die Debugtools für das Webview-Steuerelement geöffnet, das Office zum Ausführen von Add-Ins auf Ihrem Windows-Computer verwendet. Sie können Breakpoints festlegen und Code schrittweise durchlaufen, wie in einem der folgenden Artikel beschrieben:

  4. Um Änderungen am Code vorzunehmen, beenden Sie zuerst die Debugsitzung in Visual Studio, und schließen Sie die Office-Anwendung. Nehmen Sie Ihre Änderungen vor, und starten Sie eine neue Debugsitzung.

Debuggen eines Add-In-Projekts in Microsoft 365 im Web

In diesem Abschnitt wird beschrieben, wie Sie ein Add-In in Desktop-Office im Web starten und debuggen, d. h. wenn die Startaktionseigenschaft des Add-In-Projekts auf Microsoft Edge festgelegt ist.

Starten des Add-In-Projekts im Web

Starten Sie das Projekt, indem Sie in der Menüleiste Debuggen>Debuggen starten auswählen oder F5 drücken. Visual Studio erstellt die Projektmappe automatisch und startet die Seite mit dem Office-Anwendungshost Ihres Microsoft 365-Mandanten.

Hinweis

Wenn Sie ein Add-In im Web debuggen, erhalten Sie möglicherweise einen AADSTS50011 Fehler ähnlich dem folgenden:

"Der in der Anforderung angegebene Umleitungs-URI {Full absolute URL to add-in home page} stimmt nicht mit den für die Anwendung konfigurierten Umleitungs-URIs überein... "

Dies liegt daran, dass es bis zu 24 Stunden dauern kann, bis neue Webanwendungen, die in SharePoint bereitgestellt werden, verfügbar sind. Führen Sie die folgenden Schritte aus, damit Ihr Add-In sofort debugbar ist:

  1. Beenden Sie das Debuggen in Visual Studio.

  2. Erstellen Sie ein PowerShell-Skript mit den folgenden Zeilen. Ersetzen Sie den Platzhalter {Full absolute URL to add-in home page} in der Fehlermeldung durch die Umleitungs-URL, z. B. "https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx".

    Connect-MgGraph -Scopes Application.ReadWrite.All
$sharepointPrincipal = Get-MgServiceprincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'"
$sharepointPrincipal | fl
$replyUrls = $sharepointPrincipal.ReplyUrls
$replyUrls += "{Full absolute URL to add-in home page}"
Update-MgServiceprincipal -ServicePrincipalId $sharepointPrincipal.Id -ReplyUrls $replyUrls

  3. Führen Sie das Skript in PowerShell aus.

  4. Starten Sie das Projekt neu, indem Sie in der Menüleiste Debuggen>Debuggen starten auswählen oder F5 drücken.

Wenn Visual Studio das Projekt erstellt, führt es die folgenden Aufgaben aus.

  1. Fordert Sie zur Eingabe von Anmeldeinformationen auf. Wenn Sie wiederholt zur Anmeldung aufgefordert werden oder eine Fehlermeldung angezeigt wird, dass Sie nicht autorisiert sind, ist die Standardauthentifizierung möglicherweise für Konten in Ihrem Microsoft 365-Mandanten deaktiviert. Verwenden Sie in diesem Fall ein Microsoft-Konto. Sie können auch versuchen, die Eigenschaft Mehrstufige Authentifizierung verwenden im Add-In-Projekteigenschaftenbereich auf True festzulegen. Weitere Informationen finden Sie unter Add-In-Projekteigenschaften.

  2. Erstellt eine Kopie der XML-Manifestdatei und fügt sie dem _ProjectName_\bin\Debug\OfficeAppManifests Verzeichnis hinzu. Microsoft 365 nutzt diese Kopie, wenn Sie Visual Studio starten und das Add-In debuggen.

  3. Erstellt das Webanwendungsprojekt und stellt es dann im Microsoft 365-Mandanten bereit.

Danach führt Visual Studio folgende Aktionen aus:

  1. Ändert das SourceLocation-Element der XML-Manifestdatei (die in das _ProjectName_\bin\Debug\OfficeAppManifests Verzeichnis kopiert wurde), indem das ~remoteAppUrl Token durch die vollqualifizierte Adresse der Startseite ersetzt wird (z. B https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx. ).

  2. Startet das Webanwendungsprojekt.

  3. Überprüft das Manifest.

    Wichtig

    Wenn Sie Validierungsfehler für das Manifest erhalten, kann es sein, dass die Manifestschemadateien von Visual Studio nicht aktualisiert wurden, um die neuesten Features zu unterstützen. Der erste Schritt zur Problembehandlung sollte darin sein, eine oder mehrere dieser Dateien durch die neuesten Versionen zu ersetzen. Ausführliche Anweisungen finden Sie unter Manifestschemaüberprüfungsfehler in Visual Studio-Projekten.

  4. Öffnet die Seite "Office-Anwendungshost" Ihres Microsoft 365-Mandanten in Microsoft Edge.

Debuggen des Add-Ins im Web

Die beste Methode zum Debuggen eines Add-Ins in Visual Studio 2022 hängt davon ab, ob das Add-In in WebView2 ausgeführt wird, bei dem es sich um das Webview-Steuerelement handelt, das Microsoft Edge (Chromium) zugeordnet ist, oder ein älteres Webview-Steuerelement. Informationen dazu, welches Webview-Steuerelement verwendet wird, finden Sie unter Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden. Wenn Ihr Computer WebView2 verwendet, lesen Sie Verwenden des integrierten Visual Studio-Debuggers zum Debuggen im Web. Informationen zu anderen Webansichtssteuerelementen finden Sie unter Verwenden der Browserentwicklertools zum Debuggen im Web.

Verwenden des integrierten Visual Studio-Debuggers zum Debuggen im Web

  1. Legen Sie nach Bedarf Haltepunkte in den JavaScript- oder TypeScript-Quelldateien fest. Sie können dies entweder vor oder nach dem Starten des Add-Ins tun, wie im vorherigen Abschnitt Starten des Add-In-Projekts im Web beschrieben.

  2. Wenn das Add-In ausgeführt wird, verwenden Sie die Benutzeroberfläche des Add-Ins, um den Code auszuführen, der Ihre Haltepunkte enthält.

Tipp

  • Manchmal wird in Outlook im Web der Visual Studio-Debugger nicht angefügt. Wenn Sie Fehler durch die Haltepunkte erhalten, die darauf hindeuten, dass sie nicht erreicht werden, verwenden Sie die Browserentwicklertools, um an den Visual Studio-Debugger anzufügen: Nachdem Sie F5 gedrückt haben, um das Debuggen zu starten und Outlook im Web geöffnet hat, führen Sie die ersten vier Schritte unter Verwenden der Browser-Entwicklertools zum Debuggen im Web aus. (Befolgen Sie die Anweisungen für Microsoft Edge (Chromium-basiert).) Nachdem Sie einen Haltepunkt in den Browsertools festgelegt und erreicht haben, wird die Ausführung am Haltepunkt sowohl in den Browsertoolsals auch in Visual Studio angehalten. Dies gibt an, dass der Visual Studio-Debugger angefügt ist. An diesem Punkt können Sie die Browsertools schließen und wie gewohnt Breakpoints in Visual Studio hinzufügen.
  • Wenn Probleme auftreten, finden Sie weitere Informationen unter Debuggen einer JavaScript- oder TypeScript-App in Visual Studio.

Verwenden der Browserentwicklertools zum Debuggen im Web

  1. Drücken Sie für ein Add-In in einem beliebigen Host mit Ausnahme von Outlook auf der Seite der Office-Hostanwendung F12, um das Debugtool zu öffnen.

  2. Wenn das Manifest des Add-Ins für ein Outlook-Add-In für eine Leseoberfläche konfiguriert ist, wählen Sie eine E-Mail-Nachricht oder ein Terminelement aus, um es in einem eigenen Fenster zu öffnen. Wenn das Add-In nur für eine Erstelloberfläche konfiguriert ist, öffnen Sie eine neue Nachricht, beantworten Sie eine Nachricht oder ein neues Terminfenster. Stellen Sie sicher, dass das entsprechende Fenster den Fokus hat, und drücken Sie F12, um das Debugtool einzugeben.

  3. Nachdem das Tool geöffnet ist, starten Sie das Add-In. Die genauen Schritte variieren je nach Entwurf Ihres Add-Ins. In der Regel drücken Sie eine Schaltfläche, um einen Aufgabenbereich zu öffnen. Wählen Sie in Outlook auf der Symbolleiste am oberen Rand des Fensters die Schaltfläche Weitere Apps aus, und wählen Sie dann Ihr Add-In aus der sich öffnenden Legende aus.

    Die Schaltfläche Weitere Apps und die Beschriftung, die mit dem Namen und dem Symbol des Add-Ins zusammen mit anderen App-Symbolen geöffnet wird.

  4. Verwenden Sie die Anweisungen in einem der folgenden Artikel, um Haltepunkte festzulegen und Code schrittweise zu durchlaufen. Sie verfügen jeweils über einen Link zu detaillierteren Anleitungen.

    Tipp

    Um Code zu debuggen, der in der Office.initialize Funktion oder einer Office.onReady Funktion ausgeführt wird, die ausgeführt wird, wenn das Add-In geöffnet wird, legen Sie Ihre Haltepunkte fest, und schließen Sie das Add-In und öffnen Sie es erneut. Weitere Informationen zu diesen Funktionen finden Sie unter Initialisieren Ihres Office-Add-Ins.

  5. Um Änderungen am Code vorzunehmen, beenden Sie zunächst die Debugsitzung in Visual Studio, und schließen Sie die Outlook-Seiten. Nehmen Sie Ihre Änderungen vor, und starten Sie eine neue Debugsitzung.

Debuggen des Add-Ins unter Verwendung eines vorhandenen Dokuments

Wenn Sie über ein Dokument mit Testdaten verfügen, die Sie beim Debuggen Ihres Excel-, PowerPoint- oder Word-Add-Ins verwenden möchten, kann Visual Studio so konfiguriert werden, dass das Dokument beim Start des Projekts geöffnet wird. Gehen Sie wie folgt vor, um ein vorhandenes Dokument anzugeben, das beim Debuggen des Add-Ins verwendet werden soll:

  1. Wählen Sie im Projektmappen-Explorer das Add-In-Projekt (nicht das Webanwendungsprojekt) aus.

  2. Wählen Sie auf der Menüleiste Projekt>Vorhandenen Element hinzufügen aus.

  3. Wählen Sie im Dialogfeld Vorhandenes Element hinzufügen das Dokument aus, das Sie hinzufügen möchten.

  4. Wählen Sie die Schaltfläche Hinzufügen aus, um das Dokument zu Ihrem Projekt hinzuzufügen.

  5. Wählen Sie im Projektmappen-Explorer das Add-In-Projekt (nicht das Webanwendungsprojekt) aus.

  6. Wählen Sie auf der Menüleiste Ansicht>Eigenschaftenfenster aus.

  7. Wählen Sie im Fenster Eigenschaften die Liste Startdokument und anschließend das Dokument aus, das Sie dem Projekt hinzugefügt haben. Das Projekt ist jetzt so konfiguriert, dass das Add-In mit diesem Dokument gestartet wird.

Nächste Schritte

Wenn Ihr Add-In ordnungsgemäß funktioniert, lesen Sie Bereitstellen und Veröffentlichen Ihres Office-Add-Ins, um zu erfahren, wie Sie das Add-In an Benutzer verteilen können.