Usar operações assíncronas em Suplementos do SharePoint

Implemente operações assíncronas em Suplementos do SharePoint usando Trabalhos Web do Microsoft Azure.

Aplicável a: suplementos do SharePoint | SharePoint 2013 | SharePoint Online

O exemplo Core.QueueWebJobUsage mostra como criar e executar operações assíncronas usando suplementos hospedados pelo provedor e Trabalhos Web do Azure no Office 365.

Use esta solução para:

• Melhore o desempenho de seus receptores de eventos remotos.

• Migre para o SharePoint Online e implemente a mesma funcionalidade de trabalho de timer que você tinha em seu ambiente local do SharePoint.

• Implemente operações de longa duração que você deseja executar em seu ambiente do SharePoint. Por exemplo:

  • Eventos AppInstalled executados por mais tempo do que o intervalo de tempo limite de 30 segundos. Há processos assíncronos nos manipuladores de eventos de suplemento. Para obter mais informações, consulte Manipular eventos em Suplementos do SharePoint e Criar um receptor de eventos de suplemento em Suplementos do SharePoint.

  • Provisionamento de conjunto de sites personalizado.

  • Operações que sincronizam dados entre o Office 365 e seus sistemas locais.

  • Operações que executam cálculos complexos.

O diagrama a seguir mostra uma arquitetura de alto nível dos componentes necessários e o fluxo de processamento entre esses componentes quando uma operação assíncrona é executada.

Para implementar operações assíncronas no suplemento hospedado pelo provedor usando Trabalhos Web do Azure:

1. Os usuários executam o suplemento implantado no SharePoint Online.

2. O suplemento hospedado pelo provedor fornece os parâmetros de entrada exigidos pelo Trabalho Web do Azure e adiciona uma nova mensagem à fila do Armazenamento do Azure.

3. A fila de Armazenamento do Azure dispara um evento em um WebJob do Azure em execução contínua para iniciar o processamento da nova mensagem.

4. O WebJob do Azure executa lógica de negócios personalizada em seu site do SharePoint Online.

Antes de começar

Para começar, baixe o suplemento de exemplo Core.QueueWebJobUsage do projeto padrões e práticas do desenvolvedor do Office 365 no GitHub e, em seguida, crie uma conta do Azure, adicione detalhes a essa conta e verifique se o Azure WebJob está em execução.

Para criar uma conta de Armazenamento do Azure para acessar a fila de armazenamento do Azure:

1. Entre no seu portal do Azure.

2. Escolha Nova>Criação Rápidade Armazenamento de>Serviços de> Dados.

3. Em URL, insira seu nome de domínio. Por exemplo, insira contoso.

4. Em LOCALIZAÇÃO/GRUPO DE AFINIDADE, escolha uma localização apropriada.

5. Em REPLICATION, escolha Geo-Redundant.

6. Escolha CREATE STORAGE ACCOUNT (CRIAR CONTA DE ARMAZENAMENTO).

Para adicionar detalhes à sua conta de armazenamento recém-criada:

1. Quando a conta de Armazenamento do Azure for criada, escolha GERENCIAR CHAVES DE ACESSO.

2. Em Gerenciar Chaves de Acesso, copie o NOME DA CONTA DE ARMAZENAMENTO e a CHAVE DE ACESSO PRIMÁRIA.

3. Aplique a ID do cliente, o segredo do cliente e as informações da conta de Armazenamento do Azure a vários arquivos de configuração.

4. Em Helper Project\Core.QueueWebJobUsage.Console.SendMessage, abra Program.cs e insira a URL de seu site na caixa siteUrl .

5. Em Propriedades no Core.QueueWebJobUsage.Job, defina Copiar Local como True nas referências Microsoft.SharePoint.Client e Microsoft.SharePoint.Client.Runtime . Definir Copiar Local como Verdadeiro copia os assemblies referenciados para o Azure para que o Trabalho Web do Azure possa resolver as referências a esses assemblies.

6. Implante o Trabalho Web do Azure. Para obter mais informações, consulte Implantar um projeto de Trabalhos Web.

Para verificar se o trabalho Web do Azure está em execução:

1. Entre no seu portal do Azure.

2. Escolha aplicativos Web e, em seguida, escolha os Sites do Microsoft Azure que você inseriu.

3. Escolha WEBJOBS.

4. Verifique se o Trabalho Web do Azure aparece na lista e se AGENDAR está definido como Executado continuamente.

5. Escolha CONFIGURAR.

6. Nas configurações de suplemento, crie novas configurações de suplemento para ClientId e ClientSecret. Copie os pares de chave-valor ClientId e ClientSecret do arquivo Core.QueueWebJobUsage.Job\app.config.

7. Em cadeias de conexão, crie novas cadeias de conexão para AzureWebJobsDashboard e AzureWebJobsStorage. Copie os pares de chave e valor AzureWebJobsDashboard e AzureWebJobsStorage (nome) do arquivo Core.QueueWebJobUsage.Job\app.config e defina o tipo como Personalizado.

8. Escolha Salvar.

Aplicar definições de configuração

Use as informações na tabela a seguir para aplicar definições de configuração à solução Core.QueueWebJobUsage do Visual Studio.

Usando o suplemento Core.QueueWebJobUsage

A tabela a seguir descreve todos os projetos do Visual Studio na solução Core.QueueWebJobUsage.

Quando você executa o exemplo de código Core.QueueWebJobUsage, o suplemento hospedado pelo provedor aparece e exibe dois botões: operação síncrona e operação assíncrona. Quando você escolhe Operação síncrona, btnSync_Click em Páginas\Default.aspx simula um processo síncrono de execução prolongada. Nesta amostra de código, btnSync_Click coloca o thread atual em suspensão por 10 segundos e, em seguida, cria uma biblioteca de documentos. Quando você escolhe Operação assíncrona, btnAsync_Click em Páginas\Default.aspx faz o seguinte:

1. Obtém o usuário atual.

2. Cria um objeto de negócios SiteModifyRequest que armazena os dados a serem incluídos na mensagem que está sendo enviada para a fila de Armazenamento do Azure. Nessa amostra de código, os dados que estão sendo enviados incluem o nome do usuário atual e a URL do site atual.

3. chama SiteManager(). AddAsyncOperationRequestToQueue para adicionar a mensagem à fila de Armazenamento do Azure.

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.";
            }
        }

Em Core.QueueWebJobUsage.Common, em SiteManager.cs, AddAsyncOperationRequestToQueue faz o seguinte:

1. Cria um objeto CloudStorageAccount usando as informações de configuração AccountName e AccountKey no arquivo Core.QueueWebJobUsageWeb\web.config.

2. Cria um cliente de fila de Armazenamento do Azure usando CloudStorageAccount.CreateCloudQueueClient.

3. Usa CloudQueueClient.GetQueueReference para obter uma referência à fila de Armazenamento do Azure com um nome igual ao valor da constante SiteManager.StorageQueueName.

4. Usa CloudQueue.CreateIfNotExists para criar a fila de Armazenamento do Azure se ela não existir.

5. Usa CloudQueue.AddMessage para adicionar uma nova mensagem à fila do Armazenamento do Azure. O objeto de negócios modifyRequest é serializado em um objeto CloudQueueMessage, que é adicionado à fila de Armazenamento do 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)));
        }

Depois que a mensagem é adicionada à Fila de Armazenamento do Azure, um Trabalho Web do Azure em execução contínua aguarda e processa a nova mensagem. O WebJob do Azure é definido em Core.QueueWebJobUsage.Job. Quando o Azure WebJob é executado, Main em Core.QueueWebJobUsage.Job\Program.cs cria um novo JobHost e chama RunAndBlock. O JobHost coordena chamadas para métodos marcados com o atributo QueueTrigger e observa mensagens em uma fila específica. RunAndBlock garante que o Trabalho Web do Azure seja executado continuamente e chama ProcessQueueMessage, que é o método a ser disparado quando uma nova mensagem é adicionada à Fila de Armazenamento do Azure. O SDK de Trabalhos Web do Azure associa o thread principal a ProcessQueueMessage. Para obter mais informações, consulte Criar um WebJob .NET no Serviço de Suplemento do Azure.

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

ProcessQueueMessage processa novas mensagens que são adicionadas à fila de Armazenamento do Azure por:

1. Usando o atributo QueueTrigger para especificar que ProcessQueueMessage deve ser acionado quando uma nova mensagem é gravada na fila com um nome igual ao valor de SiteManager.StorageQueueName.

2. Gravando no log para o WebJob do Azure usando a variável de log que foi passada como um parâmetro para ProcessQueueMessage.

3. Chamando SiteManager(). PerformSiteModification para executar um processo empresarial de longa duração no site. Nessa amostra de código, o thread é colocado em suspensão por 10 segundos e, em seguida, uma biblioteca de documentos é criada.

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

Confira também

• Padrões e práticas de desenvolvimento do Office 365, orientação de solução.

• Usar receptores de eventos remotos no SharePoint

• Consultar o log de alterações do SharePoint com ChangeQuery e ChangeToken