Convertir un complemento de SharePoint autohospedado en uno hospedado por el proveedor

En Microsoft SharePoint se introdujo un nuevo método para extender sitios de SharePoint, además del método anterior de usar personalizaciones basadas en soluciones. Este nuevo modelo de extensibilidad de SharePoint, llamado modelo de complementos, permite a los desarrolladores crear implementaciones personalizadas que se pueden implementar en entornos de SharePoint, independientemente de que se ejecuten en una implementación local, de SharePoint Online o híbrida.

Los desarrolladores pueden compilar dos tipos distintos de complementos de SharePoint. El primer tipo, un complemento hospedado en SharePoint, se ejecuta principalmente en el explorador y todos los activos que lo admiten (como HTML, CSS, imágenes y JavaScript) se almacenan en SharePoint, que los entrega. Los demás tipos de complementos se incluyen en el modelo de complemento de nube (CAM) y se ejecutan principalmente en otro servidor externo a SharePoint y se comunican con SharePoint mediante el modelo de objetos del lado cliente (CSOM) y la API de REST. Establecen una identidad mediante el conocido protocolo OAuth 2.0 que SharePoint admite.

Los desarrolladores podían implementar complementos mediante el modelo de complemento de una de dos maneras: como complemento hospedado por el proveedor o como complemento autohospedado. Los complementos autohospedados se presentaron como un programa de versión preliminar durante el lanzamiento de SharePoint; pero, en mayo de 2014, Microsoft anunció la cancelación del programa de versión preliminar y que dejaría de admitir la creación de complementos autohospedados. Para leer el anuncio, vea Actualización del programa de versión preliminar de los complementos autohospedados.

En este artículo se explica cómo convertir un complemento autohospedado en un complemento hospedado por el proveedor y cómo migrarlo. No obstante, es importante que los desarrolladores entiendan algunas diferencias concretas entre los dos enfoques, dado que ese conocimiento simplifica en gran medida el proceso de conversión.

Requisitos previos para convertir un complemento autohospedado en uno hospedado por el proveedor

• Todos los requisitos previos para desarrollar complementos hospedados por el proveedor.

• Azure SDK para .NET 2.3

Conceptos básicos que es importante conocer antes de convertir un complemento autohospedado

Para convertir un complemento autohospedado en uno hospedado por el proveedor, debe contar con nociones básicas de los complementos de SharePoint y las diferencias entre complementos hospedados en SharePoint, hospedados por el proveedor y autohospedados. Los artículos de la tabla siguiente deberían darle esas nociones.

Conversión del complemento

Para convertir un complemento de SharePoint autohospedado en un complemento hospedado por el proveedor es necesario modificar dos o tres componentes.

• El propio complemento de SharePoint
• La aplicación web remota o los servicios
• La instancia de Microsoft Azure SQL Database, si la hubiera, del complemento

Un complemento de SharePoint autohospedado se implementa automáticamente en el sitio web de Azure y en Azure SQL Database cuando se ha instalado, pero los complementos hospedados por el proveedor pueden tener su aplicación web remota y otros servicios que se encuentran en cualquier plataforma web. En este artículo se presupone que los componentes remotos de un complemento autohospedado permanecerán como servicios de Azure tras la conversión a complemento hospedado por el proveedor.

Las secciones siguientes le guiarán a través del proceso de conversión de un complemento autohospedado en uno hospedado por el proveedor. El complemento autohospedado de ejemplo que se usa, Customer Manager, es sencillo a fin de centrarse en los pasos de conversión y no en el propio complemento. Se compone de tres proyectos:

• CustomersDb: proyecto de base de datos SQL que genera el *.dacpac necesario. Tenga en cuenta que no hay ningún esquema definido en este proyecto. Solo se utiliza para crear una base de datos, ya que la aplicación web ASP.NET crea el esquema.

• CustomerManagerAH: complemento autohospedado de SharePoint que se configura de modo que incluya el proyecto de aplicación web ASP.NET y la aplicación de capa de datos SQL de Azure en el paquete del complemento de SharePoint resultante.

• CustomerManagerAHWeb: aplicación web ASP.NET MVC que usa el enfoque "Migraciones de Code First en Entity Framework" para crear el esquema de base de datos así como para leer y escribir en la base de datos.

El complemento es una aplicación web ASP.NET MVC que tanto puede mostrar los clientes de una tabla de una instancia de Azure SQL Database como agregar nuevos clientes. Se trata de una aplicación web anónima que permite que cualquier persona vea y agregue clientes. La solución de Visual Studio para el complemento autohospedado y los proyectos asociados pueden descargarse desde el siguiente repositorio público: Autohosted-Migration-Code-Samples.

Para convertir un complemento autohospedado de SharePoint en uno hospedado por el proveedor es necesario completar varios pasos. Cada uno de estos pasos se describe en las secciones siguientes:

1. Implementar Azure SQL Database

2. Crear el sitio web de Azure para hospedar la aplicación web remota

3. Registro del complemento en el sitio de SharePoint

4. Actualizar e implementar el sitio web de Azure para la aplicación web remota

5. Reconfigurar el proyecto de complemento de SharePoint

Implementar Azure SQL Database

El primer paso para convertir el complemento autohospedado en uno hospedado por el proveedor consiste en implementar la instancia de Azure SQL Database que depende de la aplicación web ASP.NET. Hay diferentes formas de crear una instancia de Azure SQL Database, algunas de ellas se documentan en el sitio de documentación de Azure: Migración de una base de datos de SQL Server a una instancia de SQL Database en la nube.

El enfoque explicado en los siguientes pasos usa el modelo de implementación de aplicaciones de capa de datos, porque ese es el modo en que la base de datos se implementa en un complemento autohospedado de SharePoint. Eso implica crear un paquete de aplicación de capa de datos (*.dacpac) y usarlo para crear la base de datos.

Para crear la instancia de Azure SQL Database

1. Abra la solución autohospedada en Visual Studio.

2. Haga clic con el botón derecho en el proyecto de base de datos CustomerDb y seleccione Crear. Así se genera el archivo CustomerDb.dacpac en la carpeta [..]\bin\[debug | release].

3. Crear una instancia de Azure SQL Database. Inicie sesión en Azure Portal y, cuando el panel se cargue, seleccione el vínculo BASES DE DATOS SQL del margen.

   

   
   

4. Seleccione el vínculo SERVIDORES del menú de navegación superior y luego el botón AGREGAR del pie de página, tal y como se muestra en la ilustración siguiente:

   

   
   

5. En el cuadro de diálogo CREAR SERVIDOR que aparece, seleccione las opciones SUSCRIPCIÓN, NOMBRE DE INICIO DE SESIÓN y CONTRASEÑA de Azure del usuario que tendrá derechos en el servidor y seleccione la misma REGIÓN usada anteriormente al crear el sitio web de Azure. Tome nota del nombre de inicio de sesión y la contraseña, ya que los necesitará en un paso posterior.

   

   
   

6. Cuando haya rellenado el formulario, seleccione el icono de marca de verificación de la esquina inferior derecha para crear la base de datos. Aunque el servidor ya está creado, los únicos recursos que tienen acceso a él son otros servicios de Azure. Tome nota del nombre de la instancia de Azure SQL Database porque lo necesitará en un paso posterior.

Para implementar la instancia de Azure SQL Database

1. Para conectarse a la instancia de Azure SQL Database e implementar la base de datos, hay que crear una regla de firewall que permita el tráfico procedente del equipo donde se implementa la base de datos. En caso contrario, se rechazarán las conexiones a Azure SQL Database con errores similares al de la ilustración siguiente.

   

   
   

2. Para crear una regla de firewall, en Azure Portal, seleccione la instancia de Azure SQL Database que se creó anteriormente y luego elija el vínculo CONFIGURAR en el panel de navegación superior.

3. En la sección direcciones IP permitidas, la dirección IP se muestra actualmente tal y como aparece en la siguiente ilustración. Seleccione AGREGAR A LAS DIRECCIONES IP PERMITIDAS para agregar una regla de firewall. Al hacerlo, permite las conexiones a la instancia de Azure SQL Database y la implementación de la base de datos. Seleccione Guardar en el pie de página.

   

   
   

4. Implemente la base de datos de Visual Studio mediante Azure SDK para .NET 2.3.

5. En Visual Studio, abra la ventana de herramientas Explorador de objetos de SQL Server, haga clic con el botón derecho en el nodo SQL Server y seleccione Agregar SQL Server.

   

   
   

6. En el cuadro de diálogo Conectar al servidor, escriba el Nombre del servidor, establezca la Autenticación en Autenticación de SQL Server y escriba el mismo Inicio de sesión y Contraseña que definió al crear la instancia de Azure SQL Database. El nombre del servidor debe ser el nombre completo del servidor, que es [server-name].database.windows.net, tal y como se muestra en la ilustración siguiente.

   

   
   

7. Cuando se haya conectado a la instancia de Azure SQL Database, expanda el nodo del servidor que acaba de agregar, haga clic con el botón derecho en el nodo Bases de datos y seleccione Publicar aplicación de capa de datos para abrir el Asistente para la publicación.

8. En la sección Aplicación de capa de datos de origen (.dacpac), use el botón Examinar para buscar el archivo *.dacpac generado al crear el proyecto de base de datos en un paso anterior y asegúrese de que el Nombre de la base de datos esté establecido en CustomerDb.

9. Seleccione Publicar para publicar la base de datos CustomerDb en la instancia de Azure SQL Database.

   

   
   

10. Actualice la ventana de herramientas Explorador de objetos de SQL Server de Visual Studio para ver que CustomerDb aparece en el nodo Bases de datos.

Acciones posteriores a la implementación

Cuando haya creado la instancia de Azure SQL Database, copie la cadena de conexión que se usa para establecer conexión con la base de datos. Puede hacerse de dos maneras.

• Una consiste en iniciar sesión en Azure Portal e ir a la instancia de Azure SQL Database creada en el último paso: CustomerDb. En la página PANEL de la base de datos, seleccione el vínculo Mostrar cadenas de conexión para ver una lista de cadenas de conexión. Copie la cadena de conexión ADO.NET para su uso posterior.

  

  
  

• La otra forma de obtener la cadena de conexión es desde Visual Studio, siempre que esté instalado Azure SDK v2.3. En la ventana de herramientas Explorador de objetos de SQL Server de Visual Studio, seleccione la base de datos CustomerDb. Cuando haya seleccionado la base de datos, vea la cadena de conexión en la ventana de herramientas Propiedades. Se trata del mismo valor que se encuentra en Azure Portal.

  

  
  

Creación de un sitio web de Azure

El siguiente paso es crear un nuevo sitio web de Azure donde se guardará la aplicación web remota para el complemento hospedado por el proveedor. Esto debe realizarse en primer lugar, porque la dirección URL de la aplicación web remota es necesaria antes de registrar el complemento. Con todo, el registro del complemento en SharePoint debe preceder a la implementación de los archivos de la aplicación web ASP.NET porque hay dos resultados desde el proceso de registro (el Id. de cliente y el secreto de cliente) que se necesitan antes de implementar los archivos de aplicación web ASP.NET.

Para crear un sitio web de Azure

1. Inicie sesión en Azure Portal. Cuando se cargue el panel, haga clic en el vínculo de navegación Sitios web del margen izquierdo y luego seleccione el botón NUEVO del pie de página, tal y como se muestra en la ilustración siguiente.

   

   
   

2. En el Asistente para nuevos sitios web, seleccione CALCULAR, sitio web y CREACIÓN RÁPIDA, y luego especifique una dirección URL y PLAN DE HOSPEDAJE WEB. Por último, especifique la REGIÓN donde se debe crear el sitio web. Asegúrese de recordar la región seleccionada ya que debe usarse la misma región para la instancia de Azure SQL Database que se crea más adelante.

3. Si aún no existe un plan de hospedaje web o quiere usar uno nuevo, seleccione la opción Crear nuevo plan de hospedaje web. La ilustración siguiente muestra un ejemplo.

   

   
   

4. Cuando haya creado el sitio web de Azure, tome nota de la dirección URL que se usa para el sitio. En las ilustraciones anteriores, el sitio que se crea es http://spahapptoph.azurewebsites.net.

Registrar un nuevo complemento

Todos los complementos de SharePoint creados mediante el modelo de complementos deben registrarse en la granja o el inquilino de hospedaje de SharePoint para establecer una relación de confianza entre SharePoint y la aplicación web remota. Eso implica registrar una nueva entidad de seguridad del complemento en SharePoint especificando los valores siguientes:

• Id. de cliente: identificador del complemento.
• Secreto de cliente: contraseña del complemento.
• Título: nombre del complemento.
• Dominio de complemento: dominio de primer nivel de la aplicación web remota.

Cuando se instala un complemento autohospedado en SharePoint Online, Office 365 crea automáticamente la entidad de seguridad del complemento. Conoce la dirección URL de la aplicación web remota porque crea el sitio automáticamente. También toma el identificador de cliente y el secreto de cliente y los agrega al archivo Web.config de la aplicación web remota. En Web.config los busca una clase proporcionada por Microsoft (en el archivo TokenHelper.cs o .vb) al validar solicitudes y autenticarse con SharePoint.

Pero, en un complemento hospedado por el proveedor, el desarrollador tiene que registrar manualmente el complemento y actualizar manualmente el archivo Web.config en el proyecto web ASP.NET.

Para registrar un nuevo complemento

1. Vaya a la página de registro del complemento del sitio web de SharePoint donde se instalará el complemento. Esta página se encuentra en http://[SharePoint-site-url]/_layouts/15/appregnew.aspx.

2. En la página de registro del complemento, establezca Tipo de complemento en Complemento que se ejecuta en un servidor web y seleccione los dos botones Generar para crear un Id. de cliente y un Secreto de cliente.

3. Escriba el nombre del complemento en el campo Título y escriba la dirección URL del sitio web de Azure creado en el paso anterior en el campo Dominio de complemento. Por último, seleccione el botón Crear.

4. Cuando haya registrado el complemento, SharePoint mostrará un resumen de la información empleada en el formulario para crear el registro. Es muy importante copiar esta información para su salvaguarda, específicamente el identificador de cliente y el secreto de cliente, ya que se necesitan posteriormente.

Actualizar e implementar el sitio web de Azure para la aplicación web remota

El siguiente paso es reconfigurar la aplicación web remota para que se pueda implementar como un complemento hospedado por el proveedor y no como un complemento autohospedado. Hay varias formas de implementar un sitio ASP.NET en un sitio web de Azure, como implementarlo directamente desde Visual Studio, automáticamente desde un control de origen como Visual Studio Team Services, desde GitHub o incluso mediante la opción de FTP comprobada. En este artículo se utiliza Visual Studio. Aunque para poder implementar la aplicación web, esta necesita primero algunas actualizaciones para trabajar con el complemento hospedado por el proveedor.

Para actualizar el proyecto de aplicación web remota

El cambio importante que debe efectuarse en la aplicación web ASP.NET MVC se encuentra en el archivo Web.config. En este archivo hay tres valores dentro del nodo <appSettings>. Se trata de ClientId, ClientSecret y SqlAzureConnectionString. Los dos primeros se usan en la clase proporcionada por Microsoft, TokenHelper.cs o .vb, para facilitar la autenticación y comunicación con SharePoint desde la aplicación web remota. El complemento utiliza el último, SqlAzureConnectionString, para conectarse a Azure SQL Database.

En un complemento autohospedado de SharePoint, Office 365 rellena los valores de estos parámetros al crear el sitio web de Azure y la instancia de Azure SQL Database cuando se instala el complemento. Pero, en un complemento hospedado por el proveedor, estos valores deben establecerse manualmente antes de implementar el complemento.

Una posibilidad consiste en pegar los valores de los tres parámetros de los pasos anteriores de este artículo, pero la desventaja de este enfoque es que si alguna vez hay que cambiarlos, el archivo web.config se tendrá que actualizar y volver a implementar manualmente en el sitio web de Azure.

Otra posibilidad es simplemente borrar estos valores (dejar las claves, establecer tan solo el atributo value="" en una cadena vacía) y en cambio definirlos en la configuración del sitio web de Azure con Azure Portal. Este enfoque implica que los valores pueden cambiarse sin actualizar el código base. Para ello:

1. Inicie sesión en Azure Portal y vaya al sitio web de Azure creado en los pasos anteriores.

2. En la página del panel del sitio web de Azure, seleccione CONFIGURAR en el menú de navegación superior y después desplácese hacia abajo hasta la sección Configuración del complemento.

3. Agregue tres nuevas configuraciones de complemento que tengan los mismos nombres de configuración que el archivo web.config. Use los valores obtenidos en los pasos anteriores para ClientId, ClientSecret y SqlAzureConnectionString.

Asegúrese de que la cadena de conexión de la instancia de Microsoft Azure SQL Database sea correcta y válida, ya que, cuando se expone a través de Azure Portal y Visual Studio, el atributo de contraseña se sustituye por una máscara. La contraseña enmascarada de la cadena de conexión tendría que cambiarse para usar la contraseña correcta definida al crear el inicio de sesión de la instancia de Azure SQL Database.

Para implementar la aplicación web remota en el sitio web de Azure

Ahora hay que implementar los archivos de la aplicación web ASP.NET MVC en el sitio web de Azure como aplicación web remota.

1. En Visual Studio, haga clic con el botón derecho en el proyecto web y seleccione Publicar. Se iniciará el cuadro de diálogo del Asistente para publicación web.

2. En el cuadro de diálogo, seleccione Sitios web de Azure de Windows y elija Publicar.

   

   
   

3. Seleccione el nombre del sitio web de Azure creado en un paso anterior, tal y como se muestra en la ilustración siguiente, haga clic en Aceptar y asegúrese de que la dirección URL del sitio sea HTTPS.

   

   
   

4. Seleccione Validar conexión para asegurarse de que la configuración y la conexión funcionen correctamente.

5. Seleccione Publicar, lo que hará que Visual Studio implemente la aplicación web ASP.NET en el sitio web de Azure.

6. Copie la dirección URL del sitio.

Cuando haya implementado el sitio web, Visual Studio iniciará el explorador de depuración predeterminado y navegará al sitio web de Azure. Sin embargo, el sitio devolverá un error debido a que los controladores ASP.NET MVC están equipados con un atributo (en concreto SharePointContextFilter) que espera que SharePoint envíe ciertos valores al controlador en el encabezado de una solicitud HTTP POST, pero de forma predeterminada el explorador inicia una solicitud HTTP GET, así que se trata de un error esperado.

Dominios personalizados y certificados SSL para sitios web de Azure

Todos los sitios web de Azure utilizan la siguiente convención de nomenclatura: http[s]://[site-name].azurewebsites.net. Microsoft ya ha agregado un certificado SSL comodín a todos los sitios web en el dominio *.azurewebsites.net, pero los clientes pueden asociar un dominio personalizado a su sitio web de Azure así como usar sus propios certificados SSL en estos dominios personalizados.

Para obtener información sobre el uso de dominios personalizados, vea Tutorial: Asignación de un nombre DNS personalizado existente a Azure App Service.

Para obtener información sobre cómo agregar un certificado SSL personalizado para el nombre de dominio personalizado, vea Enlazar un certificado SSL personalizado a Azure Web Apps.

Reconfigurar el proyecto de complemento de SharePoint

El último paso es configurar el proyecto de complemento de SharePoint. El proyecto de Visual Studio para el complemento de SharePoint tiene el tipo de complemento configurado en autohospedado, que hay que cambiar a hospedado por el proveedor.

Para reconfigurar el proyecto de complemento de SharePoint

1. Abra el archivo AppManifest.xml del proyecto de complemento de SharePoint y cambie la opción Tipo de hospedaje de Autohospedado a Hospedado por el proveedor.

2. Establezca la Página de inicio del complemento para que apunte a la dirección URL de la página de inicio de la aplicación web remota, que es la dirección URL del sitio web de Azure. Asegúrese de incluir el valor de la cadena de consulta {StandardTokens} (si aún no se ha hecho). Así se asegura de que SharePoint agrega los tokens de cadena de consulta principales a la dirección URL cuando abra la aplicación web remota.

3. Quite la referencia a la aplicación web ASP.NET MVC del proyecto de complemento de SharePoint seleccionando el proyecto de complemento de SharePoint en el Explorador de soluciones de Visual Studio. En la ventana de herramientas Propiedades, establezca la propiedad Proyecto web en (Ninguno), tal y como se muestra en la ilustración siguiente.

   

   
   

4. Este paso requiere la actualización manual del archivo AppManifest.xml porque algunas opciones no se exponen en el diseñador. Para ello, guarde los cambios efectuados en el archivo AppManifest.xml y luego haga clic con el botón derecho en el mismo archivo en Explorador de soluciones y seleccione Ver código.

   

   
   

5. En la vista de código del archivo AppManifest.xml, quite las dos referencias al proyecto de aplicación web ASP.NET MVC y al proyecto de aplicación de capa de datos SQL, ya que no son necesarios en un complemento de SharePoint hospedado por el proveedor.

6. Cree otro GUID y reemplace el existente en el atributo ProductId. Esto indica a SharePoint que se trata de un nuevo complemento, no de una actualización a un complemento existente.

   Importante

   Si se usó el valor de ProductId existente, SharePoint devolverá el error "El complemento proporcionado difiere de otro complemento con la misma versión y el mismo identificador del producto" al instalar el complemento convertido.

7. Busque el elemento <RemoteWebApplication> y actualice el atributo ClientId para que coincida con el GUID obtenido al registrar el complemento en SharePoint y que se usó en el archivo web.config de configuración del complemento del sitio web de Azure.

   

   
   

8. Cuando haya guardado los cambios en el archivo AppManifest.xml, el complemento estará preparado para realizar pruebas como complemento de SharePoint hospedado por el proveedor. Implemente el complemento en una granja de SharePoint o un sitio de SharePoint Online para comprobar que los pasos de conversión se han realizado correctamente.

Consulte también

• Blog para desarrolladores de Office
• Desarrollar complementos para SharePoint