Konvertieren eines Add-Ins zur Verwendung des einheitlichen Manifests für Microsoft 365 (Vorschau)

  • Artikel

Um Teams-Funktionen zu einem Add-In hinzuzufügen, das das XML-Manifest verwendet, oder um das Add-In nur zukunftssicher zu machen, müssen Sie es konvertieren, um es für die Verwendung des einheitlichen Manifests für Microsoft 365 zu verwenden.

Es gibt drei grundlegende Aufgaben zum Konvertieren eines Add-In-Projekts aus dem XML-Manifest in das einheitliche Manifest.

  • Stellen Sie sicher, dass Bilddateien mit 64 x 64 Pixeln und 128 x 128 Pixeln als Symbole für das Add-In verwendet werden.
  • Konvertieren Sie das XML-Manifest selbst in das JSON-Format des einheitlichen Manifests.
  • Packen Sie das neue Manifest und Standard-Symbol- und hochauflösenden Symbolbilddateien in eine ZIP-Datei zum Querladen oder Bereitstellen.

Hinweis

  • Das einheitliche Manifest ist eine Vorschaufunktion für Office-Add-Ins und wird derzeit nur für Outlook unter Windows unterstützt.
  • Add-Ins, die das einheitliche Manifest verwenden, können nur in Office Build 16.0.16501.10000 oder höher quergeladen werden.
  • Projekte, die in Visual Studio erstellt wurden und sich von Visual Studio Code unterscheiden, können derzeit nicht konvertiert werden.
  • Wenn Sie das Projekt mit dem Teams-Toolkit oder mit der Option "Einheitliches Manifest" im Office Yeoman-Generator erstellt haben, wird bereits das einheitliche Manifest verwendet.

Stellen Sie sicher, dass Sie über die beiden Bilddateien verfügen.

Es ist sehr wahrscheinlich, dass Sie die beiden Bilddateien bereits in Ihrem Add-In haben. Sie werden im XML-Manifest in den Elementen IconUrl und HighResolutionIconUrl angegeben. Da es sich bei beiden um optionale Elemente handelt, verfügt Ihr Add-In-Projekt mignt nicht über eines oder beides. Diese sind für ein Add-In erforderlich, das das einheitliche Manifest verwendet. Daher müssen Sie sie erstellen, wenn das Projekt noch nicht über sie verfügt. Eine Anleitung finden Sie unter Create eines Symbols für Ihr Add-In.

Wenn Sie die Dateien zum Projekt hinzugefügt haben, fügen Sie IconUrl> und HighResolutionIconUrl (in dieser Reihenfolge) dem XML-Manifest direkt unter dem Description-Element hinzu<.<><> Es folgt ein Beispiel.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>01234567-89ab-cdef-0123-4567-89abcdef0123</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="Great Add-in"/>
  <Description DefaultValue="A great add-in."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-64.png" />
  <HighResolutionIconUrl DefaultValue="https://localhost:300/assets/icon-128.png" />

  <!-- Other markup omitted -->

Konvertierungstools und -optionen

Es gibt mehrere Möglichkeiten, die verbleibenden Aufgaben auszuführen, abhängig von der IDE und anderen Tools, die Sie für Ihr Projekt verwenden möchten, und dem Tool, das Sie zum Erstellen des Projekts verwendet haben.

Konvertieren des Projekts mit dem Teams-Toolkit

Die einfachste Möglichkeit zum Konvertieren ist die Verwendung des Teams-Toolkits.

Voraussetzungen

Importieren des Add-In-Projekts in das Teams-Toolkit

  1. Öffnen Sie Visual Studio Code, und wählen Sie auf der Aktivitätsleiste das Symbol Teams Toolkit aus.

    Symbol

  2. Wählen Sie Create einer neuen App aus.

  3. Wählen Sie in der Dropdownliste Neues Projektdie Option Outlook-Add-In aus.

    Die vier Optionen in der Dropdownliste Neues Projekt. Die vierte Option heißt

  4. Wählen Sie in der Dropdownliste App-Features mit einem Outlook-Add-In die Option Vorhandenes Outlook-Add-In importieren aus.

    Die beiden Optionen in der Dropdownliste App-Features mithilfe eines Outlook-Add-Ins. Die zweite Option heißt

  5. Navigieren Sie in der Dropdownliste Vorhandene Add-In-Projektordner zum Stammordner des Add-In-Projekts.

  6. Navigieren Sie in der Dropdownliste Projektmanifestdatei importieren auswählen zur XML-Manifestdatei.

  7. Wählen Sie im Dialogfeld Arbeitsbereichsordner den Ordner aus, in dem Sie das konvertierte Projekt ablegen möchten.

  8. Geben Sie dem Projekt im Dialogfeld Anwendungsname einen Namen (ohne Leerzeichen) ein. Teams Toolkit erstellt das Projekt mit Ihren Quelldateien und Gerüsten. Anschließend wird das Projekt in einem zweiten Visual Studio Code-Fenster geöffnet. Schließen Sie das ursprüngliche Visual Studio Code-Fenster.

Querladen des Add-Ins in Visual Studio Code

Sie können das Add-In mithilfe des Teams-Toolkits oder in einer Eingabeaufforderung, bash-Shell oder einem Terminal querladen.

Querladen mit dem Teams-Toolkit
  1. Stellen Sie zunächst sicher, dass Outlook-Desktop geschlossen ist.
  2. Öffnen Sie in Visual Studio Code das Teams-Toolkit.
  3. Vergewissern Sie sich im Abschnitt KONTEN , dass Sie bei Microsoft 365 angemeldet sind.
  4. Wählen Sie In Visual Studio Codeausführenanzeigen | aus. Wählen Sie im Dropdownmenü AUSFÜHREN UND DEBUGGEN die Option Outlook Desktop (Edge Chromium) aus, und drücken Sie dann F5. Das Projekt wird erstellt, und ein Node dev-server-Fenster wird geöffnet. Dieser Vorgang kann einige Minuten dauern, und dann wird Der Outlook-Desktop geöffnet.
  5. Sie können jetzt mit Ihrem Add-In arbeiten. Stellen Sie sicher, dass Sie im PosteingangIhrer Microsoft 365-Kontoidentität arbeiten.
Querladen mit einer Systemeingabeaufforderung, einer Bash-Shell oder einem Terminal
  1. Stellen Sie zunächst sicher, dass Outlook-Desktop geschlossen ist.
  2. Öffnen Sie eine Systemeingabeaufforderung, eine Bash-Shell oder das Visual Studio Code-TERMINAL, und navigieren Sie zum Stammverzeichnis des Projekts.
  3. Führen Sie den Befehl npm run start:desktop aus. Das Projekt wird erstellt, und ein Node dev-server-Fenster wird geöffnet. Dieser Vorgang kann einige Minuten dauern, bis Outlook-Desktop geöffnet wird.
  4. Sie können jetzt mit Ihrem Add-In arbeiten.

Projekte, die mit dem Office Yeoman-Generator (auch bekannt als "Yo Office") erstellt wurden

Wenn das Projekt mit dem Office Yeoman-Generator erstellt wurde (mit einer beliebigen Option außer der Option "einheitliches Manifest") und Sie das Teams Toolkit nicht verwenden möchten, konvertieren Sie es mithilfe der folgenden Schritte.

  1. Öffnen Sie im Stammverzeichnis des Projekts eine Eingabeaufforderung oder bash-Shell, und führen Sie den folgenden Befehl aus. Dadurch wird das Manifest konvertiert und die package.json aktualisiert, um aktuelle Toolpakete anzugeben. Das neue einheitliche Manifest befindet sich im Stammverzeichnis des Projekts, und das alte XML-Manifest befindet sich in einer backup.zip-Datei. Ausführliche Informationen zu diesem Befehl finden Sie unter Office-Addin-Project.

    npx office-addin-project convert -m <relative-path-to-XML-manifest>

  2. Führen Sie npm install aus.

  3. Führen npm run start:desktopSie aus, um das Add-In querzuladen. Mit diesem Befehl werden das einheitliche Manifest und die beiden Bilddateien in eine ZIP-Datei eingefügt und quer in die Office-Anwendung geladen. Außerdem wird der Server in einem separaten NodeJS-Fenster gestartet, um die Add-In-Dateien auf localhost zu hosten.

NodeJS- und npm-Projekte, die nicht mit dem Yeoman-Generator erstellt wurden

Wenn Sie das Teams-Toolkit nicht verwenden möchten und Ihr Projekt nicht mit dem Office Yeoman-Generator erstellt wurde, verwenden Sie das Tool office-addin-manifest-converter.

Öffnen Sie im Stammverzeichnis des Projekts eine Eingabeaufforderung oder bash-Shell, und führen Sie den folgenden Befehl aus. Dieser Befehl platziert das einheitliche Manifest in einem Unterordner mit demselben Namen wie der Dateinamenstamm des ursprünglichen XML-Manifests. Wenn das Manifest beispielsweise MyManifest.xml benannt ist, wird das einheitliche Manifest unter .\MyManifest\MyManifest.json erstellt. Weitere Informationen zu diesem Befehl finden Sie unter Office-Addin-Manifest-Converter.

npx office-addin-manifest-converter convert -m <relative-path-to-XML-manifest>

Nachdem Sie das einheitliche Manifest erstellt haben, gibt es zwei Möglichkeiten, die ZIP-Datei zu erstellen und querzuladen. Sie werden in den nächsten beiden Unterabschnitten beschrieben.

Querladen mit dem Office-Addin-Debugging-Tool

  1. Führen Sie den folgenden Befehl aus, um das Add-In querzuladen. Mit diesem Befehl werden das einheitliche Manifest und zwei Standardsymbolbilddateien in eine ZIP-Datei eingefügt und in die Office-Anwendung quer geladen. Außerdem wird ein Server in einem separaten NodeJS-Fenster gestartet, um die Add-In-Dateien auf localhost zu hosten. Beachten Sie, dass Sie den Pfad an das einheitliche Manifest übergeben, das Sie im vorherigen Schritt erstellt haben. Weitere Informationen zu diesem Befehl finden Sie unter Office-Addin-Debugging.

    npx office-addin-debugging start <relative-path-to-unified-manifest> desktop

  2. Wenn Sie office-addin-debugging zum Starten eines Add-Ins verwenden, beenden Sie die Sitzung immer mit dem folgenden Befehl. Durch das Schließen des Serverfensters wird der Server nicht zuverlässig beendet, und das Schließen der Office-Anwendung führt nicht zuverlässig dazu, dass Office das Add-In nicht mehr anfordert.

    npx office-addin-debugging stop <relative-path-to-unified-manifest>

Querladen mit der Teams-Toolkit-CLI (Befehlszeilenschnittstelle)

  1. Erstellen Sie das ZIP-Paket mithilfe der folgenden Schritte manuell.

    1. Öffnen Sie das einheitliche Manifest, und scrollen Sie zur Eigenschaft "Symbole". Beachten Sie den relativen Pfad der beiden Bilddateien.
    2. Verwenden Sie ein beliebiges ZIP-Hilfsprogramm, um eine ZIP-Datei zu erstellen, die das einheitliche Manifest und die beiden Imagedateien enthält. Die Bilddateien müssen denselben relativen Pfad in der ZIP-Datei aufweisen wie im Projekt. Wenn der relative Pfad beispielsweise "assets/icon-64.png" und "assets/icon-128.png" lautet, müssen Sie den Ordner "assets" mit den beiden Dateien im ZIP-Paket einschließen.
    3. Wenn der Ordner andere Dateien enthält, z. B. Bilddateien, die im Office-Menüband verwendet werden, entfernen Sie diese aus dem ZIP-Paket. Es sollten nur die beiden Bilddateien enthalten, die in der Eigenschaft "icons" angegeben sind (zusätzlich zum Manifest im Stammverzeichnis des ZIP-Pakets).

  2. Öffnen Sie im Stammverzeichnis des Projekts eine Eingabeaufforderung oder bash-Shell, und führen Sie die folgenden Befehle aus.

    npm install -g @microsoft/teamsfx-cli

teamsfx m365 sideloading --file-path <relative-path-to-zip-file>