Aprovisionar activos de SharePoint con el paquete de solución
En ocasiones, es posible que tenga que aprovisionar una lista de SharePoint o una biblioteca de documentos junto con el paquete de solución del lado cliente para que la lista o la biblioteca estén disponibles para los componentes del lado cliente, como los elementos web. 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.
También puede encontrar detalles de las opciones de aprovisionamiento en esta difusión web de SharePoint PnP que está disponible en el canal de YouTube de Microsoft 365 Platform Communtiy (PnP):
Aprovisionamiento de elementos mediante código JavaScript
Aunque es posible crear elementos de SharePoint mediante código JavaScript en el componente, como elementos web, se limita al contexto del usuario actual que usa ese componente. Si el usuario no tiene permisos suficientes para crear o modificar elementos de SharePoint, el código JavaScript no aprovisiona esos elementos. En tales casos, cuando quiera aprovisionar elementos de SharePoint en un contexto con privilegios elevados, debe empaquetar e implementar los elementos junto con el paquete de solución.
Aprovisionar elementos de SharePoint en la solución
Se pueden aprovisionar los siguientes recursos de SharePoint junto con el paquete de solución del lado cliente:
- Campos
- Tipos de contenido
- Instancias de lista
- Instancias de lista con esquema personalizado
Campos
Un campo o una columna de sitio representan un atributo, o elemento de metadatos, que el usuario desea administrar para los elementos de la lista o tipo de contenido al que agrega la columna. Es una definición de columna reutilizable, o plantilla, que puede asignar a varias listas entre varios sitios SharePoint. Las columnas de sitio reducen la repetición de trabajo y ayudar a garantizar la coherencia de los metadatos de todos los sitios y listas.
Por ejemplo, supongamos que define una columna de sitio denominada Clientes. Los usuarios pueden agregar la columna a sus listas y crear una referencia a ella en los tipos de contenido. Esto garantiza que la columna tenga los mismos atributos (al menos en principio) siempre que aparezca.
Puede consultar el esquema y los atributos en la documentación de Elemento Field (Campo) para definir un nuevo campo en la solución.
Seguidamente se muestra un ejemplo de un nuevo campo DateTime:
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
Tipos de contenido
Un tipo de contenido es una colección reutilizable de metadatos (columnas), comportamiento y otras configuraciones para una categoría de artículos o documentos en una biblioteca de documentos o lista de SharePoint. Los tipos de contenido permiten administrar la configuración de una categoría de información de una manera centralizada y reutilizable.
Por ejemplo, imagine una situación de negocios en la que tiene tres tipos diferentes de documentos: informes de gastos, pedidos de compra y facturas. Los tres tipos de documentos tienen algunas características en común; en primer lugar, son todos documentos financieros y contienen datos con valores en moneda. Sin embargo, cada uno de ellos presenta sus propios requisitos de datos, su propia plantilla de documento y su propio flujo de trabajo.
Una solución a este problema empresarial consiste en crear cuatro tipos de contenido. El primero, Documento financiero, podría englobar los requisitos de datos que son comunes a todos los documentos financieros de la organización. Los tres tipos restantes, Informe de gastos, Pedido de compra y Factura, podrían heredar elementos comunes de Documento financiero. Además, podrían definir características que son únicas para cada tipo, como un conjunto de metadatos específico, una plantilla de documento para usarla al crear un nuevo elemento y un flujo de trabajo específico para procesar un elemento.
Puede consultar el esquema y los atributos en la documentación de Elemento ContentType (Tipo de contenido) para definir un nuevo tipo de contenido en la solución.
Seguidamente se muestra un ejemplo de tipo de contenido:
<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
Name="Cost Center"
Group="Financial Content Types"
Description="Financial Content Type">
<FieldRefs>
<FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
<FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
</FieldRefs>
</ContentType>
Instancias de lista
Las listas son una función clave y subyacente de un sitio de SharePoint. Permiten a los equipos recopilar, realizar un seguimiento y compartir información. Muchas aplicaciones se basan en listas creadas en el sitio para que el almacenamiento de datos implemente sus comportamientos. Una instancia de lista es una lista predefinida de SharePoint que tiene un identificador conocido. Puede personalizar y agregar elementos a estas listas, crear listas adicionales desde las plantillas de lista disponibles y crear listas personalizadas con la configuración y las columnas que elija.
SharePoint proporciona varias plantillas de lista, como lista de contactos, calendario, lista de tareas, etc. Puede utilizar estas plantillas para crear nuevas instancias de listas de los elementos web o de otros componentes. Por ejemplo, puede definir una instancia de lista de documentos financieros basada en la plantilla Biblioteca de documentos para almacenar los documentos asociados con su elemento web.
Puede consultar el esquema y los atributos en la documentación de Elemento ListInstance (Instancia de lista) para definir una instancia de lista en la solución.
Seguidamente se muestra un ejemplo de definición de instancia de lista:
<ListInstance
FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
Title="Finance Records"
Description="Finance documents"
TemplateType="101"
Url="Lists/FinanceRecords">
</ListInstance>
Instancias de lista con esquema personalizado
Puede usar una definición de esquema de lista personalizada para definir los campos, los tipos de contenido y las vistas que se usan en la instancia de lista. El atributo CustomSchema se usa en el elemento ListInstance para hacer referencia a un esquema personalizado para la instancia de lista.
Por ejemplo, puede definir una instancia de lista Documentos financieros con un tipo de contenido Documentos financieros que puede encapsular los requisitos de datos comunes a todos los documentos de este tipo de la organización.
Seguidamente se muestra un ejemplo de definición de instancia de lista que utiliza un esquema personalizado:
<ListInstance
CustomSchema="schema.xml"
FeatureId="00bfea71-de22-43b2-a848-c05709900100"
Title="Cost Centers"
Description="Cost Centers"
TemplateType="100"
Url="Lists/CostCenters">
</ListInstance>
Se trata de la definición de esquema personalizado que define un tipo de contenido para la instancia de lista definida anteriormente:
<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>
Crear elementos de SharePoint en la solución
El paquete de solución usa características de SharePoint para empaquetar y proporcionar los elementos de SharePoint. Una característica es un contenedor que incluye uno o varios elementos de SharePoint para aprovisionar. Una característica contiene un archivo Feature.xml y uno o varios archivos de manifiesto de elemento. Estos archivos XML también se conocen como definiciones de características.
Normalmente, un paquete de solución de cliente contiene una característica. Esta característica se activa cuando la solución está instalada en un sitio. Es importante destacar que los administradores del sitio instalan el paquete de solución y no la característica.
Una característica se construye principalmente mediante los siguientes archivos XML:
Archivo de manifiesto de elemento
El archivo de manifiesto de elemento contiene las definiciones de elementos de SharePoint y se ejecuta cuando se activa la característica. Por ejemplo, las definiciones XML para crear un nuevo campo, tipo de contenido o instancia de lista se encuentra en el manifiesto del elemento.
Seguidamente se muestra un ejemplo de archivo de manifiesto de elemento que define un nuevo campo DateTime.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
</Elements>
Archivo de elemento
Los archivos admitidos que acompañan al manifiesto de elemento son archivos de elemento. Por ejemplo, el esquema de instancia de lista es un archivo de elemento asociado a una instancia de lista definida en un manifiesto de elemento.
Seguidamente se muestra un ejemplo de esquema de instancia de lista personalizada:
<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>
</MetaData>
</List>
Archivo de acciones de actualización
Como su nombre sugiere, este es el archivo que incluye las acciones de actualización cuando la solución se actualiza en el sitio. Como parte de las acciones de actualización, la acción podría incluir específicamente uno o varios manifiestos de elementos. Por ejemplo, si la actualización requiere que se agregue un nuevo campo, la definición de campo está disponible como un manifiesto de elemento y está asociada en el archivo de acciones de actualización.
Seguidamente se muestra un ejemplo de archivo de acciones de actualización que aplica un archivo de manifiesto de elemento durante la actualización:
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
Configurar la característica de SharePoint
Para incluir los archivos XML, primero debe definir la configuración de características en el archivo de configuración package-solution.json en la carpeta config del proyecto. Package-solution.json contiene la información de metadatos clave sobre el paquete de solución del lado cliente y se hace referencia al ejecutar la tarea gulp que empaqueta la package-solution solución en un .sppkg archivo.
{
"solution": {
"name": "hello-world-client-side-solution",
"id": "26364618-3056-4b45-98c1-39450adc5723",
"version": "1.1.0.0",
"features": [{
"title": "hello-world-client-side-solution",
"description": "hello-world-client-side-solution",
"id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
"version": "1.1.0.0",
"assets": {
"elementManifests": [
"elements.xml"
],
"elementFiles":[
"schema.xml"
],
"upgradeActions":[
"upgrade-actions-v1.xml"
]
}
}]
},
"paths": {
"zippedPackage": "solution/hello-world.sppkg"
}
}
El objeto JSON features contiene los metadatos sobre la característica, tal y como se muestra en la tabla siguiente:
| Propiedad | Descripción |
|---|---|
| id | Identificador único (GUID) de la característica |
| title | Título de la característica |
| description | Descripción de la característica |
| assets | Una matriz de archivos XML utilizados en la característica |
| elementManifests | Definida dentro de la propiedad assets, una matriz de archivos de manifiesto de elemento |
| elementFiles | Definida dentro de la propiedad assets, una matriz de archivos de elemento |
| upgradeActions | Definida dentro de la propiedad assets, una matriz de archivos de acción de actualización |
Crear los archivos XML de característica
La cadena de herramientas busca los archivos XML tal y como se definen en la configuración en una carpeta especial, sharepoint\assets, en el proyecto de la solución del lado cliente.
Las configuraciones definidas en el package-solution.json son lo que asigna aquí los archivos XML con su correspondiente archivo de característica XML cuando se ejecuta la tarea de Gulp package-solution.
Empaquetar elementos de SharePoint
Cuando haya definido la característica en el package-solution.json y creado los respectivos archivos XML de característica, puede utilizar la siguiente tarea de Gulp para empaquetar los elementos de SharePoint junto con el paquete .sppkg.
gulp package-solution
Este comando empaqueta uno o varios manifiestos de componente del lado cliente, como elementos web, junto con los archivos XML de característica a los que se hace referencia en el archivo de configuración package-solution.json.
Nota:
Puede usar la marca --ship para empaquetar versiones miniaturizadas de los componentes.
Actualizar elementos de SharePoint
Puede incluir nuevos elementos de SharePoint o actualizar los ya existentes al actualizar la solución del lado cliente. Dado que el aprovisionamiento de elementos de SharePoint usa características, está usando el archivo XML UpgradeActions de la característica para definir una lista de acciones de actualización.
La matriz de objetos upgradeActions en el package-solution.json hace referencia a los archivos XML de características asociados con las acciones de actualización para la característica. Al menos, un archivo de acción de actualización define el archivo XML de manifiesto de elemento que se ejecuta al actualizar la característica.
Al actualizar una solución de SharePoint Framework, también debe actualizar los atributos de versión para la solución y la característica donde se han incluido las acciones de actualización. Un aumento de la versión de la solución indica a los usuarios finales de SharePoint que hay una nueva versión del paquete disponible. Un aumento de la versión de un elemento de característica garantiza que las tareas definidas en las acciones de actualización se procesan como parte de la actualización de la solución.
Seguidamente se muestra un ejemplo de archivo de acciones de actualización que aplica un archivo de manifiesto de elemento durante la actualización:
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
Se trata del element-v2.xml correspondiente que define un nuevo campo Moneda que sea va a aprovisionar durante la actualización:
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
Name="Amount"
DisplayName="Amount"
Type="Currency"
Decimals="2"
Min="0"
Required="FALSE"
Group="Financial Columns" />
</Elements>
Subelementos
Las acciones de actualización en las soluciones del lado cliente admiten los siguientes subelementos:
AddContentTypeField
Agrega un nuevo campo a un tipo de contenido con aprovisionamiento existente. Propaga el cambio del tipo de contenido de sitio a todas las listas secundarias y tipos de contenido dentro del sitio. Por ejemplo:
<AddContentTypeField
ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
PushDown="TRUE" />
ApplyElementManifests
Agrega un nuevo elemento a una característica existente. Cuando se actualiza una característica, aprovisiona todos los elementos no declarativos a los que se hace referencia en los manifiestos de elementos especificados.
VersionRange
Especifica un intervalo de versiones al que se aplican las acciones de actualización especificadas.