Implementar con programación un botón personalizado en el complemento hospedado por el proveedor

Artículo
04/08/2023

Este es el noveno 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 BeforeProgrammaticButton.sln.

En este artículo aprenderá a incluir un botón personalizado de la cinta de opciones en un Complemento de SharePoint cuando la lista cuya cinta de opciones obtiene el botón se implementa mediante programación en el mismo complemento.

Volver a agregar el botón personalizado al proyecto

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 el artículo anterior se quitó del proyecto el botón personalizado de la cinta de opciones AddEmployeeToCorpDB. Agréguelo de nuevo con los pasos siguientes.

En la barra de herramientas en la parte superior del Explorador de soluciones, seleccione el botón Mostrar todos los archivos.

Figura 1. barra de herramientas de Explorador de soluciones
En el proyecto ChainStore, haga clic con el botón derecho en AddEmployeeToCorpDB y seleccione Incluir en el proyecto.
Seleccione el botón Mostrar todos los archivos de nuevo.
En el proyecto ChainStore, expanda AddEmployeeToCorpDB y abra el archivo elements.xml.

Información sobre un dilema y su solución

En el archivo elements.xml, el atributo RegistrationId del elemento CustomAction identifica la lista en cuya cinta de opciones se agrega el botón: {$ListId:Lists/Local Employees;}. Esto funcionaba bien cuando la lista ya se había agregado a la web de host manualmente. Pero ahora que estamos implementando la lista mediante programación en la lógica de la primera vista, la lista no existe cuando SharePoint instala el complemento e intenta volver a implementar el botón. Se producen una excepción y un error en la instalación del complemento.

Implementar la lista en el controlador de eventos de la instalación (en lugar de hacerlo en la lógica de primera vista) no solucionará el dilema porque SharePoint implementa componentes personalizados definidos de forma descriptiva, como el botón personalizado (y el elemento de complemento Realizar pedido), antes de ejecutar el controlador personalizado y, por lo tanto, la lista no existirá cuando intente implementar el botón.

Crear un botón personalizado totalmente mediante programación no resulta práctico por motivos demasiado avanzados para comentarlos en este punto. Afortunadamente, no es necesario. Hay una manera relativamente sencilla para crear, no del todo con programación, un botón personalizado y asignarlo a una lista personalizada.

Estos son los pasos básicos que deben seguirse:

Mantenga el botón definido descriptivamente en el proyecto, pero asígnelo a la cinta de opciones de algo que siempre exista en los sitios de SharePoint, en lugar de a una lista que se implementa mediante programación con el mismo complemento.
En la lógica de primera vista, después de crear con programación la lista, agregue con programación un botón no definido a la cinta de opciones de la lista.
Inicializar las propiedades del botón nuevo con los valores del botón original. En este momento, hay dos botones idénticos. El segundo se asigna a la cinta de la lista Empleados locales.
Elimine con programación el botón original.

Registrar mediante programación el botón personalizado

En el procedimiento siguiente se muestra cómo implementar esta estrategia.

En el proyecto ChainStore, expanda AddEmployeeToCorpDB, abra el archivo elements.xml y, después, cambie el valor del atributo RegistrationId del elemento CustomAction a "100". Este es el identificador de un tipo de lista. Incluso si no hay ninguna instancia de listas de este tipo en el sitio web, la lista tipo se encuentra en cada sitio web de SharePoint. El atributo ahora debería ser similar al siguiente.
```
  RegistrationId="100"
```
En el archivo SharePointComponentDeployer.cs, agregue la siguiente línea al método DeployChainStoreComponentsToHostWeb, justo debajo de la línea que llama CreateLocalEmployeesList (este método se creará en el paso siguiente).
```
  ChangeCustomActionRegistration();
```

Agregue el método siguiente a la clase SharePointComponentDeployer.

   private static void ChangeCustomActionRegistration()
 {
     using (var clientContext = sPContext.CreateUserClientContextForSPHost())
     {
 	 var query = from action in clientContext.Web.UserCustomActions
 		     where action.Name == "{button_GUID} .AddEmployeeToCorpDB"
 		     select action;
 	  IEnumerable<UserCustomAction> matchingActions = clientContext.LoadQuery(query);	       
 		 clientContext.ExecuteQuery();

 	  UserCustomAction webScopedEmployeeAction = matchingActions.Single();

 	 // TODO8: Get a reference to the (empty) collection of custom actions 
 	 // that are registered with the custom list.

 	 // TODO9: Add a blank custom action to the list's collection.

 	 // TODO10: Copy property values from the descriptively deployed
 	 // custom action to the new custom action

 	// TODO11: Delete the original custom action.         

 	  clientContext.ExecuteQuery();
     }
 }

Tenga en cuenta lo siguiente en relación con este código:

Dado que la acción personalizada (es decir, el botón personalizado) se registró con la cinta de opciones de una lista tipo, se aplica a todo el sitio web y se encuentra en la colección del sitio web de acciones personalizadas. Así que el código lo recupera de esa colección.
El valor de action.Name procede del atributo ID del elemento CustomAction del archivo elements.xml de AddEmployeeToCorpDB.

Importante

Debe cambiar el valor action.Name en el código para que coincida con el valor del archivo elements.xml. El elemento GUID del nombre será diferente. Tenga en cuenta que hay un carácter "." entre el GUID y el resto del nombre. A continuación verá un ejemplo de la línea:

where action.Name == "4a926a42-3577-4e02-9d06-fef78586b1bc.AddEmployeeToCorpDB"

Cambie TODO8 por el código siguiente. Tenga en cuenta que cuando retira un complemento, no se eliminan los componentes creados por el complemento. Después de ejecutar la lógica de primera ejecución, habrá una acción personalizada en la colección de la lista UserCustomActions y no se retirará la próxima vez que seleccione F5. Para evitar confusiones, la última línea de este código listActions.Clear(); vacía la colección.
```
 var queryForList = from list in clientContext.Web.Lists
 		   where list.Title == "Local Employees"
 		   select list;
 IEnumerable<List> matchingLists = clientContext.LoadQuery(queryForList);
 clientContext.ExecuteQuery();

 List employeeList = matchingLists.First();
 var listActions = employeeList.UserCustomActions;
 clientContext.Load(listActions);
 listActions.Clear();
```
Cambie TODO9 por la línea siguiente, que agrega una acción personalizada no definida en la lista Empleados locales.
```
  var listScopedEmployeeAction = listActions.Add();
```
Cambie TODO10 por el código siguiente.
```
 listScopedEmployeeAction.Title = webScopedEmployeeAction.Title;
 listScopedEmployeeAction.Location = webScopedEmployeeAction.Location;
 listScopedEmployeeAction.Sequence = webScopedEmployeeAction.Sequence;
 listScopedEmployeeAction.CommandUIExtension = webScopedEmployeeAction.CommandUIExtension;
 listScopedEmployeeAction.Update();
```
Tenga en cuenta lo siguiente en relación con este código:
- Asigna los valores de propiedad del botón de ámbito web (que se implementó con marcado descriptivo) a las propiedades correspondientes del botón de ámbito de la lista, por lo que los dos botones son idénticos excepto en el ámbito.
- La propiedad Secuencia especifica el orden relativo en el que el botón aparecerá en el área de la cinta de opciones. En este caso, el botón se encuentra en la sección Acciones de la pestaña Elementos de la cinta de opciones. En el marcado descriptivo, se establece este valor en 10001, que es lo suficientemente alto como para asegurar que aparecerá después (es decir, a la derecha) de los botones en el equipo que SharePoint coloca en la sección Acciones de la cinta.
Reemplace TODO11 con la siguiente línea, que elimina el botón original definido de forma descriptiva. Si no ha tenido esta línea, cada lista en el sitio web que usa la plantilla de lista "100" tendrá el botón personalizado. Dado que la funcionalidad del botón está ligada estrechamente a la lista Empleados locales, no tendría sentido tener el botón en cualquier otra lista. Además, sin esta línea, el botón aparecería dos veces en la lista Empleados locales, porque esa lista usa la plantilla "100".
```
  webScopedEmployeeAction.DeleteObject();
```

El método completo ahora debería ser similar al siguiente (pero debería haber un GUID en lugar del marcador de posición).

   private static void ChangeCustomActionRegistration()
 {
     using (var clientContext = SPContext.CreateUserClientContextForSPHost())
     {
 	 var query = from action in clientContext.Web.UserCustomActions
 		     where action.Name == "{button_GUID} .AddEmployeeToCorpDB"
 		     select action;
 	  IEnumerable<UserCustomAction> matchingActions = clientContext.LoadQuery(query);	       
 		 clientContext.ExecuteQuery();

 	  UserCustomAction webScopedEmployeeAction = matchingActions.Single();

 	 var queryForList = from list in clientContext.Web.Lists
 			    where list.Title == "Local Employees"
 			    select list;
 	 IEnumerable<List> matchingLists = clientContext.LoadQuery(queryForList);
 	 clientContext.ExecuteQuery();

 	List employeeList = matchingLists.First();
 	var listActions = employeeList.UserCustomActions;
 	clientContext.Load(listActions);
 	listActions.Clear();

 	var listScopedEmployeeAction = listActions.Add();

 	listScopedEmployeeAction.Title = webScopedEmployeeAction.Title;
 	listScopedEmployeeAction.Location = webScopedEmployeeAction.Location;
 	listScopedEmployeeAction.Sequence = webScopedEmployeeAction.Sequence;
 	listScopedEmployeeAction.CommandUIExtension = webScopedEmployeeAction.CommandUIExtension;
 	listScopedEmployeeAction.Update();

 	webScopedEmployeeAction.DeleteObject();         

 	clientContext.ExecuteQuery();
     }
 }

Solicitar control total de la web de host

Dado que el complemento ahora agrega y elimina acciones personalizadas de ámbito web, necesitamos elevar los permisos que el complemento solicita de Administrar a Control total:

En el Explorador de soluciones, abra el archivo AppManifest.xml en el proyecto ChainStore.
Abra la pestaña Permisos. Deje el valor Ámbito en Web; pero, en el campo Permiso de la lista desplegable, seleccione Control total.
Guarde el archivo.

Ejecutar el complemento y probar la implementación del botón

Abra la página Contenidos del sitio del sitio web de la tienda Hong Kong y elimine la lista Empleados locales.

Nota:

Retirar un complemento en Visual Studio no quita las listas que creó el complemento, por lo que necesita eliminarlo de forma manual cada vez se está probando código que lo crea.
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 Volver al sitio en el control de cromo de la parte superior.
Vaya a la página Contenidos del sitio. La lista Empleados locales está presente porque la lógica de primera ejecución la agregó.

Nota:

Si la lista no existe o tiene otras indicaciones de que el código de primera ejecución no se está ejecutando, es posible que la tabla Inquilinos no vuelva a un estado vacío al seleccionar F5. La causa más común de esto es que el proyecto ChainCorporateDB ya no está establecido como un proyecto de inicio en Visual Studio. Consulte la nota en la parte superior de este artículo sobre cómo solucionar este problema. Además, asegúrese de que ha configurado la base de datos para que se recopile como se describe en Configurar Visual Studio para recompilar la base de datos corporativa con cada sesión de depuración.
Abra la lista y agregue un elemento.
En la vista de lista, seleccione el elemento y, a continuación, abra la pestaña Elemento en la cinta de opciones.
En la pestaña Elemento, seleccione el botón Agregado a BD corporativa. El empleado se agrega a la base de datos corporativa y el campo Agregado a BD corporativa se cambia a Sí.
Vaya de nuevo a navegar a la página Contenidos del sitio y seleccione Agregar un complemento.
Agregar una nueva Lista personalizada. De forma predeterminada será de tipo "Genérico" (Genérico es el tipo de lista 100). Después de crea la lista, abra la pestaña Elemento en la cinta de opciones. Observe que el botón Agregar a BD corporativano se encuentra en la cinta de opciones. Esto es porque el código elimina el botón de ámbito de web.
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

Los eventos en listas y los elementos de lista pueden tener controladores personalizados en SharePoint. Aprenderá a crear uno e implementarlo en la lógica de primera ejecución en Controlar los eventos de elemento de lista en el complemento hospedado por el proveedor.

Compartir a través de