Importación de un proyecto de complemento a Microsoft 365 Agents Toolkit

La extensión Agents Toolkit para Visual Studio Code es una herramienta enriquecida para trabajar con extensiones en la plataforma para desarrolladores de Microsoft 365, incluidas las aplicaciones de Teams, los complementos de Office y las extensiones de Copilot, entre otros. También facilita el trabajo con extensiones que trascienden los límites entre aplicaciones, complementos y extensiones de Copilot de Teams. Por ejemplo, facilita la transferencia local de estas extensiones entre límites.

No puede haber ningún procedimiento algoritmo para importar un complemento en el kit de herramientas porque un algoritmo tendría que hacer suposiciones sobre los siguientes aspectos del proyecto.

• La carpeta y la estructura de archivos del complemento existente. Pero estas estructuras varían en función de qué herramienta se usó para crear el proyecto y qué versión de esa herramienta. Es posible que el desarrollador del complemento también haya cambiado la estructura después de crear el proyecto.
• La configuración de varios archivos de configuración. Pero esta configuración también varía en función de cómo se creó el proyecto y de los cambios realizados en la configuración desde su creación.
• Qué lenguaje, TypeScript o JavaScript, se usó para el código fuente del lado cliente de la aplicación web.

Sin embargo, podemos hacer algunas recomendaciones generales.

Nota:

• Este artículo no se aplica a los proyectos de complemento creados con Visual Studio. Estos proyectos se basan en el marco de aplicación web ASP.NET y están diseñados para ejecutarse en Internet Information Server (IIS). Convertir un proyecto de este tipo para que funcione en Agents Toolkit sería significativamente más difícil y está fuera del ámbito de este artículo.
• Los proyectos de complementos de Agents Toolkit deben usar el manifiesto unificado para Microsoft 365. Si el proyecto de complemento usa una característica que aún no se admite con el manifiesto unificado, no puede importarla al kit de herramientas de agentes a menos que primero la rediseñe para que no use características no admitidas.
• Actualmente, los complementos que usan el manifiesto unificado no se pueden transferir localmente en un Equipo Mac. Si el equipo de desarrollo es un Equipo Mac, no importe el proyecto en Agents Toolkit hasta que se admita la instalación local en mac.

Hay dos estrategias básicas disponibles.

• Uso de la característica de importación del kit de herramientas
• Inicio con un nuevo proyecto de kit de herramientas

Independientemente de cuál elija, empiece por asegurarse de que ha instalado Visual Studio Code y la extensión Agents Toolkit.

Uso de la característica de importación del kit de herramientas

Hay cuatro tareas para usar la característica de importación.

• Preparación del manifiesto existente
• Importación del proyecto
• Compruebe que el complemento se puede transferir localmente.
• Posterior a la importación: Ajuste de la estructura del proyecto según sea necesario

Preparación del manifiesto existente

Importante

Si el proyecto existente usa el manifiesto de solo complemento, la característica de importación la convierte automáticamente en un manifiesto unificado. Por lo tanto, debe realizar los pasos descritos en Asegúrese de que el manifiesto está listo para convertirse antes de importar el proyecto.

Importación del proyecto

1. Abra Visual Studio Code y seleccione el icono del kit de herramientas de agentes en la barra de actividad.

   

2. Seleccione Crear una nueva aplicación.

3. Se abre el menú desplegable Nuevo proyecto . Las opciones enumeradas varían en función de la versión de Agents Toolkit. Seleccione Complemento de Office.

   

4. Se abre el menú desplegable Características de la aplicación con un complemento de Office . Las opciones enumeradas varían en función de la versión de Agents Toolkit. Seleccione Actualizar un complemento de Office existente.

   

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). Agents 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.

Compruebe que el complemento se puede transferir localmente.

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.

Descargue localmente el complemento con las instrucciones de Transferencia local con microsoft 365 Agents Toolkit.

Si encuentra problemas, como paso de solución de problemas, pruebe a transferir localmente con un símbolo del sistema, un shell de Bash o un terminal. Si puede, el problema se aísla en el kit de herramientas.

Es posible que los problemas de instalación de prueba sean el resultado de una estructura de archivos y carpetas, o una configuración, que sean diferentes de lo que normalmente espera agents Toolkit. Vea la sección Posterior a la importación: Ajuste de la estructura y la configuración del proyecto según sea necesario.

Posterior a la importación: ajuste la estructura y la configuración del proyecto según sea necesario

El proceso de importación crea algunas carpetas y archivos que Visual Studio Code o el Kit de herramientas de agentes necesitan, pero no reorganiza los archivos de origen, como archivos HTML, JavaScript y CSS. Tampoco cambia el contenido de los archivos del proyecto, incluidos los archivos de configuración de herramientas. Se recomienda cambiar el proyecto para que coincida con el patrón de proyectos creados en Agents Toolkit. A medida que trabaje, tenga en cuenta los siguientes puntos.

• Los archivos HTML de los proyectos del kit de herramientas no tienen elementos insertados <script> . Solo usan <script> elementos con un src atributo que carga un archivo externo.

• Los archivos de origen de un nuevo proyecto de kit de herramientas se encuentran en una carpeta denominada \src. Dentro de esta carpeta, los archivos de origen se dividen aún más en subcarpetas en función de los tiempos de ejecución en los que se ejecutan normalmente. A continuación se muestra una estructura típica.

  \src
      \commands
         commands.html
         commands.js
      \taskpane
         taskpane.css
         taskpane.html
         taskpane.js
  

• Los proyectos del kit de herramientas de agentes tienen una carpeta denominada \appPackage. El manifiesto y cualquier otro archivo que debe estar en el archivo zip del paquete de la aplicación se encuentran en esta carpeta.

Importante

• Las direcciones URL del manifiesto reflejarán la estructura original del proyecto. Cambie estas direcciones URL según sea necesario si realiza cambios en la estructura de archivos y carpetas.
• Los archivos de configuración de herramientas, como webpack.config.js, pueden tener direcciones URL. Cámbielas según sea necesario.

Inicio con un nuevo proyecto de kit de herramientas

Como alternativa al uso de la característica de importación del kit de herramientas, puede crear un nuevo proyecto de complemento en el kit de herramientas y mover archivos del proyecto existente a él y realizar cambios en otros archivos. A continuación se muestran las tareas que debe llevar a cabo.

1. Si el proyecto existente usa el manifiesto de solo complemento, conviértalo. Consulte Conversión de un complemento para usar el manifiesto unificado para Microsoft 365.

2. Cree un nuevo proyecto de complemento en Agents Toolkit. Para cada elección que el kit de herramientas le pida, como la elección entre JavaScript y TypeScript, elija la opción que mejor coincida con el complemento existente. Consulte Creación de proyectos de complementos de Office con Microsoft 365 Agents Toolkit.

3. Reemplace el manifiesto de la carpeta \appPackage del nuevo proyecto por el manifiesto convertido.

   Nota:

   Si el proceso de conversión produjo archivos de cadena de idioma, como fr-fr.json, agréguelos a la carpeta \appPackage .

4. Reemplace los archivos de la carpeta \src del nuevo proyecto por los archivos de origen del proyecto anterior. Para maximizar la compatibilidad con los archivos de configuración del nuevo proyecto, se recomienda dividir los archivos de origen en subcarpetas en función de los tiempos de ejecución en los que se ejecutan normalmente. Por ejemplo, tiene carpetas independientes para los archivos de origen de los comandos de función, el panel de tareas, los eventos de ejecución automática y las funciones personalizadas de Excel.

5. Edite el manifiesto para asegurarse de que las direcciones URL del mismo sean compatibles con la nueva estructura del proyecto.

6. Inspeccione los archivos de configuración del nuevo proyecto para asegurarse de que son compatibles con la organización del proyecto.

   Sugerencia

   Cuando el proyecto antiguo y el nuevo tengan un archivo de configuración con el mismo nombre (por ejemplo ,babel.config.json), use una herramienta de comparación de archivos ("diff") para buscar las diferencias. Para cada diferencia, determine qué archivo es correcto para el nuevo proyecto y cambie el archivo en el nuevo proyecto según sea necesario.

7. Es probable que elwebpack.config.js necesite edición. No es posible proporcionar reglas universales para ese archivo, pero en la mayoría de los casos se aplican los siguientes principios.

   • Asegúrese de que las direcciones URL coincidan con la estructura del proyecto.
   • Asegúrese de que hay una entry subpropiedad para cada subcarpeta en la carpeta \src .
   • Asegúrese de que la plugins matriz también tenga en cuenta cada subcarpeta en la carpeta \src .
   • Asegúrese de que las extensions propiedades y rules tienen en cuenta los tipos de archivo del proyecto que deben controlar los cargadores y empaquetar.

8. Asegúrese de que puede transferir localmente el complemento en el nuevo proyecto. Consulte Comprobación de que el complemento se puede transferir localmente.