Aprovisionar activos de SharePoint desde un elemento web del lado cliente de SharePoint

Artículo
04/08/2023

Se pueden aprovisionar activos de SharePoint como parte de la solución de SharePoint Framework e implementarse en sitios de SharePoint que tengan instalada la solución.

Antes de empezar, complete los procedimientos de los artículos siguientes para asegurarse de que entiende el flujo básico de crear un elemento web del lado cliente personalizado:

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

Crear un proyecto de elementos web

Cree un directorio de proyecto nuevo en su ubicación favorita:
```
md asset-deployment-webpart
```
Vaya al directorio del proyecto:
```
cd asset-deployment-webpart
```
Ejecute el Generador de Yeoman de SharePoint para crear una solución de elemento web del lado cliente:
```
yo @microsoft/sharepoint
```
En el momento en que se le solicite, introduzca los siguientes valores (seleccione la opción predeterminada para todas las solicitudes que se omitan a continuación):

¿Cómo se llama su solución?: asset-deployment-webpart
¿Cuál es el tipo de componente del lado cliente que se va a crear?: Elemento web
¿Cómo se llama su elemento web?: AssetDeployment
¿Qué plantilla le gustaría usar?: sin marco de JavaScript

En ese momento, Yeoman instalará las dependencias necesarias y aplicará scaffolding en los archivos de la solución. Esta operación puede tardar unos minutos. Yeoman aplica scaffolding en el proyecto para incluir también el elemento web AssetDeployment.

Después, ejecute lo siguiente para abrir el proyecto de elemento web en Visual Studio Code:
```
code .
```

Crear la estructura de carpetas para activos de SharePoint

Primero, debe crear la carpeta assets, donde colocará todos los activos de Feature Framework usados para aprovisionar estructuras de SharePoint cuando el paquete está instalado.

Cree una carpeta llamada sharepoint en el directorio raíz de solución.
Cree una carpeta llamada assets como subcarpeta de la carpeta sharepoint creada.

La estructura de la solución debería tener un aspecto similar al de la imagen siguiente:

Crear archivos de Feature Framework para la implementación inicial

Para aprovisionar activos de SharePoint en sitios con elementos de Feature Framework es necesario crear los archivos XML necesarios en la carpeta de activos. Los elementos compatibles con los paquetes de solución de SharePoint Framework son los siguientes:

Columnas de sitio o campos
Tipos de contenido
Instancias de lista
Instancias de lista con esquema personalizado

Agregar un archivo elements.xml para definiciones de SharePoint

En los pasos siguientes, definiremos la estructura necesaria que se aprovisionará.

Cree un nuevo archivo elements.xml en la carpeta sharepoint\assets.

Copie la siguiente estructura XML en elements.xml.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

    <Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
            Name="SPFxAmount"
            DisplayName="Amount"
            Type="Currency"
            Decimals="2"
            Min="0"
            Required="FALSE"
            Group="SPFx Columns" />

    <Field ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}"
            Name="SPFxCostCenter"
            DisplayName="Cost Center"
            Type="Choice"
            Required="FALSE"
            Group="SPFx Columns">
        <CHOICES>
        <CHOICE>Administration</CHOICE>
        <CHOICE>Information</CHOICE>
        <CHOICE>Facilities</CHOICE>
        <CHOICE>Operations</CHOICE>
        <CHOICE>Sales</CHOICE>
        <CHOICE>Marketing</CHOICE>
        </CHOICES>
    </Field>

    <ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
            Name="Cost Center"
            Group="SPFx Content Types"
            Description="Sample content types from web part solution">
        <FieldRefs>
            <FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
            <FieldRef ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}" />
        </FieldRefs>
    </ContentType>

    <ListInstance
            CustomSchema="schema.xml"
            FeatureId="00bfea71-de22-43b2-a848-c05709900100"
            Title="SPFx List"
            Description="SPFx List"
            TemplateType="100"
            Url="Lists/SPFxList">
    </ListInstance>

</Elements>

Hay algunas cosas que debe tener en cuenta sobre este XML:

Aprovisionamos dos campos en el sitio: un tipo de contenido y una instancia de lista con un esquema personalizado.
Las definiciones usan el esquema de Feature Framework estándar, que es conocido por los desarrolladores de SharePoint.
Se hace referencia a los campos personalizados en el tipo de contenido introducido.
Usamos el atributo CustomSchema en el elemento ListInstance para definir un archivo schema.xml de tiempo de aprovisionamiento para la lista. De esta forma, la lista sigue basándose en la plantilla de lista prediseñada (en este caso, la lista personalizada normal "100"), pero se pueden establecer otra definición de aprovisionamiento durante el aprovisionamiento inicial.
Cuando se aprovisionan instancias de lista con características, debe proporcionar el Id. de la característica asociada a la definición de la lista específica. Al usar el atributo FeatureId debería proporcionar el Id. de la característica, el cual contiene la definición de lista. Por ejemplo: si aprovisiona una instancia de una lista personalizada debe establecer el atributo FeatureId en {00bfea71-de22-43b2-a848-c05709900100}.

Para más información sobre el esquema de manifiesto del elemento de característica, consulte: Uso de características en SharePoint Foundation.

Agregar un archivo schema.xml para definir la estructura de la lista

En el paso anterior hicimos referencia al archivo schema.xml en el atributo CustomSchema del elemento ListInstance, por lo que debemos incluir dicho archivo en el paquete.

Cree un nuevo archivo schema.xml en la carpeta sharepoint\assets.

Copie la siguiente estructura XML en schema.xml.

<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
  <MetaData>
    <ContentTypes>
      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
    </ContentTypes>
    <Fields></Fields>
    <Views>
      <View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
        <XslLink Default="TRUE">main.xsl</XslLink>
        <JSLink>clienttemplates.js</JSLink>
        <RowLimit Paged="TRUE">30</RowLimit>
        <Toolbar Type="Standard" />
        <ViewFields>
          <FieldRef Name="LinkTitle"></FieldRef>
          <FieldRef Name="SPFxAmount"></FieldRef>
          <FieldRef Name="SPFxCostCenter"></FieldRef>
        </ViewFields>
        <Query>
          <OrderBy>
            <FieldRef Name="ID" />
          </OrderBy>
        </Query>
      </View>
    </Views>
    <Forms>
      <Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
    </Forms>
  </MetaData>
</List>

Hay algunas cosas que debe tener en cuenta sobre este XML:

Se hace referencia al tipo de contenido personalizado implementado con el archivo elements.xml en el elemento ContentTypeRef.
Se hace referencia a los campos personalizados SPFxAmount y SPFxCostCenter en el elemento FieldRef.

Para más información sobre el esquema de Schema.xml, consulte: Descripción de los archivos Schema.xml.

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

En este momento, hemos creado los archivos para el aprovisionamiento de activos de SharePoint con el esquema de características de la solución cuando se implementa. El siguiente paso consiste en incluirlos en el archivo *.sppkg del paquete de SharePoint.

Abra package-solution.json desde la carpeta “config”.

El archivo package-solution.json define los metadatos del paquete como se muestra en el siguiente código:

Compruebe los nuevos archivos de Feature Framework incluidos en el paquete de SharePoint.

Incluya una definición de la característica de Feature Framework para el paquete de soluciones. Incluya una definición de JSON para la característica necesaria en la estructura de la solución, como se muestra en el código siguiente:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    // >>> START
    //     add the following to the package-solution.json file
    "features": [{
      "title": "asset-deployment-webpart-client-side-solution",
      "description": "asset-deployment-webpart-client-side-solution",
      "id": "00000000-0000-0000-0000-000000000000",     // <-- Update new GUID
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ]
      }
    }]
    // <<< END
  },
  "paths": {
    "zippedPackage": "solution/asset-deployment-webpart.sppkg"
  }
}

Hay algunas cosas que debe tener en cuenta sobre este XML:

Asegúrese de definir un GUID único para la propiedad id en la propiedad feature.
Técnicamente, puede tener varias características en el paquete, porque la propiedad features es una matriz. Sin embargo, no se recomienda.
Se hace referencia a elements.xml en elementManifests de modo que esté empaquetado correctamente para la definición de la característica como archivo de manifiesto de elemento.
Puede tener varios archivos element.xml en la definición y se ejecutarían en el orden indicado en la definición de JSON. Normalmente, le recomendamos que evite usar varios archivos element.xml, ya que, de lo contrario, se añade una complejidad innecesaria. Puede definir todos los activos necesarios en un único archivo element.xml.

Implementar y probar el aprovisionamiento de activos

Ahora ya está preparado para implementar la solución SharePoint. Como estamos aprovisionando activos directamente en los sitios de SharePoint cuando la solución está instalada, no puede probar la función en Workbench en línea o local.

En la consola, ejecute el comando siguiente para empaquetar la solución del lado cliente que contenga el elemento web, con el objetivo de tener preparada la estructura básica necesaria para el paquete:
```
gulp bundle
```
Ejecute el comando siguiente para crear el paquete de solución:
```
gulp package-solution
```
El comando crea el paquete asset-deployment-webpart.sppkg en la carpeta sharepoint/solution.
Antes de probar el paquete en SharePoint, vamos a ver rápidamente las estructuras predeterminadas creadas para el paquete en relación con los elementos de Feature Framework definidos.

Vuelva al lado Visual Studio Code y expanda la carpeta sharepoint/solution/debug, que contiene las estructuras XML sin procesar que se van a incluir en el paquete *.sppkg real.
Implemente el paquete que se generó en el Catálogo de aplicaciones.

En el explorador, vaya al catálogo de aplicaciones de su espacio empresarial.
Cargue (o arrastre y coloque) el archivo asset-deployment-webpart.sppkg de la carpeta sharepoint/solution en el Catálogo de aplicaciones. SharePoint muestra un cuadro de diálogo y le pregunta si confía en la solución del lado cliente para su implementación.

Nota:

SharePoint valida el paquete publicado una vez implementado. Solo verá el cuadro de diálogo de confianza si el paquete es válido para implementación. También verá el estado de esta validación en la columna Paquete de aplicación válido del Catálogo de aplicaciones.
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.
Seleccione el icono de engranaje (a la derecha de la barra de navegación superior) y luego elija Agregar una aplicación para ir a la página Aplicaciones.
En el cuadro Buscar, escriba deployment y presione ENTRAR para filtrar las aplicaciones.
Seleccione la aplicación asset-deployment-webpart-client-side-solution para instalarla en el sitio. Cuando la instalación se haya completado, presione F5 para actualizar la página. Como puede ver, la lista de SPFx personalizada se ha aprovisionado en el sitio como parte de la implementación del paquete de solución.
Seleccione Lista de SPFx para ir a la lista. Como puede ver, los campos personalizados Importe y Centro de costos son visibles automáticamente en la vista predeterminada de la lista.

Definir acciones de actualización para la nueva versión

Cada vez que compile una nueva versión de la solución de SharePoint Framework, puede que tenga que realizar algunos cambios obligatorios en los activos de SharePoint aprovisionados. Puede aprovechar la compatibilidad con la acción de actualización de Feature Framework cuando se implemente una nueva versión del paquete.

Las soluciones de SharePoint Framework son compatibles con las siguientes definiciones de acción de actualización de Feature Framework:

ApplyElementManifest
AddContentTypeField

Para más información sobre las definiciones de acciones de actualización de Feature Framework, consulte el artículo Proceso de actualización de los Complementos de SharePoint.

Agregar un nuevo archivo element.xml a la nueva versión

Vuelva a la solución en Visual Studio Code.
Cree un nuevo archivo elements-v2.xml en la carpeta sharepoint\assets.

Copie la siguiente estructura XML en elements-v2.xml, que define una nueva lista de SharePoint que se aprovisionará con el título Nueva lista.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ListInstance
    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
    Title="New List"
    Description="New list provisioned from v2"
    TemplateType="100"
    Url="Lists/NewList">
  </ListInstance>
</Elements>

Importante

No cambie el GUID en este XML. Este señala al GUID en el que se define el tipo de lista.

También necesitamos una definición para las acciones de actualización de Feature Framework en sí, por lo que crearemos un nuevo archivo upgrade-actions-v2.xml en la carpeta sharepoint\assets.
Copie la siguiente estructura XML en upgrade-actions-v2.xml. Como puede ver, la referencia del GUID de característica en la ruta de acceso hace referencia a la carpeta creada automáticamente dentro de la carpeta sharepoint/solution/debug y es necesario actualizarla en función de la solución. Este GUID también coincide con el GUID de la característica, que se ha definido en el archivo package-solution.json.
```
<ApplyElementManifests>
  <ElementManifest Location="{feature-guid}\elements-v2.xml" />
</ApplyElementManifests>
```

Importante

{feature-guid} debe coincidir con el GUID de la característica que agregó al archivo package-solution.json.

Implementar la nueva versión en SharePoint

A continuación, tenemos que actualizar tanto la versión de la solución como la versión de la característica responsable del aprovisionamiento de activos.

Importante

La versión de la solución indica a SharePoint que hay disponible una nueva versión de la solución de SharePoint Framework. La versión de la característica garantiza que las acciones de actualización se ejecuten en consecuencia cuando se actualice el paquete de solución en los sitios existentes.

Abra package-solution.json en la carpeta config y actualice los valores de versión de la solución y la característica a 2.0.0.0.

También es necesario incluir elements-v2.xml en la sección elementManifest, así como incluir el elemento upgradeActions con un puntero al archivo upgrade-actions-v2.xml creado.

Aquí está el archivo package-solution.json completo con los cambios necesarios. Tenga en cuenta que los identificadores de la solución pueden ser ligeramente distintos, así que observe solo cómo agregar las partes que faltan.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...
    "version": "2.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [{
      "title": "asset-deployment-webpart-client-side-solution",
      "description": "asset-deployment-webpart-client-side-solution",
      "id": "{feature-guid}",
      "version": "2.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml",
          "elements-v2.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ],
        "upgradeActions":[
          "upgrade-actions-v2.xml"
        ]
      }
    }]
    //...
  }
}

Importante

Como puede ver, también hemos incluido el archivo elements-v2.xml en la sección elementManifest. Esto garantiza que, al instalar el paquete en un sitio nuevo con la versión 2.0, el resultado final coincida con los paquetes actualizados.

En la ventana de la consola, ejecute el comando siguiente para volver a crear un paquete de la solución del lado cliente que contenga el elemento web, de forma que tendremos preparada la estructura básica necesaria para el paquete:
```
gulp bundle
```
Ejecute el comando siguiente para crear el paquete de solución:
```
gulp package-solution
```
El comando crea la nueva versión del paquete de solución en la carpeta sharepoint/solution. Tenga en cuenta que, desde la carpeta sharepoint/solution/debug, puede confirmar fácilmente si los archivos XML actualizados se incluyen en el paquete de solución.
Después, necesita implementar la nueva versión que se generó en el Catálogo de aplicaciones. Vaya al Catálogo de aplicaciones del espacio empresarial.
Cargue (o arrastre y coloque) el archivo asset-deployment-webpart.sppkg de la carpeta sharepoint/solution en el Catálogo de aplicaciones. SharePoint le pedirá que confirme si quiere reemplazar la versión existente.
Seleccione Reemplazar para actualizar a la versión más reciente en el Catálogo de aplicaciones.
Seleccione Implementar para confiar en la versión más reciente.

Como puede ver, la columna Versión de la aplicación de asset-deployment-webpart-client-side-solution se ha actualizado a 2.0.0.0.

Actualizar una instancia existente en el sitio

Una vez actualizado el paquete en el Catálogo de aplicaciones, podemos ir al sitio de contenido de SharePoint y actualizar la instancia existente.

Vaya al sitio donde ha implementado la primera versión de la solución de SharePoint Framework
Vaya a la página Contenidos del sitio.
Seleccione Detalles en el menú contextual de la solución asset-deployment-webpart-client-side-solution.

Verá los detalles actuales de la solución de SharePoint Framework instalada. En esta página ahora también se muestra el texto Hay disponible una versión nueva de esta aplicación. Obténgala ahora para indicar que hay una nueva versión disponible.
Seleccione el botón DESCARGAR para iniciar el proceso de actualización del paquete.

Si pasa a la experiencia clásica, podrá ver más detalles sobre la acción de actualización real que se aplica para la solución de SharePoint Framework.

Nota:

Dado que SharePoint Framework usa la misma infraestructura de aplicación que los complementos de SharePoint, el estado de la actualización indica que la actualización puede producirse para un complemento o una aplicación.

La actualización puede tardar un tiempo, pero, cuando el estado de la solución vuelva a ser normal, actualice la página de contenidos del sitio para confirmar que una nueva lista denominada Nueva lista se ha aprovisionado correctamente como parte del proceso de actualización.

Hemos actualizado correctamente esta instancia a la versión más reciente. La opción de Feature Framework para el aprovisionamiento de activos de SharePoint es similar al modelo de Complementos de SharePoint. La diferencia principal es que los activos se aprovisionan directamente en el sitio de SharePoint normal, ya que no existe el concepto de aplicación o complemento web con las soluciones de SharePoint Framework.