Conversión de un complemento para usar el manifiesto unificado para Microsoft 365
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:
- 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 Yeoman para complementos de Office (Yo Office), ya usa el manifiesto unificado.
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
Cambie el valor del
<ID>
elemento a un nuevo GUID aleatorio.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 valor1.0.0.0
a1.0.1
. No se admiten las extensiones de cadena de versión preliminar y de metadatos del estándar semver.Asegúrese de que el segmento de dominio de las direcciones URL del complemento en el manifiesto apunta a
https://localhost:3000
.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 aassociate()
también.
Comprobación de que el manifiesto de solo complemento modificado funciona
Valide el manifiesto modificado de solo complemento. Vea Validar el manifiesto de un complemento de Office.
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
- 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)
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
- Instalar Visual Studio Code
- Instalación del kit de herramientas de Teams
Importación del proyecto de complemento al kit de herramientas de Teams
Abra Visual Studio Code y seleccione el icono Kit de herramientas de Teams en la barra de actividad.
Seleccione Crear una nueva aplicación.
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.
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.
En el menú desplegable Carpeta del proyecto de complemento existente , vaya a la carpeta raíz del proyecto de complemento.
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.
En el cuadro de diálogo Carpeta del área de trabajo, seleccione la carpeta donde desea colocar el proyecto convertido.
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:
- Transferencia local con el kit de herramientas de Teams
- Transferencia local con un símbolo del sistema, un shell de Bash o un terminal
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.
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>
Ejecute
npm install
.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.