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.

Nota:

Nota:

El manifiesto unificado para Microsoft 365 se puede usar en complementos de Outlook de producción. Solo está disponible como versión preliminar para excel, PowerPoint y complementos de Word.

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 dos archivos de imagen de icono (descritos más adelante) en un archivo ZIP para realizar la instalación local o la implementación. En función de cómo realice la transferencia local del complemento convertido, esta tarea puede realizarse automáticamente.

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.

Desinstalación de la versión existente del complemento

Para evitar conflictos con los nombres de control de interfaz de usuario y otros problemas, asegúrese de que el complemento existente no está instalado en el equipo donde realiza la conversión.

Asegúrese de que tiene dos archivos de imagen especiales

Si el manifiesto de solo complemento no tiene <elementos IconUrl> y <HighResolutionIconUrl> (en ese orden), agréguelos justo debajo del <elemento Description> . Los valores del atributo DefaultValue deben ser las direcciones URL completas de los archivos de imagen. Las imágenes deben tener un tamaño especificado, como se muestra en la tabla siguiente.

Aplicación de Office <IconUrl> <HighResolutionIconUrl>
Outlook 64 x 64 píxeles 128x128 píxeles
Todas las demás aplicaciones de Office
 32x32 píxeles 64 x 64 píxeles

El marcado siguiente es 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 -->

Actualizar el identificador, la versión, el dominio y los nombres de función del complemento en el manifiesto

  1. Cambie el valor del <ID> elemento a un nuevo GUID aleatorio.

  2. Actualice el valor del <Version> elemento y asegúrese de que se ajusta al estándar semver (MAJOR. MENOR. PATCH). Cada segmento no puede tener más de cinco dígitos. Por ejemplo, cambie el valor 1.0.0.0 a 1.0.1. No se admiten las extensiones de cadena de versión preliminar y de metadatos del estándar semver.

  3. Asegúrese de que el segmento de dominio de las direcciones URL del complemento en el manifiesto apunta a https://localhost:3000.

  4. Si el manifiesto tiene algún <elemento FunctionName> , asegúrese de que sus valores tengan menos de 65 caracteres.

    Importante

    El valor de este elemento debe coincidir exactamente con el nombre de una acción asignada a una función de un archivo JavaScript o TypeScript con la función Office.actions.associate . Si lo cambia en el manifiesto, asegúrese de cambiarlo en el actionId parámetro pasado a associate() también.

Comprobación de que el manifiesto de solo complemento modificado funciona

  1. Valide el manifiesto modificado de solo complemento. Vea Validar el manifiesto de un complemento de Office.

  2. Compruebe que el complemento se puede transferir localmente y ejecutarse. Consulte Transferir localmente un complemento de Office para realizar pruebas.

Resuelva los problemas antes de intentar convertir el proyecto.

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. Se abre el menú desplegable Nuevo proyecto . Las opciones enumeradas variarán en función de la versión del kit de herramientas de Teams. Seleccione Complemento de Office.

    Las opciones del menú desplegable Nuevo proyecto. Una opción se denomina

  4. Se abre el menú desplegable Características de la aplicación con un complemento de Office . Las opciones enumeradas variarán en función de la versión del kit de herramientas de Teams. Seleccione Importar un complemento de Office existente.

    Las opciones del menú desplegable Características de la aplicación mediante un complemento de Office. Una opción se denomina

  5. En el menú desplegable Carpeta del proyecto de complemento existente , vaya a la carpeta raíz del proyecto de complemento.

  6. En el menú 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. Para más información, vea:

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.

Convertir proyectos creados con el generador de Yeoman para complementos de Office (también conocido como "Yo Office")

Si el proyecto se creó con el generador de Yeoman para complementos de Office 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. Para transferir localmente el complemento, consulte Instalación local de complementos creados con el generador de Yeoman para complementos de Office (Yo Office).

Conversión de proyectos NodeJS y npm que no se crearon con el generador de Yeoman para complementos de Office (Yo Office)

Si no quiere usar el kit de herramientas de Teams y el proyecto no se creó con Yo Office, 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. Para obtener más información, vea Transferir localmente otros proyectos de NodeJS y npm.

Pasos siguientes

Considere si desea mantener las versiones antigua y nueva del complemento. Consulte Administración de un manifiesto unificado y una versión de manifiesto de solo complemento del complemento de Office.