Agregar operaciones de escritura de SharePoint al complemento hospedado por el proveedor

Artículo
04/08/2023

Este es el quinto de una serie de artículos sobre los conceptos básicos de desarrollo de un Complementos de SharePoint hospedados por el proveedor. Primero debe familiarizarse con Complementos de SharePoint y con los anteriores artículos de esta serie, los cuales puede encontrar en Introducción a la creación de complementos de SharePoint hospedados por el proveedor.

Nota:

Si a lo largo de esta serie ha estado trabajando sobre los complementos hospedados por el proveedor, tiene una solución de Visual Studio que puede usar para continuar con este tema. También puede descargar el repositorio en Tutoriales_de_Complementos_Hospedados-por-el-proveedor_de_SharePoint_ y abrir el archivo BeforeSharePointWriteOps.sln.

En este artículo, volveremos a crear código al agregar algunas funciones que escriben datos en el complemento de SharePoint de Chain Store.

Cambiar un valor de columna en un elemento de lista de SharePoint

Nuestro complemento tiene un botón de cinta de opciones personalizado que agrega un empleado de la lista Empleados locales de la tienda de Hong Kong a la base de datos corporativa. Pero el usuario debe acordarse de cambiar manualmente el valor del campo Agregado a BD corporativa a Sí. Vamos a agregar código para hacerlo automáticamente.

Nota:

La configuración de inicio de proyectos en Visual Studio tiende a revertir a los valores predeterminados cada vez que la solución se vuelve a abrir. Siempre debe seguir estos pasos inmediatamente después de abrir de nuevo la solución de ejemplo de esta serie de artículos:

Haga clic con el botón derecho en el nodo de la solución en la parte superior del Explorador de soluciones y después seleccione Establecer proyectos de inicio.
Asegúrese de que los tres proyectos estén establecidos en Iniciar en la columna Acción.

En Explorador de soluciones, abra el archivo EmployeeAdder.aspx.cs.
Agregue la siguiente línea al método Page_Load entre la llamada de AddLocalEmployeeToCorpDB y la llamada de Response.Redirect. En el paso siguiente, creará el método SetLocalEmployeeSyncStatus .
```
   // Write to SharePoint
 SetLocalEmployeeSyncStatus();
```
Agregue el nuevo método siguiente a la clase EmployeeAdder.
```
   private void SetLocalEmployeeSyncStatus()
 {
     using (var clientContext = spContext.CreateUserClientContextForSPHost())
     {
         List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
         ListItem selectedLocalEmployee = localEmployeesList.GetItemById(listItemID);
         selectedLocalEmployee["Added_x0020_to_x0020_Corporate_x"] = true;
         selectedLocalEmployee.Update();
         clientContext.ExecuteQuery();
     }
 }
```
Tenga en cuenta lo siguiente en relación con este código:
- El nombre interno para el campo Agregado a BD corporativa es extraño. Los nombres de campos internos no pueden contener espacios, por lo que cuando un usuario crea un campo con espacios en su nombre para mostrar, SharePoint coloca la cadena "x0020" en cada espacio cuando establece el nombre interno. Esto convierte "Agregado a BD de empleados" en "Agregado_x0020_a_x0020_BD_x0020_corporativa". Los nombres internos no pueden contener más de 32 caracteres, por lo que el nombre se queda en "Agregado_x0020_a_x0020_BD_x0020_".
- Aunque la columna Agregado a BD corporativa se conoce como campo del tipo Sí/No en la interfaz de usuario de SharePoint, realmente es un valor booleano, por lo que su valor se establece en true y no en Sí.
- El método Update de la clase ListItem debe llamarse para confirmar los cambios en la base de datos de contenido de SharePoint. Es una regla general, pero no del todo universal, que, al cambiar un valor de propiedad de un objeto que se almacena en las bases de datos de SharePoint, debe llamar al método Update del objeto.

Solicitar permiso para escribir en la lista de la web de host

Dado que el complemento ahora está escribiendo en la lista, así como leyéndola, es preciso escalar los permisos que el complemento solicita de lectura a escritura. Siga estos pasos.

En el Explorador de soluciones, abra el archivo AppManifest.xml en el proyecto ChainStore.
Abra la pestaña Permisos y, en el campo Permiso, seleccione Escribir en la lista desplegable.
Guarde el archivo.

Ejecutar el complemento y probar el botón

Use la tecla F5 para implementar y ejecutar el complemento. Visual Studio hospeda la aplicación web remota en IIS Express y hospeda la base de datos SQL en SQL Express. También instala temporalmente el complemento en el sitio de SharePoint de prueba y ejecuta el complemento inmediatamente. Se le solicitará que conceda permisos al complemento antes de que se abra su página de inicio.
En el formulario de permiso, seleccione Empleados locales de la lista y, después, seleccione De confianza.
Cuando se abra la página de inicio del complemento, haga clic en Volver al sitio en el control de cromo de la parte superior.
En la página de inicio del sitio web, vaya a Contenido del sitio>Empleados locales. Se abrirá la página de vista de la lista.
Si no hay ningún empleado en la lista que tenga No en la columna Agregado a BD corporativa, agregue un empleado a la lista, pero no seleccione la casilla Agregado a BD corporativa.
En la cinta de opciones, abra la pestaña Elementos. En la sección Acciones de la pestaña se encuentra el botón personalizado Agregar a BD corporativa.
Seleccione un empleado en la lista que tenga No en la columna Agregado a BD corporativa.
Seleccione el botón Agregar a base de datos corporativa . (Primero debe seleccionar un elemento).
Parece que la página se vuelve a cargar, ya que el método Page_Load de la página EmployeeAdder redirige otra vez a ella. El valor del campo Agregado a la base de datos corporativa para el empleado cambia a Sí.

Nota:

¿Qué impide al usuario cambiar manualmente el valor Agregado a BD corporativa de una manera que hace que la lista y la base de datos corporativa sean incoherentes? Nada por el momento. Obtendrá la solución a este problema en un artículo posterior de esta serie.

1.To finalizar la sesión de depuración, cierre la ventana del explorador o detenga la depuración en Visual Studio. Cada vez que seleccione F5, Visual Studio retira la versión anterior del complemento e instala la más reciente. 1.Haga clic con el botón derecho en el proyecto en Explorador de soluciones y seleccione Retraer.

Crear una lista personalizada en el sitio web de host

La siguiente mejora en el complemento Chain Store es crear nuevos elementos en una lista en lugar de simplemente cambiar un campo de un elemento existente. En concreto, cuando se realiza un pedido nuevo en el nivel de empresa, se crea automáticamente un elemento en una lista de SharePoint que alerta a los empleados locales de que deben esperar un envío. La lista se denomina Envíos esperados y se crea con los pasos siguientes. En un artículo posterior de esta serie, aprenderá a agregar mediante programación una lista personalizada a un sitio web de host, pero por ahora agregaremos esta manualmente.

En la página principal de la tienda de Hong Kong de Fabrikam, vaya a Contenidos del sitio>Agregar un complemento>Lista personalizada.
En el cuadro de diálogo Agregar lista personalizada, especifique Envíos esperados como nombre y seleccione Crear.
En la página Contenido del sitio, abra la lista Envíos esperados.
En la pestaña Lista de la cinta, seleccione Configuración de la lista.
En la sección Columnas de la página Configuración de la lista, seleccione la columna Título.
En el formulario Editar columna, cambie el Nombre de columna de Título a Producto y, después, seleccione Aceptar.
En la página Configuración, seleccione Crear columna.

En un artículo anterior de esta serie, aprendimos a crear columnas personalizadas para una lista. Para la lista Envíos esperados, agregue cuatro columnas usando los valores de la tabla siguiente. Deje todas las demás opciones con los valores predeterminados.

Nombre de columna	Tipo	Obligatorio	Valor predeterminado
Proveedor	Una línea de texto	No necesario	Ninguno
Cantidad	Número	Obligatorio	1
Recibido	Sí/No	No necesario	No
Agregado al inventario	Sí/No	No necesario	No

Después de crear las columnas, en la página de configuración de lista, seleccione Contenido del sitio para abrir la página Contenido del sitio . Abra la lista Envíos esperados.
Seleccione nuevo elemento. El formulario de creación de elementos debe tener un aspecto exactamente similar al siguiente, incluidos los dos asteriscos que indican los campos necesarios.

Figura 1. Formulario de creación de artículos para la lista Envíos esperados
Como no queremos crear manualmente elementos en esta lista, haga clic en Cancelar.

Insertar un elemento en una lista de SharePoint

Ahora agregamos una función al complemento que crea un elemento en la lista Envíos esperados cada vez que se realiza un pedido para la tienda de Hong Kong en el nivel de empresa.

En el Explorador de soluciones, abra el archivo OrderForm.aspx.cs.
Agregue una instrucción using para Microsoft.SharePoint.Client al principio del archivo.
En el método btnCreateOrder_Click , agregue la siguiente línea justo debajo de la llamada a CreateOrder. Creará el método CreateExpectedShipment en el paso siguiente.
```
  CreateExpectedShipment(txtBoxSupplier.Text, txtBoxItemName.Text, quantity);
```
Agregue el método siguiente a la clase OrderForm.
```
private void CreateExpectedShipment(string supplier, string product, UInt16 quantity)
{
  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
    List expectedShipmentsList = clientContext.Web.Lists.GetByTitle("Expected Shipments");
    ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
    ListItem newItem = expectedShipmentsList.AddItem(itemCreateInfo);
    newItem["Title"] = product;
    newItem["Supplier"] = supplier;
    newItem["Quantity"] = quantity;
    newItem.Update();
    clientContext.ExecuteQuery();
  }
}
```
Tenga en cuenta lo siguiente en relación con este código:
- Un objeto ListItem no se crea con un constructor. Esto es así por cuestiones de rendimiento. Un objeto ListItem tiene muchas propiedades (con valores predeterminados). Si se usara un constructor, se incluiría el objeto completo en el mensaje XML que el método ExecuteQuery envía al servidor.
- El objeto ListItemCreationInformation es un objeto liviano que solo contiene los valores mínimos que no están predeterminados y que el servidor necesita para crear un objeto ListItem. Puede parecer que existe una línea que crea un objeto ListItem, pero recuerde que esta línea solo agrega un poco de marcado XML a un mensaje que se envía al servidor. El objeto ListItem se crea allí en el servidor.
- No es necesario devolver el objeto ListItem al cliente, por lo que no se realiza ninguna llamada al método ClientContext.Load.
- No es necesario que el código establezca de forma explícita los campos Entregado o Agregado al inventario porque tienen valores predeterminados de No, que es lo que queremos.

Comprobar los componentes eliminados

Cualquier usuario con privilegios de propietario de lista para una lista de SharePoint puede eliminar la lista. Además, si la lista está implementada en la web de host mediante un complemento, el propietario del sitio web de la web de host puede eliminarla. Eso puede ocurrir si el propietario decide trabajar sin la funcionalidad de la lista. (Se puede restaurar desde la Papelera de reciclaje de SharePoint si el propietario cambia de opinión).

El método CreateExpectedShipment depende de la existencia de la lista Envíos esperados. Supongamos que el propietario de un sitio web decidió eliminar la lista. Más adelante, cuando se agrega un pedido con el formulario de pedido del complemento, se llama al método CreateExpectedShipment y se produce una excepción cuyo mensaje indica que no hay ninguna lista de envíos esperados en el sitio web de SharePoint.

Es posible que desee que el método compruebe la expectedShipmentsList nullidad antes de que haga nada con él. Cuando trabaja con CSOM, no puede realizar esta comprobación con una estructura simple como esta:

if (expectedShipmentsList != null) { ... }

En su lugar, debe usar una clase especial de CSOM denominada ConditionalScope. Los motivos están conectados al sistema de procesamiento por lotes de CSOM, que se mencionó en el artículo anterior de esta serie (consulte Tiempo de ejecución del lado cliente y procesamiento por lotes). ConditionalScope y el sistema de procesamiento por lotes son temas avanzados que están fuera del ámbito de esta serie de introducción, pero debería ver la documentación de MSDN sobre ellos después de haber completado esta serie de tutoriales.

Una forma alternativa de comprobar que existe una lista sería la siguiente: en lugar de usar el método GetByTitle para obtener una referencia a la lista, puede comprobar si una lista con el nombre especificado se encuentra en la “lista de listas” del sitio web con un código como este.

var query = from list in clientContext.Web.Lists 
             where list.Title == "Expected Shipments" 
             select list; 
IEnumerable<List> matchingLists = clientContext.LoadQuery(query); 
clientContext.ExecuteQuery(); 
if (matchingLists.Count() != 0) 
{ 
  List expectedShipmentsList = matchingLists.Single(); 
  // Do something with the list. 
}
clientContext.ExecuteQuery();

El código anterior tiene la ventaja de permitirle evitar las complicaciones de la clase ConditionalScope y se usa exactamente este mismo código en otra parte de esta serie de artículos. Pero también tiene una desventaja: este código requiere una llamada adicional de ExecuteQuery únicamente para obtener el valor que desea comprobar en la instrucción if.

Si usamos esta técnica en el método CreateExpectedShipment para comprobar la existencia de la lista, ese método tendrá dos llamadas de ExecuteQuery, cada una de las cuales realiza una solicitud HTTP desde el servidor web remoto a SharePoint. Estas solicitudes son la parte más lenta de cualquier método CSOM, por lo que generalmente se recomienda minimizarlas.

Dejaremos el método CreateExpectedShipment tal y como está, pero en un complemento de producción, debe pensar en cómo funcionará el código si se elimina un componente al que hace referencia. Una opción es restaurar mediante programación la lista desde la Papelera de reciclaje, pero eso podría molestar a los usuarios que decidieron eliminar la lista.

También debería tener en cuenta que no hacer nada en absoluto para evitar la excepción podría ser la mejor opción. Una excepción de SharePoint advertiría a los usuarios de que la eliminación de la lista interrumpió parte del complemento (la persona que lo eliminó podría no haberse dado cuenta de esto). Un usuario puede decidir luego si quiere restaurar la lista desde la Papelera de reciclaje o trabajar sin la parte de la funcionalidad del complemento que ya no funciona.

Solicitar permiso para administrar el sitio web

Recuerde que cuando un complemento solicita permiso de lectura o escritura con el ámbito de Lista, SharePoint pide al usuario que confíe en el complemento y el cuadro de diálogo contiene una lista desplegable donde el usuario selecciona la lista a la que debe tener acceso el complemento. Solo se puede seleccionar una lista. Pero el complemento Chain Store ahora escribe en dos listas diferentes. Para obtener acceso a varias listas, el complemento tiene que solicitar permiso con el ámbito de Web. Siga estos pasos:

En el Explorador de soluciones, abra el archivo AppManifest.xml en el proyecto ChainStore.
Abra la pestaña Permisos y, en el campo Ámbito, seleccione Web en la lista desplegable.
En el campo Permiso, seleccione Escribir en la lista desplegable.
Guarde el archivo.

Ejecutar el complemento y probar la creación de elementos

Use la tecla F5 para implementar y ejecutar el complemento. Visual Studio hospeda la aplicación web remota en IIS Express y hospeda la base de datos SQL en SQL Express. También instala temporalmente el complemento en el sitio de SharePoint de prueba y ejecuta el complemento inmediatamente. Se le solicitará que conceda permisos al complemento antes de que se abra su página de inicio.
Cuando se abra la página de inicio del complemento, seleccione el vínculo Formulario de pedido situado en la parte inferior de la página.
Escriba algunos valores en el formulario y seleccione Realizar pedido.
Use el botón Volver del explorador para volver a la página de inicio y, después, seleccione Volver al sitio en el control de cromo de la parte superior.
En la página principal de la tienda de Hong Kong, vaya a Contenido del sitio y abra la lista Envíos esperados . Ahora hay un elemento en la lista correspondiente al pedido. La captura de pantalla siguiente es un ejemplo.

Figura 2. Lista de envíos esperados con un solo elemento
Para finalizar la sesión de depuración, cierre la ventana del explorador o detenga la depuración en Visual Studio. Cada vez que seleccione F5, Visual Studio retirará la versión anterior del complemento e instalará la más reciente.
Haga clic con el botón derecho en el proyecto en el Explorador de soluciones y seleccione Retirar.

Pasos siguientes

En el siguiente artículo, aprenderá a exponer el Formulario de pedido remoto como elemento web en una página de SharePoint: Incluir un elemento de complemento en el complemento hospedado por el proveedor.

Compartir a través de