Incluir un botón personalizado en el complemento hospedado por el proveedor

Artículo
04/08/2023

Este es el tercero 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 que encontrará en SharePoint_Provider-hosted_Add-Ins_Tutorials y abrir el archivo BeforeRibbonButton.sln.

Un complemento de SharePoint puede incluir acciones personalizadas, que es el término de SharePoint para los elementos de menú personalizados o los botones de la cinta de opciones. En este artículo aprenderá a crear un botón personalizado que sincronice una lista de SharePoint con una base de datos remota.

Crear una lista personalizada en el sitio web de host

El botón personalizado va a estar en la cinta de opciones de una lista específica que registra a los empleados de la tienda local. 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 lo haremos 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 Empleados locales como el nombre y seleccione Crear.
En la página Contenido del sitio, abra la lista Empleados locales.
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 Nombre y, después, seleccione Aceptar.
En la página Configuración, seleccione Crear columna.
En el formulario Crear columna, haga lo siguiente:
1. En el Nombre de columna, escriba Agregado a BD corporativa.
2. Establezca el tipo en Sí/No (casilla).
3. Establezca el Valor predeterminado en No.
4. Seleccione Aceptar. Volverá a la página Configuración.
Seleccione Contenido del sitio para abrir la página Contenido del sitio. Aquí aparece el icono de la nueva lista. Ábralo.
Haga clic en Nuevo elemento y, en el formulario de creación del elemento, escriba un nombre pero no seleccione Agregado a BD corporativa. Seleccione Guardar. La lista debería parecerse a la siguiente.

Figura 1. Lista de empleados locales con un solo elemento

Agregar un botón personalizado

En esta sección, se incluyen marcas en el complemento que implementa un botón en la cinta de opciones de la lista. Cuando un usuario resalta un empleado en la lista y selecciona el botón, el nombre del empleado se agrega a la base de datos corporativa y el campo Agregado a BD corporativa del empleado cambia de No a Sí.

Si Visual Studio está abierto, debe cerrarlo y volver a abrir la solución Chain Store para que Visual Studio pueda detectar la nueva lista (ejecute Visual Studio como administrador).
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:
1. 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.
2. Asegúrese de que los tres proyectos estén establecidos en Iniciar en la columna Acción.
Haga clic con el botón derecho en el proyecto ChainStore en el Explorador de soluciones y después seleccione Agregar>Nuevo elemento.
En el cuadro de diálogo Agregar nuevo elemento, seleccione Acción personalizada de cinta, asígnele el nombre AddEmployeeToCorpDB y, después, seleccione Agregar.

El cuadro de diálogo que se abre hace tres preguntas. Proporcione las respuestas siguientes:

Pregunta	Proporcione esta respuesta:
¿Dónde desea exponer la acción personalizada?	Web de host
¿Qué ámbito tiene la acción personalizada?	Instancia de lista
¿Qué elemento específico tiene como ámbito la acción personalizada?	Empleados locales

Seleccione Siguiente para obtener tres preguntas más:

Pregunta	Proporcione esta respuesta:
¿Dónde se encuentra el control?	Ribbon.ListItem.Actions
¿Cuál es el texto de la etiqueta del control de botón?	Agregar a BD corporativa
¿A dónde dirige el control de botón?	ChainStoreWeb\Pages\EmployeeAdder.aspx (es una página cuyo código subyacente agregará el empleado a la base de datos)

Haga clic en Finalizar.

Se agrega al proyecto y se abre un archivo elements.xml que define la acción personalizada. En la mayoría de casos, puede tratar este archivo como un cuadro en blanco y no tendrá que realizar cambios en él hasta llegar a un artículo posterior de esta serie. Por ahora, tenga en cuenta lo siguiente:
- El atributo Location del elemento CommandUIDefinition tiene el valor Ribbon.ListItem.Actions.Controls_children. La segunda parte de este valor, ListItem, identifica la pestaña de la cinta donde se colocará el botón (pero puede que no sea el nombre exacto de la pestaña que se verá). La tercera parte, Actions, es el nombre de la sección de la cinta donde se colocará el botón.
- El atributo CommandAction del elemento CommandUIHandler comienza con el marcador de posición ~remoteAppUrl. Se reemplazará por la dirección URL de la aplicación web remota cuando se implemente el botón.
- Algunos parámetros de consulta se han agregado al valor CommandAction con los valores del marcador de posición entre llaves "{}". Estos marcadores de posición se resuelven en tiempo de ejecución. Tenga en cuenta que uno de ellos es el identificador del elemento de lista que el usuario seleccione antes de seleccionar el botón personalizado en la cinta de opciones.
En el proyecto ChainStoreWeb, abra el archivo Pages/EmployeeAdder.aspx. Observe que no tiene ninguna interfaz de usuario. El complemento utilizará esta página como un tipo de servicio web. Esto es posible porque la clase ASP.NET System.Web.UI.Page implementa System.Web.IHttpHandler y porque el evento Page_Load se ejecuta automáticamente cuando se solicita la página.
Abra el archivo de código subyacente Pages/EmployeeAdder.aspx.cs. El método que se agrega al empleado a la base de datos remota, AddLocalEmployeeToCorpDB, ya existe. Usa el objeto SharePointContext para obtener la dirección URL del sitio web de host que el complemento utiliza como discriminador de inquilino. Lo primero que el método Page_Load debe hacer es inicializar este objeto. Cuando se carga la página de inicio del complemento, el objeto se crea y se guarda en caché en la sesión. Agregue el código siguiente al método Page_Load. El objeto SharePointContext se define en el archivo SharePointContext.cs generado por Office Developer Tools para Visual Studio al crear la solución del complemento.
```
spContext = Session["SPContext"] as SharePointContext;
```
El método AddLocalEmployeeToCorpDB toma el nombre del empleado como parámetro. Por lo tanto, agregue la siguiente línea al método Page_Load. Creará el método GetLocalEmployeeName en un paso posterior.
```
// Read from SharePoint 
string employeeName = GetLocalEmployeeName();
```
Debajo de esta línea, agregue la llamada al método AddLocalEmployeeToCorpDB.
```
// Write to remote database 
AddLocalEmployeeToCorpDB(employeeName);
```
Agregue una instrucción using al archivo para el espacio de nombres Microsoft.SharePoint.Client. (Office Developer Tools para Visual Studio incluyó el ensamblado Microsoft.SharePoint.Client en el proyecto ChainStoreWeb cuando se creó).
Ahora agregue el método siguiente a la clase EmployeeAdder. En otra parte de MSDN se profundiza con detalle en el modelo de objetos del lado cliente (CSOM) .NET de SharePoint. Le recomendamos que lo consulte cuando termine con esta serie de artículos. Para este artículo, tenga en cuenta que la clase ListItem representa un elemento de una lista de SharePoint y que puede hacer referencia al valor de un campo del elemento con la sintaxis "indizador". Observe también que en el código se hace referencia al campo como Título, aunque haya cambiado el nombre del campo por Nombre. Esto es así porque en el código siempre se hace referencia a los campos con el nombre interno, no con el nombre para mostrar. El nombre interno de los campos se define al crear los campos y no se puede cambiar nunca. Completará TODO1 en un paso posterior.
```
private string GetLocalEmployeeName()
{
  ListItem localEmployee;

  // TODO1: Initialize the localEmployee object by getting  
  // the item from SharePoint.

  return localEmployee["Title"].ToString();
}
```
El código necesitará el id. del elemento de la lista para poder recuperarlo de SharePoint. Agregue la siguiente declaración a la clase EmployeeAdder, justo debajo de la declaración del objeto spContext.
```
private int listItemID;
```

Ahora, agregue el método siguiente a la clase EmployeeAdder para obtener el id. del elemento de la lista del parámetro de consulta.

private int GetListItemIDFromQueryParameter()
{
  int result;
  Int32.TryParse(Request.QueryString["SPListItemId"], out result);
  return result;
}

Para inicializar la variable listItemID, agregue la línea siguiente al método Page_Load, justo debajo de la línea que inicializa la variable spContext.
```
listItemID = GetListItemIDFromQueryParameter();
```

En GetLocalEmployeeName, reemplace TODO1 por el siguiente código. De momento, considere este código como un cuadro en blanco mientras nos centramos en hacer que el botón personalizado funcione. Obtendremos más información sobre este código en el siguiente artículo de esta serie, que trata del modelo de objetos del lado cliente de SharePoint.

using (var clientContext = spContext.CreateUserClientContextForSPHost())
{
  List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
  localEmployee = localEmployeesList.GetItemById(listItemID);
  clientContext.Load(localEmployee);
  clientContext.ExecuteQuery();
}

El método completo tendrá la siguiente apariencia.

private string GetLocalEmployeeName()
{
  ListItem localEmployee;

  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
    List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
    selectedLocalEmployee = localEmployeesList.GetItemById(listItemID);
    clientContext.Load(selectedLocalEmployee);
    clientContext.ExecuteQuery();
  }
  return localEmployee["Title"].ToString();
}

En realidad, la página de EmployeeAdder no debería renderizarse, así que agregue lo siguiente como última línea del método Page_Load. El explorador se redirige a la página de vista de la lista Empleados locales.

// Go back to the Local Employees page
Response.Redirect(spContext.SPHostUrl.ToString() + "Lists/Local%20Employees/AllItems.aspx", true);

Ahora el método completo Page_Load debería tener el aspecto siguiente.

protected void Page_Load(object sender, EventArgs e)
{
  spContext = Session["SPContext"] as SharePointContext;
  listItemID = GetListItemIDFromQueryParameter();

  // Read from SharePoint
  string employeeName = GetLocalEmployeeName();

  // Write to remote database
  AddLocalEmployeeToCorpDB(employeeName);

  // Go back to the preceding page
  Response.Redirect(spContext.SPHostUrl.ToString() + "Lists/Local%20Employees/AllItems.aspx", true);
}

Solicitar permiso para leer la lista de web de host

Como ha visto, SharePoint le pregunta si desea conceder los permisos del complemento a la web de host durante la instalación. Cada vez que seleccione F5, estará volviendo a instalar el complemento. Hasta el momento, el complemento solo ha necesitado permisos mínimos, pero el método GetLocalEmployeeName requiere que el permiso lea las listas del sitio web de host. El complemento usa su manifiesto para indicar a SharePoint qué permisos necesita. Siga estos pasos.

En el Explorador de soluciones, abra el archivo AppManifest.xml del proyecto ChainStore (el archivo se denomina AppManifest porque los complementos se solían llamar “aplicaciones”). Se abrirá el diseñador de manifiestos.
Abra la pestaña Permisos y seleccione la celda vacía de la columna Ámbito. Después, seleccione Lista en la lista desplegable.
En el campo Permiso, seleccione Lectura en la lista desplegable.
Deje vacío el campo Propiedades y guarde el archivo. La pestaña Permisos debe tener un aspecto similar al siguiente.

Figura 2. Pestaña Permisos

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. Esta vez, en la solicitud, aparece una lista desplegable en la que puede seleccionar la lista que la aplicación tiene que leer, como se muestra en la siguiente captura de pantalla.

Figura 3. Solicitud de permiso del complemento de SharePoint
Seleccione Empleados locales en la lista y, después, seleccione Confiar.
Cuando se abra la página de inicio del complemento, seleccione 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.
Agregue a algunos empleados a la lista. 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 elemento de la lista. La página y la cinta de opciones serán similares al ejemplo siguiente.

Figura 4. Lista de empleados locales
Después de seleccionar un elemento de la lista, seleccione Agregar a BD corporativa.
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.
Toque dos veces el botón Atrás del explorador para volver a la página de inicio del complemento.
Seleccione Mostrar empleados para que la lista de empleados se rellene con el empleado que agregó. Debería parecerse a la lista siguiente.

Figura 5. Lista de empleados corporativos en la página de inicio del complemento
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.
Trabajará con este complemento y con la solución de Visual Studio en otros artículos. Es recomendable que vuelva a retirar el complemento cuando deje de trabajar con él por un tiempo. 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, dejaremos brevemente la codificación para echar un vistazo rápido al modelo de objetos del lado cliente de SharePoint.

Compartir a través de