Depurar complementos de Office en Visual Studio

En este artículo se describe cómo depurar código del lado cliente en complementos de Office creados con una de las plantillas de proyecto de complemento de Office en Visual Studio 2022. Para obtener información sobre la depuración de código del lado servidor en complementos de Office, vea Información general sobre la depuración de complementos de Office en el lado servidor o en el lado cliente.

Nota:

No puede usar Visual Studio para depurar complementos en Office en Mac. Para obtener información sobre la depuración en un Equipo Mac, vea Depurar complementos de Office en un Equipo Mac.

Revisar las propiedades de compilación y depuración

Antes de iniciar la depuración, revise las propiedades de cada proyecto para confirmar que Visual Studio abrirá la aplicación de Office deseada y que otras propiedades de compilación y depuración se establecen correctamente.

Propiedades de un proyecto de complemento

Abra la ventana Propiedades del proyecto del complemento para revisar las propiedades del proyecto.

1. En el Explorador de soluciones, elija el proyecto del complemento (no el proyecto de la aplicación web).

2. En la barra de menús, elija Ver>Ventana Propiedades.

En la tabla siguiente se describen las propiedades del proyecto de complemento.

Propiedad	Descripción
Acción de inicio	Especifica el modo de depuración para el complemento. Debe establecerse en Cliente de escritorio de Office cuando quiera depurar en Microsoft 365 en Windows. Para depurar en Microsoft 365 en la web, debe establecerse en Microsoft Edge.
Documento de inicio (Solo complementos de Excel, PowerPoint y Word)	Especifica qué documento debe abrirse cuando inicia el proyecto. En un nuevo proyecto, se establece en [Nuevo libro de Excel], [Nuevo documento de Word] o [Nueva presentación de PowerPoint]. Para especificar un documento determinado, siga los pasos descritos en Uso de un documento existente para depurar el complemento.
Proyecto web	Especifica el nombre del proyecto web asociado con el complemento.
Dirección de correo electrónico (Solo complementos de Outlook)	Especifica la dirección de correo electrónico de la cuenta de usuario en Exchange Server o Exchange Online con la que quiere probar el complemento de Outlook. Si se deja en blanco, se le pedirá la dirección de correo electrónico al iniciar la depuración.
Dirección Url de EWS (Solo complementos de Outlook)	Especifica la dirección URL de Los servicios web de Exchange (por ejemplo: https://www.contoso.com/ews/exchange.aspx). Esta propiedad se puede dejar en blanco.
Dirección Url de OWA (Solo complementos de Outlook)	Especifica la dirección URL de Outlook en la web (por ejemplo: https://www.contoso.com/owa). Esta propiedad se puede dejar en blanco.
Usar la autenticación multifactor (Solo complementos de Outlook)	Especifica el valor booleano que indica si se debe usar la autenticación multifactor. El valor predeterminado es false, pero la propiedad no tiene ningún efecto práctico. Si normalmente tiene que proporcionar un segundo factor para iniciar sesión en la cuenta de correo electrónico, se le pedirá al iniciar la depuración.
Nombre de usuario (Solo complementos de Outlook)	Especifica el nombre de la cuenta de usuario en Exchange Server o Exchange Online con la que quiere probar el complemento de Outlook. Esta propiedad se puede dejar en blanco.
Archivo de proyecto	Especifica el nombre del archivo que contiene la compilación, configuración y otra información sobre el proyecto.
Carpeta de proyecto	Especifica la ubicación del archivo de proyecto.
Configuración de implementación activa (presente solo al depurar Excel, PowerPoint o Word en la web)	Especifica la configuración de implementación. Debe establecerse en Predeterminado.
Conexión del servidor (presente solo al depurar Excel, PowerPoint o Word en la web)	Especifica si el proyecto se conecta al servicio de SharePoint especificado en la propiedad Url del sitio . Debe establecerse en En línea.
Dirección URL del sitio (presente solo al depurar Excel, PowerPoint o Word en la web)	Especifica la dirección URL completa y absoluta del inquilino de SharePoint que desea hospedar las páginas del complemento al depurar. Por ejemplo https://mysite.sharepoint.com/

Nota:

Para un complemento de Outlook, puede elegir especificar valores para una o varias de las propiedades solo de los complementos de Outlook en la ventana Propiedades , pero no es necesario hacerlo.

Propiedades del proyecto de aplicación web

Abra la ventana Propiedades del proyecto de aplicación web para revisar las propiedades del proyecto.

1. En el Explorador de soluciones, elija el proyecto de aplicación web.

2. En la barra de menús, elija Ver>Ventana Propiedades.

La siguiente tabla describe las propiedades del proyecto de aplicación web más relevantes para proyectos de complementos de Office.

Propiedad	Descripción
SSL habilitado	Especifica si SSL está habilitado en el sitio. Debe establecer esta propiedad en True para proyectos de complementos de Office.
Dirección URL de SSL	Especifica la dirección URL HTTPS segura para el sitio. Solo lectura.
URL	Especifica la dirección URL HTTP para el sitio. Solo lectura.
Archivo de proyecto	Especifica el nombre del archivo que contiene la compilación, configuración y otra información sobre el proyecto.
Carpeta de proyecto	Especifica la ubicación del archivo de proyecto. Solo lectura. El archivo de manifiesto que genera Visual Studio durante el tiempo de ejecución se escribe en la carpeta bin\Debug\OfficeAppManifests en esta ubicación.

Depuración de un proyecto de complemento en el escritorio de Windows

En esta sección se describe cómo iniciar y depurar un complemento en Office de escritorio en Windows; es decir, cuando la propiedad Acción de inicio del proyecto de complemento se establece en Cliente de escritorio de Office.

Inicio del proyecto de complemento

Inicie el proyecto eligiendo Depurar>Iniciar depuración en la barra de menús o presione el botón F5. Visual Studio compila automáticamente la solución e inicia la aplicación host de Office.

Cuando Visual Studio compila el proyecto, realiza las siguientes tareas:

1. Crea una copia del archivo de manifiesto de solo complemento y lo agrega al _ProjectName_\bin\Debug\OfficeAppManifests directorio. La aplicación de Office que hospeda el complemento consume esta copia al iniciar Visual Studio y depurar el complemento.

2. Crea un conjunto de entradas del Registro en el equipo Windows que permite que el complemento aparezca en la aplicación de Office.

3. Compila el proyecto de aplicación web y, a continuación, lo implementa en el servidor web iis local (https://localhost).

4. Si este es el primer proyecto de complemento que ha implementado en el servidor web iis local, es posible que se le pida que instale un certificado de Self-Signed en el almacén de certificados raíz de confianza del usuario actual. Esto es necesario para que IIS Express muestre el contenido de su complemento correctamente.

Nota:

Si Office usa el control webview heredado de Edge (EdgeHTML) para ejecutar complementos en el equipo Windows, Visual Studio puede solicitarle que agregue una exención de bucle invertido de red local. Esto es necesario para que el control de vista web pueda acceder al sitio web implementado en el servidor web de IIS local. También puede cambiar esta configuración en cualquier momento en Visual Studio en Herramientas>Opciones>Herramientas de Office (Web)>Depuración de complemento web. Para averiguar qué control de vista web se usa en el equipo Windows, consulte Exploradores y controles de vista web que usan los complementos de Office.

Luego, Visual Studio lleva a cabo las acciones siguientes:

1. Modifica el elemento SourceLocation del archivo de manifiesto de solo complemento (que se copió en el _ProjectName_\bin\Debug\OfficeAppManifests directorio) reemplazando el ~remoteAppUrl token por la dirección completa de la página de inicio (por ejemplo, https://localhost:44302/Home.html).

2. Inicia el proyecto de aplicación web en IIS Express.

3. Valida el manifiesto.

   Importante

   Si recibe errores de validación para el manifiesto, es posible que los archivos de esquema de manifiesto de Visual Studio no se hayan actualizado para admitir las características más recientes. El primer paso para solucionar problemas debe ser reemplazar uno o varios de estos archivos por las versiones más recientes. Para obtener instrucciones detalladas, vea Manifiesto de errores de validación de esquemas en proyectos de Visual Studio.

4. Abre la aplicación de Office y descarga localmente el complemento.

Depuración del complemento

El mejor método para depurar un complemento en Visual Studio 2022 depende de si el complemento se ejecuta en WebView2, que es el control webview asociado a Microsoft Edge (Chromium) o a un control webview anterior. Para determinar qué control de vista web se usa, vea Exploradores y controles de vista web que usan los complementos de Office. Si el equipo usa WebView2, consulte Uso del depurador integrado de Visual Studio para depurar en el escritorio. Para cualquier otro control de vista web, consulte Uso de las herramientas de desarrollo del explorador para depurar en el escritorio.

Uso del depurador integrado de Visual Studio para depurar en el escritorio

1. Establezca puntos de interrupción, según sea necesario, en los archivos JavaScript o TypeScript de origen. Puede hacerlo antes o después de iniciar el complemento, como se describe en la sección anterior Inicio del proyecto de complemento. Si la configuración de un punto de interrupción hace que el servidor de Internet Information Services (IIS) se apague, reinicie la depuración después de establecer los puntos de interrupción.

2. Cuando el complemento se esté ejecutando, use la interfaz de usuario del complemento para ejecutar el código que contiene los puntos de interrupción.

Importante

Los puntos de interrupción establecidos en Office.initialize o Office.onReady no se alcanzan. Para depurar estos métodos, vea Depurar las funciones initialize y onReady.

Sugerencia

Si encuentra algún problema, hay más información en Depuración de una aplicación JavaScript o TypeScript en Visual Studio.

Uso de las herramientas de desarrollo del explorador para depurar en el escritorio

1. Siga los pasos descritos en la sección anterior Iniciar el proyecto de complemento.

2. Inicie el complemento en la aplicación de Office si aún no está abierto. Por ejemplo, si es un complemento de panel de tareas, habrá agregado un botón a la cinta de opciones Inicio (por ejemplo, un botón Mostrar panel de tareas ). Seleccione el botón de la cinta de opciones.

   Nota:

   Si Visual Studio no carga de forma local el complemento, puede transferirlo de forma local manualmente. Siga las instrucciones para transferir localmente un complemento de Office para realizar pruebas para su plataforma.

   En la lista de complementos disponibles, busque la sección de complementos para desarrolladores y seleccione el complemento para registrarlo.

   Sugerencia

   El panel de tareas puede aparecer en blanco cuando se abre por primera vez. Si es así, debe representarse correctamente al iniciar las herramientas de depuración en un paso posterior.

3. Abra el menú Personalidad y, a continuación, elija Asociar un depurador. Esta acción abre las herramientas de depuración para el control de vista web que Office usa para ejecutar complementos en el equipo Windows. Puede establecer puntos de interrupción y recorrer el código como se describe en uno de los artículos siguientes:

   • Depuración de complementos con herramientas de desarrollo para Internet Explorer
   • Depuración de complementos con herramientas de desarrollo para Edge (versión heredada)
   • Depuración de complementos con herramientas de desarrollo para Microsoft Edge (Chromium)

4. Para realizar cambios en el código, detenga primero la sesión de depuración en Visual Studio y cierre la aplicación de Office. Realice los cambios e inicie una nueva sesión de depuración.

Depuración de un proyecto de complemento en Microsoft 365 en la web

En esta sección se describe cómo iniciar y depurar un complemento en Office de escritorio en la web; es decir, cuando la propiedad Acción de inicio del proyecto de complemento se establece en Microsoft Edge.

Inicio del proyecto de complemento en la web

Inicie el proyecto eligiendo Depurar>Iniciar depuración en la barra de menús o presione el botón F5. Visual Studio compila automáticamente la solución e inicia la página host de la aplicación de Office del inquilino de Microsoft 365.

Nota:

Al depurar un complemento en la web, puede obtener un error AADSTS50011 similar al siguiente:

"El URI {Full absolute URL to add-in home page} de redireccionamiento especificado en la solicitud no coincide con los URI de redireccionamiento configurados para la aplicación... "

Esto ocurre porque las nuevas aplicaciones web implementadas en SharePoint pueden tardar hasta 24 horas en estar disponibles. Para que el complemento se pueda depurar inmediatamente, siga estos pasos:

1. Detener la depuración en Visual Studio.

2. Cree un script de PowerShell con las líneas siguientes. Reemplace el marcador de posición {Full absolute URL to add-in home page} por la dirección URL de redireccionamiento en el mensaje de error; por ejemplo, "https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx".

   Connect-MgGraph -Scopes Application.ReadWrite.All
   $sharepointPrincipal = Get-MgServiceprincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'"
   $sharepointPrincipal | fl
   $replyUrls = $sharepointPrincipal.ReplyUrls
   $replyUrls += "{Full absolute URL to add-in home page}"
   Update-MgServiceprincipal -ServicePrincipalId $sharepointPrincipal.Id -ReplyUrls $replyUrls
   

3. Ejecute el script en PowerShell.

4. Reinicie el proyecto eligiendo Depurar>Iniciar depuración en la barra de menús o presione el botón F5.

Cuando Visual Studio compila el proyecto, realiza las siguientes tareas.

1. Le pide credenciales de inicio de sesión. Si se le pide que inicie sesión repetidamente o si recibe un error que indica que no está autorizado, es posible que la autenticación básica esté deshabilitada para las cuentas de su inquilino de Microsoft 365. En este caso, intente usar una cuenta de Microsoft en su lugar. También puede intentar establecer la propiedad Usar autenticación multifactor en True en el panel de propiedades del proyecto de complemento. Consulte Propiedades del proyecto de complemento.

2. Crea una copia del archivo de manifiesto de solo complemento y lo agrega al _ProjectName_\bin\Debug\OfficeAppManifests directorio. Microsoft 365 consume esta copia al iniciar Visual Studio y depurar el complemento.

3. Compila el proyecto de aplicación web y, a continuación, lo implementa en el inquilino de Microsoft 365.

Luego, Visual Studio lleva a cabo las acciones siguientes:

1. Modifica el elemento SourceLocation del archivo de manifiesto de solo complemento (que se copió en el _ProjectName_\bin\Debug\OfficeAppManifests directorio) reemplazando el ~remoteAppUrl token por la dirección completa de la página de inicio (por ejemplo, https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx).

2. Inicia el proyecto de aplicación web.

3. Valida el manifiesto.

   Importante

   Si recibe errores de validación para el manifiesto, es posible que los archivos de esquema de manifiesto de Visual Studio no se hayan actualizado para admitir las características más recientes. El primer paso para solucionar problemas debe ser reemplazar uno o varios de estos archivos por las versiones más recientes. Para obtener instrucciones detalladas, vea Manifiesto de errores de validación de esquemas en proyectos de Visual Studio.

4. Abre la página host de la aplicación de Office del inquilino de Microsoft 365 en Microsoft Edge.

Depuración del complemento en la web

El mejor método para depurar un complemento en Visual Studio 2022 depende de si el complemento se ejecuta en WebView2, que es el control webview asociado a Microsoft Edge (Chromium) o a un control webview anterior. Para determinar qué control de vista web se usa, vea Exploradores y controles de vista web que usan los complementos de Office. Si el equipo usa WebView2, consulte Uso del depurador integrado de Visual Studio para depurar en la web. Para cualquier otro control de vista web, consulte Uso de las herramientas de desarrollo del explorador para depurar en la web.

Uso del depurador integrado de Visual Studio para depurar en la web

1. Establezca puntos de interrupción, según sea necesario, en los archivos JavaScript o TypeScript de origen. Puede hacerlo antes o después de iniciar el complemento, como se describe en la sección anterior Inicio del proyecto de complemento en la web.

2. Cuando el complemento se esté ejecutando, use la interfaz de usuario del complemento para ejecutar el código que contiene los puntos de interrupción.

Sugerencia

• A veces, en Outlook en la web, el depurador de Visual Studio no se asocia. Si recibe errores por los puntos de interrupción que indican que no se alcanzarán, use las herramientas para desarrolladores del explorador para asociarlos al depurador de Visual Studio: después de presionar F5 para iniciar la depuración y de que Outlook en la web se haya abierto, siga los cuatro primeros pasos de Usar las herramientas de desarrollo del explorador para depurar en la web. (Use las instrucciones para Microsoft Edge (basado en Chromium). Después de establecer un punto de interrupción en las herramientas del explorador y de alcanzarlo, la ejecución se pausa en el punto de interrupción tanto en las herramientas del explorador como en Visual Studio. Esto indica que el depurador de Visual Studio está asociado. En este punto, puede cerrar las herramientas del explorador y agregar puntos de interrupción en Visual Studio como lo haría normalmente.
• Si encuentra algún problema, hay más información en Depuración de una aplicación JavaScript o TypeScript en Visual Studio.

Uso de las herramientas de desarrollo del explorador para depurar en la web

1. Para un complemento en cualquier host excepto Outlook, en la página de la aplicación host de Office, presione F12 para abrir la herramienta de depuración.

2. Para un complemento de Outlook, si el manifiesto del complemento está configurado para una superficie de lectura, seleccione un mensaje de correo electrónico o un elemento de cita para abrirlo en su propia ventana. Si el complemento está configurado solo para una superficie de redacción, abra un mensaje nuevo, responda al mensaje o una nueva ventana de cita. Asegúrese de que la ventana adecuada tiene el foco y presione F12 para aplicar lápiz a la herramienta de depuración.

3. Una vez abierta la herramienta, inicie el complemento. Los pasos exactos varían en función del diseño del complemento. Normalmente, se presiona un botón para abrir un panel de tareas. En Outlook, en la barra de herramientas de la parte superior de la ventana, seleccione el botón Más aplicaciones y, a continuación, seleccione el complemento en la llamada que se abre.

   

4. Use las instrucciones de uno de los artículos siguientes para establecer puntos de interrupción y recorrer el código. Cada uno de ellos tiene un vínculo a instrucciones más detalladas.

   • Depuración de complementos con herramientas de desarrollo para Edge (versión heredada)
   • Depuración de complementos con herramientas de desarrollo para Microsoft Edge (Chromium)

   Sugerencia

   Para depurar código que se ejecuta en la Office.initialize función o una Office.onReady función que se ejecuta cuando se abre el complemento, establezca los puntos de interrupción y, a continuación, cierre y vuelva a abrir el complemento. Para obtener más información sobre estas funciones, vea Inicializar el complemento de Office.

5. Para realizar cambios en el código, detenga primero la sesión de depuración en Visual Studio y cierre las páginas de Outlook. Realice los cambios e inicie una nueva sesión de depuración.

Usar un documento existente para depurar el complemento

Si tiene un documento que contiene datos de prueba que desea usar al depurar el complemento Excel, PowerPoint o Word, Visual Studio puede configurarse para abrir el documento al iniciar el proyecto. Para especificar un documento existente para usar al depurar el complemento, siga los pasos siguientes.

1. En el Explorador de soluciones, elija el proyecto del complemento (no el proyecto de la aplicación web).

2. En la barra de menús, elija Proyecto>Agregar elemento existente.

3. En el cuadro de diálogo Agregar elemento existente, busque y seleccione el documento que quiere agregar.

4. Elija el botón Agregar para agregar el documento al proyecto.

5. En el Explorador de soluciones, elija el proyecto del complemento (no el proyecto de la aplicación web).

6. En la barra de menús, elija Ver>Ventana Propiedades.

7. En la ventana Propiedades, elija la lista Documento de inicio y seleccione el documento que añadió al proyecto. El proyecto ya está configurado para iniciar el complemento en ese documento.

Pasos siguientes

Una vez que el complemento funcione como quiere, vea Implementar y publicar el complemento de Office para ver las formas en las que puede distribuir el complemento a usuarios.