Spécifier la configuration requise du complément Office dans le manifeste unifié pour Microsoft 365

  • Article

Il existe plusieurs propriétés « requises » dans le manifeste unifié pour Microsoft 365. La propriété extensions.requirements contrôle les applications Office et les versions sur lesquelles le complément peut être installé. D’autres propriétés « conditions requises » sont utilisées pour supprimer de manière sélective certaines fonctionnalités d’un complément sur des applications ou des versions Office spécifiques où ces fonctionnalités seraient inutiles ou non prises en charge. Pour plus d’informations, consultez Filtrer les fonctionnalités.

extensions.requirements

La propriété « extensions.requirements » spécifie les étendues, les facteurs de forme et les ensembles de conditions requises pour les compléments Microsoft 365. Si la version de Microsoft 365 ne prend pas en charge les exigences spécifiées, l’extension ne sera pas disponible pour l’installation. Les utilisateurs ne le verront pas dans l’interface utilisateur Office pour la recherche et l’installation des compléments. Voici quelques exemples :

  • Si la propriété « requirements.capabilities.name » est définie sur « Mailbox » et « requirements.capabilities.minVersion » sur « 1.10 », le complément n’est pas installable sur les versions antérieures d’Office qui ne prennent pas en charge les ensembles de conditions requises pour les boîtes aux lettres supérieures à la version 1.9.
  • Si « requirements.scopes » est défini sur « mail », le complément n’est installable que sur Outlook.
  • Si « requirements.formFactors » est défini uniquement sur « desktop », le complément n’est pas installable sur Office exécuté sur un appareil mobile.

Vous pouvez avoir plusieurs objets de capacité. L’exemple suivant montre comment s’assurer qu’un complément est installable uniquement sur des versions d’Office qui prennent en charge deux ensembles de conditions requises différents et non sur des appareils mobiles.

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

Fonctionnalités de filtre

Les propriétés « requirements » dans les objets descendants de « extensions » sont utilisées pour bloquer certaines fonctionnalités d’un complément tout en autorisant l’installation du complément. L’implémentation de ce filtrage s’effectue à la source de l’installation, par exemple AppSource ou Administration Microsoft 365 Center. Si la version d’Office ne prend pas en charge les exigences spécifiées pour la fonctionnalité, le nœud JSON de la fonctionnalité est supprimé du manifeste avant son installation dans l’application Office.

extensions.alternates.requirements

La propriété « extensions.alternates » permet aux développeurs de compléments d’effectuer les opérations suivantes :

  • Conservez une version d’un complément qui a été créée sur une plateforme d’extensibilité plus ancienne (comme les compléments COM ou VSTO) ou à l’aide du manifeste XML, en plus de la version qui utilise le manifeste unifié.
  • Masquez ou préférez la version qui utilise l’ancienne technologie.
  • Spécifiez les icônes nécessaires pour rendre la version du manifeste unifié du complément installable sur les versions d’Office qui ne prennent pas directement en charge le manifeste unifié.

Remarque

Les compléments Office qui utilisent le manifeste unifié pour Microsoft 365 sont directement pris en charge dans Office sur le Web, dans le nouvel Outlook sur Windows (préversion) et dans Office sur Windows connecté à un abonnement Microsoft 365, version 2304 (build 16320.00000) ou ultérieure.

Lorsque le package d’application qui contient le manifeste unifié est déployé dans AppSource ou le centre Administration Microsoft 365, si le manifeste a une propriété « alternateIcons » valide, un manifeste XML est généré à partir du manifeste unifié et stocké. Ce manifeste XML permet d’installer le complément sur les plateformes qui ne prennent pas directement en charge le manifeste unifié, notamment Office sur Mac, Office sur mobile, les versions d’abonnement d’Office sur Windows antérieures à 2304 (build 16320.00000) et les versions perpétuelles d’Office sur Windows.

Pour plus d’informations, voir Gérer à la fois un manifeste unifié et une version de manifeste XML de votre complément Office.

La sous-propriété « requirements » de « extensions.alternates » pour appliquer de manière sélective les sous-propriétés « hide » ou « prefer » uniquement lorsque certaines conditions sont remplies.

Par exemple, supposons que vous souhaitiez masquer (à partir de l’interface utilisateur Office pour l’installation des compléments) une version antérieure de votre complément, mais uniquement dans les versions d’Office qui prennent en charge l’ensemble de conditions requises de la boîte aux lettres 1.10 . Vous pouvez le faire avec un balisage similaire à ce qui suit :

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

extensions.autoRunEvents.requirements

La propriété « extensions.autoRunEvents » configure un complément pour exécuter automatiquement le code spécifié en réponse aux événements spécifiés. La sous-propriété « requirements » peut être utilisée pour bloquer ce comportement dans certaines versions d’Office.

Par exemple, supposons qu’un complément Outlook soit configuré pour le lancement automatique en réponse à l’événement OnMailSend et que le code de la fonction qui s’exécute nécessite l’ensemble de conditions requises Mailbox 1.13 . Mais le complément a d’autres fonctionnalités qui seraient utiles dans les versions d’Office qui prennent uniquement en charge la version 1.12. Pour s’assurer que le complément est installable dans les versions qui prennent en charge la version 1.12, un développeur peut définir la propriété « extensions.requirements.capabilities » sur l’ensemble de conditions requises Mailbox 1.12 au lieu de 1.13. Toutefois, pour bloquer la fonctionnalité de lancement automatique dans les versions qui ne prennent pas en charge la version 1.13, le développeur peut ajouter une propriété « extensions.autoRunEvents.requirements.capabilities » qui spécifie Mailbox 1.13. Voici un exemple.

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

extensions.ribbons.requirements

La propriété « extensions.ribbons » est utilisée pour personnaliser le ruban de l’application Office lors de l’installation du complément. La sous-propriété « requirements » peut être utilisée pour empêcher les personnalisations dans certaines versions d’Office.

Par exemple, supposons qu’un complément Outlook soit configuré pour ajouter un bouton personnalisé au ruban et qu’il exécute une fonction qui utilise le code introduit dans l’ensemble de conditions requises mailbox 1.9 . Mais le complément a d’autres fonctionnalités qui seraient utiles sur les versions d’Office qui prennent uniquement en charge la version 1.8. Pour s’assurer que le complément est installable sur les versions qui prennent en charge la version 1.8, un développeur peut définir la propriété « extensions.requirements.capabilities » sur l’ensemble de conditions requises Mailbox 1.8 au lieu de 1.9. Toutefois, pour empêcher le bouton personnalisé d’apparaître sur le ruban dans les versions qui ne prennent pas en charge la version 1.9, le développeur peut ajouter une propriété « extensions.ribbons.requirements.capabilities » qui spécifie Mailbox 1.9. Voici un exemple. Pour plus d’informations sur la configuration du ruban personnalisé, consultez Créer des commandes de complément avec le manifeste unifié pour Microsoft 365.

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

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

extensions.runtimes.requirements

La propriété « extensions.runtimes » configure les ensembles de runtimes et d’actions que chaque point d’extension peut utiliser. Pour plus d’informations sur son utilisation, consultez Créer des commandes de complément, Configurer le runtime pour un volet Office et Configurer le runtime pour la commande de fonction. Pour plus d’informations sur les runtimes dans les compléments Office, voir Runtimes dans les compléments Office.

La sous-propriété « requirements » peut être utilisée pour empêcher le runtime d’être inclus dans les versions d’Office ou dans les applications Office où il ne serait pas utilisé.

L’exemple précédent présenté dans extensions.autoRunEvents.requirements montre comment bloquer la fonctionnalité de lancement automatique dans les versions qui ne prennent pas en charge tout le code de la fonction, ce qui inclut le logOutgoingEmail code qui nécessite mailbox 1.13. Supposons que dans ce même scénario, l’objet « runtime » configuré pour prendre en charge l’action « logOutgoingEmail » n’est pas configuré pour prendre en charge une autre action. Dans ce cas, le développeur doit bloquer l’objet runtime dans les versions qui ne prennent pas en charge la boîte aux lettres 1.13 , car elle ne sera jamais utilisée. Voici un exemple. Pour plus d’informations sur la configuration du runtime, consultez Créer des commandes de complément avec le manifeste unifié pour Microsoft 365.

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

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

De même, pour l’exemple dans extensions.ribbons.requirements, si l’action liée au bouton personnalisé est la seule action configurée dans un objet runtime, cet objet runtime doit être bloqué dans les mêmes circonstances que dans lesquelles l’objet ruban est bloqué.