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

Um Teams-Funktionen oder eine Copilot-Erweiterung zu einem Add-In hinzuzufügen, das nur das Add-In-Manifest verwendet, oder um das Add-In nur zukunftssicher zu machen, müssen Sie es konvertieren, um das einheitliche Manifest für Microsoft 365 zu verwenden.

Hinweis

Das einheitliche Manifest für Microsoft 365 kann in Outlook-Produktions-Add-Ins verwendet werden. Es ist nur als Vorschau für Excel-, PowerPoint- und Word-Add-Ins verfügbar.

Es gibt drei grundlegende Aufgaben zum Konvertieren eines Add-In-Projekts vom reinen Add-In-Manifest in das einheitliche Manifest.

• Stellen Sie sicher, dass Ihr Manifest 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 zwei Symbolbilddateien (weiter unten beschrieben) zum Querladen oder Bereitstellen in eine ZIP-Datei. Je nachdem, wie Sie das konvertierte Add-In querladen, kann diese Aufgabe automatisch für Sie ausgeführt werden.

Hinweis

Informationen zu Clients und Plattformen, die Office-Add-Ins direkt unterstützen, die das einheitliche Manifest für Microsoft 365 verwenden, finden Sie unter Office-Add-Ins mit dem einheitlichen App-Manifest für Microsoft 365.

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 Teams Toolkit oder Microsoft 365 Agents Toolkit oder mit der Option "einheitliches Manifest" im Office Yeoman-Generator erstellt haben, wird bereits das einheitliche Manifest verwendet.

Stellen Sie sicher, dass Ihr Manifest für die Konvertierung bereit ist.

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

Deinstallieren der vorhandenen Version des Add-Ins

Um Konflikte mit Ui-Steuerelementnamen und anderen Problemen zu vermeiden, stellen Sie sicher, dass das vorhandene Add-In nicht auf dem Computer installiert ist, auf dem Sie die Konvertierung durchführen. Wenn Beim Deinstallieren des Add-Ins Probleme auftreten, lesen Sie Entfernen eines Ghost-Add-Ins.

Stellen Sie sicher, dass Sie über zwei spezielle Bilddateien verfügen.

Wenn Ihr reines Add-In-Manifest nicht bereits über <IconUrl> - und <HighResolutionIconUrl-Elemente> (in dieser Reihenfolge) verfügt, fügen Sie sie direkt unterhalb des <Description-Elements> hinzu. Die Werte des DefaultValue-Attributs sollten die vollständigen URLs von Bilddateien sein. Die Bilder müssen eine angegebene Größe aufweisen, wie in der folgenden Tabelle dargestellt.

Office-Anwendung	<IconUrl>	<HighResolutionIconUrl>
Outlook	64 x 64 Pixel	128 x 128 Pixel
Alle anderen Office-Anwendungen	32 x 32 Pixel	64 x 64 Pixel

Das folgende Markup ist 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 -->

Reduzieren der Anzahl von Add-In-Befehlen nach Bedarf

Ein Add-In, das das einheitliche Manifest verwendet, verfügt möglicherweise nicht über mehr als 20 Add-In-Befehle. Wenn die Gesamtzahl der <Action-Elemente> im reinen Add-In-Manifest größer als 20 ist, müssen Sie das Add-In so umgestalten, dass es nicht mehr als 20 hat.

Aktualisieren der Add-In-ID, Der Version, der Domäne und der Funktionsnamen im Manifest

1. Ändern Sie den Wert des <ID> Elements in eine neue zufällige GUID.

2. Aktualisieren Sie den Wert des <Version> Elements, und stellen Sie sicher, dass es dem Semver-Standard (MAJOR. KLEINER. PATCH). Jedes Segment darf nicht mehr als fünf Ziffern aufweisen. Ändern Sie z. B. den Wert 1.0.0.0 in 1.0.1. Die Zeichenfolgenerweiterungen für die Vorabversion und die Metadatenversion des Semver-Standards werden nicht unterstützt.

3. Stellen Sie sicher, dass das Domänensegment der URLs des Add-Ins im Manifest auf https://localhost:3000verweist.

4. Wenn Ihr Manifest <über FunctionName-Elemente> verfügt, stellen Sie sicher, dass deren Werte weniger als 65 Zeichen enthalten.

   Wichtig

   Der Wert dieses Elements muss genau mit dem Namen einer Aktion übereinstimmen, die einer Funktion in einer JavaScript- oder TypeScript-Datei mit der Office.actions.associate-Funktion zugeordnet ist. Wenn Sie es im Manifest ändern, müssen Sie es auch im Parameter ändern, der actionId an associate() übergeben wird.

Kürzen von Zeichenfolgenwerten nach Bedarf

Überprüfen und ändern Sie manifestierte Werte nach Bedarf unter Berücksichtigung der folgenden Auswirkungen der Konvertierung.

• Die ersten 30 Zeichen von <DisplayName> werden zum Wert von "name.short" im einheitlichen Manifest.
• Die ersten 100 Zeichen von <DisplayName> werden zum Wert von "name.full" im einheitlichen Manifest.
• Die ersten 250 Zeichen von <Description> werden zum Wert von "description.short" im einheitlichen Manifest.
• Die ersten 4000 Zeichen von <Description> werden zum Wert von "description.full" im einheitlichen Manifest.
• Die ersten 32 Zeichen von <ProviderName> werden zum Wert von "developer.name" im einheitlichen Manifest.

Überprüfen, ob das geänderte Add-In-Manifest nur funktioniert

1. Überprüfen Sie das geänderte Add-In-Manifest nur. Weitere Informationen finden Sie unter Überprüfen des Manifests eines Office-Add-Ins.

2. Vergewissern Sie sich, dass das Add-In quergeladen und ausgeführt werden kann. Weitere Informationen finden Sie unter Querladen eines Office-Add-Ins zum Testen.

Beheben Sie alle Probleme, bevor Sie versuchen, das Projekt zu konvertieren.

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 von Projekten, die mit dem Yeoman-Generator für Office-Add-Ins (auch bekannt als "Yo Office") erstellt wurden
• Konvertieren von NodeJS- und npm-Projekten, die nicht mit dem Yeoman-Generator für Office-Add-Ins (Yo Office) erstellt wurden

Hinweis

Die Konvertierung des Manifests ist einer der Auswirkungen des Importierens des Add-In-Projekts in das Agents Toolkit, wenn Sie dies mithilfe des Importfeatures des Toolkits tun. Weitere Informationen finden Sie unter Importieren eines Add-In-Projekts in das Agents-Toolkit.

Konvertieren von Projekten, die mit dem Yeoman-Generator für Office-Add-Ins (auch bekannt als "Yo Office") erstellt wurden

Wenn das Projekt mit dem Yeoman-Generator für Office-Add-Ins erstellt wurde, 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. Informationen zum Querladen des Add-Ins finden Sie unter Querladen von Add-Ins, die mit dem Yeoman-Generator für Office-Add-Ins (Yo Office) erstellt wurden.

Konvertieren von NodeJS- und npm-Projekten, die nicht mit dem Yeoman-Generator für Office-Add-Ins (Yo Office) erstellt wurden

Wenn Ihr Projekt nicht mit Yo Office 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. Weitere Informationen finden Sie unter Querladen anderer NodeJS- und npm-Projekte.

Hinweis

Wenn das ursprüngliche Add-In-Manifest nur <Override-Elemente> verwendet hat, um Zeichenfolgen im Manifest zu lokalisieren, erzeugt der Konvertierungsprozess JSON-Zeichenfolgendateien für jede lokalisierte Sprache. Diese Dateien müssen auch in der ZIP-Datei enthalten sein, und sie müssen sich am relativen Pfad befinden, der in der "localizationInfo.additionalLanguages.file" -Eigenschaft angegeben ist.

Nächste Schritte

Überlegen Sie, ob sowohl die alte als auch die neue Version des Add-Ins beibehalten werden sollen. Weitere Informationen finden Sie unter Verwalten eines einheitlichen Manifests und einer reinen Add-In-Manifestversion Ihres Office-Add-Ins.