Partilhar via

Receptores de eventos e receptores de lista de eventos no modelo de suplemento do SharePoint

  • Artigo

A abordagem usada para manipular eventos no SharePoint é diferente no novo modelo de Suplemento do SharePoint do que era com o código de confiança total.

Em um cenário típico de Solução de Farm/Código de Confiança Total (FTC), os receptores de eventos e os Receptores de Lista de Eventos foram criados com o Microsoft Office SharePoint Online

Código do Modelo de Objeto do Lado do Servidor e implantado por meio de Soluções. Neste cenário, o código do receptor de eventos é executado no servidor do SharePoint.

Em um cenário de modelo de Suplemento do SharePoint, receptores de evento são criados fora do SharePoint em um serviço Web e registrados no SharePoint. Eles são chamados de Receptores de evento remoto (RER). Neste cenário, o código do receptor de eventos é executado no servidor Web em que o serviço Web está hospedado.

Importante

Em janeiro de 2017, o Microsoft Office SharePoint Online oferece suporte a webhooks de lista que você pode usar em vez de receptores de eventos remotos "-ed". Confira Visão geral dos webhooks do Microsoft Office SharePoint Online para saber mais sobre os webhooks. Além disso, vários exemplos de webhook estão disponíveis no repositório do GitHub sp-dev-samples.

Diretrizes de alto nível

Como boa prática, gostaríamos de fornecer as seguintes diretrizes gerais para a criação de receptores de eventos.

  • O ponto de extremidade de serviço que implementa um destinatário de evento deve ser acessível por usuários anônimos.
  • Receptores de eventos adicionados ao suplemento Web permitem retornar um token de acesso.
  • Receptores de eventos adicionados ao host Web retornarão um token de acesso se forem aplicados a partir do contexto do aplicativo usando o token de acesso ao aplicativo e as operações no host Web forem controladas pelo usuário final (ItemAdded etc.)
  • O evento AppInstalled deve ser concluído dentro de 30 segundos ou o SharePoint considerará que ele falhou. O SharePoint executará o evento novamente três vezes e, após a quarta execução, considerará que a instalação do suplemento falhou
  • Eventos normais, como ItemAdded, também têm tempo limite de 30 segundos, mas não há mecanismo de nova tentativa
  • Receptores de eventos adicionados ao host Web sem contexto de aplicativo, por exemplo, com SharePointOnlineCredentials ou outros meios, não retornam um token de acesso, e será necessário acessar o host Web com o token de acesso somente de aplicativo
  • Há suporte para a adição de receptores de eventos no host Web.
    • É possível fazer isso por meio de APIs CSOM/REST, e não usando assistentes do Visual Studio.
  • O SharePoint certamente chamará os pontos de extremidade de receptor de evento configurados para determinado evento. No entanto, não há garantia de que o código dos pontos de extremidade de receptor de evento serão executados, pois o código não é executado no servidor do SharePoint.

Por exemplo:

Se a URL do ponto de extremidade do receptor de evento não estiver disponível, o código do receptor de evento não será executado. A URL pode estar indisponível por vários motivos. Entre as causas mais comuns estão um erro de configuração quando a URL do ponto de extremidade é registrada, problemas de DNS ao tentar resolver a URL ou o site que hospeda o ponto de extremidade está desativado ou em um estado inoperante.

Além disso, se houver um bug de código do receptor de evento mal escrito, não será possível notificar o SharePoint sobre isso, e o evento será executado novamente. Você pode contornar isso de certa maneira com receptores de evento anexados a listas do SharePoint. Veja mais informações sobre esse método abaixo.

  • Quando um receptor de evento executa uma quantidade significativa de código, um padrão assíncrono deve ser usado.
  • Confira o seguinte artigo do MSDN para saber mais sobre tempos limite de receptores de evento. (Pesquise tempo limite no artigo.) Manipular eventos em suplementos para SharePoint (artigo MSDN)
  • Quando os receptores de eventos operam nas listas do SharePoint, recomendamos o uso de um mecanismo de rastreamento de alterações específico junto com o receptor de evento para garantir um processamento de maior qualidade.

Depuração de receptores de evento

É preciso definir algumas configurações no Azure e no Visual Studio para depurar receptores de evento. O artigo a seguir fornece instruções passo a passo e mais informações relacionadas à depuração.

Mais exemplos

  • Core.EventReceivers (exemplo O365 PnP)
    • Este exemplo mostra como um Suplemento do SharePoint pode usar o evento App Installed para realizar trabalho adicional no host da Web, como anexar receptores de evento a listas do host da Web.
  • Core.AppEvents.HandlerDelegation (amostra O365 PnP)
    • Este exemplo mostra como implementar manipuladores nos eventos AppInstalled e AppUninstalling que:
      1. Incorporem a lógica de reversão caso o manipulador encontre um erro.
      2. Incorporem uma lógica “pronta” para aceitar o fato de que o SharePoint tentará usar o manipulador até três vezes mais se ele falhar ou levar mais de 30 segundos para ser concluído.
      3. Use a estratégia de delegação do manipulador para minimizar chamadas do serviço Web do manipulador para o SharePoint.
      4. Use as classes CSOM ExceptionHandlingScope e ConditionalScope.
  • Core.AppEvents (exemplo O365 PnP)
    • Este exemplo mostra como implementar manipuladores nos eventos AppInstalled e AppUninstalling que:
      1. Incorporem a lógica de reversão caso o manipulador encontre um erro.
      2. Incorporem uma lógica “pronta” para aceitar o fato de que o SharePoint tentará usar o manipulador até três vezes mais se ele falhar ou levar mais de 30 segundos para ser concluído.

Exemplos de PnP

Aplicável a

  • Office 365 Multilocatário (MT)
  • Office 365 dedicado (D)
  • SharePoint 2013 local