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

Para actualizar un complemento que usa el manifiesto de solo complemento a una aplicación completa para Microsoft 365 a la que puede agregar funcionalidades de Teams o una extensión de Copilot, debe convertirlo para usar el manifiesto unificado para Microsoft 365.

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

• Asegúrese de que el manifiesto está listo para convertirse.
• Convierta el propio manifiesto del complemento con formato XML al formato JSON del manifiesto unificado.
• Edite el manifiesto unificado recién creado.
• Empaquete el nuevo manifiesto y dos archivos de imagen de icono (descritos más adelante) en un archivo de paquete de aplicación (zip) para 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.

Asegúrese de que el manifiesto 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. Si tiene dificultades para desinstalar el complemento, consulte Eliminación de un complemento fantasma.

Asegúrese de que tiene dos archivos de imagen especiales

Si el manifiesto de solo complemento no tiene elementos y <IconUrl><HighResolutionIconUrl> (en ese orden), agréguelos justo debajo del <Description> elemento . 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.

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

Reducir el número de comandos de complemento según sea necesario

Es posible que un complemento que usa el manifiesto unificado no tenga más de 20 comandos de complemento. Si el número total de <Action> elementos del manifiesto de solo complemento es mayor que 20, debe rediseñar el complemento para que no tenga más de 20.

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 <FunctionName> elemento, 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.

Acortar los valores de cadena según sea necesario

Revise y cambie, según sea necesario, los valores de manifiesto a la luz de los siguientes efectos de la conversión.

• Los primeros 30 caracteres de <DisplayName> se convierten en el valor de "name.short" en el manifiesto unificado.
• Los primeros 100 caracteres de <DisplayName> se convierten en el valor de "name.full" en el manifiesto unificado.
• Los primeros 250 caracteres de <Description> se convierten en el valor de "description.short" en el manifiesto unificado.
• Los primeros 4000 caracteres de <Description> se convierten en el valor de "description.full" en el manifiesto unificado.
• Los primeros 32 caracteres de <ProviderName> se convierten en el valor de "developer.name" en el manifiesto unificado.

Garantizar la conformidad de la configuración de funciones personalizadas

Si el complemento tiene funciones personalizadas, incluye un archivo de configuración JSON. En el pasado, Office o Microsoft Marketplace no siempre aplicaban algunos requisitos para este archivo, pero todos se aplican cuando el complemento tiene un manifiesto unificado. Antes de convertir el manifiesto, asegúrese de que este archivo JSON se ajusta a todos los requisitos. Para obtener más información, consulte Asignación de nombres y localización de funciones personalizadas y Creación manual de metadatos JSON para funciones personalizadas.

En concreto, tenga en cuenta que todos los nombres de función y los identificadores de función deben tener al menos 3 caracteres y que cada objeto de función debe tener una propiedad "result".

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.

• Convertir proyectos creados con el generador de Yeoman para complementos de Office (también conocido como "Yo Office")
• Conversión de proyectos NodeJS y npm que no se crearon con el generador de Yeoman para complementos de Office (Yo Office)

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, 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. Siga los pasos descritos en Editar el nuevo manifiesto unificado.

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

Si el proyecto no se creó con Yo Office, use la herramienta office-addin-manifest-converter.

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

2. Siga los pasos descritos en Editar el nuevo manifiesto unificado.

Edición del nuevo manifiesto unificado

1. Abra el archivo de manifiesto unificado.

2. Actualice las "$schema" propiedades y "manifestVersion" en la parte superior del archivo para usar la versión más reciente publicada o la versión preliminar. Estos son algunos ejemplos:

   "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.24/MicrosoftTeams.schema.json#",
   "manifestVersion": "1.24",
   

   "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json#",
   "manifestVersion": "devPreview",
   

   Nota:

   Trate estos dos valores de propiedad como distinguen mayúsculas de minúsculas.

3. Vaya a la "developer" propiedad y asegúrese de que hay elementos secundarios "privacyUrl" y "termsOfUseUrl" propiedades. Estas propiedades deben tener los valores adecuados con un dominio localhost.

4. Ahora puede transferir localmente el complemento.

Transferir el complemento localmente

El proceso de transferencia local depende de cómo se creó el proyecto.

Transferir localmente un complemento creado con el generador de Yeoman para complementos de Office

1. Ejecute npm install.
2. Para transferir localmente el complemento, consulte Instalación local de complementos creados con el generador de Yeoman para complementos de Office (Yo Office). El archivo zip del paquete de la aplicación se crea automáticamente como parte de este proceso.

Transferir localmente nodeJS y npm proyectos que no se crearon con el generador de Yeoman para complementos de Office

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.