Angeben der Office-Add-In-Anforderungen im einheitlichen Manifest für Microsoft 365

  • Artikel

Es gibt mehrere "Requirements"-Eigenschaften im einheitlichen Manifest für Microsoft 365. Die extensions.requirements-Eigenschaft steuert die Office-Anwendungen und -Versionen, auf denen das Add-In installiert werden kann. Andere "Requirements"-Eigenschaften werden verwendet, um selektiv einige Features eines Add-Ins für bestimmte Office-Anwendungen oder -Versionen zu unterdrücken, bei denen diese Features nicht benötigt oder nicht unterstützt werden. Weitere Informationen finden Sie unter Filterfeatures.

extensions.requirements

Die Eigenschaft "extensions.requirements" gibt die Bereiche, Formfaktoren und Anforderungssätze für Microsoft 365-Add-Ins an. Wenn die Microsoft 365-Version die angegebenen Anforderungen nicht unterstützt, steht die Erweiterung nicht für die Installation zur Verfügung. Benutzern wird sie nicht auf der Office-Benutzeroberfläche zum Suchen und Installieren von Add-Ins angezeigt. Einige Beispiele:

  • Wenn die Eigenschaft "requirements.capabilities.name" auf "Mailbox" und "requirements.capabilities.minVersion" auf "1.10" festgelegt ist, kann das Add-In nicht in älteren Versionen von Office installiert werden, die keine Postfachanforderungssätze unterstützen, die höher als Version 1.9 sind.
  • Wenn "requirements.scopes" auf "mail" festgelegt ist, kann das Add-In nur in Outlook installiert werden.
  • Wenn "requirements.formFactors" nur auf "desktop" festgelegt ist, kann das Add-In nicht auf Office installiert werden, das auf einem mobilen Gerät ausgeführt wird.

Sie können über mehrere Funktionsobjekte verfügen. Das folgende Beispiel zeigt, wie Sie sicherstellen können, dass ein Add-In nur in Versionen von Office installiert werden kann, die zwei verschiedene Anforderungssätze unterstützen und nicht auf mobilen Geräten.

"extensions": [
    ...
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.10"
            },
            {
                "name": "DialogAPI",
                "minVersion": "1.2"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    }
]

Filterfeatures

Die Eigenschaften "requirements" in Nachfolgerobjekten von "Extensions" werden verwendet, um einige Features eines Add-Ins zu blockieren, während das Add-In weiterhin installiert werden kann. Die Implementierung dieser Filterung erfolgt an der Quelle der Installation, z. B. AppSource oder Microsoft 365 Admin Center. Wenn die Office-Version die für das Feature angegebenen Anforderungen nicht unterstützt, wird der JSON-Knoten für das Feature aus dem Manifest entfernt, bevor er in der Office-Anwendung installiert wird.

extensions.alternates.requirements

Die Eigenschaft "extensions.alternates" ermöglicht Add-In-Entwicklern folgendes:

  • Verwalten Sie eine Version eines Add-Ins, die auf einer älteren Erweiterbarkeitsplattform (z. B. COM- oder VSTO-Add-Ins) erstellt wurde, oder verwenden Sie das XML-Manifest zusätzlich zu der Version, die das einheitliche Manifest verwendet.
  • Blenden Sie entweder die Version aus, die die ältere Technologie verwendet, oder bevorzugen Sie sie.
  • Geben Sie Symbole an, die erforderlich sind, damit die einheitliche Manifestversion des Add-Ins in Office-Versionen installiert werden kann, die das einheitliche Manifest nicht direkt unterstützen.

Hinweis

Office-Add-Ins, die das einheitliche Manifest für Microsoft 365 verwenden, werden direkt in Office im Web, in outlook unter Windows (Vorschau) 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 XML-Manifest aus dem einheitlichen Manifest generiert und gespeichert, wenn das Manifest über eine gültige "alternateIcons"-Eigenschaft verfügt. Dieses XML-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.

Weitere Informationen finden Sie unter Verwalten eines einheitlichen Manifests und einer XML-Manifestversion Ihres Office-Add-Ins.

Die Untereigenschaft "requirements" von "extensions.alternates", um die Untereigenschaften "hide" oder "prefer" nur dann selektiv anzuwenden, wenn bestimmte Anforderungen erfüllt sind.

Angenommen, Sie möchten (auf der Office-Benutzeroberfläche zum Installieren von Add-Ins) eine ältere Version Ihres Add-Ins ausblenden, jedoch nur in Office-Versionen, die den Anforderungssatz Mailbox 1.10 unterstützen. Sie könnten dies mit Markup ähnlich dem folgenden tun:

"extensions": [
    ...
    {
        ...
        "alternates": [
            ...
            {
                ...
                "hide": {
                    "storeOfficeAddin": {
                        "officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
                        "assetId": "WA999999999"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.10"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.autoRunEvents.requirements

Die Eigenschaft "extensions.autoRunEvents" konfiguriert ein Add-In so, dass der angegebene Code automatisch als Reaktion auf angegebene Ereignisse ausgeführt wird. Die Untereigenschaft "requirements" kann verwendet werden, um dieses Verhalten in einigen Versionen von Office zu blockieren.

Angenommen, ein Outlook-Add-In ist für den automatischen Start als Reaktion auf das OnMailSend-Ereignis konfiguriert, und angenommen, der Code in der Funktion, die ausgeführt wird, erfordert den Anforderungssatz Mailbox 1.13 . Das Add-In verfügt jedoch über andere Features, die in Office-Versionen nützlich wären, die nur Version 1.12 unterstützen. Um sicherzustellen, dass das Add-In in Versionen installiert werden kann, die 1.12 unterstützen, kann ein Entwickler die Eigenschaft "extensions.requirements.capabilities" auf den Anforderungssatz Mailbox 1.12 anstelle von 1.13 festlegen. Um jedoch das Feature für den automatischen Start in Versionen zu blockieren, die 1.13 nicht unterstützen, kann der Entwickler eine Eigenschaft "extensions.autoRunEvents.requirements.capabilities" hinzufügen, die Mailbox 1.13 angibt. Es folgt ein Beispiel.

"extensions": [
    ...
    {
        ...
        "autoRunEvents": [
            ...
            {
                ...
                "events": {
                    "type": "OnMailSend",
                    "actionId": "logOutgoingEmail",
                    "options": {
                        "sendMode": "promptUser"
                    }
                },
                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.ribbons.requirements

Die Eigenschaft "extensions.ribbons" wird verwendet, um das Menüband der Office-Anwendung anzupassen, wenn das Add-In installiert ist. Die Untereigenschaft "requirements" kann verwendet werden, um anpassungen in einigen Versionen von Office zu verhindern.

Angenommen, ein Outlook-Add-In ist so konfiguriert, dass dem Menüband eine benutzerdefinierte Schaltfläche hinzugefügt wird, und die Schaltfläche führt eine Funktion aus, die Code verwendet, der im Anforderungssatz Mailbox 1.9 eingeführt wurde. Das Add-In verfügt jedoch über andere Features, die für Office-Versionen nützlich wären, die nur Version 1.8 unterstützen. Um sicherzustellen, dass das Add-In in Versionen installiert werden kann, die Version 1.8 unterstützen, kann ein Entwickler die Eigenschaft "extensions.requirements.capabilities" auf den Anforderungssatz Mailbox 1.8 anstelle von 1.9 festlegen. Um jedoch zu verhindern, dass die benutzerdefinierte Schaltfläche in Versionen, die 1.9 nicht unterstützen, auf dem Menüband angezeigt wird, kann der Entwickler eine "extensions.ribbons.requirements.capabilities"-Eigenschaft hinzufügen, die Mailbox 1.9 angibt. Es folgt ein Beispiel. Ausführliche Informationen zur konfiguration des benutzerdefinierten Menübands finden Sie unter Erstellen von Add-In-Befehlen mit dem einheitlichen Manifest für Microsoft 365.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                // Insert details of the ribbon configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.9"
                        }
                    ]
                }
            }
        ]
    }
]

extensions.runtimes.requirements

Die Eigenschaft "extensions.runtimes" konfiguriert die Sätze von Laufzeiten und Aktionen, die jeder Erweiterungspunkt verwenden kann. Weitere Informationen zur Verwendung finden Sie unter Erstellen von Add-In-Befehlen, Konfigurieren der Laufzeit für einen Aufgabenbereich und Konfigurieren der Laufzeit für den Funktionsbefehl. Weitere Informationen zu Runtimes in Office-Add-Ins finden Sie unter Runtimes in Office-Add-Ins.

Die Untereigenschaft "requirements" kann verwendet werden, um zu verhindern, dass die Runtime in Versionen von Office oder in Office-Anwendungen enthalten ist, in denen sie nicht verwendet würde.

Das vorherige Beispiel in extensions.autoRunEvents.requirements zeigt, wie das Feature für den automatischen Start in Versionen blockiert wird, die nicht den gesamten Code in der logOutgoingEmail Funktion unterstützen, einschließlich Code, der Mailbox 1.13 erfordert. Angenommen, in diesem Szenario ist das "runtime"-Objekt, das für die Unterstützung der Aktion "logOutgoingEmail" konfiguriert ist, nicht für die Unterstützung anderer Aktionen konfiguriert. In diesem Fall sollte der Entwickler das Laufzeitobjekt in Versionen blockieren, die Mailbox 1.13 nicht unterstützen, da es nie verwendet würde. Es folgt ein Beispiel. Ausführliche Informationen zur Laufzeitkonfiguration finden Sie unter Erstellen von Add-In-Befehlen mit dem einheitlichen Manifest für Microsoft 365.

"extensions": [
    ...
    {
        ...
        "runtimes": [
            ...
            {
                // Insert details of the runtime configuration here.

                "requirements": {
                    "capabilities": [
                        {
                            "name": "Mailbox",
                            "minVersion": "1.13"
                        }
                    ]
                }
            }
        ]
    }
]

Wenn die mit der benutzerdefinierten Schaltfläche verknüpfte Aktion für das Beispiel in extensions.ribbons.requirements die einzige in einem Laufzeitobjekt konfigurierte Aktion ist, sollte dieses Laufzeitobjekt unter den gleichen Umständen blockiert werden, unter denen das Menübandobjekt blockiert wird.