Dar al complemento hospedado por el proveedor la apariencia de SharePoint

Artículo
04/08/2023

Este es el segundo de una serie de artículos sobre los conceptos básicos de desarrollo de complementos de SharePoint hospedados por el proveedor. Primero tiene que familiarizarse con el tema Complementos de SharePoint y con el artículo de información general de esta serie:

Empezar a crear complementos hospedados en proveedor para SharePoint

En el artículo anterior de esta serie, ha aprendido cómo configurar un entorno de desarrollo y cómo usar Visual Studio para crear un primer complemento de nivel "Hola a todos" que expone datos de SharePoint en la aplicación web remota del complemento.

Este artículo comienza con una solución de complemento de SharePoint que ya se ha creado. Incluye una base de datos de SQL Azure y una aplicación de ASP.NET Web Forms. Esta serie de artículos se centra únicamente en los complementos de SharePoint. Agregará más funcionalidades e integración de SharePoint al complemento con cada artículo de esta serie.

Introducción al complemento de base

No vamos a tratar programación T-SQUL o ASP.NET en esta serie, pero necesita saber un poco acerca de los componentes remotos del complemento antes de que podamos empezar su integración en SharePoint. El escenario del complemento usa como ejemplo una cadena de tiendas y cada una de ellas tiene un sitio web de grupo en la suscripción de SharePoint Online de la empresa matriz. Cuando una tienda instala el complemento en su sitio de grupo, el complemento permite que integren sus datos y experiencia de SharePoint con los datos de la base de datos de la empresa matriz. Cada instancia del complemento tiene su propio arrendamiento en la base de datos de la empresa y los usuarios solo pueden interactuar con los datos de la empresa asociados a su tienda.

Crear sitios de grupo para dos tiendas de la cadena

Abra la página principal del sitio de SharePoint Online y, a continuación, seleccione el vínculo Contenido del sitio en el inicio rápido. En la página Contenido del sitio, desplácese hacia abajo hasta que vea el vínculo Nuevo subsitio y selecciónelo.
En la página Nuevo sitio de SharePoint, rellene el formulario de un sitio de grupo con estos valores (también mostrados en la captura de pantalla siguiente):
- Título: tienda de Fabrikam en Hong Kong
- URL: hongkong
Figura 1. Formulario para crear un subsitio de SharePoint
Deje las demás opciones con los valores predeterminados y haga clic en Crear.

Explorar el complemento

Vaya a SharePoint_Provider-hosted_Add-Ins_Tutorials y haga clic en el botón Descargar ZIP para descargar el repositorio en el escritorio. Descomprima el archivo.
Inicie Visual Studio como administrador y, después, abra BeforeSharePointUI.sln. La solución contiene tres proyectos:
- ChainStore: el proyecto de complemento de SharePoint.
- ChainStoreWeb: la aplicación web remota.
- ChainCorporateDB: la base de datos de SQL Azure.
Seleccione el proyectoChainStore y, en la ventana Propiedades, establezca la propiedad URL del sitio como la dirección URL completa del sitio de grupo Hong Kong: https://{YOUR_SHAREPOINT_DOMAIN}/hongkong/ (asegúrese de incluya el carácter "/" al final). Haga clic en Guardar. En algún punto en este proceso, se le pedirá que inicie sesión en su suscripción a SharePoint Online.
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.
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.
La p?gina de inicio del complemento es similar a la figura 2. En la parte superior se encuentra el nombre del sitio web de SharePoint donde está instalado el complemento. Se trata de un efecto secundario de algún código de ejemplo que genera Office Developer Tools para Visual Studio. Se cambiará en un paso posterior. La página tiene áreas donde se pueden ver los datos de las tablas de bases de datos SQL pedidos, inventario y empleados de la empresa. Estas tablas están inicialmente en blanco.

Figura 2. Página de inicio del complemento de almacén de cadena
Seleccione el vínculo Formulario de pedido en la parte inferior de la página para abrir un formulario de pedido. Escriba algunos valores en el formulario y seleccione Realizar pedido. La captura de pantalla en la ilustración 3 muestra un ejemplo. No parece que ha sucedido nada, pero el código subyacente del botón pasa los valores a un procedimiento almacenado con parámetros de la base de datos SQL. Usar procedimientos almacenados con parámetros protege la base de datos de los ataques de inserción de SQL.

Figura 3. Formulario de pedido
Use el botón Atrás del explorador para volver a la página de inicio y, después, seleccione el botón Mostrar pedidos. La página de inicio se actualiza y su pedido aparece en una página parecida a la captura de pantalla de la Figura 4.

Figura 4. Página de inicio después de seleccionar Mostrar pedidos

La tabla contiene un campo Espacio empresarial con la dirección URL de su sitio web de SharePoint de prueba como valor. No se hace referencia a la suscripción a SharePoint Online, que en ocasiones recibe el nombre de "arrendamiento". En su lugar, cada instancia del complemento es un espacio empresarial distinto en la base de datos de la empresa. Al no poder instalarse más de una instancia de un complemento en una web de host de SharePoint determinada, la dirección URL de la web de host puede usarse como discriminador de clientes en la base de datos. (Para recordar la distinción entre web de host y complemento web, consulte Complementos de SharePoint).

Todos los procedimientos almacenados en el complemento incluyen el valor discriminador al escribir o leer de la base de datos. Así garantiza que, cuando un usuario selecciona Mostrar pedidos (o Mostrar inventario o Mostrar empleados), únicamente se recuperan de la base de datos los datos asociados con la tienda del usuario. Este diseño también asegura que los usuarios solo pueden realizar pedidos y agregar empleados para su propia tienda.

La aplicación web remota obtiene la dirección URL del web de host de una cadena de parámetros de consulta que SharePoint agrega a la dirección URL de la página de inicio al iniciar el complemento. Como ya est? usando SSL, esta cadena de consultas se cifra al viajar por Internet a la aplicaci?n web remota.
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 retira la versi?n anterior del complemento e instala la m?s reciente.
De manera predeterminada, el complemento permanece instalado en la web de host de SharePoint entre las sesiones de depuraci?n de Visual Studio. Para ver cómo lo lanzarían los usuarios finales tras su instalación, abra el sitio de SharePoint de Fabrikam Hong Kong en su navegador y vaya a la página Contenidos del sitio. Verá el icono para el complemento tal y como se muestra en la captura de pantalla siguiente.

Figura 5. Icono de inicio para el complemento Chain Store

Icono de inicio del complemento “Chain Store” en la página de contenidos del sitio con el icono y el nombre del complemento.

Nota:

Si selecciona el icono, no se abrirá la página de inicio porque Visual Studio cierra la sesión de IIS Express cuando detiene la depuración.

Configurar Visual Studio para recompilar la base de datos corporativa con cada sesión de depuración

De forma predeterminada, Visual Studio no recompilará la base de datos de SQL Express. Por lo tanto, los pedidos y otros elementos que agregue a la base de datos en una sesión de depuración permanecerán en ella en sesiones posteriores. Resulta más sencillo comenzar con una base de datos vacía cada vez que pulsa F5, así que siga estos pasos:

Haga clic con el botón derecho en el proyecto ChainCorporateDB y seleccione Propiedades.
Abra la pestaña Depurar y habilite la opción Volver a crear siempre la base de datos.

Asignar a la aplicación web remota la apariencia de SharePoint

En algunos escenarios, necesita que sus páginas remotas tengan su propia marca, pero en la mayoría de los casos deben imitar la interfaz de usuario de SharePoint para que los usuarios sientan que aún están dentro de SharePoint.

Agregar el cromo y la barra superior de SharePoint a la página de inicio

En el Explorador de soluciones, vaya a ChainStoreWeb>Páginas y abra el archivo CorporateDataViewer.aspx (la página de inicio del complemento).

En la sección de encabezado, verá un script que carga algunas bibliotecas de JavaScript. Agregue la siguiente secuencia de comandos adicional debajo. Este script carga el archivo SP.UI.Controls.js, que se encuentra en todos los sitios web de SharePoint en la carpeta /_layouts/15/. Entre otras cosas, este archivo carga la biblioteca de SharePoint CSS.

  <script type="text/javascript">
    var hostweburl;

    // Load the SharePoint resources.
    $(document).ready(function () {

        // Get the URI decoded add-in web URL.
        hostweburl =
            decodeURIComponent(
                getQueryStringParameter("SPHostUrl")
        );

        // The SharePoint js files URL are in the form:
        // web_url/_layouts/15/resource.js
        var scriptbase = hostweburl + "/_layouts/15/";

        // Load the js file and continue to the 
        // success handler.
        $.getScript(scriptbase + "SP.UI.Controls.js")
    });

    // Function to retrieve a query string value.
    function getQueryStringParameter(paramToRetrieve) {
        var params =
            document.URL.split("?")[1].split("&amp;");
        var strParams = "";
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
        }
    }
</script>

En la parte superior del cuerpo de la página, agregue la siguiente marcación. Esto insertará la barra superior de SharePoint, llamada el control de cromo, en la página. Los detalles de esta marcación quedarán más claros cuando probemos el complemento revisado más adelante en este artículo (la cadena "app" aparece en algunos de los nombres de propiedades porque los complementos antes recibían el nombre de "app").

  <!-- Chrome control placeholder. Options are declared inline.  -->
<div 
    id="chrome_ctrl_container"
    data-ms-control="SP.UI.Controls.Navigation"  
    data-ms-options=
        '{  
            "appHelpPageUrl" : "Help.aspx",
            "appIconUrl" : "/Images/AppIcon.png",
            "appTitle" : "Chain Store",
            "settingsLinks" : [
                {
                    "linkUrl" : "Account.aspx",
                    "displayName" : "Account settings"
                },
                {
                    "linkUrl" : "Contact.aspx",
                    "displayName" : "Contact us"
                }
            ]
         }'>
</div>

Los encabezados H1 y el hipervínculo en el cuerpo de la página usan estilos definidos automáticamente en la biblioteca de SharePoint CSS, por lo que no es necesario modificarlos. Para mostrar cómo puede usar los estilos de SharePoint, establezca los encabezados de columna en los tres controles de GridView como el estilo de SharePoint "Todo mayúsculas" agregando el atributo HeaderStyle-CssClass a cada uno de los controles y estableciendo su valor en ms-uppercase. Este es un ejemplo. Realice el mismo cambio en los tres controles de GridView.
```
  <asp:GridView ID="ordersGridView" runat="server" CellPadding="5" GridLines="None" 
HeaderStyle-CssClass="ms-uppercase" />
```
El control de cromo utiliza el icono de complemento, por lo que debemos enviar una segunda copia del archivo del icono al servidor web remoto. En el Explorador de soluciones, haga clic con el botón derecho en el archivo AppIcon.png del proyecto ChainStore y seleccione Copiar.
Haga clic con el botón derecho en la carpeta Imágenes del proyecto ChainStoreWeb y seleccione Pegar.
Abra el archivo CorporateDataViewer.aspx.cs.
La clase CorporateDataViewer declara un miembro privado de tipo SharePointContext. Esta clase se define en el archivo SharePointContext.cs generado por Office Developer Tools para Visual Studio cuando creó el proyecto. Se puede considerar como similar la clase HttpContextBase de ASP.NET, pero con información contextual de SharePoint como la dirección web de host agregada.

En el método Page_Load, una instrucción using escribe el nombre de la web de host en la página de inicio remota. Esto es código de ejemplo, por lo que debe eliminar completamente la instrucción using (pero conserve la línea que inicia la variable spContext). El método tendrá la siguiente apariencia.
```
  protected void Page_Load(object sender, EventArgs e)
{
    spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
}
```
Hay otros cuatro archivos de ASP.NET que necesitan la interfaz de usuario de SharePoint:
- Account.aspx
- Contact.aspx
- Help.aspx
- OrderForm.aspx
Nota:

El último archivo aspx en el proyecto, EmployeeAdder.aspx, nunca se representa en verdad, de modo que no cambie su interfaz de usuario. Obtendrá más información en un artículo posterior de esta serie.

No queremos el control de cromo en estas páginas. Solo es necesario acceder a la biblioteca de SharePoint CSS. Para cada uno de estos cuatro archivos, agregue la siguiente marcación en el elemento encabezado.
```
  <link type="text/css" rel="stylesheet" 
href="<%= spContext.SPHostUrl.ToString() + "_layouts/15/defaultcss.ashx" %>" />
```
Este paso y el siguiente ya se han realizado en las páginas Formulario de pedido y Cuenta, por lo que solo se aplican a las páginas de Contacto y Ayuda. Para obtener el spContext objeto en cada una de las páginas, abra el código *.aspx.cs detrás de los archivos de las tres páginas aspx. En cada caso, agregue el siguiente miembro a la clase Página.
```
  protected SharePointContext spContext;
```
Reemplace el método Page_Load por la siguiente versión. Se obtiene el objeto de la memoria caché de la sesión. Se almacenó en la memoria caché cuando se creó inicialmente con el método Page_Load de la página de inicio del complemento.
```
  protected void Page_Load(object sender, EventArgs e)
{
    spContext = Session["SPContext"] as SharePointContext;
}
```
Abra la página OrderForm.aspx. En el elemento Etiqueta de la parte superior, reemplace el elemento <b> de la frase Realizar pedido con etiquetas que hagan referencia a la clase CSS ms-accentText. Todo el control de etiqueta debería tener este aspecto cuando acabe.
```
  <asp:Label ID="lblOrderPrompt" runat="server"
         Text="Enter a supplier, product, and quantity; and then press <span class='ms-accentText'>Place Order</span>.">
</asp:Label>
```

Ejecutar el complemento y probar la nueva interfaz de usuario de SharePoint

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.
Al abrir la p?gina de inicio del complemento, ahora tiene el aspecto de una p?gina de SharePoint. Seleccione el vínculo Formulario de pedido. Ahora tiene el aspecto de un formulario de SharePoint.

Figura 6. Formulario de pedido con fuentes Segoe y un pedido de posición resaltado
Cree un pedido y seleccione Realizar pedido.
Use el botón Atrás del explorador para volver al complemento de la página de inicio y, después, seleccione Mostrar pedidos. Ahora la página será similar a la siguiente. Tenga en cuenta que los encabezados de columna están ahora en mayúsculas.

Figura 7. Página de inicio con un control de cromo
Seleccione el icono ? al final del control de cromo. Se abrirá una página de ayuda sencilla. Seleccione el botón Atrás del navegador.
Seleccione el icono del engranaje en el control de cromo. Se abrirá un menú con vínculos a una página de cuenta y otra de contacto. Abra la página de cuenta y use el botón Atrás del explorador para volver a la página de inicio. Haga lo mismo para la página de Contacto.
Seleccione el botón Volver al sitio en el control de cromo. Se abrirá la página principal de la web de host, el sitio de grupo de la tienda de Hong Kong.
Seleccione el icono de engranaje en la barra superior y, después, seleccione Cambiar la apariencia.
Siga las indicaciones para cambiar el sitio a una de las “apariencias” alternativas.
Vaya a la página Contenido del sitio y ejecute la aplicación Chain Store desde el icono correspondiente. Las páginas personalizadas adoptaron el aspecto elegido. Las capturas de pantalla siguientes muestran cómo aparecen en el aspecto compuesto Naturaleza.

Figura 8. La página de inicio y el formulario de pedido con el aspecto compuesto por la naturaleza

Página de inicio del complemento y formulario de pedido con los colores verdosos de la apariencia compuesta Naturaleza.

Cambie nuevamente el aspecto del sitio al predeterminado, que se denomina Office.
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 retira la versión anterior del complemento e instala 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

El complemento ahora es similar a SharePoint, pero aún es tan solo una aplicación web que realmente no se integra con SharePoint más allá de que se ejecuta desde un icono de SharePoint. En el siguiente artículo vamos a agregar un comando personalizado que se inicia desde un botón personalizado de la cinta de opciones: Incluir un botón personalizado en el complemento hospedado por el proveedor.