Compartir a través de

Conversión de un complemento para usar el manifiesto unificado para Microsoft 365

  • Artículo

Para agregar funcionalidades de Teams a un complemento que use el manifiesto de solo complemento, o simplemente para probar el complemento en el futuro, debe convertirlo para usar el manifiesto unificado para Microsoft 365.

Hay tres tareas básicas para convertir un proyecto de complemento del manifiesto de solo complemento al manifiesto unificado.

  • Asegúrese de que el complemento está listo para convertirse.
  • Convierta el propio manifiesto del complemento con formato XML al formato JSON del manifiesto unificado.
  • Empaquete el nuevo manifiesto y los dos archivos de imagen de icono en un archivo ZIP para la instalación local o la implementación.

Nota:

Los complementos de Office que usan el manifiesto unificado para Microsoft 365 se admiten directamente en Office en la Web, en el nuevo Outlook en Windows y en Office en Windows conectado a una suscripción de Microsoft 365, versión 2304 (compilación 16320.00000) o posterior.

Cuando el paquete de aplicación que contiene el manifiesto unificado se implementa en AppSource o en el Centro de Administración de Microsoft 365, se genera un manifiesto de solo complemento a partir del manifiesto unificado y se almacena. Este manifiesto de solo complemento permite instalar el complemento en plataformas que no admiten directamente el manifiesto unificado, incluido Office en Mac, Office en dispositivos móviles, versiones de suscripción de Office en Windows anteriores a 2304 (compilación 16320.00000) y versiones perpetuas de Office en Windows.

Nota:

  • Los complementos que usan el manifiesto unificado solo se pueden transferir de forma local en office versión 2304 (compilación 16320.20000) o posterior.
  • Los proyectos creados en Visual Studio, como distintos de Visual Studio Code, no se pueden convertir en este momento.
  • Si creó el proyecto con El kit de herramientas de Teams o con la opción "manifiesto unificado" en el generador de Office Yeoman, ya usa el manifiesto unificado.

Asegúrese de que el complemento está listo para convertirse

En las secciones siguientes se describen las condiciones que se deben cumplir antes de convertir el manifiesto.

Asegúrese de que tiene los dos archivos de imagen.

Cuando haya agregado los archivos al proyecto, agregue <IconUrl> y <HighResolutionIconUrl> (en ese orden) al manifiesto de solo complemento justo debajo del <elemento Description> . A continuación se muestra un ejemplo.

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

Asegúrese de que los nombres de comandos de la función sean lo suficientemente cortos

Si el manifiesto tiene algún <elemento FunctionName> , asegúrese de que sus valores tengan menos de 65 caracteres. El valor de este elemento debe coincidir exactamente con el nombre de una función en un archivo JavaScript o TypeScript. Si lo cambia en el manifiesto, asegúrese de cambiarlo también en el archivo de código.

Asegúrese de que el complemento sso solicita permisos

Si el complemento usa el inicio de sesión único de Microsoft con el flujo en nombre de (OBO), el complemento tiene un <elemento Scopes> que especifica microsoft graph u otros permisos de API que necesita el complemento. Con el manifiesto unificado, los permisos se deben solicitar en tiempo de ejecución en el código. Actualice el código según sea necesario para solicitar estos permisos. El código exacto depende de la arquitectura y las bibliotecas de código de autorización que esté usando. Normalmente, el código solicita permisos en una función que solicita un token de acceso.

Herramientas y opciones de conversión

Hay varias maneras de llevar a cabo las tareas restantes, según el IDE y otras herramientas que quiera usar para el proyecto, y en la herramienta que usó para crear el proyecto.

Conversión del proyecto con el kit de herramientas de Teams

La manera más fácil de convertir es usar el kit de herramientas de Teams.

Requisitos previos

Importación del proyecto de complemento al kit de herramientas de Teams

  1. Abra Visual Studio Code y seleccione el icono Kit de herramientas de Teams en la barra de actividad.

    Icono del kit de herramientas de Teams.

  2. Seleccione Crear una nueva aplicación.

  3. En la lista desplegable Nuevo proyecto , seleccione Complemento de Outlook.

    Las cuatro opciones del menú desplegable Nuevo proyecto. La cuarta opción se denomina

  4. En la lista desplegable Características de la aplicación con un complemento de Outlook , seleccione Importar un complemento de Outlook existente.

    Las dos opciones de la lista desplegable Características de la aplicación mediante un complemento de Outlook. La segunda opción se denomina

  5. En la lista desplegable Existing add-in project folder (Proyecto de complemento existente ), vaya a la carpeta raíz del proyecto de complemento.

  6. En la lista desplegable Seleccionar archivo de manifiesto del proyecto de importación , vaya al archivo de manifiesto de solo complemento, normalmente denominado manifest.xml.

  7. En el cuadro de diálogo Carpeta del área de trabajo, seleccione la carpeta donde desea colocar el proyecto convertido.

  8. En el cuadro de diálogo Nombre de la aplicación , asigne un nombre al proyecto (sin espacios). Teams Toolkit crea el proyecto con los archivos de origen y scaffolding. A continuación, abre el proyecto en una segunda ventana Visual Studio Code. Cierre la ventana de Visual Studio Code original.

Transferir localmente el complemento en Visual Studio Code

Puede transferir localmente el complemento mediante el kit de herramientas de Teams o en un símbolo del sistema, un shell de Bash o un terminal.

Transferencia local con el kit de herramientas de Teams
  1. En primer lugar, asegúrese de que el escritorio de Outlook está cerrado.
  2. En Visual Studio Code, abra el Kit de herramientas de Teams.
  3. En la sección CUENTAS , compruebe que ha iniciado sesión en Microsoft 365.
  4. Seleccione Ver | ejecución en Visual Studio Code. En el menú desplegable EJECUTAR Y DEPURAR, seleccione la opción Outlook Desktop (Edge Chromium) y, a continuación, presione F5. El proyecto se compila y se abre una ventana de servidor de desarrollo de Node. Este proceso puede tardar un par de minutos y, a continuación, se abre el escritorio de Outlook.
  5. Ahora puede trabajar con el complemento. Asegúrese de que está trabajando en la Bandeja de entrada de la identidad de la cuenta de Microsoft 365.
Transferencia local con un símbolo del sistema, un shell de Bash o un terminal
  1. En primer lugar, asegúrese de que el escritorio de Outlook está cerrado.
  2. Abra un símbolo del sistema, el shell de Bash o el Visual Studio Code TERMINAL y vaya a la raíz del proyecto.
  3. Si la sección "scripts" del archivo package.json del proyecto tiene un script "start:desktop", ejecute npm run start:desktop; en caso contrario, ejecute npm run start. El proyecto se compila y se abre una ventana de servidor de desarrollo de Node. Este proceso puede tardar un par de minutos y, a continuación, se abre el escritorio de Outlook.
  4. Ahora puede trabajar con el complemento.
  5. Cuando haya terminado de trabajar con el complemento, asegúrese de ejecutar el comando npm run stop.

Proyectos creados con el generador de Office Yeoman (también conocido como "Yo Office")

Si el proyecto se creó con el generador de Office Yeoman y no quiere usar el kit de herramientas de Teams, conviértalo mediante los pasos siguientes.

  1. En la raíz del proyecto, abra un símbolo del sistema o un shell de Bash y ejecute el siguiente comando. Esto convierte el manifiesto y actualiza el package.json para especificar los paquetes de herramientas actuales. El nuevo manifiesto unificado está en la raíz del proyecto y el manifiesto del complemento anterior solo está en un archivo backup.zip. Para obtener más información sobre este comando, vea Office-Addin-Project.

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

  2. Ejecute npm install.

  3. El comando para transferir localmente el complemento depende de cuándo se creó el proyecto. Si la sección "scripts" del archivo package.json del proyecto tiene un script "start:desktop", ejecute npm run start:desktop; en caso contrario, ejecute npm run start. Este comando coloca el manifiesto unificado y los dos archivos de imagen en un archivo ZIP y lo carga de forma local en la aplicación de Office. También inicia el servidor en una ventana de NodeJS independiente para hospedar los archivos de complemento en localhost.

Cuando esté listo para detener el servidor de desarrollo y desinstalar el complemento, ejecute el comando npm run stop.

Proyectos de NodeJS y npm que no se crean con Yeoman Generator

Si no desea usar el kit de herramientas de Teams y el proyecto no se creó con el generador de Office Yeoman, use la herramienta office-addin-manifest-converter.

En la raíz del proyecto, abra un símbolo del sistema o un shell de Bash y ejecute el siguiente comando. Este comando coloca el manifiesto unificado en una subcarpeta con el mismo nombre que la raíz de nombre de archivo del manifiesto original de solo complemento. Por ejemplo, si el manifiesto se denomina MyManifest.xml, el manifiesto unificado se crea en .\MyManifest\MyManifest.json. Para obtener más información sobre este comando, vea Office-Addin-Manifest-Converter.

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

Una vez creado el manifiesto unificado, hay dos maneras de crear el archivo zip y transferirlo localmente. Se describen en las dos subsecciones siguientes.

Instalación local con la herramienta Office-Addin-Debugging

  1. Para transferir localmente el complemento, ejecute el siguiente comando. Este comando coloca el manifiesto unificado y dos archivos de imagen de icono predeterminados en un archivo ZIP y lo carga localmente en la aplicación de Office. También inicia un servidor en una ventana de NodeJS independiente para hospedar los archivos de complemento en localhost. Tenga en cuenta que pasa la ruta de acceso al manifiesto unificado que creó en el paso anterior. Para obtener más información sobre este comando, vea Office-Addin-Debugging.

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

  2. Cuando use office-addin-debugging para iniciar un complemento, detenga siempre la sesión con el siguiente comando. El cierre de la ventana del servidor no detiene el servidor de forma confiable y el cierre de la aplicación de Office no hace que Office desconocierte el complemento de forma confiable.

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

Transferencia local con la CLI del kit de herramientas de Teams (interfaz de línea de comandos)

  1. Cree manualmente el paquete zip mediante los pasos siguientes.

    1. Abra el manifiesto unificado y desplácese hasta la propiedad "icons". Observe la ruta de acceso relativa de los dos archivos de imagen.
    2. Use cualquier utilidad zip para crear un archivo ZIP que contenga el manifiesto unificado y los dos archivos de imagen. Los archivos de imagen deben tener la misma ruta de acceso relativa en el archivo ZIP que en el proyecto. Por ejemplo, si la ruta de acceso relativa es "assets/icon-64.png" y "assets/icon-128.png", debe incluir la carpeta "assets" con los dos archivos en el paquete zip.
    3. Si la carpeta contiene otros archivos, como los archivos de imagen usados en la cinta de Opciones de Office, quítelos del paquete zip. Solo debe tener los dos archivos de imagen especificados en la propiedad "icons" (además del manifiesto en la raíz del paquete zip).

  2. En la raíz del proyecto, abra un símbolo del sistema o un shell de Bash y ejecute los siguientes comandos.

    npm install -g @microsoft/teamsapp-cli

teamsapp install --file-path <relative-path-to-zip-file>

  3. Cuando use la CLI del kit de herramientas de Teams para iniciar un complemento, detenga siempre la sesión con el siguiente comando. El cierre de la ventana del servidor no detiene el servidor de forma confiable y el cierre de la aplicación de Office no hace que Office desconocierte el complemento de forma confiable. Reemplace el "{GUID del complemento}" por el GUID en la propiedad "id" del manifiesto unificado.

    teamsapp uninstall -manifest-id {GUID of the add-in}