Share via

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

  • Artículo

Para agregar funcionalidades de Teams a un complemento que usa el manifiesto XML, 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 desde el manifiesto XML al manifiesto unificado.

  • Asegúrese de que el complemento está listo para convertirse.
  • Convierta el propio manifiesto 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 (versión preliminar) 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, si el manifiesto tiene una propiedad "alternateIcons" válida, se genera un manifiesto XML a partir del manifiesto unificado y se almacena. Este manifiesto XML 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 XML 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.

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 Create 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 de proyecto de importación , vaya al archivo de manifiesto 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. Ejecute el comando npm run start:desktop. 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.

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 XML antiguo 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. Para transferir localmente el complemento, ejecute npm run start:desktop. 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.

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 del nombre de archivo del manifiesto XML original. 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 -m <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/teamsfx-cli

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