Usar operaciones asincrónicas en Complementos de SharePoint

Implementar operaciones asincrónicas en Complementos de SharePoint mediante Microsoft Azure WebJobs.

Se aplica a: SharePoint 2013 | Complementos de SharePoint | SharePoint Online

El ejemplo Core.QueueWebJobUsage muestra cómo crear y ejecutar operaciones asincrónicas mediante complementos hospedados por el proveedor y Azure WebJobs en Office 365.

Use esta solución para:

• Mejore el rendimiento de los receptores de eventos remotos.

• Migre a SharePoint Online e implemente la misma funcionalidad de trabajo del temporizador que tenía en el entorno local de SharePoint.

• Implemente operaciones de ejecución prolongada que desee ejecutar en el entorno de SharePoint. Por ejemplo:

  • Eventos AppInstalled que se ejecutan más tiempo que el intervalo de tiempo de espera de 30 segundos. Hay procesos asincrónicos en controladores de eventos de complemento. Para obtener más información, vea Controlar eventos en complementos de SharePoint y Crear un receptor de eventos de complemento en complementos de SharePoint.

  • Aprovisionamiento de colecciones de sitios personalizados.

  • Operaciones que sincronizan datos entre Office 365 y los sistemas locales.

  • Operaciones que realizan cálculos complejos.

En el diagrama siguiente se muestra una arquitectura de alto nivel de los componentes necesarios y el flujo de procesamiento entre esos componentes cuando se realiza una operación asincrónica.

Para implementar operaciones asincrónicas en el complemento hospedado por el proveedor mediante Azure WebJobs:

1. Los usuarios ejecutan el complemento implementado en SharePoint Online.

2. El complemento hospedado por el proveedor proporciona los parámetros de entrada necesarios para Azure WebJob y, a continuación, agrega un nuevo mensaje a la cola de Azure Storage.

3. La cola de Azure Storage desencadena un evento en una instancia de Azure WebJob en ejecución continua para empezar a procesar el nuevo mensaje.

4. Azure WebJob ejecuta lógica de negocios personalizada en el sitio de SharePoint Online.

Antes de empezar

Para empezar, descargue el complemento de ejemplo Core.QueueWebJobUsage del proyecto Office 365 Developer patterns and practices en GitHub y, a continuación, cree una cuenta de Azure, agregue detalles a esa cuenta y compruebe que Azure WebJob se está ejecutando.

Para crear una cuenta de Azure Storage para acceder a la cola de Azure Storage:

1. Inicie sesión en su Azure Portal de Microsoft.

2. Elija Nueva>creación rápidade Almacenamiento de>Data Services>.

3. En URL, escriba el nombre de dominio. Por ejemplo, escriba contoso.

4. En LOCATION/AFFINITY GROUP, elija una ubicación adecuada.

5. En REPLICACIÓN, elija Redundancia geográfica.

6. Elija CREATE STORAGE ACCOUNT (CREAR CUENTA DE ALMACENAMIENTO).

Para agregar detalles a la cuenta de almacenamiento recién creada:

1. Cuando se cree la cuenta de Azure Storage, elija ADMINISTRAR CLAVES DE ACCESO.

2. En Administrar claves de acceso, copie el NOMBRE DE LA CUENTA DE ALMACENAMIENTO y LA CLAVE DE ACCESO PRINCIPAL.

3. Aplique el identificador de cliente, el secreto de cliente y la información de la cuenta de Azure Storage a varios de los archivos de configuración.

4. En Helper Project\Core.QueueWebJobUsage.Console.SendMessage, abra Program.cs y escriba la dirección URL del sitio en el cuadro siteUrl .

5. En Propiedades en Core.QueueWebJobUsage.Job, establezca Copiar local en True en las referencias Microsoft.SharePoint.Client y Microsoft.SharePoint.Client.Runtime . Al establecer Copiar local en True , se copian los ensamblados a los que se hace referencia en Azure para que Azure WebJob pueda resolver las referencias a estos ensamblados.

6. Implemente Azure WebJob. Para obtener más información, consulte Implementación de un proyecto de WebJobs.

Para comprobar que Azure WebJob se está ejecutando:

1. Inicie sesión en el Azure Portal.

2. Elija aplicaciones web y, a continuación, elija los sitios web de Microsoft Azure que especificó.

3. Elija WEBJOBS.

4. Compruebe que Azure WebJob aparece en la lista y que SCHEDULE está establecido en Ejecuciones continuamente.

5. Elija CONFIGURAR.

6. En la configuración del complemento, cree una nueva configuración de complemento para ClientId y ClientSecret. Copie los pares clave-valor ClientId y ClientSecret del archivo Core.QueueWebJobUsage.Job\app.config.

7. En las cadenas de conexión, cree nuevas cadenas de conexión para AzureWebJobsDashboard y AzureWebJobsStorage. Copie los pares clave (nombre) y valor de AzureWebJobsDashboard y AzureWebJobsStorage del archivo Core.QueueWebJobUsage.Job\app.config y, a continuación, establezca el tipo en Personalizado.

8. Seleccione Guardar.

Aplicación de valores de configuración

Use la información de la tabla siguiente para aplicar los valores de configuración a la solución Core.QueueWebJobUsage de Visual Studio.

Uso del complemento Core.QueueWebJobUsage

En la tabla siguiente se describen todos los proyectos de Visual Studio de la solución Core.QueueWebJobUsage.

Al ejecutar el ejemplo de código Core.QueueWebJobUsage, aparece el complemento hospedado por el proveedor y muestra dos botones: Operación sincrónica y Operación asincrónica. Al elegir Operación sincrónica, btnSync_Click en Pages\Default.aspx simula un proceso sincrónico de ejecución prolongada. En este ejemplo de código, btnSync_Click coloca el subproceso actual en suspensión durante 10 segundos y, a continuación, crea una biblioteca de documentos. Al elegir Operación asincrónica, btnAsync_Click en Pages\Default.aspx hace lo siguiente:

1. Obtiene el usuario actual.

2. Crea un objeto empresarial SiteModifyRequest que almacena los datos que se van a incluir en el mensaje que se envía a la cola de Azure Storage. En este ejemplo de código, los datos que se envían incluyen el nombre del usuario actual y la dirección URL del sitio actual.

3. Llama a SiteManager(). AddAsyncOperationRequestToQueue para agregar el mensaje a la cola de Azure Storage.

protected void btnAsync_Click(object sender, EventArgs e)
        {

            var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);

            using (var clientContext = spContext.CreateUserClientContextForSPHost())
            {
                // Get the current user.
                var currUser = clientContext.Web.CurrentUser;
                clientContext.Load(currUser);
                clientContext.ExecuteQuery();

                // Create business object, and then add the request to the queue.
                SiteModifyRequest request = new SiteModifyRequest() { RequestorName = currUser.Title, SiteUrl = Page.Request["SPHostUrl"] };
                new SiteManager().AddAsyncOperationRequestToQueue(request,
                                                                  ConfigurationManager.AppSettings["StorageConnectionString"]);

                processViews.ActiveViewIndex = 1;
                lblStatus.Text = "Asynchronous operation to create document library started.";
            }
        }

En Core.QueueWebJobUsage.Common, en SiteManager.cs, AddAsyncOperationRequestToQueue hace lo siguiente:

1. Crea un objeto CloudStorageAccount mediante la información de configuración AccountName y AccountKey del archivo Core.QueueWebJobUsageWeb\web.config.

2. Crea un cliente de cola de Azure Storage mediante CloudStorageAccount.CreateCloudQueueClient.

3. Usa CloudQueueClient.GetQueueReference para obtener una referencia a la cola de Azure Storage con el nombre igual al valor de la constante SiteManager.StorageQueueName .

4. Usa CloudQueue.CreateIfNotExists para crear la cola de Azure Storage si no existe.

5. Usa CloudQueue.AddMessage para agregar un nuevo mensaje a la cola de Azure Storage. El objeto de negocio modifyRequest se serializa en un objeto CloudQueueMessage , que se agrega a la cola de Azure Storage.

public void AddAsyncOperationRequestToQueue(SiteModifyRequest modifyRequest, 
                                                    string storageConnectionString)
        {
            CloudStorageAccount storageAccount =
                                CloudStorageAccount.Parse(storageConnectionString);

            // Get queue or create a new one if one does not exist.
            CloudQueueClient queueClient = storageAccount.CreateCloudQueueClient();
            CloudQueue queue = queueClient.GetQueueReference(SiteManager.StorageQueueName);
            queue.CreateIfNotExists();

            // Add a message to queue.
            queue.AddMessage(new CloudQueueMessage(JsonConvert.SerializeObject(modifyRequest)));
        }

Una vez que el mensaje se agrega a la cola de Azure Storage, una instancia de Azure WebJob en ejecución continua espera y, a continuación, procesa el nuevo mensaje. Azure WebJob se define en Core.QueueWebJobUsage.Job. Cuando se ejecuta Azure WebJob, Main en Core.QueueWebJobUsage.Job\Program.cs crea un nuevo JobHost y, a continuación, llama a RunAndBlock. JobHost coordina las llamadas a métodos marcados con el atributo QueueTrigger y busca mensajes en una cola específica. RunAndBlock garantiza que Azure WebJob se ejecuta continuamente y llama a ProcessQueueMessage, que es el método que se desencadena cuando se agrega un nuevo mensaje a la cola de Azure Storage. El SDK de Azure WebJobs asocia el subproceso Main a ProcessQueueMessage. Para obtener más información, consulte Creación de un trabajo web de .NET en el servicio de complementos de Azure.

static void Main()
        {
            var host = new JobHost();
            // The following code ensures that the WebJob will run continuously.
            host.RunAndBlock();
        }

ProcessQueueMessage procesa nuevos mensajes que se agregan a la cola de Azure Storage mediante:

1. Usar el atributo QueueTrigger para especificar que ProcessQueueMessage debe desencadenarse cuando se escribe un nuevo mensaje en la cola con el nombre igual al valor de SiteManager.StorageQueueName.

2. Escribir en el registro de Azure WebJob mediante la variable de registro que se pasó como parámetro a ProcessQueueMessage.

3. Llamar a SiteManager(). PerformSiteModification para realizar un proceso empresarial de larga duración en el sitio. En este ejemplo de código, el subproceso se pone en suspensión durante 10 segundos y, a continuación, se crea una biblioteca de documentos.

public static void ProcessQueueMessage(
            [QueueTrigger(SiteManager.StorageQueueName)] 
            SiteModifyRequest modifyRequest, TextWriter log)
        {
            log.WriteLine(string.Format("{0} '{1}' {2} '{3}'.",
                            "Received new site modification request with URL", 
                            modifyRequest.SiteUrl, 
                            "from person named as ", 
                            modifyRequest.RequestorName));
            
            try
            {
                Uri targetSite = new Uri(modifyRequest.SiteUrl);
                
                // Get the realm for the URL.
                string realm = TokenHelper.GetRealmFromTargetUrl(targetSite);

                // Get the access token for the URL.  
                // Requires this add-in to be registered with the tenant.
                string accessToken = TokenHelper.GetAppOnlyAccessToken(
                                                    TokenHelper.SharePointPrincipal,
                                                    targetSite.Authority, realm).AccessToken;

                // Get client context with access token.
                using (var ctx =
                    TokenHelper.GetClientContextWithAccessToken(
                                                    targetSite.ToString(), accessToken))
                {
                    // Call business logic code.
                    new SiteManager().PerformSiteModification(ctx, modifyRequest);
                }
            }
            catch (Exception ex)
            {
                log.WriteLine(string.Format("Site modification to URL {0} failed with following details.", modifyRequest.SiteUrl));
                log.WriteLine(ex.ToString());
                throw;
            }
        }

Vea también

• Guía de la solución de procedimientos y prácticas para desarrolladores de Office 365.

• Usar receptores de eventos remotos en SharePoint

• Consultar el registro de cambios de SharePoint con ChangeQuery y ChangeToken