Usar operaciones asincrónicas en Complementos de SharePoint

Importante

Los complementos de SharePoint alcanzaron la finalización de su vida útil en SharePoint Online el 2 de abril de 2026. Tanto los complementos hospedados por SharePoint como los hospedados por el proveedor se retiran y ya no funcionan en SharePoint Online, incluidas las nubes de administración pública. Las instrucciones de uso, implementación y desarrollo de complementos se conservan como referencia histórica y para escenarios de SharePoint Server aplicables, no para nuevas soluciones de SharePoint Online.

Los complementos de SharePoint Server implementados a través de un catálogo de aplicaciones local no se retiran por este cambio. La adquisición de complementos de SharePoint en el marketplace público finalizó el 2 de abril de 2026 para SharePoint Server.

Esta retirada no retira las API de REST DE SHAREPOINT, CSOM, JSOM o SharePoint Framework (SPFx). Para SharePoint Online, use SPFx para las extensiones de la interfaz de usuario y Microsoft Entra ID para la autenticación en aplicaciones externas. Consulte el anuncio de retirada y las instrucciones de migración de complementos.

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

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

En el ejemplo Core.QueueWebJobUsage se muestra cómo crear y ejecutar operaciones asincrónicas mediante complementos hospedados por el proveedor y WebJobs de Azure 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 de temporizador que tenía en su entorno local de SharePoint.

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

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.

Diagrama que muestra el flujo de operaciones asíncronas. El complemento de SharePoint llama al complemento hospedado por el proveedor, que agrega un mensaje a la cola de almacenamiento de Azure. Un WebJob de Azure procesa el mensaje y realiza acciones en el sitio de SharePoint.

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

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

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

  3. La cola de almacenamiento de Azure desencadena un evento en un trabajo web de Azure que se ejecuta continuamente para comenzar a procesar el nuevo mensaje.

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

Nota:

Al agregar un mensaje a la cola de almacenamiento de Azure se usa un proceso diferente del proceso que ejecuta el WebJob de Azure. Por lo tanto, el complemento puede implementar operaciones asincrónicas agregando nuevos mensajes a la cola mediante un proceso y, a continuación, mediante el WebJob de Azure para controlar esos mensajes en otro proceso.

Antes de empezar

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

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

  1. Inicie sesión en el portal de Microsoft Azure Portal.

  2. Elija Nueva>creación rápidade almacenamiento> de >servicios de datos.

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

  4. En UBICACIÓN/GRUPO de AFINIDAD, elija una ubicación adecuada.

  5. En REPLICACIÓN, elija Con redundancia geográfica.

  6. Elija CREAR CUENTA DE ALMACENAMIENTO.

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

  1. Cuando se cree la cuenta de almacenamiento de Azure, 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 su cuenta de almacenamiento de Azure a varios de los archivos de configuración.

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

  5. En Propiedades de Core.QueueWebJobUsage.Job, establezca Copiar local en True en las referencias de Microsoft.SharePoint.Client y Microsoft.SharePoint.Client.Runtime . Si establece Copiar local en TRUE, se copian los ensamblados a los que se hace referencia en Azure para que el trabajo web de Azure pueda resolver las referencias a estos ensamblados.

  6. Implemente el trabajo web de Azure. Para obtener más información, consulte Implementar un proyecto WebJobs.

Para comprobar que su trabajo web de Azure se está ejecutando:

  1. Inicie sesión en el Azure Portal.

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

  3. Elija WEBJOBS.

  4. Compruebe que el trabajo web de Azure aparece en la lista y que PROGRAMAR está establecido en Se ejecuta 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 cadenas de conexión, cree nuevas cadenas de conexión para AzureWebJobsDashboard y AzureWebJobsStorage. Copie los pares de clave (nombre) y valor AzureWebJobsDashboard y AzureWebJobsStorage del archivo Core.QueueWebJobUsage.Job\app.config y, a continuación, establezca el tipo en Personalizado.

  8. Seleccione Guardar.

Aplicar opciones de configuración

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

Ubicación del archivo Clave para actualizar Información de valor que se va a actualizar
Project\Core.QueueWebJobUsage.Console.SendMessage\app.config de la aplicación auxiliar StorageConnectionString Reemplace [nombre de su cuenta] por el nombre de la cuenta de almacenamiento copiado de Azure Portal.
Reemplace [su clave de cuenta] por la clave de acceso principal copiada de Azure Portal.
Core.QueueWebJobUsageWeb\web.config StorageConnectionString Reemplace [suNombreDeCuenta] por el nombre de la cuenta de almacenamiento copiado de Azure Portal.
Reemplace [YourAccountKey] por la clave de acceso principal copiada de Azure Portal.
Core.QueueWebJobUsage.Job\app.config StorageConnectionString Reemplace [suNombreDeCuenta] por el nombre de la cuenta de almacenamiento copiado de Azure Portal.
Reemplace [YourAccountKey] por la clave de acceso principal copiada de Azure Portal.
Identificador de cliente Reemplace [su id. de complemento] por el id. de cliente copiado del Core.QueueWebJobUsageWeb\web.config.
ClientSecret Reemplace [su secreto de complemento] por el secreto de cliente copiado del Core.QueueWebJobUsageWeb\web.config.
AzureWebJobsDashboard Reemplace [suCuenta] por el nombre de la cuenta de almacenamiento copiado de Azure Portal.
Reemplace [SuClave] por la clave de acceso principal copiada de Azure Portal.
AzureWebJobsStorage Reemplace [suCuenta] por el nombre de la cuenta de almacenamiento copiado de Azure Portal.
Reemplace [SuClave] por la clave de acceso principal copiada de Azure Portal.

Nota:

Si se actualizan ClientId y ClientSecret en Core.QueueWebJobUsageWeb, por ejemplo, al incrementar el número de versión en la AppManifest.xml, asegúrese de actualizar ClientId y ClientSecret en la Core.QueueWebJobUsage.Job\app.config.

Uso del complemento Core.QueueWebJobUsage

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

Proyecto de Visual Studio Description
Core.QueueWebJobUsage Su proyecto de complemento de SharePoint. Se requieren los siguientes permisos:
  • AllowAppOnlyPolicy

  • permisos de FullControl en la Web.

Core.QueueWebJobUsage.Common Contiene los objetos de negocio y el código de lógica de negocio, como los métodos para añadir mensajes a la cola de almacenamiento, para esta solución. Este proyecto se incluye para compartir objetos de negocio y lógica de negocio entre diferentes proyectos. Es posible que no necesite esto en su implementación.
Core.QueueWebJobUsage.Job El trabajo web de Azure que se ejecuta cuando se agrega un mensaje nuevo a la cola de almacenamiento de Azure. Este proyecto contiene el código de lógica de negocios personalizado.
Core.QueueWebJobUsageWeb El complemento hospedado por el proveedor que contiene la interfaz de usuario del proyecto Core.QueueWebJobUsage.
Helper Project\Core.QueueWebJobUsage.Console.SendMessage Un proyecto auxiliar que se puede utilizar para validar la información de la cuenta de almacenamiento y el proceso de creación de colas, y para enviar mensajes a la cola para su procesamiento sin configurar la solución completa descrita en este artículo.

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 la operación sincrónica, btnSync_Click en Páginas\Default.aspx simula un proceso sincrónico de larga duración. En este ejemplo de código, btnSync_Click pone el subproceso actual en suspensión durante 10 segundos y, después, crea una biblioteca de documentos. Cuando eliges Operación asincrónica, btnAsync_Click en Páginas\Default.aspx hace lo siguiente:

  1. Obtiene el usuario actual.

  2. Crea un objeto de negocio 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 código de ejemplo, 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 almacenamiento de Azure.

Nota:

El código de este artículo se proporciona tal cual, sin garantía de ningún tipo, expresa o implícita, incluidas las garantías implícitas de aptitud para un propósito particular, comerciabilidad o ausencia de infracción.

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 utilizando 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 almacenamiento de Azure con un nombre igual al valor de la constante SiteManager.StorageQueueName.

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

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

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)));
        }

Después de agregar el mensaje a la cola de almacenamiento de Azure, un WebJob de Azure que se ejecuta continuamente espera el nuevo mensaje y, a continuación, lo procesa. El trabajo web de Azure se define en Core.QueueWebJobUsage.Job. Cuando se ejecuta el 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 los métodos marcados con el atributo QueueTrigger y vigila los mensajes de una cola específica. RunAndBlock garantiza que el trabajo web de Azure se ejecuta de forma continua y llama a ProcessQueueMessage, que es el método que se desencadena cuando se agrega un mensaje nuevo a la cola de almacenamiento de Azure. El SDK de WebJobs de Azure asocia el subproceso principal con ProcessQueueMessage. Para obtener más información, consulte Creación de un trabajo web .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 los mensajes nuevos que se agregan a la cola de Azure Storage mediante:

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

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

  3. Llamar a SiteManager(). PerformSiteModification para llevar a cabo 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