Usar receptores de eventos remotos no SharePoint
Usar receptores de eventos remotos para manipular eventos no modelo de Suplemento do SharePoint. Use os eventos AppInstalled e AppUninstalling para definir ou remover objetos do SharePoint e outros receptores de eventos de que seu suplemento precise.
Aplica-se a: suplementos do SharePoint | SharePoint 2013 | SharePoint Online
Importante Desde janeiro de 2017, o SharePoint Online oferece suporte a webhooks de lista que podem ser usados no lugar dos receptores de eventos remoto "-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.
O exemplo Core.EventReceivers mostra como usar um suplemento hospedado pelo provedor com um receptor de eventos remoto para lidar com os eventos AppInstalled e AppUninstalling. Os eventos AppInstalled e AppUninstalling configuram e removem objetos do SharePoint que o suplemento usa quando é executado. Além disso, o manipulador de eventos AppInstalled adiciona o manipulador de eventos ItemAdded a uma lista. Use esta solução se desejar:
- Configure o seu complemento na primeira execução usando o evento AppInstalled para configurar vários objetos do SharePoint ou receptores de eventos adicionais com os quais o seu suplemento trabalha.
- Substitua os receptores de eventos implementados usando soluções de código totalmente confiáveis. Em soluções de código totalmente confiáveis, você pode executar receptores de eventos no servidor do SharePoint. No novo modelo de Suplemento do SharePoint, como você não pode executar o receptor de eventos no servidor do SharePoint, é necessário implementar um receptor de eventos remoto em um servidor da web.
- Receba notificações de alterações que ocorrem no SharePoint. Por exemplo, quando um novo item é adicionado a uma lista, você deseja executar uma tarefa.
- Complemente sua solução de log de alterações. Usar o padrão de receptor de eventos remoto com um padrão de log de alterações fornece uma arquitetura mais confiável para lidar com todas as alterações feitas nos bancos de dados de conteúdo, conjuntos de sites, sites ou listas do SharePoint. Os receptores de eventos remotos são executados imediatamente, mas como funcionam em um servidor remoto, pode haver falha na comunicação. O padrão de log de alteração garante que todas as alterações fiquem disponíveis para processamento, mas o aplicativo que processa as alterações geralmente é executado de acordo com uma programação (por exemplo, um trabalho de timer). Isso significa que as alterações não são processadas imediatamente. Se usar esses dois padrões juntos, você garante que estará usando um mecanismo para impedir o processamento da mesma alteração duas vezes. Para obter mais informações, consulte Consultar o log de alterações do SharePoint com ChangeQuery e ChangeToken.
Observação
Os suplementos hospedados no SharePoint não oferecem suporte a receptores de eventos remotos. Para usar receptores de eventos remotos, você precisa usar um suplemento hospedado pelo provedor. Você não deve usar receptores de eventos remotos para cenários de sincronização ou para processos de longa execução. Para obter mais informações, consulte Como criar um receptor de evento de suplemento.
Antes de começar
Para começar, baixe o suplemento de exemplo Core.EventReceivers do projeto de padrões e práticas do desenvolvedor Office 365 no GitHub.
Antes de executar este exemplo de código, faça o seguinte:
Nas propriedades do projeto Core.EventReceivers, verifique se Manipular Aplicativo Instalado e Manipular Desinstalação de Aplicativo está definido como True. A configuração Desinstalar o aplicativo instalado e manipular a desinstalação do aplicativo para True cria um serviço WCF que define o manipulador de eventos para o evento AppInstalled e AppUninstalling. Em Core.EventReceivers, abra o menu de atalho (clique com o botão direito do mouse) em AppManifest.xml e escolha Propriedades. O ponto InstalledEventEndpoint e UninstallingEventEndpoint para o receptor de eventos remoto que manipula os eventos AppInstalled e AppUninstalling .
Anexar um receptor de eventos remoto a um objeto na Web do host geralmente requer a permissão Gerenciar somente para esse objeto. Por exemplo, ao anexar um receptor de eventos a uma lista existente, o suplemento requer a permissão Gerenciar somente na Lista. Este exemplo de código requer permissões Gerenciar na Web porque ele adiciona uma lista e ativa um recurso na web de host. Para definir gerenciar permissões na web:
Clique duas vezes em Core.EventReceivers\AppManifest.xml.
Escolha Permissões.
Verifique se o Escopo está definido como Web e a permissão está definida como Gerenciar.
Para executar este exemplo de código, você precisa de uma assinatura do Azure. Para solicitar uma avaliação, confira Avaliação gratuita de um mês.
Crie um Namespace de Barramento de Serviço do Azure.
Siga as instruções em Criar um namespace de Barramento de Serviço.
Copie Cadeia de Conexão Primária do Namespace de Barramento de Serviço recém-criado
Volte para o Visual Studio.
Clique com o botão direito do mouse em Propriedades> Core.EventReceivers >SharePoint.
Selecione Habilitar depuração por meio de Barramento de Serviço do Microsoft Azure.
Em Barramento de Serviço do Microsoft Azure cadeia de conexão, cole a Cadeia de Conexão.
Escolha Salvar.
Execute o código de exemplo e execute as seguintes etapas adicionais:
Clique em Confiar nele na janela Conceder permissões para o aplicativo .
Feche as permissões de concessão para a janela do aplicativo .
Quando a instalação do suplemento e do serviço WCF for concluída, o navegador será aberto.
Faça logon em seu site do Office 365. A página inicial do suplemento Core.EventReceivers é exibida.
Use o suplemento Core.EventReceivers
Para ver uma demonstração do exemplo de código Core.EventReceivers:
Execute o exemplo e, na página inicial, escolha Voltar para Site.
Escolha Conteúdo do Site.
Escolha Trabalhos de Receptor de Eventos Remotos.
Escolha novo item.
Em Título, insira Contoso e, em Descrição, insirao teste Contoso.
Volte para a lista e atualize a página.
Verifique se a descrição do item recém-adicionado foi atualizada para o teste Contoso Atualizado pelo ReR 192336, em que 192336 é um carimbo de data/hora.
Em Services/AppEventReceiver.cs, AppEventReceiver implementa a interface IRemoteEventService . Este código fornece uma implementação para o método ProcessEvent porque ele usa eventos síncronos. Se você usar eventos assíncronos, precisará fornecer uma implementação para o método ProcessOneWayEvent.
O ProcessEvent manipula os seguintes eventos remotos SPRemoteEventType :
Eventos AppInstalled ao instalar o suplemento. Quando ocorre um evento AppInstalled, o ProcessEvent chama o HandleAppInstalled.
Eventos AppUninstalling ao desinstalar o suplemento. Quando um evento AppUninstalling ocorre, o ProcessEvent chama o HandleAppUninstalling. O evento AppUninstalling só é executado quando um usuário remove completamente o suplemento excluindo o suplemento da lixeira do site (para usuários finais) ou removendo o suplemento dos Aplicativos na lista de testes (para desenvolvedores).
Eventos ItemAdded quando um item é adicionado a uma lista. Quando ocorre um evento ItemAdded, o ProcessEvent chama o HandleItemAdded.
Observação
Nas propriedades do projeto Core.EventReceiver, apenas as propriedades Manipular Aplicativo Instalado e Manipular Desinstalação de Aplicativos estão disponíveis. Este exemplo de código mostra como você pode adicionar o manipulador de eventos ItemAdded a uma lista na web de host usando o evento AppInstalled durante a instalação do suplemento.
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.
public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
{
SPRemoteEventResult result = new SPRemoteEventResult();
switch (properties.EventType)
{
case SPRemoteEventType.AppInstalled:
HandleAppInstalled(properties);
break;
case SPRemoteEventType.AppUninstalling:
HandleAppUninstalling(properties);
break;
case SPRemoteEventType.ItemAdded:
HandleItemAdded(properties);
break;
}
return result;
}
O HandleAppInstalled chama o RemoteEventReceiverManager.AssociateRemoteEventsToHostWeb em RemoteEventReceiverManager.cs.
private void HandleAppInstalled(SPRemoteEventProperties properties)
{
using (ClientContext clientContext =
TokenHelper.CreateAppEventClientContext(properties, false))
{
if (clientContext != null)
{
new RemoteEventReceiverManager().AssociateRemoteEventsToHostWeb(clientContext);
}
}
}
O AssociateRemoteEventsToHostWeb cria ou ativa vários objetos do SharePoint que o suplemento Core.EventReceivers usa. Seus requisitos podem ser diferentes. O AssociateRemoteEventsToHostWeb faz o seguinte:
Habilita o recurso de Notificação por Push usando Web.Features.Add.
Usa o objeto clientContext para pesquisar uma lista. Se a lista não existir, o CreateJobsList criará a lista. Se a lista existir, o List.EventReceivers será usado para procurar um receptor de evento existente cujo nome seja ItemAddedEvent.
Se o receptor de eventos ItemAddedEvent não existir:
Instancia um novo objeto EventReceiverDefinitionCreationInformation para criar o novo receptor de eventos remoto. O tipo de receptor de evento ItemAdded é adicionado ao EventReceiverDefinitionCreationInformation.EventType.
Define o EventReceiverDefinitionCreationInformation.ReceiverURL como a URL do receptor de eventos remotos AppInstalled .
Adiciona um novo receptor de eventos à lista usando List.EventReceivers.Add.
public void AssociateRemoteEventsToHostWeb(ClientContext clientContext)
{
// Add Push Notification feature to host web.
// Not required but it is included here to show you
// how to activate features.
clientContext.Web.Features.Add(
new Guid("41e1d4bf-b1a2-47f7-ab80-d5d6cbba3092"),
true, FeatureDefinitionScope.None);
// Get the Title and EventReceivers lists.
clientContext.Load(clientContext.Web.Lists,
lists => lists.Include(
list => list.Title,
list => list.EventReceivers).Where
(list => list.Title == LIST_TITLE));
clientContext.ExecuteQuery();
List jobsList = clientContext.Web.Lists.FirstOrDefault();
bool rerExists = false;
if (null == jobsList)
{
// List does not exist, create it.
jobsList = CreateJobsList(clientContext);
}
else
{
foreach (var rer in jobsList.EventReceivers)
{
if (rer.ReceiverName == RECEIVER_NAME)
{
rerExists = true;
System.Diagnostics.Trace.WriteLine("Found existing ItemAdded receiver at "
+ rer.ReceiverUrl);
}
}
}
if (!rerExists)
{
EventReceiverDefinitionCreationInformation receiver =
new EventReceiverDefinitionCreationInformation();
receiver.EventType = EventReceiverType.ItemAdded;
// Get WCF URL where this message was handled.
OperationContext op = OperationContext.Current;
Message msg = op.RequestContext.RequestMessage;
receiver.ReceiverUrl = msg.Headers.To.ToString();
receiver.ReceiverName = RECEIVER_NAME;
receiver.Synchronization = EventReceiverSynchronization.Synchronous;
// Add the new event receiver to a list in the host web.
jobsList.EventReceivers.Add(receiver);
clientContext.ExecuteQuery();
System.Diagnostics.Trace.WriteLine("Added ItemAdded receiver at " + receiver.ReceiverUrl);
}
}
Quando um item é adicionado à lista Trabalhos do Receptor de Eventos Remotos , ProcessEvent em AppEventReceiver.svc.cs manipula o evento ItemAdded e, em seguida, chama HandleItemAdded. O HandleItemAdded chama o RemoteEventReceiverManager.ItemAddedToListEventHandler. O ItemAddedToListEventHandler busca o item da lista que foi adicionado e adiciona a cadeia de caracteres Atualizado pelo ReR à descrição do item da lista.
public void ItemAddedToListEventHandler(ClientContext clientContext, Guid listId, int listItemId)
{
try
{
List photos = clientContext.Web.Lists.GetById(listId);
ListItem item = photos.GetItemById(listItemId);
clientContext.Load(item);
clientContext.ExecuteQuery();
item["Description"] += "\nUpdated by RER " +
System.DateTime.Now.ToLongTimeString();
item.Update();
clientContext.ExecuteQuery();
}
catch (Exception oops)
{
System.Diagnostics.Trace.WriteLine(oops.Message);
}
}