Aprovisionar activos de SharePoint desde un elemento web del lado cliente de SharePoint
Artículo
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:
Consola
md asset-deployment-webpart
Vaya al directorio del proyecto:
Consola
cd asset-deployment-webpart
Ejecute el Generador de Yeoman de SharePoint para crear una solución de elemento web del lado cliente:
Consola
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:
Consola
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
<?xml version="1.0" encoding="utf-8"?><Elementsxmlns="http://schemas.microsoft.com/sharepoint/"><FieldID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"Name="SPFxAmount"DisplayName="Amount"Type="Currency"Decimals="2"Min="0"Required="FALSE"Group="SPFx Columns" /><FieldID="{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><ContentTypeID="0x010042D0C1C200A14B6887742B6344675C8B"Name="Cost Center"Group="SPFx Content Types"Description="Sample content types from web part solution"><FieldRefs><FieldRefID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" /><FieldRefID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}" /></FieldRefs></ContentType><ListInstanceCustomSchema="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}.
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.
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:
JSON
{
"$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:
Consola
gulp bundle
Ejecute el comando siguiente para crear el paquete de solución:
Consola
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:
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
<?xml version="1.0" encoding="utf-8"?><Elementsxmlns="http://schemas.microsoft.com/sharepoint/"><ListInstanceFeatureId="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.
{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.
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:
Consola
gulp bundle
Ejecute el comando siguiente para crear el paquete de solución:
Consola
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.
La cadena de herramientas de SharePoint Framework le permite empaquetar e implementar elementos de SharePoint con su paquete de solución del lado cliente. Estos elementos se suministran a continuación, cuando se instala la solución de cliente en un sitio.
SPFx es un modelo de elementos web y páginas que proporciona compatibilidad completa con el desarrollo de SharePoint del lado cliente, integración fácil con los datos de SharePoint y extensión de Microsoft Teams.
Información previa, ventajas y conocimientos que necesitan los administradores para administrar correctamente componentes basados en SharePoint Framework en sus entornos de SharePoint.
La tarea package-solution de Gulp examina /config/package-solution.json para obtener diversos detalles de configuración de SharePoint Framework, incluidas las definiciones de ISolution y IFeature.