Compartilhar via

Criar um receptor de eventos remotos em Suplementos do SharePoint

  • Artigo

É útil que você tenha inicialmente uma ideia sobre Suplementos do SharePoint hospedados pelo provedor e que você tenha desenvolvido alguns suplementos além do simples "Hello World". Consulte Começar a criar suplementos do SharePoint hospedados pelo provedor.

Além disso, você deve estar familiarizado com a Manipulação de eventos nos suplementos do SharePoint.

Criar um receptor de eventos remoto

Este artigo mostra como estender um Suplemento do SharePoint adicionando um RER (receptor de eventos remotos) que lida com o evento ItemAdded para uma lista personalizada na web do suplemento. O RER está registrado com a web do suplemento usando a marcação de declaração. Os RERs são registrados na web de hospedagem por programação. Para obter um exemplo do código para fazer isso, confira SharePoint/PnP/Samples/Core.EventReceivers.

Um RER deve ser um serviço web SOAP. A continuação do exemplo implementa isso como um serviço WCF (Windows Communication Foundation), mas é possível em princípio implementar um RER em uma pilha não Microsoft.

Para acompanhar este artigo e inserir o código por conta própria, baixe o exemplo de SharePoint-Add-in-CSOM-BasicDataOperations e abra o exemplo no Visual Studio.

Observação

O exemplo usa um arquivo TokenHelper.cs gerado pelo Office Developer Tools para Visual Studio. Essa era a versão atual quando o exemplo foi criado, mas pode não ser a versão mais recente quando você ler este artigo. O exemplo ainda é ótimo para criar seu primeiro RER. Quando estiver pronto para ir além, você deve examinar os exemplos apresentados no final deste artigo, na seção Confira também. Provavelmente eles têm mais chances de estarem atualizados.

Para registrar um receptor de eventos remotos

  1. Abra o projeto de Suplemento do SharePoint no Visual Studio.

  2. No Gerenciador de Soluções, selecione o nó do projeto de suplemento.

  3. Na barra de menus, selecione Projeto>Adicionar novo item.

  4. No painel Modelos instalados, selecione o nó Office/SharePoint.

  5. No painel Modelos, selecione o modelo Receptor de Eventos Remotos.

  6. Na caixa Nome, mantenha o nome padrão (RemoteEventReceiver1) e selecione Adicionar.

  7. Na lista Que tipo de receptor de eventos você deseja?, selecione Eventos de Item de Lista.

  8. Na lista Qual item deve ser a origem do evento?, selecione Lista Personalizada.

    A continuação do exemplo usa uma lista genérica personalizada. Porém, um RER também pode manipular eventos que ocorrem em listas do SharePoint padrão, como Comunicados ou Contatos.

  9. Na lista Manipule os seguintes eventos, selecione Um item está sendo adicionado e, em seguida, selecione Concluir.

    Um serviço Web é adicionado ao aplicativo Web para manipular o evento remoto que você especificou. Um receptor de eventos remotos é adicionado ao suplemento do SharePoint, e o evento de item de lista é referenciado no arquivo Elements.xml do receptor, que está contido no recurso da web de suplemento.

Para criar a lista

  1. No Gerenciador de Soluções, selecione o nó do projeto de suplemento.

  2. Na barra de menus, selecione Projeto>Adicionar novo item.

  3. No painel Modelos instalados, selecione o nó Office SharePoint.

  4. No painel Modelos, selecione o modelo Lista.

  5. Na caixa Nome, deixe o nome padrão (List1) e selecione Adicionar.

  6. Selecione Criar uma instância de lista com base em um modelo de lista existente, escolha Lista Personalizada na lista e, em seguida, selecione Concluir.

Para adicionar funcionalidade ao receptor de eventos remotos

  1. Se o seu farm de teste do SharePoint não estiver no mesmo computador que está executando o Visual Studio (ou se você estiver usando uma locatário do SharePoint Online como o site de teste do SharePoint), configure o projeto para depuração usando o Barramento de Serviço do Microsoft Azure. Para saber mais, confira Depurar e solucionar problemas com um receptor de eventos remotos em um Suplemento do SharePoint.

  2. No arquivo de código do serviço do receptor de eventos remotos (ou seja, RemoteEventReceiver1.svc.cs), substitua o conteúdo pelo código a seguir. Esse comando executa as seguintes tarefas:

    • Obtém um objeto de contexto de cliente válido.

    • Se uma lista EventLog ainda não existir, cria uma para conter os nomes dos eventos remotos que ocorrerem.

    • Adiciona uma entrada à lista do evento, incluindo um carimbo de data e hora.

    Observação

    No momento que este artigo foi escrito, as Ferramentas de Desenvolvedor do Office para Visual Studio faziam referências a todos os assemblies necessários para criar o receptor, mas pode ser que as versões posteriores das ferramentas não tenham. Se você receber erros do compilador, basta adicionar as referências ausentes; por exemplo, talvez seja necessário adicionar referências ao System.ServiceModel ou System.ComponentModel.DataAnnotations.

    using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Text;
using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.EventReceivers;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.ServiceModel.Channels;

namespace BasicDataOperationsWeb.Services
{
    public class RemoteEventReceiver1 : IRemoteEventService
    {
        public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
        {
            // When a "before" event occurs (such as ItemAdding), call the event 
            // receiver code.
            ListRemoteEventReceiver(properties);
            return new SPRemoteEventResult();
        }

        public void ProcessOneWayEvent(SPRemoteEventProperties properties)
        {
            // When an "after" event occurs (such as ItemAdded), call the event 
            // receiver code.            
        }

        public static void ListRemoteEventReceiver(SPRemoteEventProperties properties)
        {
            string logListTitle = "EventLog";

            // Return if the event is from the EventLog list itself. Otherwise, it may go into
            // an infinite loop.
            if (string.Equals(properties.ItemEventProperties.ListTitle, logListTitle, 
                StringComparison.OrdinalIgnoreCase))
                return;

            // Get the token from the request header.
            HttpRequestMessageProperty requestProperty = 
                (HttpRequestMessageProperty)OperationContext
                .Current.IncomingMessageProperties[HttpRequestMessageProperty.Name];
            string contextTokenString = requestProperty.Headers["X-SP-ContextToken"];

            // If there is a valid token, continue.
            if (contextTokenString != null)
            {
                SharePointContextToken contextToken =
                    TokenHelper.ReadAndValidateContextToken(contextTokenString, 
                        requestProperty.Headers[HttpRequestHeader.Host]);

                Uri sharepointUrl = new Uri(properties.ItemEventProperties.WebUrl);
                string accessToken = TokenHelper.GetAccessToken(contextToken, 
                                                    sharepointUrl.Authority).AccessToken;
                bool exists = false;

                // Retrieve the log list "EventLog" and add the name of the event that occurred
                // to it with a date/time stamp.
                using (ClientContext clientContext = 
                    TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), 
                                                                                                        accessToken))
                {
                    clientContext.Load(clientContext.Web);
                    clientContext.ExecuteQuery();
                    List logList = clientContext.Web.Lists.GetByTitle(logListTitle);

                    try
                    {
                        clientContext.Load(logList);
                        clientContext.ExecuteQuery();
                        exists = true;
                    }

                    catch (Microsoft.SharePoint.Client.ServerUnauthorizedAccessException)
                    {
                        // If the user doesn't have permissions to access the server that's 
                        // running SharePoint, return.
                        return;
                    }

                    catch (Microsoft.SharePoint.Client.ServerException)
                    {
                        // If an error occurs on the server that's running SharePoint, return.
                        exists = false;
                    }

                    // Create a log list called "EventLog" if it doesn't already exist.
                    if (!exists)
                    {
                        ListCreationInformation listInfo = new ListCreationInformation();
                        listInfo.Title = logListTitle;
                        // Create a generic custom list.
                        listInfo.TemplateType = 100;
                        clientContext.Web.Lists.Add(listInfo);
                        clientContext.Web.Context.ExecuteQuery();
                    }

                    // Add the event entry to the EventLog list.
                    string itemTitle = "Event: " + properties.EventType.ToString() + 
                        " occurred on: " + 
                        DateTime.Now.ToString(" yyyy/MM/dd/HH:mm:ss:fffffff");
                    ListCollection lists = clientContext.Web.Lists;
                    List selectedList = lists.GetByTitle(logListTitle);
                    clientContext.Load<ListCollection>(lists);
                    clientContext.Load<List>(selectedList);
                    ListItemCreationInformation listItemCreationInfo = 
                        new ListItemCreationInformation();
                    var listItem = selectedList.AddItem(listItemCreationInfo);
                    listItem["Title"] = itemTitle;
                    listItem.Update();
                    clientContext.ExecuteQuery();
                }
            }
        }
    }
}

  3. Em Home.aspx.cs, altere todas as instâncias de SPHostUrl para SPAppWebUrl.

    Por exemplo, sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]); deve ser alterada para sharepointUrl = new Uri(Request.QueryString["SPAppWebUrl"]);.

Executar e testar o manipulador de eventos

Teste seu manipulador com o procedimento a seguir.

  1. Selecione a tecla F5 para executar o projeto.

  2. Confie no suplemento quando solicitado a fazê-lo. O suplemento do SharePoint é executado, e uma tabela de listas disponíveis é exibida com List1.

  3. Selecione a ID de List1. Essa ID é copiada para a caixa Recuperar Itens de Lista.

  4. Selecione o botão Recuperar Itens de Lista. List1 aparece sem itens.

  5. Na caixa Adicionar Item, especifique o Primeiro item e depois selecione o botão Adicionar Item. Um item de lista chamado de Primeiro Item é adicionado a List1, fazendo com que o receptor de eventos remotos seja disparado e adicione uma entrada à lista EventLog.

  6. Selecione o botão Atualizar Listas para retornar à tabela de listas. Na tabela, uma nova lista denominada EventLog é exibida.

  7. Selecione o valor de GUID ListID para EventLog e depois selecione o botão Recuperar Itens de Lista. Uma tabela para EventLog aparece com uma entrada para o evento Handle ItemAdding, que ocorreu quando você adicionou o item a List1.

Adicionar ou remover manipuladores de eventos usando o Visual Studio

  1. No Gerenciador de Soluções, selecione o nó do projeto para o receptor de eventos remotos.

  2. No painel Propriedades, defina as propriedades dos eventos que você deseja manipular como True.

    Por exemplo, se quiser responder sempre que um usuário adicionar um item de lista, defina o valor da propriedade Handle ItemAdding como True. Se não quer manipular esse evento, defina o valor dessa propriedade como False.

    Eventos remotos do SharePoint no Visual Studio

    Eventos remotos do SharePoint no Visual Studio

  3. Se você tiver adicionado um evento, adicione o código de manipulação de evento ao arquivo de código do serviço Web, exatamente como foi feito com os eventos anteriores.

    Para lidar com um tipo diferente de evento, adicione outro receptor de eventos remoto no Suplemento do SharePoint. Por exemplo, se um receptor de eventos remoto manipula os eventos de item de lista, você pode adicionar outro evento de item de lista a ele. Mas você deve adicionar outro receptor de eventos remoto para manipular os eventos de lista.

Restrições de URL e hospedagem para receptores de eventos remotos de produção

O receptor de eventos remoto pode ser hospedado na nuvem ou em um servidor local que também não está 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.)

Confira também