Freigeben über

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

  • Artikel

Um Teams-Funktionen zu einem Add-In hinzuzufügen, das nur das Add-In-Manifest verwendet, oder um das Add-In nur für die Zukunft zu überprüfen, 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 vom reinen Add-In-Manifest in das einheitliche Manifest.

  • Stellen Sie sicher, dass Das Add-In für die Konvertierung bereit ist.
  • Konvertieren Sie das XML-formatierte Add-In-Manifest selbst in das JSON-Format des einheitlichen Manifests.
  • Packen Sie das neue Manifest und die beiden Symbolbilddateien zum Querladen oder Bereitstellen in eine ZIP-Datei.

Hinweis

Office-Add-Ins, die das einheitliche Manifest für Microsoft 365 verwenden, werden direkt in Office im Web, in outlook unter Windows und in Office unter Windows unterstützt, die mit einem Microsoft 365-Abonnement, Version 2304 (Build 16320.00000) oder höher verbunden sind.

Wenn das App-Paket, das das einheitliche Manifest enthält, in AppSource oder im Microsoft 365 Admin Center bereitgestellt wird, wird ein reines Add-In-Manifest aus dem einheitlichen Manifest generiert und gespeichert, wenn das Manifest über eine gültige "alternateIcons"-Eigenschaft verfügt. Dieses Reine Add-In-Manifest ermöglicht die Installation des Add-Ins auf Plattformen, die das einheitliche Manifest nicht direkt unterstützen, einschließlich Office für Mac, Office auf Mobilgeräten, Abonnementversionen von Office unter Windows vor 2304 (Build 16320.00000) und unbefristete Versionen von Office unter Windows.

Hinweis

  • Add-Ins, die das einheitliche Manifest verwenden, können nur in Office Version 2304 (Build 16320.20000) 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 Ihr Add-In für die Konvertierung bereit ist.

In den folgenden Abschnitten werden Bedingungen beschrieben, die erfüllt sein müssen, bevor Sie das Manifest konvertieren.

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

Wenn Sie die Dateien zum Projekt hinzugefügt haben, fügen Sie <IconUrl> und <HighResolutionIconUrl> (in dieser Reihenfolge) dem Add-In-Manifest nur unterhalb des <Description-Elements> 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 -->

Stellen Sie sicher, dass die Namen der Funktionsbefehle kurz genug sind.

Wenn Ihr Manifest <über FunctionName-Elemente> verfügt, stellen Sie sicher, dass deren Werte weniger als 65 Zeichen enthalten. Der Wert dieses Elements muss genau mit dem Namen einer Funktion in einer JavaScript- oder TypeScript-Datei übereinstimmen. Wenn Sie es im Manifest ändern, müssen Sie es auch in der Codedatei ändern.

Stellen Sie sicher, dass Ihr SSO-Add-In Berechtigungen anfordert.

Wenn Ihr Add-In das einmalige Anmelden von Microsoft mit dem On-Behalf-of-Fluss (OBO) verwendet, verfügt Ihr Add-In über ein <Scopes-Element> , das die Microsoft Graph- oder andere API-Berechtigungen angibt, die das Add-In benötigt. Mit dem einheitlichen Manifest müssen Berechtigungen zur Laufzeit im Code angefordert werden. Aktualisieren Sie Ihren Code nach Bedarf, um diese Berechtigungen anzufordern. Der genaue Code hängt von der Architektur und den Autorisierungscodebibliotheken ab, die Sie verwenden. In der Regel fordert Code Berechtigungen in einer Funktion an, die ein Zugriffstoken anfordert.

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 Neue App erstellen 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 Select import project manifest file (Projektmanifestdatei importieren auswählen ) zu der Manifestdatei, die in der Regel manifest.xmlgenannt wird.

  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.
  5. Wenn Sie mit dem Add-In fertig sind, stellen Sie sicher, dass Sie den Befehl npm run stopausführen.

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

Wenn das Projekt mit dem Office Yeoman-Generator erstellt wurde 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 Nur-Add-In-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. Ausführen npm install.

  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.

Wenn Sie bereit sind, den Entwicklungsserver zu beenden und das Add-In zu deinstallieren, führen Sie den Befehl aus npm run stop.

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 Add-In-Manifests. Wenn das Manifest beispielsweise MyManifest.xmlbenannt 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 <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>