Convertir un complément pour utiliser le manifeste unifié pour Microsoft 365 (préversion)

  • Article

Pour ajouter des fonctionnalités Teams à un complément qui utilise le manifeste XML, ou simplement pour prouver le complément, vous devez le convertir pour utiliser le manifeste unifié pour Microsoft 365.

Il existe trois tâches de base pour convertir un projet de complément du manifeste XML en manifeste unifié.

  • Vérifiez que vous disposez de fichiers images 64 x 64 pixels et 128 x 128 pixels pour servir d’icônes pour le complément.
  • Convertissez le manifeste XML lui-même au format JSON du manifeste unifié.
  • Empaquetez le nouveau manifeste et les fichiers d’icône de main et d’icône haute résolution dans un fichier zip pour le chargement indépendant ou le déploiement.

Remarque

  • Le manifeste unifié est une fonctionnalité en préversion pour les compléments Office et est actuellement pris en charge uniquement pour Outlook sur Windows.
  • Les compléments qui utilisent le manifeste unifié peuvent être chargés de manière indépendante uniquement sur Office Build 16.0.16501.10000 ou version ultérieure.
  • Les projets créés dans Visual Studio, contrairement à Visual Studio Code, ne peuvent pas être convertis pour l’instant.
  • Si vous avez créé le projet avec teams Toolkit ou avec l’option « manifeste unifié » dans le générateur Office Yeoman, il utilise déjà le manifeste unifié.

Vérifiez que vous disposez des deux fichiers image

Il est fort probable que vous ayez déjà les deux fichiers image dans votre complément. Elles sont spécifiées dans les éléments IconUrl et HighResolutionIconUrl du manifeste XML. Étant donné qu’il s’agit des deux éléments facultatifs, votre projet de complément n’en a pas ou les deux. Ces éléments sont requis pour un complément qui utilise le manifeste unifié. Vous devez donc les créer si le projet n’en a pas encore. Pour obtenir de l’aide, consultez Create une icône pour votre complément.

Une fois que vous avez ajouté les fichiers au projet, ajoutez <IconUrl> et <HighResolutionIconUrl> (dans cet ordre) au manifeste XML juste en dessous de l’élément <Description> . Voici un exemple.

<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 -->

Outils et options de conversion

Il existe plusieurs façons d’effectuer les tâches restantes, en fonction de l’IDE et des autres outils que vous souhaitez utiliser pour votre projet, et de l’outil que vous avez utilisé pour créer le projet.

Convertir le projet avec teams Toolkit

Le moyen le plus simple de convertir consiste à utiliser teams Toolkit.

Configuration requise

Importer le projet de complément dans teams Toolkit

  1. Ouvrez Visual Studio Code et sélectionnez l’icône Teams Toolkit dans la barre d’activité.

    Icône du Kit de ressources Teams.

  2. Sélectionnez Create une nouvelle application.

  3. Dans la liste déroulante Nouveau projet , sélectionnez Complément Outlook.

    Les quatre options de la liste déroulante Nouveau projet. La quatrième option est appelée « Complément Outlook ».

  4. Dans la liste déroulante Fonctionnalités de l’application à l’aide d’un complément Outlook , sélectionnez Importer un complément Outlook existant.

    Les deux options de la liste déroulante Fonctionnalités de l’application à l’aide d’un complément Outlook. La deuxième option est appelée « Importer un complément Outlook existant ».

  5. Dans la liste déroulante Dossier du projet de complément existant , accédez au dossier racine du projet de complément.

  6. Dans la liste déroulante Sélectionner l’importation du fichier manifeste de projet , accédez au fichier manifeste XML.

  7. Dans la boîte de dialogue Dossier de l’espace de travail, sélectionnez le dossier dans lequel vous souhaitez placer le projet converti.

  8. Dans la boîte de dialogue Nom de l’application, donnez un nom au projet (sans espace). Teams Toolkit crée le projet avec vos fichiers sources et votre structure. Il ouvre ensuite le projet dans une deuxième fenêtre Visual Studio Code. Fermez la fenêtre Visual Studio Code d’origine.

Charger une version test du complément dans Visual Studio Code

Vous pouvez charger une version test du complément à l’aide du Kit de ressources Teams ou dans une invite de commandes, un interpréteur de commandes bash ou un terminal.

Chargement indépendant avec le Kit de ressources Teams
  1. Tout d’abord, vérifiez que le bureau Outlook est fermé.
  2. Dans Visual Studio Code, ouvrez le Kit de ressources Teams.
  3. Dans la section COMPTES , vérifiez que vous êtes connecté à Microsoft 365.
  4. Sélectionnez Afficher | l’exécution dans Visual Studio Code. Dans le menu déroulant EXÉCUTER ET DÉBOGUER, sélectionnez l’option Bureau Outlook (Edge Chromium), puis appuyez sur F5. Le projet est généré et une fenêtre Node dev-server s’ouvre. Ce processus peut prendre quelques minutes, puis le bureau Outlook s’ouvre.
  5. Vous pouvez maintenant utiliser votre complément. Veillez à travailler dans la boîte de réception de votre identité de compte Microsoft 365.
Chargement de version test avec une invite système, un interpréteur de commandes Bash ou un terminal
  1. Tout d’abord, vérifiez que le bureau Outlook est fermé.
  2. Ouvrez une invite système, un interpréteur de commandes Bash ou le terminal Visual Studio Code, puis accédez à la racine du projet.
  3. Exécutez la commande npm run start:desktop. Le projet est généré et une fenêtre Node dev-server s’ouvre. Ce processus peut prendre quelques minutes avant l’ouverture du bureau Outlook.
  4. Vous pouvez maintenant utiliser votre complément.

Projets créés avec le générateur Office Yeoman (alias « Yo Office »)

Si le projet a été créé avec le générateur Office Yeoman (à l’aide d’une option à l’exception de l’option « manifeste unifié ») et que vous ne souhaitez pas utiliser le kit de ressources Teams, convertissez-le en procédant comme suit.

  1. À la racine du projet, ouvrez une invite de commandes ou un interpréteur de commandes bash et exécutez la commande suivante. Cela convertit le manifeste et met à jour le package.json pour spécifier les packages d’outils actuels. Le nouveau manifeste unifié se trouve à la racine du projet et l’ancien manifeste XML se trouve dans un fichier backup.zip. Pour plus d’informations sur cette commande, voir Office-Addin-Project.

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

  2. Exécutez npm install.

  3. Pour charger une version test du complément, exécutez npm run start:desktop. Cette commande place le manifeste unifié et les deux fichiers image dans un fichier zip et les charge dans l’application Office. Il démarre également le serveur dans une fenêtre NodeJS distincte pour héberger les fichiers de complément sur localhost.

Projets NodeJS et npm qui ne sont pas créés avec Yeoman Generator

Si vous ne souhaitez pas utiliser le Kit de ressources Teams et que votre projet n’a pas été créé avec le générateur Office Yeoman, utilisez l’outil office-addin-manifest-converter.

À la racine du projet, ouvrez une invite de commandes ou un interpréteur de commandes bash et exécutez la commande suivante. Cette commande place le manifeste unifié dans un sous-dossier portant le même nom que la tige de nom de fichier du manifeste XML d’origine. Par exemple, si le manifeste est nommé MyManifest.xml, le manifeste unifié est créé à l’emplacement .\MyManifest\MyManifest.json. Pour plus d’informations sur cette commande, voir Office-Addin-Manifest-Converter.

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

Une fois le manifeste unifié créé, il existe deux façons de créer le fichier zip et de le charger de manière indépendante. Elles sont décrites dans les deux sous-sections suivantes.

Chargement de version test avec l’outil Office-Addin-Débogage

  1. Pour charger une version test du complément, exécutez la commande suivante. Cette commande place le manifeste unifié et deux fichiers image d’icône par défaut dans un fichier zip et le charge dans l’application Office. Il démarre également un serveur dans une fenêtre NodeJS distincte pour héberger les fichiers de complément sur localhost. Notez que vous passez le chemin au manifeste unifié que vous avez créé à l’étape précédente. Pour plus d’informations sur cette commande, voir Office-Addin-Debugging.

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

  2. Lorsque vous utilisez office-addin-debugging pour démarrer un complément, arrêtez toujours la session avec la commande suivante. La fermeture de la fenêtre du serveur n’arrête pas de manière fiable le serveur et la fermeture de l’application Office n’entraîne pas de manière fiable l’annulation de l’exécution du complément par Office.

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

Chargement indépendant avec l’interface CLI du Kit de ressources Teams (interface de ligne de commande)

  1. Créez manuellement le package zip en procédant comme suit.

    1. Ouvrez le manifeste unifié et faites défiler jusqu’à la propriété « icons ». Notez le chemin relatif des deux fichiers image.
    2. Utilisez n’importe quel utilitaire zip pour créer un fichier zip qui contient le manifeste unifié et les deux fichiers image. Les fichiers image doivent avoir le même chemin relatif dans le fichier zip que dans le projet. Par exemple, si le chemin relatif est « assets/icon-64.png » et « assets/icon-128.png », vous devez inclure le dossier « assets » avec les deux fichiers dans le package zip.
    3. Si le dossier contient d’autres fichiers, tels que des fichiers image utilisés dans le ruban Office, supprimez-les du package zip. Il doit avoir uniquement les deux fichiers image spécifiés dans la propriété « icons » (en plus du manifeste à la racine du package zip).

  2. À la racine du projet, ouvrez une invite de commandes ou un interpréteur de commandes bash et exécutez les commandes suivantes.

    npm install -g @microsoft/teamsfx-cli

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