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

Implemente operações assíncronas nos suplementos do SharePoint usando o Microsoft Azure WebJobs.

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 WebJobs do Azure em Office 365.

Use esta solução para:

• Melhore o desempenho dos receptores de eventos remotos.

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

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

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

  • Provisionamento de coleção de sites personalizado.

  • Operações que sincronizam dados entre 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 o Azure WebJobs:

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

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

3. A fila de Armazenamento do Azure dispara um evento em um WebJob do Azure em execução contínua para começar a processar a nova mensagem.

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

Observação

Adicionar uma mensagem à fila de Armazenamento do Azure usa um processo diferente do processo que executa o WebJob do Azure. Portanto, seu suplemento pode implementar operações assíncronas adicionando novas mensagens à fila usando um processo e, em seguida, usando o WebJob do Azure para lidar com essas mensagens em outro processo.

Antes de começar

Para começar, baixe o suplemento de exemplo Core.QueueWebJobUsage do projeto de padrões e práticas do desenvolvedor Office 365 no GitHub e 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 microsoft portal do Azure.

2. Escolha CriaçãoRápida do Armazenamento de Novos>Serviços>de> Dados.

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

4. No GRUPO LOCATION/AFFINITY, escolha um local apropriado.

5. Em REPLICAÇÃO, escolha Redundância Geográfica.

6. Escolha 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ÁRIO.

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

4. No Helper Project\Core.QueueWebJobUsage.Console.SendMessage, abra Program.cs e insira a URL do 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 True copia os assemblies referenciados para o Azure para que o Azure WebJob possa resolve as referências a esses assemblies.

6. Implante o Azure WebJob. Para obter mais informações, consulte Implantar um projeto WebJobs.

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

1. Entre no portal do Azure.

2. Escolha aplicativos Web e escolha os Sites do Microsoft Azure inseridos.

3. Escolha WEBJOBS.

4. Verifique se o WebJob do Azure aparece na lista e se SCHEDULE está definido como Execuções continuamente.

5. Escolha CONFIGURAR.

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

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

8. Escolha Salvar.

Aplicar configurações

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

Local do arquivo	Chave a ser atualizada	Informações de valor a serem atualizadas
Auxiliar Project\Core.QueueWebJobUsage.Console.SendMessage\app.config	StorageConnectionString	Substitua [o nome da conta] pelo nome da conta de armazenamento copiado do portal do Azure.
		Substitua [Sua Chave de Conta] pela chave de acesso primário copiada do portal do Azure.
Core.QueueWebJobUsageWeb\web.config	StorageConnectionString	Substitua [YourAccountName] pelo nome da conta de armazenamento copiado do portal do Azure.
		Substitua [YourAccountKey] pela chave de acesso primário copiada do portal do Azure.
Core.QueueWebJobUsage.Job\app.config	StorageConnectionString	Substitua [YourAccountName] pelo nome da conta de armazenamento copiado do portal do Azure.
		Substitua [YourAccountKey] pela chave de acesso primário copiada do portal do Azure.
	Clientid	Substitua [sua ID de suplemento] pela ID do cliente copiada do Core.QueueWebJobUsageWeb\web.config.
	ClientSecret	Substitua [Seu segredo de suplemento] pelo segredo do cliente copiado do Core.QueueWebJobUsageWeb\web.config.
	AzureWebJobsDashboard	Substitua [YourAccount] pelo nome da conta de armazenamento copiado do portal do Azure.
		Substitua [YourKey] pela chave de acesso primário copiada do portal do Azure.
	AzureWebJobsStorage	Substitua [YourAccount] pelo nome da conta de armazenamento copiado do portal do Azure.
		Substitua [YourKey] pela chave de acesso primário copiada do portal do Azure.

Observação

Se o ClientId e o ClientSecret no Core.QueueWebJobUsageWeb forem atualizados, por exemplo, quando você incrementar o número de versão no AppManifest.xml, atualize o ClientId e o ClientSecret no Core.QueueWebJobUsage.Job\app.config.

Usando o suplemento Core.QueueWebJobUsage

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

Projeto do Visual Studio	Descrição
Core.QueueWebJobUsage	Seu projeto de suplemento do SharePoint. As seguintes permissões são necessárias: AllowAppOnlyPolicy Permissões fullcontrol na Web.
Core.QueueWebJobUsage.Common	Contém os objetos de negócios e o código lógico de negócios – como os métodos para adicionar mensagens à fila de armazenamento – para essa solução. Este projeto é incluído para compartilhar objetos de negócios e lógica de negócios entre projetos diferentes. Talvez você não precise disso em sua implementação.
Core.QueueWebJobUsage.Job	O WebJob do Azure que é executado quando uma nova mensagem é adicionada à fila de Armazenamento do Azure. Este projeto contém seu código lógico de negócios personalizado.
Core.QueueWebJobUsageWeb	O suplemento hospedado pelo provedor que contém a interface do usuário para o projeto Core.QueueWebJobUsage.
Projeto auxiliar\Core.QueueWebJobUsage.Console.SendMessage	Um projeto auxiliar que pode ser usado para validar as informações da conta de armazenamento e o processo de criação da fila e para enviar mensagens à fila para processamento sem configurar toda a solução descrita neste artigo.

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 a operação síncrona, btnSync_Click em Pages\Default.aspx simula um processo síncrono de longa execução. Neste exemplo de código, btnSync_Click coloca o thread atual para dormir por 10 segundos e cria uma biblioteca de documentos. Quando você escolhe a operação Assíncrona, btnAsync_Click em Pages\Default.aspx faz o seguinte:

1. Obtém o usuário atual.

2. Cria um objeto comercial SiteModifyRequest que armazena os dados a serem incluídos na mensagem que está sendo enviada para a fila de Armazenamento do Azure. Neste exemplo de código, os dados 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.

Observação

The code in this article is provided as-is, without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement.

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 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 de Armazenamento do Azure. O objeto modifiRequest business é 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 WebJob do Azure em execução continuamente aguarda e processa a nova mensagem. O Azure WebJob é definido em Core.QueueWebJobUsage.Job. Quando o Azure WebJob é executado, Main in 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 Azure WebJob seja executado continuamente e chame ProcessQueueMessage, que é o método a ser disparado quando uma nova mensagem é adicionada à Fila de Armazenamento do Azure. O SDK do Azure WebJobs associa o thread Principal ao ProcessQueueMessage. Para obter mais informações, consulte Criar um .NET WebJob 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 disparado quando uma nova mensagem é escrita na fila com nome igual ao valor de SiteManager.StorageQueueName.

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

3. Chamando SiteManager(). ExecuteSiteModification para executar um processo de negócios de longa execução no site. Neste exemplo de código, o thread é colocado para dormir 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

• Office 365 os padrões de desenvolvimento e as diretrizes da solução de práticas.

• Usar receptores de eventos remotos no SharePoint

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