Manipular eventos nos Suplementos do SharePoint
Seu código personalizado pode manipular três categorias de eventos de suplementos hospedados pelo provedor:
- Eventos de lista, como a adição ou a exclusão de uma lista em um site.
- Eventos de item de lista, como a edição de um item em uma lista.
- Eventos de suplemento, como a instalação de um suplemento.
Os Suplementos do SharePoint hospedados pelo SharePoint não oferecem suporte à manipulação de eventos, mas você pode transformar um fluxo de trabalho em um tipo de lista ou manipulador de eventos de itens de lista, definindo um evento para acionar o fluxo de trabalho. Para obter mais informações, confira Fluxos de trabalho no SharePoint. Os fluxos de trabalho não podem ser acionados por eventos de suplemento, portanto, os eventos de suplemento não podem ser manipulados com um suplemento hospedado no SharePoint.
Observação
Eventos de site e eventos de conjunto de sites não são suportados nos Suplementos do SharePoint.
Há dois tipos de eventos:
Antes que os eventos sejam acionados, a infraestrutura do SharePoint realiza seu próprio tratamento do evento (incluindo a confirmação de alterações no banco de dados de conteúdo). No SharePoint personalizado antes de os manipuladores de eventos sempre executam sincronamente. Entre outros propósitos, eles podem ser usados para cancelar o evento. Por exemplo, se um suplemento tiver uma função para excluir uma lista, um manipulador do evento de exclusão de lista poderá cancelar a exclusão se determinadas condições não forem atendidas. Se o evento fizer parte de uma sequência de eventos, cancelá-lo impedirá a ocorrência de qualquer um dos eventos posteriores. Por exemplo, se o manipulador do evento ItemAdding cancelar o evento, o evento ItemAdded, que normalmente ocorre mais tarde, não será acionado.
Depois que os eventos são acionados, a infraestrutura do SharePoint realiza sua própria manipulação do evento. No SharePoint, os manipuladores remotos após eventos, para eventos de lista e item de lista, sempre são executados de forma assíncrona. (Eventos de aplicativo são uma exceção.) Entre outros propósitos, eles podem ser usados para registrar eventos.
Lidar com lista e eventos de item de lista
Para manipular eventos de lista e item de lista, crie receptores de eventos remotos (RERs), que são serviços Web executados externamente no farm do SharePoint ou no SharePoint Online. A URL do serviço RER é registrada para os eventos que ele manipula. Há duas maneiras de registrar um manipulador:
Eventos no host da Web são registrados, via programação, com o CSOM (modelo de objeto do lado do cliente) ou a API REST do SharePoint. Esta tarefa é normalmente realizada na lógica "primeira execução" no suplemento ou em um manipulador de um suplemento do evento. (Para obter uma visão geral dos eventos de suplemento, confira Manipular eventos de suplemento posteriormente neste artigo.) Para obter um exemplo de código que registra um evento de lista via programação, confira SharePoint/PnP/Samples/Core.EventReceivers.
Os eventos na Web de suplemento geralmente são registrados em um recurso da Web de suplemento com algumas marcações XML simples. Os detalhes de como criar a marcação e o serviço estão em Criar um receptor de eventos remotos nos Suplementos do SharePoint. Também é possível registrar eventos da Web de suplemento via programação.
Observação
RERs têm a mesma finalidade de receptores de evento em soluções de farm, mas os receptores de evento têm um código personalizado que é executado em servidores do SharePoint, então eles não podem ser usados em Suplementos do SharePoint.
O suplemento pode lidar com os seguintes eventos de lista e da biblioteca de documentos. Eventos que terminam em "ing" são eventos anteriores (síncronos) e aqueles que terminam em "ed" são eventos posteriores (assíncronos).
| Anterior (síncrono) | Posterior (assíncrono) |
|---|---|
| ListAdding | ListAdded |
| ListDeleting | ListDeleted |
| FieldAdding | FieldAdded |
| FieldDeleting | FieldDeleted |
| FieldUpdating | FieldUpdated |
Os eventos de atualização do campo são sobre como alterar as propriedades de um campo (coluna) em uma lista, como se ela é classificável, não sobre como alterar os dados no campo.
O suplemento pode lidar com os seguintes eventos de item de lista.
| Anterior (síncrono) | Posterior (assíncrono) |
|---|---|
| ItemAdding | ItemAdded |
| ItemUpdating | ItemUpdated |
| ItemDeleting | ItemDeleted |
| ItemCheckingOut | ItemCheckedOut |
| ItemCheckingIn | ItemCheckedIn |
| ItemUncheckingOut | ItemUncheckedOut |
| ItemAttachmentAdding | ItemAttachmentAdded |
| ItemAttachmentDeleting | ItemAttachmentDeleted |
| ItemFileMoving | ItemFileMoved |
| ItemVersionDeleting* | ItemVersionDeleted* |
| ItemFileConverted |
Observação
*Esses dois novos eventos podem não estar disponíveis na interface do usuário do Visual Studio. Caso contrário, escolha ItemDeleting ou ItemDeleted e altere manualmente os nomes.
Quando você estiver trabalhando no Visual Studio e adicionar um RER a um projeto de suplemento do SharePoint, as ferramentas de desenvolvedor do Office para Visual Studio fazem o seguinte:
Um arquivo de serviço da Web, como RemoteEventReceiver1.svc, é adicionado ao aplicativo Web para manipular os eventos que você especificou quando adicionou o receptor de evento remoto ao Suplemento do SharePoint. O serviço da Web contém um arquivo de código para manipular os eventos remotos.
Depois de criar o receptor de evento remoto, você adiciona código ao arquivo de código do serviço de aplicativo Web para manipular os eventos. Por padrão, o arquivo de código contém dois métodos aos quais você adiciona seu código de manipulação:
ProcessEvent()manipula eventos "anteriores" (como os da coluna à esquerda nas tabelas anterior no artigo) e retorna um objeto para o SharePoint que relata se o evento deverá ser cancelado ou prosseguir.ProcessOneWayEvent()manipula eventos "posteriores". Ele é executado de forma assíncrona e não retorna nada ao SharePoint.
Quando ocorre um evento registrado, o SharePoint chama o método apropriado no serviço e passa um objeto que fornece algumas informações de contexto para o código. Por exemplo, o tipo de evento (de uma das duas tabelas anteriores neste artigo) é identificado, para que seu código possa ramificar para a lógica apropriada ao evento.
Um item de projeto para o receptor de evento remoto é adicionado ao projeto de Suplemento do SharePoint. O arquivo Elements.xml para o receptor de evento remoto faz referência ao serviço da Web no aplicativo Web e aos eventos remotos que você especificou. O exemplo a seguir mostra um arquivo Elements.xml que lida com a adição ou exclusão de um item da lista.
<?xml version="1.0" encoding="utf-8"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <Receivers ListTemplateId="104"> <Receiver> <Name>RemoteEventReceiver1ItemAdding</Name> <Type>ItemAdding</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> <Receiver> <Name>RemoteEventReceiver1ItemDeleting</Name> <Type>ItemDeleting</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> </Receivers> </Elements>
Para alterar os eventos manipulados pelo receptor de eventos remoto, abra Gerenciador de Soluções, abra a janela Propriedades do receptor de eventos remoto, expanda o nó Eventos do SharePoint e configure somente os eventos que você deseja tratar como Verdadeiro.
Observação
Para saber mais sobre RERs, incluindo algumas informações sobre solução de problemas, confira Perguntas frequentes sobre Receptores de eventos remotos.
Manipular eventos de suplemento
Os eventos de suplemento também são manipulados por serviços Web remotos, mas são configurados de maneira diferente no pacote de suplemento dos RERs da lista e do item de lista, para que sejam tratados como uma categoria separada do componente. Para um evento de suplemento, o serviço Web remoto é registrado no manifesto do suplemento, não em um recurso Web de suplemento. O suplemento nem precisa ter uma Web de suplemento. Existem três eventos de suplementos, conforme descrito nas próximas seções.
Evento AppInstalled
O evento AppInstalled é executado imediatamente após o SharePoint concluir tudo o que é necessário quando o suplemento é instalado, mas antes que o usuário seja notificado de que a instalação está concluída. Embora este seja um evento após , o SharePoint executa seu manipulador de forma síncrona. O suplemento não está disponível para uso até que o manipulador tenha sido concluído e ele pode cancelar a instalação (o que faz com que o SharePoint reverta tudo o que fez como parte da instalação). Na verdade, é uma prática recomendada detectar erros no manipulador e instruir o SharePoint a reverter a instalação. Pra obter mais informações, confira Incluir lógica de reversão e lógica "já concluído" em manipuladores de eventos de suplemento.
Observação
Quando você instala um suplemento com Escopo de locatário, ele é instalado no conjunto de sites do catálogo de suplementos e o evento AppInstalled é executado apenas nesse momento. O suplemento é visível em vários sites da locação, mas o evento não é executado separadamente para cada um deles.
Além de cancelar uma instalação de suplemento, esse evento pode ser usado para muitas outras finalidades, incluindo:
Instalar os componentes do SharePoint no host da Web que não pode ser instalado de maneira declarativa com o recurso do host da Web, como listas ou subsites.
Registrar, via programação, manipuladores de eventos de lista e de item de lista no host da Web ou na Web de suplemento.
Definir configurações de inicialização relativas à instância do aplicativo. Por exemplo, seu suplemento pode ter um recipiente de propriedades Web de suplemento para manter configurações que variam de uma instância do suplemento para outra. O manipulador AppInstalled pode gravar valores variados no pacote de propriedades, com base, digamos, no tipo de site do host da Web (como Site de Equipe ou Site do Blog).
Observação
Verificar se o host da Web é um site do AppCatalog é uma boa maneira de detectar se o suplemento foi instalado com o escopo do locatário. Confira Locações e escopos de implantação para Suplementos do SharePoint.
Executar a configuração relativa à instância no aplicativo remoto da Web, como adicionar uma tabela a um banco de dados.
Importante
Sua implementação do evento AppInstalled deve ser concluída em 30 segundos ou a infraestrutura de instalação do SharePoint acha que falhou. A infraestrutura executa novamente o evento e repete seu código desde o início, até três vezes adicionais. Após quatro tempos limite, o SharePoint reverte toda a instalação do suplemento. As implicações completas desses fatos são discutidas em Incluir lógica de reversão e lógica "já concluído" em seus manipuladores de eventos de suplemento.
Evento AppUninstalling
O evento AppUninstalling não é executado quando o suplemento é removido da Web do host. A remoção de um suplemento move o suplemento para a lixeira do usuário. Mais duas etapas são necessárias antes que o evento AppUninstalling seja acionado. Primeiro, o usuário deve remover o suplemento da lixeira, que o move para a lixeira de segundo estágio. Em segundo lugar, um usuário deve remover o suplemento da lixeira do segundo estágio. Esta última tarefa dispara o evento AppUninstalling. O evento AppUninstalling é síncrono e você pode usá-lo para cancelar a desinstalação, o que deixaria o suplemento na lixeira de segundo estágio.
O principal objetivo de um manipulador para esse evento é excluir ou reciclar itens implantados com um manipulador AppInstalled (ou AppUpdated). O SharePoint não pode excluir esses itens ou movê-los para a lixeira, porque não os conhece, pelo menos não como componentes do suplemento. Geralmente, é uma boa prática remover esses itens. Mas você não deseja excluir as coisas que ainda têm vida útil após o término do suplemento: se uma lista ou site criado pelo manipulador do AppInstalled ainda for usado, não o exclua no manipulador do AppUninstalling.
Evento AppUpgraded
O evento AppUpgraded é executado imediatamente após o SharePoint concluir tudo o que é necessário quando o suplemento é atualizado para uma nova versão, mas antes que o usuário seja notificado de que a atualização está concluída. Como o evento AppInstalled, é um evento posterior, mas é essencialmente síncrono e é uma prática recomendada para detectar erros e notificar o SharePoint para reverter a atualização.
Alguns exemplos do que um manipulador deste evento pode fazer:
Adicionar, alterar ou remover componentes de suplemento do host da Web.
Fazer coisas na Web de suplemento que não são possíveis com a semântica de atualização declarativa em um recurso Web de suplemento. Por exemplo, não é possível excluir nada com a marcação declarativa da atualização, mas você pode fazê-lo, via programação, em um manipulador AppUpgraded.
Fazer alterações nos componentes relativos à instância do aplicativo no aplicativo Web do suplemento ou no banco de dados remoto.
Para obter instruções detalhadas sobre como criar manipuladores de eventos de suplemento, confira Criar um receptor de eventos de suplemento nos Suplementos do SharePoint.
Incluir lógica de reversão e lógica "já concluído" em seus manipuladores de eventos de suplemento
Se o SharePoint encontrar um erro ao processar qualquer um dos três eventos de suplemento, ele cancelará o evento e reverterá quaisquer alterações feitas em conexão com o evento. O manipuladores de eventos de complemento precisam se integrar a esse sistema porque, se a parte do evento que você está implementando falhar, você vai querer que o evento seja revertido, em vez de continuar e deixar as coisas em um estado possivelmente corrompido. Aqui está o que seu manipulador geralmente tem que fazer:
Informe ao SharePoint que ocorreu um erro. A mensagem SOAP de que o serviço Web de manipulação de eventos do suplemento retorna ao SharePoint tem uma propriedade Status que pode ter os valores de Continuar, CancelWithError ou CancelWithoutError. O status Cancelar indica ao SharePoint para reverter o evento.
Reverta o que o manipulador já fez antes de encontrar o erro. O SharePoint geralmente não pode fazer isso por você porque não sabe o que seu manipulador fez. Essa não é uma regra universal. Por exemplo, se uma instalação de suplemento for cancelada, o SharePoint excluirá toda a Web de suplemento, portanto, não há sentido em um manipulador de eventos AppInstalled reverter tudo o que foi feito Wa web de suplemento. Mas geralmente ele deve reverter o que fez para o hosta da Web ou para os componentes remotos do suplemento.
Observação
Os pontos anteriores se aplicam ao evento AppUninstalling e aos outros dois eventos de suplemento. Por exemplo, se o manipulador do evento de desinstalação excluir uma linha em um banco de dados remoto e, em seguida, encontrar um erro, a linha precisará ser restaurada. Como o serviço envia uma mensagem de cancelamento ao SharePoint, o suplemento não é removido da lixeira. Se ele for restaurado a partir daí e usado novamente, poderá falhar ao trabalhar sem essa entrada no banco de dados. No entanto, o manipulador AppUninstalling é concluído antes que o SharePoint remova o suplemento da lixeira. Portanto, se o próprio SharePoint encontrar um erro e precisar cancelar a remoção, o manipulador não poderá desfazer o que fez.
Se o SharePoint não receber uma mensagem de resultados do manipulador em 30 segundos, ele chamará o manipulador novamente. Ele desiste completamente e reverte o evento após três novas tentativas (quatro tentativas ao todo). Sempre que chamar o manipulador, o código é iniciado novamente desde o início. No entanto, você geralmente não deseja que seu manipulador refaça o que já fez, como criar uma lista no host da Web e não pode saber se sua lógica de reversão foi concluída ou mesmo acionada antes que o manipulador atingisse o tempo limite. Por esse motivo, a lógica do manipulador não deve executar nenhuma ação sem primeiro verificar se a ação já foi executada, a menos que seja inofensivo executá-la novamente.
Os erros de instalação e atualização podem ser vistos na interface do usuário do SharePoint, conforme mostrado na figura a seguir.
Obter detalhes do erro de instalação
Estratégias de arquitetura de manipulador de eventos de suplemento
Expressado em pseudocódigo, seu manipulador geralmente deve ser estruturado da seguinte forma. Se ocorrer um erro na seção Try, a seção Catch e Rollback deve ser chamada. (Isso pode acontecer automaticamente, dependendo do idioma e da estrutura.)
Try
If X not already done,
Do X.
Catch
Send cancel message to SharePoint.
If X not already undone,
Undo X.
No entanto, a implementação da reversão e lógica "já concluído" no seu serviço Web pode diminuir a velocidade do manipulador. Tanto a sua instalação quanto a lógica de reversão geralmente fazem alterações em algo mais ou menos remoto do serviço Web, como o host da Web do SharePoint ou um banco de dados de back-end. Se o código de instalação e reversão estiver dividido entre as seções Try e Catch, o serviço fará chamadas separadas para os componentes remotos, geralmente várias chamadas em cada seção.
Geralmente, a prática recomendada é implementar a lógica de instalação e de reversão no próprio componente remoto em um procedimento que possa ser chamado pelo manipulador na seção Try. O procedimento deve retornar uma mensagem de êxito ou falha e, se relatar falha, o código na seção Try chama a seção Catch (emitindo, por exemplo, uma exceção). A única coisa que a seção Catch faz é notificar o SharePoint. Chamamos isso de estratégia de delegação do manipulador. O pseudocódigo a seguir ilustra a estratégia:
Try
Call the "Do X" procedure on remote platform.
If remote platform reports failure, call Catch.
Catch
Send cancel message to SharePoint.
O procedimento de "Faça X", que é executado no sistema remoto em si conteria a reversão e a lógica "já concluído" semelhante ao seguinte.
Try
If X not already done,
Do X.
Set success flag to true.
Catch
If X was done before error,
Undo X.
Set success flag to false.
Send
Return success flag to the event handler.
Por exemplo, se seu manipulador precisa agir em um banco de dados do SQL Server, você poderá instalar um procedimento armazenado no SQL Server que usa um bloco TRY-CATCH para implementar a lógica de reversão da instalação com blocos IF-ELSE blocos para implementar a lógica "já concluído".
O modelo de Suplemento do SharePoint não fornece uma maneira de armazenar código personalizado do lado do servidor no SharePoint e invocá-lo no CSOM (modelo de objeto do lado do cliente). No entanto, o CSOM fornece uma maneira de agrupar a lógica try-catch e if-then-else e enviá-lo ao servidor para execução.
Para obter um exemplo detalhado de um manipulador de eventos de suplemento que usa a estratégia de delegação de manipulador para adicionar uma lista a um host da Web, confira Criar um receptor de eventos de suplemento nos Suplementos do SharePoint. Para um exemplo de código, confira SharePoint/PnP/Samples/Core.AppEvents.HandlerDelegation.
Você nem sempre pode usar a estratégia de delegação de manipulador. Por exemplo, quando seu manipulador está chamando para mais de um componente, como um banco de dados e o host da Web do SharePoint, há uma chance de que um possa ser concluído com êxito e o outro falhar. Nesse cenário, a lógica de reversão para o primeiro componente não será executada se você a tiver projetado com a estratégia de delegação do manipulador. Por esse motivo, se você estiver chamando os componentes de forma síncrona, apenas o último chamado poderá usar a estratégia de delegação do manipulador. Se eles forem chamados de forma assíncrona, não será possível usar essa estratégia em nenhum deles.
Para obter um exemplo de um manipulador de eventos de suplemento que não usa a estratégia de delegação do manipulador, consulte SharePoint/PnP/Samples/Core.AppEvents.
Dica
Se o evento AppInstalled falhar, o SharePoint excluirá a Web de suplemento, se houver; e se o evento AppUpated falhar, o SharePoint restaurará a Web de suplemento para o estado de pré-atualização. Por esse motivo, os manipuladores nunca precisam reverter as ações que executam na Web de suplemento. Se o manipulador executar ações no host da Web e na Web de suplemento, ele deverá lidar primeiro com a Web de suplemento. Isso torna seguro o uso da estratégia de delegação de manipulador para o host da Web. Mesmo se as ações da Web de suplemento forem bem-sucedidas e as ações d host da Web falharem, nenhuma lógica de reversão será executada.
Receptores de evento remotos em suplementos que oferecem suporte a várias zonas de segurança
Algumas restrições sobre como você cria um suplemento oferecem suporte a várias zonas de segurança e têm um receptor de eventos remotos.
Perguntas Frequentes sobre Receptores de Eventos Remotos
Estas são perguntas comuns que você pode fazer ao usar receptores de eventos remotos.
Como receptores de eventos remotos são diferentes dos receptores de eventos no SharePoint 2010?
No SharePoint 2010, os receptores de eventos manipulam eventos que ocorrem em listas, sites e outros objetos do SharePoint executando o código no servidor do SharePoint (confiança total ou em uma área restrita). Esse tipo de receptor de eventos ainda existe no SharePoint. No entanto, o SharePoint também oferece suporte a receptores de eventos remotos nos quais o código executado quando o evento é disparado e é hospedado por um serviço Web. Isso significa que, se você registrar um receptor de eventos remotos, também precisará informar ao SharePoint qual serviço Web invocar.
Nos exemplos de código a seguir, o primeiro exemplo (soluções do SharePoint) implementa a funcionalidade usando um manipulador de eventos. O segundo exemplo (Suplementos do SharePoint) implementa a mesma funcionalidade usando um receptor de eventos remotos.
Soluções do SharePoint
// Trigger an event when an item is added to the SharePoint list.
Public class OnPlantUpdated : SPItemEventReceiver
{
Public override void ItemAdding (SPItemEventProperties properties)
{
Properties.After.Properties.ChangedProperties.Add("Image",CreateLink(properties));
Properties.status =SPEventReceiverStatus.Continue;
}
/// When an item updates, run the following.
Public override void ItemUpdating(SPItemEventProperties properties)
{
Properties.AfterProperties.ChangedProperties.Add("Image",CreateLink9properties));
Properties.Status= SPEventReceiverStatus.Continue;
}
Suplementos do SharePoint
/* Trigger an event when an item is added to the SharePoint list*/
Public class OnPlantUpdated : IRemoteEventService
{
public SPRemoteEventResult ProcessEvent (SPRemoteEventProperties properties)
{
SPRemoteEventResult result =new SPRemoteEventResult();
If (properties.EventType == SPRemoteEventType.ItemAdding ||
properties.EventType == SPRemoteEventType.ItemUpdating)
{
// Add code that runs when an item is added or updated.
}
Para obter o exemplo de código completo, confira Adicionar propriedades do item da lista com um receptor de eventos remotos.
Para obter uma demonstração detalhada do exemplo de código, confira Migrar um receptor de eventos do SharePoint para um receptor de eventos remotos.
Para obter mais informações, confira Enumeração SPRemoteEventType
Como os receptores de eventos remotos funcionam?
A figura a seguir mostra como os receptores de eventos remotos funcionam:
O usuário executa uma ação no SharePoint (por exemplo, editar um item de lista).
O SharePoint então conversa com o serviço Web registrado. Você pode executar algumas operações (por exemplo, atualizar uma propriedade de item de lista ou atualizar um sistema de back-end).
O serviço da Web também pode conversar com o Serviço de Controle de Acesso (ACS) para solicitar seu próprio token assinado para fazer uma chamada de volta ao SharePoint. Usando esse token, você pode executar ações remotas no serviço Web como resultado da operação anterior no item da lista ou no sistema de back-end.
Como os receptores de eventos emote funcionam no SharePoint
Como posso depurar receptores de eventos remotos?
Confira Depurar e solucionar problemas de um receptor de eventos remotos em um Suplemento do SharePoint.
Posso executar código do lado do cliente (JavaScript) de receptores de eventos remotos?
Não, você não executar código do lado do cliente (JavaScript) de receptores de eventos remotos.
Há restrições sobre onde um receptor de eventos remotos pode ser hospedado em sua URL?
O receptor de eventos remotos pode ser hospedado na nuvem ou em um servidor local que também não esteja sendo usado como um servidor do SharePoint. A URL de um receptor de produção não pode especificar uma porta. Isso significa que você deve usar a porta 443 para HTTPS, que recomendamos, ou a porta 80 para HTTP. Se você estiver usando HTTPS e o serviço do receptor estiver hospedado no local, mas o suplemento estiver no SharePoint Online, o servidor de hospedagem deverá ter um certificado publicamente confiável de uma autoridade de certificação. (Um certificado autoassinado funciona somente se o suplemento estiver em um farm do SharePoint no local.)
Um manipulador de eventos do SharePoint 2010 funcionará no SharePoint após a atualização?
Se um pacote de solução do SharePoint 2010 contendo um manipulador de eventos for atualizado para o SharePoint, dependendo de suas personalizações, o pacote de solução poderá funcionar sem nenhuma modificação. Isso inclui também o manipulador de eventos. Se a solução do SharePoint 2010 for remodelada em um Suplemento do SharePoint no SharePoint, o manipulador de eventos deverá ser regravado como um receptor de eventos remotos. Confira Migrar um receptor de eventos do SharePoint para um receptor de eventos remotos.