Depurar soluciones de SharePoint Framework en páginas modernas de SharePoint

Al compilar soluciones de SharePoint Framework, puede probarlas en páginas modernas de SharePoint. Para compilar extensiones de SharePoint Framework, la única posibilidad es probarlas en páginas modernas, ya que en este momento, SharePoint Workbench no admite la carga de extensiones. Pero las pruebas en páginas modernas pueden usarse también para depurar elementos web cuando ofrecen a los desarrolladores un valor adicional.

Importante

Aunque no existen restricciones técnicas para depurar soluciones de SharePoint Framework local en páginas modernas de SharePoint, debe tener cuidado al usarlo en el espacio empresarial de producción. Esta función le permite ejecutar código que no se ha probado y verificado según las directivas de la organización y podría resultar perjudicial para los datos de producción.

Depurar extensiones de SharePoint Framework en páginas modernas de SharePoint

En este momento, se puede depurar una extensión SharePoint Framework en páginas modernas de SharePoint. Según la versión de SharePoint Framework que use, hay distintas formas de depurar extensiones en páginas modernas.

Depurar extensiones mediante la configuración de serve

Cuando agrega una extensión de SharePoint Framework a su proyecto, el generador de Yeoman de SharePoint Framework extenderá la configuración de su proyecto. Con esta configuración, puede iniciar automáticamente una página de SharePoint moderna en su navegador web con todos los parámetros necesarios para depurar la extensión en esa página ya presente.

Cómo funciona

Al agregar una nueva extensión de SharePoint Framework a un proyecto, el generador de Yeoman de SharePoint Framework agregará una nueva entrada al archivo config/serve.json del proyecto. Un ejemplo de entrada tiene el siguiente aspecto:

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    }
  }
}

Junto a la configuración predeterminada, el generador de Yeoman de SharePoint Framework creará una entrada para cada extensión que se agregue a un proyecto. Cada entrada contiene una dirección URL de la página moderna que debe usarse para probar la extensión concreta, la lista de extensiones que debe cargarse y, para cada extensión, la lista de propiedades que debe establecerse en ellas. Para usar la configuración de serve concreta, ejecute en la línea de comandos:

gulp serve --config=<name>

Por ejemplo:

gulp serve --config=helloWorld

Después de ejecutar este comando, gulp iniciará el explorador web con la página moderna especificada en la configuración. La página mostrará un cuadro emergente que le pide que confirme que ahora va a cargar scripts de depuración.

Cuando lo confirme, la página cargará las extensiones especificadas en la configuración de serve.

Deshabilitar scripts de depuración

De forma predeterminada, una vez que se habilitan los scripts de depuración y se les da permiso por primera vez en una página, el permiso se extenderá durante toda la sesión del explorador. Para deshabilitar la carga de scripts de depuración sin tener que finalizar la sesión del explorador o eliminar manualmente los datos de la sesión, incluya el parámetro de URL reset=true en la solicitud.

Depurar extensiones creando manualmente la dirección URL de depuración

Si trabaja con una versión de SharePoint Framework anterior a 1.3.0 y quiere depurar una extensión en una página moderna, tiene que crear manualmente la dirección URL con los parámetros necesarios. En primer lugar, inicie el servidor gulp local cambiando, en la línea de comandos, el directorio de trabajo a la carpeta del proyecto y luego ejecute:

gulp serve --nobrowser

Después, en el explorador web, navegue a la página moderna en la que quiere probar la extensión. Después de cargar la página, copie su dirección URL. Según el tipo de extensión que quiera probar, hay distintos parámetros que ha de agregar a la dirección URL.

Depurar el personalizador de aplicación

Para depurar un Personalizador de aplicaciones, agregue lo siguiente a la URL de su página moderna:

Precaución

Se agregaron saltos de línea y sangría al siguiente fragmento para facilitar la lectura. El texto siguiente debe estar en una sola línea sin espacios en blanco.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
    "location":"<extensionType>",
    "properties":<propertiesJSON>
}}

Por ejemplo:

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
    ?loadSPFX=true
    &debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={
        "e5625e23-5c5a-4007-a335-e6c2c3afa485":{
          "location":"ClientSideExtension.ApplicationCustomizer",
          "properties":{
            "testMessage":"Hello as property!"
          }
        }
    }

Estos son los parámetros de cadena de consulta que tiene que agregar:

Parámetro	Descripción
loadSPFX=true	Garantiza que se carga SharePoint Framework en la página. Por motivos de rendimiento, el marco no se carga a no ser que se registre por lo menos una extensión. Dado que no hay componentes registrados, debe cargar de forma explícita el marco.
debugManifestsFile	Especifica que quiere cargar componentes que se sirven de forma local. El cargador solo busca componentes en el catálogo de aplicaciones (para la solución implementada) y en el servidor del manifiesto de SharePoint (para las bibliotecas del sistema).
customActions	Simula una acción personalizada. Al implementar y registrar este componente en un sitio, creará este objeto CustomAction y describirá las diferentes propiedades que puede establecer en él.

El parámetro customActions tiene los siguientes tokens que deben reemplazarse:

Token	Description
<extensionId>	Use el GUID de la extensión como clave para asociar a la acción personalizada. Esto ha de coincidir con el valor de identificador de la extensión, que está disponible en la extensión archivo manifest.json.
<extensionType>	Tipo de acción personalizada. Use ClientSideExtension.ApplicationCustomizer para la extensión del personalizador de aplicación.
<propertiesJSON>	Un objeto JSON opcional que contiene propiedades que están disponibles a través del miembro this.properties.

Con los parámetros agregados a la dirección URL, vuelva a cargar la página en el explorador web. La página mostrará un cuadro emergente que le pide que confirme que ahora va a cargar scripts de depuración.

Cuando lo confirme, la página cargará las extensiones especificadas en la configuración de serve.

Depurar personalizador de campo

Para depurar un personalizador de campo, agregue lo siguiente a la URL de su página moderna:

Precaución

Se agregaron saltos de línea y sangría al siguiente fragmento para facilitar la lectura. El texto siguiente debe estar en una sola línea sin espacios en blanco.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={
    "<fieldName>":{
      "id":"<fieldCustomizerId>",
      "properties":<propertiesJSON>
    }
}

Por ejemplo:

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &fieldCustomizers={
    "Percent":{
      "id":"45a1d299-990d-4917-ba62-7cb67158be16",
      "properties":{
        "sampleText":"Hello!"
      }
    }
  }

Estos son los parámetros de cadena de consulta que tiene que agregar:

Parámetro	Descripción
loadSPFX=true	Garantiza que se carga SharePoint Framework en la página. Por motivos de rendimiento, el marco no se carga a no ser que se registre por lo menos una extensión. Dado que no hay componentes registrados, debe cargar de forma explícita el marco.
debugManifestsFile	Especifica que quiere cargar componentes que se sirven de forma local. El cargador solo busca componentes en el catálogo de aplicaciones (para la solución implementada) y en el servidor del manifiesto de SharePoint (para las bibliotecas del sistema).
fieldCustomizers	Indica qué campos de la lista deben tener su representación controlada por el personalizador de campo. El parámetro ID especifica el GUID de la extensión que se debe usar para controlar la representación del campo. El parámetro propiedades es una cadena de texto opcional que contiene un objeto JSON que se deserializa en this.properties para la extensión.

El parámetro fieldCustomizers tiene los siguientes tokens que deben reemplazarse:

Token	Description
<fieldName>	El nombre interno del campo.
<fieldCustomizerId>	GUID de la extensión Field Customizer asociada a este campo.
<propertiesJSON>	Valores de propiedad que se definen en la extensión. En este ejemplo, sampleText es una propiedad que define la extensión.

Con los parámetros agregados a la dirección URL, vuelva a cargar la página en el explorador web. La página mostrará un cuadro emergente que le pide que confirme que ahora va a cargar scripts de depuración.

Cuando lo confirme, la página cargará las extensiones especificadas en la configuración de serve.

Depurar conjunto de comandos de vista de lista

Para depurar un conjunto de comandos de vista de lista, agregue lo siguiente a la URL de su página moderna:

Precaución

Se agregaron saltos de línea y sangría al siguiente fragmento para facilitar la lectura. El texto siguiente debe estar en una sola línea sin espacios en blanco.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
  "location":"<extensionType>",
  "properties":<propertiesJSON>
}}

Por ejemplo:

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{
    "location":"ClientSideExtension.ListViewCommandSet.CommandBar",
    "properties":{
      "sampleTextOne":"One item is selected in the list.",
      "sampleTextTwo":"This command is always visible."
    }
  }}

Estos son los parámetros de cadena de consulta que tiene que agregar:

Parámetro	Descripción
loadSPFX=true	Garantiza que se carga SharePoint Framework en la página. Por motivos de rendimiento, el marco no se carga a no ser que se registre por lo menos una extensión. Dado que no hay componentes registrados, debe cargar de forma explícita el marco.
debugManifestsFile	Especifica que quiere cargar componentes que se sirven de forma local. El cargador solo busca componentes en el catálogo de aplicaciones (para la solución implementada) y en el servidor del manifiesto de SharePoint (para las bibliotecas del sistema).
customActions	Simula una acción personalizada. Puede establecer muchas propiedades en este objeto CustomAction que afectan a la apariencia y la ubicación del botón; las trataremos todas ellas más adelante.

El parámetro customActions tiene los siguientes tokens que deben reemplazarse:

Token	Description
<extensionId>	GUID de la extensión.
<extensionType>	Lugar donde se muestran los comandos. Los valores posibles son: ClientSideExtension.ListViewCommandSet.ContextMenu: El menú contextual de los elementos, ClientSideExtension.ListViewCommandSet.CommandBar: El menú del conjunto de comandos superior de una lista o biblioteca. ClientSideExtension.ListViewCommandSet: menú contextual y barra de comandos (corresponde a SPUserCustomAction.Location="CommandUI.Ribbon").
<propertiesJSON>	Un objeto JSON opcional que contiene las propiedades que estarán disponibles a través del miembro this.properties.

Con los parámetros agregados a la dirección URL, vuelva a cargar la página en el explorador web. La página mostrará un cuadro emergente que le pide que confirme que ahora va a cargar scripts de depuración.

Cuando lo confirme, la página cargará las extensiones especificadas en la configuración de serve.

Depurar elementos web de SharePoint Framework en páginas modernas de SharePoint

Para probar las versiones locales de los elementos web del lado cliente de SharePoint Framework en páginas modernas de SharePoint del espacio empresarial, inicie primero el servidor gulp local, cambiando el directorio de trabajo a la carpeta de proyecto y, en la línea de comandos, ejecute:

gulp serve --nobrowser

A continuación, en el explorador web, vaya a la página moderna en la que quiere probar los elementos web. Después de cargar la página, agregue lo siguiente a la dirección URL:

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

Por ejemplo:

Precaución

Se agregaron saltos de línea y sangría al siguiente fragmento para facilitar la lectura. El texto siguiente debe estar en una sola línea sin espacios en blanco.

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js

La página se volverá a cargar y mostrará un cuadro emergente que le pide que confirme que ahora va a cargar scripts de depuración.

Cuando haya confirmado que quiere cargar los elementos web que está desarrollando, puede editar la página y, en el cuadro de herramientas, seleccionar cualquiera de los elementos web locales.

Valor agregado de pruebas de elementos web de SharePoint Framework en páginas modernas

Al compilar elementos web de SharePoint Framework, puede probarlos utilizando el área de trabajo local. Esto, además de práctico, es también eficaz: cada vez que cambie algo en el código, el área de trabajo local se volverá a cargar automáticamente mostrando así los cambios más recientes.

En algunos casos, como al crear elementos web que se comunican con SharePoint, no puede usar el área de trabajo local de SharePoint ya que necesita acceso a las API de SharePoint a las que solo se puede llamar cuando se trata de un sitio de SharePoint. En esos casos, en lugar de usar el área de trabajo local, puede usar la instancia del área de trabajo de SharePoint hospedada a la que tiene acceso agregando /_layouts/15/workbench.aspx a la dirección URL del sitio, por ejemplo: https://contoso.sharepoint.com/sites/team-a/_layouts/15/workbench.aspx.

Restricciones de TI

SharePoint Framework Workbench convenientemente imita el lienzo de las páginas modernas de SharePoint. Pero no imita todos los aspectos. El ancho del lienzo es diferente y no todos los colores del tema se reflejan. Además, el área de trabajo no permite probar la experiencia de sangrado completo cuando un elemento web abarca todo el ancho del explorador web, sin ningún margen horizontal ni relleno.

¿Funciona con otros elementos web y extensiones?

Si usa la instancia de SharePoint Workbench, solo puede probar elementos web de su solución. Pero, ¿qué sucede si quiere ver cómo el elemento web funciona con otros elementos web en la página? Probar la solución local en páginas modernas con el método que se describe en este artículo resulta más eficaz que empaquetar el proyecto, implementarlo en el catálogo de aplicaciones y agregar el elemento web a la página.

Depurar elementos web de SharePoint Framework: un enfoque alternativo

Si crea una solución de elementos web sin el argumento --ship como se ve a continuación:

gulp bundle
gulp package-solution

los paquetes generados harán referencia al código desde el equipo local (https://localhost:4321). Puede implementar la solución en el catálogo de aplicaciones como lo haría normalmente.

Luego, puede iniciar el servidor local ejecutando lo siguiente:

gulp serve --nobrowser

Ahora puede volver a un sitio de SharePoint donde se implementó la solución y agregar elementos web a cualquier página, moderna o clásica, y se cargará el código del elemento web de su entorno de desarrollo local. Puede depurar los elementos web como lo haría si ejecutara gulp serve y agregara el elemento web al área de trabajo.

Este enfoque solo puede usarse cuando esté en modo de desarrollo. Si implementa una aplicación en el catálogo de aplicaciones que apunta al host local, no se ejecutará si no se está ejecutando el entorno de desarrollo.

Vea también

• Depurar soluciones de SharePoint Framework en Visual Studio Code
• (Probar fácilmente los elementos web de SharePoint Framework en páginas modernas [Waldek Mastykarz, Rencore])
• (Probar y depurar las soluciones SPFx en producción sin causar ningún impacto [Elio Struyf])
• Generador de Yeoman para SharePoint Framework
• Información general sobre SharePoint Framework