Implementar la extensión en SharePoint (parte 3 de Hola mundo)

En este artículo se describe cómo implementar el personalizador de aplicación de SharePoint Framework (SPFx) en SharePoint y ver su funcionamiento en las páginas modernas de SharePoint.

Asegúrese de haber completado los procedimientos de los siguientes artículos antes de comenzar:

• Compilar la primera extensión de SharePoint Framework (parte 1 de Hello World)
• Usar marcadores de posición de página en Application Customizer (parte 2 de Hello World)

También puede seguir estos pasos viendo el vídeo en el canal de YouTube, Microsoft 365 Platform Communtiy (PnP):

Hay diferentes maneras de implementar y activar las extensiones de SPFX en los sitios de SharePoint. La opción correcta depende de los objetivos y requisitos empresariales. Las opciones principales son las siguientes:

• Activar la extensión en un sitio(s) específico con la opción de activación única en función del marco de características cuando se instala la solución. Este es el único modelo que admite creación o implementación de activos de nivel del sitio como parte de la activación de la solución.
• Use la opción de implementación de ámbito del inquilino y active la extensión en sitios específicos disponible en las API de SharePoint y las interfaces.
• Use la opción de implementación para todo el espacio empresarial para las extensiones del catálogo de aplicaciones. Esta función se introdujo en la v1.6 de SharePoint Framework.

Empaquetar la extensión Hello World de Application Customizer

En este ejemplo, activaremos la extensión en un único sitio. Esto significa que usaremos la activación basada en Feature Framework cuando la solución se instale en el sitio.

1. En la ventana de la consola, vaya al directorio del proyecto de extensión creado en Compilar la primera extensión de SharePoint Framework (parte 1 de Hello World).

   cd app-extension
   

2. Si Gulp serve se sigue ejecutando, deténgalo pulsando CTRL+C.

   A diferencia del modo Depurar, para usar una extensión en páginas modernas de SharePoint, debe implementar y registrar la extensión en SharePoint con ámbito Colección de sitios, Sitio o Lista. El ámbito define dónde y cómo se activará el personalizador de aplicación. En este caso particular, el personalizador de aplicación se va a registrar con ámbito Colección de sitios.

   Antes de empaquetar nuestra solución, queremos incluir el código necesario para automatizar la activación de extensión dentro del sitio cuando la solución se instale en el sitio. En este caso, se van a usar elementos de Feature Framework para realizar estas acciones en el paquete de solución, pero también se podría asociar el personalizador de aplicación a un sitio de SharePoint mediante REST o CSOM de SharePoint como parte de su aprovisionamiento.

3. Instale el paquete de solución en el sitio correspondiente para que el manifiesto de la extensión se permita en la ejecución.

4. Asocie el personalizador de aplicación al ámbito planeado. Puede hacerlo automáticamente mediante SharePoint REST o las API de CSOM, o mediante Feature Framework en el paquete de solución de SharePoint Framework. Tendrá que asociar las siguientes propiedades del objeto UserCustomAction en el nivel de colección de sitios, de sitio o de lista.

   • ClientSideComponentId: se trata del identificador (GUID) de la extensión SPFx, que se ha instalado en el catálogo de aplicaciones.
   • ClientSideComponentProperties: es un parámetro opcional que se puede usar para especificar propiedades para la instancia de la extensión SPFx.

   Puede controlar el requisito de agregar una solución que contenga su extensión al sitio con el valor skipFeatureDeployment del archivo ./config/package-solution.json. Aunque no es preciso que la solución esté instalada en el sitio, tendrá que asociar ClientSideComponentId a objetos concretos para que la extensión esté visible.

Revise el archivo elements.xml existente con definiciones de SharePoint

En los pasos siguientes, se revisará la definición de CustomAction creada automáticamente para la solución como parte de la operación de scaffolding para habilitar la solución en un sitio cuando se instala.

1. Vuelva al paquete de solución en Visual Studio Code (o el editor que prefiera).

2. Abrir el archivo ./sharepoint/assets/elements.xml.

   

Revise la estructura XML existente en el archivo elements.xml. La propiedad ClientSideComponentId se actualizó en función del id. único del personalizador de aplicación definido en el archivo ./src/extensions/helloWorld/HelloWorldApplicationCustomizer.manifest.json.

La propiedad ClientSideComponentProperties se establece en la estructura predeterminada y en las propiedades JSON de la extensión. Observe que JSON es de escape para que se pueda establecer correctamente en un atributo XML.

La configuración usa la ubicación específica de ClientSideExtension.ApplicationCustomizer para definir si se trata de un personalizador de aplicación. Debido a que elements.xml se asocia de forma predeterminada a una característica de ámbito Web, este elemento CustomAction se agrega automáticamente a la propiedad Web.UserCustomAction del sitio donde se instala la solución.

Asegúrese de que la configuración coincide con los cambios realizados en las propiedades del personalizador de aplicación. Establezca la propiedad ClientSideComponentProperties en la siguiente cadena JSON codificada en HTML que contiene los valores de propiedad:

{"Top":"Top area of the page","Bottom":"Bottom area in the page"}

¿Qué pasa con el archivo ClientSideInstance.xml en la carpeta de activos?

El archivo ClientSideInstance.xml se usa con la Implementación en todo el espacio empresarial de las extensiones de SharePoint Framework. Puede usar este archivo para agregar una entrada a la lista centralizada de Extensiones de todo el inquilino en el sitio del catálogo de aplicaciones del inquilino si elige la opción de implementación de ámbito del inquilino. En este tutorial, seleccionamos la solución para instalarla al nivel de sitio, lo que significa que el archivo se omitirá cuando la solución se active en el catálogo de aplicaciones.

La lista Extensiones de todo el inquilino puede usarse para activar automáticamente las extensiones de inquilino desde una ubicación centralizada. La implementación para todo el inquilino es compatible con personalizadores de aplicación y conjuntos de comandos de vista de lista. Puede especificar varias definiciones de destino, como la activación según el tipo de sitio o de lista.

En este tutorial, no es necesario este archivo ya que se activará la solución en un sitio específico con la característica de aprovisionamiento basado en xml.

Sugerencia

Para obtener más información, consulte Implementación en todo el inquilino de las Extensiones de SharePoint Framework.

Comprobar que las definiciones se usan en la canalización de compilación

El archivo ./config/package-solution.json define los metadatos del paquete. Para asegurarse de que el archivo deelements.xml se tiene en cuenta mientras se empaqueta la solución, el scaffolding predeterminado incluye la configuración necesaria para definir una definición de característica de Feature Framework en el paquete de solución.

La propiedad elementManifests original del archivo ./config/package-solution.json tiene el siguiente aspecto:

"assets": {
  "elementManifests": [
    "elements.xml",
    "clientsideinstance.xml"
  ]
}

Quite la entrada de clientsideinstance.xml en elementManifests, ya que no se necesita para este tutorial:

"assets": {
  "elementManifests": [
    "elements.xml"
  ]
}

El ./config/package-solution.json ahora es similar al ejemplo siguiente después de las modificaciones necesarias:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "app-extension-client-side-solution",
    "id": "65e15d73-515b-4d57-8c92-66ba5890c7b4",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "developer": {
      "name": "",
      "websiteUrl": "",
      "privacyUrl": "",
      "termsOfUseUrl": "",
      "mpnId": "Undefined-1.14.0"
    },
    "metadata": {
      "shortDescription": {
        "default": "app-extension description"
      },
      "longDescription": {
        "default": "app-extension description"
      },
      "screenshotPaths": [],
      "videoUrl": "",
      "categories": []
    },
    "features": [
      {
        "title": "Application Extension - Deployment of custom action",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "41b490c7-49f7-4db4-b7ea-c632d0fb9785",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/app-extension.sppkg"
  }
}

Implementar la extensión en SharePoint Online y hospedar JavaScript en el host local

Ya está listo para implementar la solución en un sitio de SharePoint y asociar el objeto CustomAction en el nivel de sitio.

1. En la ventana de la consola, escriba el comando siguiente para crear un paquete de la solución del lado cliente que contenga la extensión, y así tener preparada la estructura básica necesaria para el paquete:

   gulp bundle
   

2. Ejecute el comando siguiente para crear el paquete de solución:

   gulp package-solution
   

   Este comando crea el paquete siguiente: ./sharepoint/solution/app-extension.sppkg.

3. Ahora, tiene que implementar el paquete en el catálogo de aplicaciones. Vaya al catálogo de aplicaciones de su espacio empresarial y cargue (o arrastre y coloque) el archivo ./sharepoint/solution/app-extension.sppkg en la lista Aplicaciones para SharePoint. SharePoint muestra un panel que le pide que habilite la solución del lado cliente.

   No se han actualizado las direcciones URL para hospedar la solución de esta implementación, por lo que la dirección URL sigue apuntando a https://localhost:4321.

4. Selecciona el botón de radio Habilitar solo esta aplicación y, a continuación, selecciona el botón Habilitar aplicación.

   

5. Volver a la consola y asegúrese de que la solución se está ejecutando. Si no se está ejecutando, ejecute el siguiente comando en la carpeta de la solución:

   gulp serve --nobrowser
   

6. Vaya al sitio donde quiere probar el aprovisionamiento de activos de SharePoint. Puede ser cualquier colección de sitios del espacio empresarial donde ha implementado este paquete de solución.

7. Seleccione el icono de engranaje que se encuentra a la derecha de la barra de navegación de la parte superior y elija Agregar una aplicación para ir a la página Aplicaciones.

8. En el cuadro Buscar, escriba app y presione ENTRAR para filtrar las aplicaciones.

   

9. Seleccione la aplicación app-extension-client-side-solution para instalar la solución en el sitio. Cuando se complete la instalación, vuelva al sitio donde instaló la aplicación.

   Ahora puede ver que el encabezado y pie de página se representan igual que con los parámetros de consulta de depuración.

   

Siguientes pasos

Implementó una extensión en una página moderna de SharePoint desde el Catálogo de aplicaciones.

Puede seguir compilando la extensión Hola mundo en el tema siguiente, Hospedar extensiones desde la red CDN de Office 365 (parte 4 de Hola mundo), donde aprenderá a implementar y cargar los activos de la extensión desde una red CDN y no de localhost.