Manipular eventos de suplemento no suplemento hospedado pelo provedor

Artigo
04/08/2023

Este é o sétimo de uma série de artigos sobre os conceitos básicos do desenvolvimento de suplementos do SharePoint hospedados pelo provedor. Primeiro, você deve estar familiarizado com suplementos do SharePoint e os artigos anteriores desta série, que podem ser encontrados em Introdução à criação de suplementos do SharePoint hospedados pelo provedor.

Observação

Se você trabalhou com esta série sobre suplementos hospedados pelo provedor, você terá uma solução do Visual Studio que pode ser usada para continuar com este tópico. Você também pode baixar o repositório em SharePoint_Provider-hosted_Add-Ins_Tutorials e abrir o arquivo BeforeAdd-inEventHandlers.sln.

Neste artigo, personalizaremos o tratamento de um tipo de evento no SharePoint chamado eventos de suplemento. Especificamente, criamos manipuladores para os eventos de instalação e desinstalação do suplemento. Os eventos de item de lista e lista também podem obter tratamento personalizado; você aprenderá sobre isso em um artigo posterior nesta série. Todos esses eventos são disparados no SharePoint, mas seu código personalizado que manipula cada evento está em seu aplicativo Web remoto. Você configura o SharePoint para chamar seu manipulador personalizado registrando a URL do manipulador com o evento do SharePoint.

Dois lugares para implantar componentes do SharePoint via programação

Queremos que nosso suplemento da Chain Store crie e implante automaticamente as listas funcionários locais e remessas esperadas . Um suplemento pode implantar componentes do SharePoint, como uma lista personalizada, a qualquer momento. Mas quando um suplemento depende de um componente específico, como uma lista personalizada, o componente realmente deve ser implantado antes que os usuários comecem a trabalhar com o suplemento. Para esses componentes vitais, há dois locais em que a lógica de implantação personalizada pode ir:

Em um manipulador para o evento de instalação do suplemento.
Na lógica de "primeira execução", que é executada na primeira vez que o suplemento for iniciado no SharePoint.

Decidir qual é o melhor para um determinado suplemento é um tópico avançado. Neste artigo, podemos mencionar apenas alguns pontos de comparação:

Um manipulador de instalação personalizado precisa ser concluído em 30 segundos. Não há limite para quanto tempo a lógica de primeira execução pode levar.
Se algo der errado durante uma instalação de suplemento, o SharePoint reverterá tudo o que fez como parte da instalação. Um manipulador de instalação personalizado é executado após o SharePoint ter feito tudo o que vai fazer para instalar o suplemento, para que um manipulador personalizado possa participar desse sistema.

Por exemplo, se sua lógica personalizada gerar uma exceção, você poderá dizer ao SharePoint para reverter toda a instalação do suplemento. No entanto, se algo der errado na lógica personalizada de primeira execução, o suplemento permanecerá instalado e, presumivelmente, não funcionará corretamente.
O SharePoint não desistirá se precisar reverter uma instalação de suplemento. Ele tenta imediatamente a instalação novamente. Ele faz até quatro tentativas (o limite de tempo de 30 segundos se aplica a cada tentativa). Sempre que ele tenta novamente, o manipulador de instalação personalizado é executado novamente desde o início. Se o manipulador conseguiu instalar, digamos, uma lista antes da reversão, ele tentará instalar a mesma lista novamente na nova tentativa.

Para evitar que isso aconteça, o código em um manipulador de instalação precisa ser gravado para que ele não tome nenhuma ação (como implantar um componente) a menos que primeiro verifique se essa ação já foi feita. Isso torna a lógica de um manipulador de instalação mais complexa do que a lógica de primeira execução porque a lógica de primeira execução não tentará novamente (a menos que você o codifica especificamente para fazê-lo). Além disso, verificar se um componente já foi implantado geralmente requer uma chamada demorada pela Internet do manipulador remoto para o SharePoint. Uma segunda chamada também é necessária para realmente implantar o componente (se ele ainda não tiver sido implantado).

Para o suplemento Chain Store, combinamos essas estratégias. Neste artigo, você cria um manipulador de instalação que registra a Web host como locatário no banco de dados corporativo e define um sinal que especifica se o suplemento foi executado ainda na Web do host.

Em um artigo posterior nesta série, você colocará a lógica de primeira execução no método Page_Load da página inicial de suplementos. Essa lógica implanta as duas listas personalizadas e também faz outras coisas.

Configurar a solução para a depuração do receptor de eventos

A depuração de receptores de evento requer o uso do Barramento de Serviço do Azure. Siga as instruções em Depurar e solucionar problemas de um receptor de eventos remoto em um Suplemento do SharePoint. Como você está usando um site do SharePoint Online como seu site de teste, verifique se você realiza as instruções para um site de teste remoto. O restante desta série pressupõe que você configurou a depuração com êxito.

Criar o manipulador de instalação

Observação

As configurações de Projetos de Inicialização no Visual Studio tendem a reverter para padrões sempre que a solução é reaberta. Sempre siga estas etapas imediatamente após a reabertura da solução de exemplo nesta série de artigos:

Clique com botão direito do mouse no nó da solução na parte superior do Gerenciador de Soluções e então selecione Definir Projetos de Inicialização.
Verifique se todos os três projetos estão definidos como Iniciar na coluna Ação.

Em Gerenciador de Soluções, selecione o projeto ChainStore para que suas propriedades apareçam no painel Propriedades do Visual Studio.
Defina o valor de Identificador Suplemento Instalado como True (ele ainda pode ser chamado de Manipular Aplicativo Instalado). Isso faz duas coisas:
- Uma pasta chamada Serviços é criada no projeto ChainStoreWeb (não no projeto ChainStore ) e dois arquivos são adicionados a ele: um arquivo AppEventReceiver.svc e seu arquivo AppEventReceiver.svc.cs de código (os nomes de arquivo começam com a cadeia de caracteres "App" porque os suplementos costumavam ser chamados de "aplicativos"; não renomeie esses arquivos porque as Ferramentas de Desenvolvedor do Office para Visual Studio pressupõem que os arquivos manterão esses nomes).
- A URL do manipulador está registrada no manifesto de suplemento. Essa parte do manifesto não está visível no designer de manifesto. Para vê-lo, clique com o botão direito do mouse no arquivo AppManifest.xml e selecione Exibir Código. Um novo filho do elemento Properties se parece com o seguinte.
```
   <InstalledEventEndpoint>~remoteAppUrl/Services/AppEventReceiver.svc</InstalledEventEndpoint>
```
  Essa marcação informa ao SharePoint para chamar o método ProcessEvent desse serviço quando ele terminar de fazer todo o seu próprio trabalho relacionado à instalação do suplemento. O manipulador personalizado é a última coisa que é executada como parte da instalação. A cadeia de caracteres ~remoteAppUrl é um espaço reservado que as Ferramentas de Desenvolvedor do Office para Visual Studio substituem pela URL do host de serviço. Quando você está depurando, é uma URL Barramento de Serviço do Azure. Quando você cria o pacote para implantação em produção, ele é a URL de produção.
Abra o arquivo AppEventReceiver.svc.cs.
Você vê que as Ferramentas de Desenvolvedor do Office para Visual Studio criaram uma implementação de exemplo do método ProcessEvent . Todas as implementações desse método começam inicializando um objeto SPRemoteEventResult e todas terminam retornando esse objeto ao SharePoint. Entre outras coisas, esse objeto informa ao SharePoint se ele deve ou não reverter o evento porque a lógica de tratamento personalizado falhou.

As ferramentas também podem ter incluído um bloco de uso neste método que cria um objeto ClientContext . O manipulador personalizado no suplemento Chain Store não chamará novamente para o SharePoint, portanto, exclua esse bloco. Agora o método deve ter a aparência a seguir.
```
   public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
 {
     SPRemoteEventResult result = new SPRemoteEventResult();

     return result;
 }
```

O receptor de eventos pode ser chamado por qualquer um dos três eventos de suplemento possíveis, portanto, adicione a seguinte estrutura de comutador ao método ProcessEvent entre as linhas que criam e retornam o result objeto (os nomes de evento têm a cadeia de caracteres "App" neles porque os suplementos costumavam ser chamados de "aplicativos").

  switch (properties.EventType)
{
    case SPRemoteEventType.AppInstalled:

        // TODO2: Custom installation logic goes here.

        break;
    case SPRemoteEventType.AppUpgraded:
        // This sample does not implement an add-in upgrade handler.
        break;
    case SPRemoteEventType.AppUninstalling:

        // TODO3: Custom uninstallation logic goes here.         

        break;
}

Nossa lógica de instalação chamará um procedimento armazenado de SQL para registrar a loja de Hong Kong como locatário no aplicativo Web remoto. É muito importante que, se esse processo falhar, o manipulador sinalize o SharePoint para reverter a instalação do suplemento, portanto, adicione os seguintes blocos de tentativa/captura no lugar de TODO2.
```
  try
{
    CreateTenant(tenantName);
 }
catch (Exception e)
{
     // Tell SharePoint to cancel and roll back the event.
    result.ErrorMessage = e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;
}
```
Observe o seguinte sobre este código:
- Você cria o objeto e CreateTenant o tenantName método em uma etapa posterior.
- A propriedade Status do objeto SPRemoteEventResult pode ter três valores possíveis: Continuar (o padrão), CancelNoError e CancelWithError. Um dos dois últimos diz ao SharePoint para reverter o evento.
A URL Web do host, que é o discriminatório de locatário do exemplo, faz parte das informações que o SharePoint passa para o receptor no parâmetro SPRemoteEventProperties . Adicione a linha a seguir ao método ProcessEvent na linha que está logo abaixo da inicialização do objeto SPRemoteEventResult .
```
  string tenantName = properties.AppEventProperties.HostWebFullUrl.ToString();
```
Agora nosso código precisa lidar com uma pequena peculiaridade da propriedade AppEventProperties.HostWebFullUrl . Na maioria dos outros contextos, o SharePoint inclui um caractere de fechamento "/" no final da URL Web do host, portanto, a lógica do nosso código de exemplo pressupõe que esse caractere esteja presente. Mas o SharePoint adiciona esse caractere no final do valor HostWebFullUrl se, e somente se, a Web do host for a web raiz de uma coleção de sites. Como nosso site de Hong Kong é uma subweb na coleção de sites, precisamos adicionar esse caractere para garantir que a mesma cadeia de caracteres de nome de locatário seja usada em todo o exemplo.

Adicione o código a seguir sob a inicialização do tenantName objeto.
```
  if (!tenantName.EndsWith("/"))
{
    tenantName += "/";
}
```

Adicione as instruções de uso a seguir à parte superior do arquivo.

  using System.Data.SqlClient;
  using System.Data;
  using ChainStoreWeb.Utilities;

Adicione o método a seguir à classe AppEventReceiver. Não discutimos isso em detalhes porque a finalidade desta série de artigos é ensinar programação de Suplemento do SharePoint, não SQL Server/Programação do Azure.
```
  private void CreateTenant(string tenantName)
{
    // Do not catch exceptions. Allow them to bubble up and trigger roll back
    // of installation.

    using (SqlConnection conn = SQLAzureUtilities.GetActiveSqlConnection())
    using (SqlCommand cmd = conn.CreateCommand())
    {
        conn.Open();
        cmd.CommandText = "AddTenant";
        cmd.CommandType = CommandType.StoredProcedure;
        SqlParameter name = cmd.Parameters.Add("@Name", SqlDbType.NVarChar);
        name.Value = tenantName;
        cmd.ExecuteNonQuery();
    }//dispose conn and cmd
}
```
Esse método cria uma linha em uma tabela de banco de dados chamada Locatários. Além da coluna Nome , a tabela também tem uma coluna Versão com um valor padrão definido como 0000.0000.0000.0000.0000.0000. Em um artigo posterior nesta série, você criará uma lógica de primeira execução que analisa esse valor para determinar se o suplemento já foi instalado na Web do host. Se a versão for 0000.0000.0000.0000, o código implantará as listas Funcionários Locais e Remessas Esperadas e, em seguida, aumentará o número da versão.

Criar o manipulador de desinstalação

Geralmente, é uma boa prática lidar com o evento de desinstalação sempre que você estiver lidando com o evento instalado. A ideia básica é que o manipulador de desinstalação exclua ou recicla coisas que o manipulador instalado implantou. No entanto, há muitas exceções, portanto, você realmente precisa entender os casos de uso do suplemento. Por exemplo, uma lista implantada com um suplemento e preenchida com o suplemento ainda pode ter valor mesmo depois que o suplemento em si for desinstalado, nesse caso, você não gostaria de desinstalar a lista no manipulador de eventos desinstalação.

O evento de desinstalação não é executado, como era de se esperar, quando um usuário remove o suplemento da página Conteúdo do Site . Isso só move o suplemento para a Lixeira do site. Um usuário pode restaurá-lo, mas restaurar não executa novamente o manipulador de eventos instalado, portanto, você deseja que qualquer coisa implantada com o manipulador de eventos instalado ainda exista se o suplemento for restaurado. Os componentes do SharePoint podem ser movidos da Lixeira para a Lixeira do segundo estágio. É somente quando um suplemento é excluído do segundo estágio em que o evento de desinstalação acontece; quando um usuário faz isso, o suplemento é insociável de qualquer maneira, portanto, queremos que o aluguel da loja de Hong Kong seja removido do banco de dados corporativo nesse ponto.

Defina o valor de Desinstalação de Suplemento de Identificador como True (ele ainda pode ser chamado de Desinstalação do Aplicativo handle). Isso registra o manipulador no arquivo AppManifest.xml assim como você registrou anteriormente o manipulador de instalação. Se você olhar para o arquivo, verá que eles têm exatamente a mesma URL. As Ferramentas de Desenvolvedor do Office para Visual Studio pressupõem que você esteja usando o mesmo arquivo *.svc. Estamos fazendo isso neste exemplo, e é uma prática padrão.
Adicione o código a seguir no lugar do TODO3 no arquivo AppEventReceiver.svc.cs.
```
  try
{
    DeleteTenant(tenantName);
 }
catch (Exception e)
{
     // Tell SharePoint to cancel and roll back the event.
    result.ErrorMessage = e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;
}
```
Observe o seguinte sobre este código:
- O DeleteTenant método é adicionado na próxima etapa.
- Reverter a desinstalação do suplemento o deixa na lixeira do segundo estágio, da qual ele ainda pode ser restaurado.

Adicione o método a seguir à classe AppEventReceiver.

  private void DeleteTenant(string tenantName)
{
    // Do not catch exceptions. Allow them to bubble up and trigger roll back
    // of un-installation (removal from 2nd level Recycle Bin).

    using (SqlConnection conn = SQLAzureUtilities.GetActiveSqlConnection())
    using (SqlCommand cmd = conn.CreateCommand())
    {
        conn.Open();
        cmd.CommandText = "RemoveTenant";
        cmd.CommandType = CommandType.StoredProcedure;
        SqlParameter name = cmd.Parameters.Add("@Name", SqlDbType.NVarChar);
        name.Value = tenantName;
        cmd.ExecuteNonQuery();                
    }//dispose conn and cmd
}

Observação

Em um artigo anterior nesta série, você configurou o projeto para recompilar o banco de dados corporativo sempre que selecionasse F5. Isso esvazia a tabela Locatários .

Executar o suplemento e testar o manipulador de instalação

Use a tecla F5 para implantar e executar o suplemento. O Visual Studio hospeda o aplicativo Web remoto no IIS Express e hospeda o banco de dados SQL no SQL Express. Ele também faz uma instalação temporária do suplemento em seu site de teste do SharePoint, executa o manipulador de eventos de instalação e executa imediatamente o suplemento. Você é solicitado a conceder permissões ao suplemento antes que sua página inicial seja aberta.
Quando a página inicial do suplemento for aberta, selecione o ícone de engrenagem no controle cromado na parte superior e selecione Configurações da conta.
Na página Configurações de Contas , selecione o botão Mostrar Versão de Suplemento . A versão é exibida como 0000.0000.0000.0000.

Figura 1. Página configurações da conta
Para encerrar a sessão de depuração, feche a janela do navegador ou interrompa a depuração no Visual Studio. Sempre que você seleciona F5, o Visual Studio retira a versão anterior do suplemento e instala a versão mais recente.
Você lidará com esse suplemento e com a solução do Visual Studio em outros artigos, e recomenda-se retirar o suplemento uma última vez quando for deixar de trabalhar com ele por algum tempo. Clique com botão direito do mouse no projeto no Gerenciador de Soluções e escolha Retirar.

Próximas etapas

No próximo artigo da série, você adicionará lógica de primeira execução ao suplemento que implanta programaticamente a lista Funcionários Locais e o botão de faixa de opções personalizada: Adicione lógica de primeira execução ao suplemento hospedado pelo provedor.

Partilhar via

Manipular eventos de suplemento no suplemento hospedado pelo provedor

Dois lugares para implantar componentes do SharePoint via programação

Configurar a solução para a depuração do receptor de eventos

Criar o manipulador de instalação

Criar o manipulador de desinstalação

Executar o suplemento e testar o manipulador de instalação

Próximas etapas

Recursos adicionais