Criar um manipulador para o evento de atualização nos suplementos do SharePoint

Artigo
04/08/2023

Antes de começar, familiarize-se com o tratamento de eventos de suplemento e atualizar suplementos do SharePoint e os pré-requisitos e os conceitos principais listados neles.

Observação

Sistema de numeração de versão: Para consistência, este tópico pressupõe que os números da versão de suplemento sejam 1.0.0.0, 2.0.0.0, 3.0.0.0 e assim por diante. No entanto, a lógica e as diretrizes se aplicam não importa qual seja o sistema de numeração.

Criar um receptor UpgradedEventEndpoint

Para a lógica de atualização personalizada, você pode criar um receptor de eventos remoto do SharePoint que manipula o evento atualizado do suplemento. Você deve ser conservador ao usar essa técnica. Use-o apenas para atualizar etapas que não podem ser feitas de outra maneira. Além disso, as diretrizes encontradas no tratamento de eventos de suplemento se aplicam ao evento atualizado do suplemento tanto quanto o suplemento instalado e os eventos de desinstalação de suplementos. Isso inclui:

Seu manipulador precisa concluir e retornar um cancelamento ou um status de continuação para o SharePoint em 30 segundos. Se isso não acontecer, o SharePoint chamará o manipulador novamente até mais três vezes.
Se o manipulador retornar um status de cancelamento, o SharePoint tentará novamente até mais três vezes.
Normalmente, você precisa incluir a reversão e a lógica "já concluída" no manipulador.

Um cenário em que um manipulador UpgradedEventEndpoint é útil é quando um campo computado é adicionado a um banco de dados remoto. Suponha que uma coluna city seja adicionada e seu valor seja calculado a partir de uma coluna do Código Postal já existente. Seu código em um manipulador UpgradedEventEndpoint poderia iterar por meio de itens existentes no banco de dados e preencher o valor do novo campo City com base no valor do campo Código Postal e em alguma fonte de dados externa que mapeia códigos postais para as cidades. A alteração no esquema de banco de dados em si é melhor feita fora do manipulador UpgradedEventEndpoint usando as melhores práticas da plataforma de banco de dados.

Para obter mais detalhes sobre como criar um manipulador para o evento de suplemento, confira Manipular eventos em Suplementos do SharePoint e Criar um receptor de evento de suplemento nos Suplementos do SharePoint.

O procedimento a seguir pressupõe que você tenha adicionado o item do receptor de eventos de suplemento ao seu projeto de suplemento do SharePoint no Visual Studio.

Para lidar com o evento atualizado do suplemento pela primeira vez

Abra o arquivo AppEventReceiver.svc.cs e adicione uma estrutura condicional ao método ProcessEvent que testa se o evento que invocou o manipulador é o evento atualizado. Seu código de atualização entra nessa estrutura. Se o código precisar acessar o SharePoint, você poderá usar a interface CSOM (modelo de objeto cliente de código gerenciado) do SharePoint ou REST (Transferência de Estado Representacional).

Onde a estrutura condicional está localizada no método depende de como você estruturou o outro código no método. Normalmente, ele é um par de estruturas condicionais semelhantes que testam para os eventos de desinstalação do suplemento instalados e do suplemento. Ele pode estar dentro de uma estrutura condicional que testa determinadas propriedades ou subpropertidades do objeto SPRemoteEventProperties que é passado para ProcessEvent para valores nulos ou outros valores inválidos. Ele também pode estar dentro de um bloco de tentativas .

A seguir está um exemplo da estrutura. O objeto properties é um objeto SPRemoteEventProperties .
```
   if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
 }
```
Para usar o CSOM no manipulador, adicione (dentro do bloco condicional) um bloco usando que obtém um objeto ClientContext chamando o método TokenHelper.CreateAppEventClientContext . Especifique true para que o segundo parâmetro acesse a Web de suplemento. Especifique false para acessar a Web do host. Se você precisar acessar ambos, precisará de dois objetos de contexto de cliente diferentes.

Se o manipulador precisar acessar componentes que não são do SharePoint, coloque esse código fora de todos os blocos de contexto do cliente. Seu código deve ser estruturado de forma semelhante ao seguinte:

   if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
     using (ClientContext cc = TokenHelper.CreateAppEventClientContext(properties, true))
     {
         // CSOM code that accesses the add-in web
     }
     using (ClientContext cc = TokenHelper.CreateAppEventClientContext(properties, false))
     {
         // CSOM code that accesses the host web
     }
     // Other update code
 }

Para usar a interface REST, seu código usa outros métodos na classe TokenHelper para obter um token de acesso, que é então incluído nas solicitações que ele faz ao SharePoint. Para obter mais informações, confira Concluir operações básicas usando pontos de extremidade REST do SharePoint. Seu código deve ser estruturado de forma semelhante à seguinte.

   if (properties.EventType == SPRemoteEventType.AppUpgraded)
 {
     string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
     if (contextTokenString != null)
     {
         contextToken = TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                                                                                                                   Request.Url.Authority);
         accessToken = TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority)
                                    .AccessToken;

        // REST code that accesses SharePoint
     }  
     // Other update code
 }

Para acessar o SharePoint, seu código REST também precisa saber a URL da Web do host ou do suplemento web ou ambos. Essas URLs são subpropertias do objeto SPRemoteEventProperties que é passado para o método ProcessEvent . O código a seguir mostra como obtê-los.
```
   Uri hostWebURL = properties.AppEventProperties.HostWebFullUrl;
   Uri appWebURL = properties.AppEventProperties.AppWebFullUrl;
```

Ao atualizar um suplemento para o segundo (ou terceiro e assim por diante), talvez seja necessário garantir que alguma lógica de atualização não seja executada várias vezes na mesma instância de suplemento. O procedimento a seguir mostra como.

Para lidar com o evento atualizado do suplemento em atualizações subsequentes

Abra o arquivo AppEventReceiver.svc.cs e localize o código que implementou ações de atualização na primeira atualização (de 1.0.0.0.0. para 2.0.0.0). Vamos chamar isso de código de atualização anterior. (Esse código geralmente está localizado após o código de autorização que obtém o contexto do cliente ou os tokens de acesso.) Agora que você está atualizando novamente (de 2.0.0.0 para 3.0.0.0), normalmente haverá ações no código de atualização anterior aqui que você não deseja executar novamente na mesma instância de suplemento, mas você deseja que ele seja executado em uma instância de suplemento que nunca foi atualizada para 2.0.0.0 (nesse caso, a instância agora está sendo atualizada de 1.0.0.0. para 3.0.0.0).
Embrulhe o código de atualização anterior em uma estrutura condicional que testa a versão anterior da instância de suplemento e executa somente se o código na estrutura não tiver sido executado antes nesta instância de suplemento. A versão anterior da instância é armazenada na subpropertia PreviousVersion do objeto SPRemoteEventProperties .

Adicione sua nova lógica de atualização (para a atualização de 2.0.0.0 para 3.0.0.0) sob essa estrutura. Apresentamos um exemplo a seguir.

   Version ver2OOO = new Version("2.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver2OOO)
 {
     // Code to update from 1.0.0.0 to 2.0.0.0 (previous update code) is here.
 }
 // Code to update from 2.0.0.0 to 3.0.0.0 is here.

Para cada atualização subsequente, repita estas etapas. Para a atualização de 3.0.0.0 para 4.0.0.0, seu código deve ter a estrutura a seguir.

 Version ver2OOO = new Version("2.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver2OOO)
 {
     // Code to update from 1.0.0.0 to 2.0.0.0 is here.
 }

 Version ver3OOO = new Version("3.0.0.0");
 if (properties.AppEventProperties.PreviousVersion < ver3OOO)
 {
     // Code to update from 2.0.0.0 to 3.0.0.0 (previous update code) is here.
 }
 // Code to update from 3.0.0.0 to 4.0.0.0 is here.

Importante

Se você adicionar um componente a um suplemento em um manipulador UpgradedEventEndpoint , adicione o mesmo código a um manipulador InstalledEventEndpoint porque deseja que esse componente seja incluído no suplemento em uma nova instalação. Além disso, você deve adicionar um DesinstalingEventEndpoint (ou revisá-lo) para que o suplemento remova o componente.

Na maioria das vezes, qualquer coisa que tenha sido adicionada ou alterada pelo InstalledEventEndpoint deve ser revertida ou excluída pelo DesinstalingEventEndpoint. Uma exceção é que os dados que permanecerão úteis depois que o suplemento for removido da lixeira do segundo estágio não devem ser excluídos. (Sites, além do suplemento Web, que são criados pelo suplemento devem ser considerados dados.)

Adicionar lógica de reversão ao manipulador

Se ocorrer um erro quando um suplemento estiver sendo atualizado, a infraestrutura do SharePoint interromperá o processo de atualização e reverterá a instância de suplemento e todos os seus componentes para a versão anterior da instância de suplemento. Mas a infraestrutura não tem como saber o que a lógica do manipulador UpgradedEventEndpoint faz, portanto, nem sempre pode desfazê-la. Uma exceção sem tratamento gerada enquanto o manipulador UpgradedEventEndpoint está executando certamente indica que todo o processo de atualização de suplemento deve ser revertido, mas não será porque a infraestrutura não sabe como desfazer algumas coisas que seu código UpgradedEventEndpoint pode ter feito. Por esse motivo, o código UpgradedEventEndpoint deve:

Pegue todas as exceções.
Branch para código de reversão personalizado para desfazer o que foi feito até esse ponto.
Sinalize para a infraestrutura do SharePoint que toda a atualização de suplemento deve ser revertida.
Passe uma mensagem de erro para a infraestrutura.

Nem tudo o que seu UpgradedEventEndpoint faz precisa ser explicitamente revertido dentro do manipulador. A Web de suplemento será revertida pela infraestrutura para que seu código não precise desfazer alterações na Web de suplemento. Mas o manipulador UpgradedEventEndpoint geralmente precisa reverter as alterações feitas na Web do host ou em outros componentes externos ao Suplemento do SharePoint.

Na segunda (ou terceira, e assim por diante), sua lógica de entrega de exceção deve levar em conta o fato de que a instância de suplemento que está sendo atualizada não é necessariamente a versão imediatamente anterior. Se não for, pode haver dois ou mais blocos de código de atualização que precisam ser revertidos. Por esse motivo, você precisa de uma lógica condicional baseada no número da versão anterior. A seguir está um exemplo da lógica de reversão para uma atualização para a versão 4.0.0.0.

catch (Exception e)
{ 
    // Rollback of the 3.0.0.0 to 4.0.0.0 update logic goes here.

    Version ver3OOO = new Version("3.0.0.0");
    if (properties.AppEventProperties.PreviousVersion < ver3OOO)
    {
        // Rollback of the 2.0.0.0 to 3.0.0.0 update logic goes here.
    }

    Version ver2OOO = new Version("2.0.0.0");
    if (properties.AppEventProperties.PreviousVersion < ver2OOO)
    {
        // Rollback of the 1.0.0.0 to 2.0.0.0 update logic goes here.
    }
}

As últimas coisas que seu tratamento de erros deve fazer é atribuir uma mensagem de erro e um status de cancelamento ao objeto SPRemoteEventResult que o método ProcessEvent retorna à infraestrutura de atualização do SharePoint. Apresentamos um exemplo a seguir. Neste código, o resultado é um objeto SPRemoteEventResult que foi declarado anteriormente no método ProcessEvent .

catch (Exception e)
{     
    result.ErrorMessage = "custom message " + e.Message;
    result.Status = SPRemoteEventServiceStatus.CancelWithError;

     // Rollback logic from the preceding code snippet  is here. 

}

Importante

Atribuir SPRemoteEventServiceStatus.CancelWithError (ou SPRemoteEventServiceStatus.CancelNoError) à propriedade Status é crucial. Essa propriedade é o que sinaliza a infraestrutura para reverter a atualização. Mas o SharePoint tentará novamente seu manipulador três vezes antes de reverter a atualização.

Usar a estratégia de delegação do manipulador

A estratégia de delegação do manipulador descrita no Tratamento de eventos de suplemento também pode ser usada em um UpdatedEventHandler . Não só a sua reversão e a lógica "já feita" são empacotadas e executadas no componente remoto, mas também a lógica de versão. As limitações da estratégia também se aplicam aqui; Normalmente, você não pode usá-lo para atualizar mais de um sistema remoto.

Próximas etapas

Retorne às principais etapas para atualizar um suplemento ou vá diretamente para um dos artigos a seguir para saber como atualizar o próximo componente principal do suplemento do SharePoint.

Partilhar via