SharePoint アドインでリモート イベント レシーバーを作成するCreate a remote event receiver in SharePoint Add-ins

事前にプロバイダー向けのホスト型 SharePoint アドインについて理解していること、少なくとも "Hello World" レベル以上のものを開発した経験があると助けになります。It is helpful if you first have an understanding of provider-hosted SharePoint Add-ins, and for you to have developed a few that go a least a little beyond the "Hello World" level. Also, you should be familiar with Handle events in SharePoint Add-ins. プロバイダー向けのホスト型 SharePoint アドインの作成を始める」を参照してください。See Get started creating provider-hosted SharePoint Add-ins.

また、SharePoint アドインのイベントの処理に精通している必要もあります。Also, you should be familiar with Handle events in SharePoint Add-ins.

リモート イベント レシーバーを作成するCreate a remote event receiver

この記事では、アドイン Web 内でカスタム リストの ItemAdded イベントを処理するリモート イベント レシーバー (RER) を追加して SharePoint アドインを拡張する方法を示しています。This article shows how you extend a SharePoint Add-in by adding a remote event receiver (RER) that handles the ItemAdded event for a custom list in the add-in web. The RER is registered with the add-in web using declarative markup. RERs are registered with the host web programmatically. For a code sample that does so, see OfficeDev/PnP/Samples/Core.EventReceivers. RER は宣言型マークアップを使用してアドイン Web に登録されます。The RER is registered with the add-in web using declarative markup. RER はプログラムを使用してホスト Web に登録されます。RERs are registered with the host web programmatically. それを行うコード サンプルについては、SharePoint/PnP/Samples/Core.EventReceivers をご覧ください。For a code sample that does so, see SharePoint/PnP/Samples/Core.EventReceivers.

RER は SOAP Web サービスにする必要があります。An RER must be a SOAP web service. 継続して用いられている例では、Windows Communication Foundation (WCF) サービスとして実装していますが、基本的には RER を Microsoft 以外のスタックに実装することが可能です。An RER must be a SOAP web service. The continuing example implements this as a Windows Communication Foundation (WCF) service; but it is possible in principle to implement an RER on a non-Microsoft stack.

この記事の内容に沿って自分でコードを入力する場合は、「 SharePoint-Add-in-CSOM-BasicDataOperations」のサンプルをダウンロードしてから、Visual Studio で開きます。To follow along with this article and enter the code yourself, download the sample from SharePoint-Add-in-CSOM-BasicDataOperations, and then open the sample in Visual Studio.

注意

このサンプルでは、Office Developer Tools for Visual Studio によって生成される TokenHelper.cs ファイルを使用します。It uses the TokenHelper.cs file that is generated by the Office Developer Tools for Visual Studio. このサンプルを作成する時点では最新バージョンでしたが、この資料をお読みになる時点では最新バージョンではない可能性もあります。It was the current version when the sample was created, but may not be the most recent version when you read this. しかし、このサンプルは、初めて RER を作成する際に非常に参考になります。The sample is still great for creating your first RER. さらに先に進む用意ができたら、この記事の末尾にある「関連項目」セクションに記載されているサンプルを参照してください。But when you are ready to move beyond that, you should look at the samples listed in the See also section at the end of this article. そこに記載されているサンプルがおそらく最新です。They are more likely to be kept up to date.

リモート イベント レシーバーを登録するにはTo register a remote event receiver

  1. Visual Studio で SharePoint アドイン プロジェクトを開きます。Open the SharePoint Add-in project in Visual Studio.

  2. ソリューション エクスプローラーで、アドイン プロジェクトのノードを選択します。In Solution Explorer select the add-in project's node.

  3. メニュー バーで、[プロジェクト] > [新しい項目の追加] の順に選択します。On the menu bar, select Project > Add New Item.

  4. [インストールされたテンプレート] ウィンドウで、[Office/ SharePoint] ノードを選択します。In the Installed Templates pane, choose the Office/ SharePoint node.

  5. [テンプレート] ウィンドウで、[リモート イベント レシーバー] テンプレートを選択します。In the Templates pane, choose the Remote Event Receiver template.

  6. [名前] ボックスは既定の名前 (RemoteEventReceiver1) のままにし、[追加] を選択します。In the Name box, keep the default name (RemoteEventReceiver1), and then choose the Add button.

  7. [使用するイベント レシーバーの種類] ボックスの一覧で、[リスト項目イベント] を選択します。In the What type of event receiver do you want? list, choose List Item Events.

  8. [イベント ソースとなる項目] の一覧で、[カスタム リスト] を選択します。In the What Item should be the event source? list, select Custom List.

    この記事の例では、カスタム ジェネリック リストを使用しています。ただし、RER は [ お知らせ] や [ 連絡先] などの標準の SharePoint リストで発生するイベントも処理できます。The continuing example uses a custom generic list. But an RER can also handle events that occur in standard SharePoint lists, such as Announcements or Contacts.

  9. [次のイベントを処理] リストで、[項目が追加されています] を選択し、[完了] を選択します。In the Handle the following events list, choose An item is being added, and then choose the Finish button.

    Web サービスが、指定したリモート イベントを処理する Web アプリケーションに追加されます。A web service is added to the web application to handle the remote event that you specified. リモート イベント レシーバーは SharePoint アドインに追加され、リスト項目イベントはレシーバーの Elements.xml ファイル (アドイン Web 機能に含まれます) で参照されます。A web service is added to the web application to handle the remote event that you specified. A remote event receiver is added to the SharePoint Add-in and the list item event is referenced in the receiver's Elements.xml file that is itself contained in the add-in web Feature.

リストを作成するにはTo create the list

  1. ソリューション エクスプローラーで、アドイン プロジェクトのノードを選択します。In Solution Explorer select the add-in project's node.

  2. メニュー バーで、[プロジェクト] > [新しい項目の追加] の順に選択します。On the menu bar, select Project > Add New Item.

  3. [インストールされたテンプレート] ウィンドウで、[Office SharePoint] ノードを選択します。In the Installed Templates pane, choose the Office SharePoint node.

  4. [テンプレート] ウィンドウで、[リスト] テンプレートを選択します。In the Templates pane, choose the List template.

  5. [名前] ボックスは既定の名前 (List1) のままにし、[追加] を選択します。In the Name box, leave the default name (List1), and then choose the Add button.

  6. [既存のリスト テンプレートに基づくリスト インスタンスを作成]、リストの [カスタム リスト][完了] の順に選択します。Choose the Create a list instance based on an existing list template option button, choose Custom List in the list, and then choose the Finish button.

リモート イベント レシーバーに機能を追加するにはTo add functionality to the remote event receiver

  1. SharePoint テスト ファームが Visual Studio が実行されているのと同じコンピューター上にない場合 (または SharePoint Online テナンシーを SharePoint テスト サイトとして使用している場合) には、Microsoft Azure サービス バスを使用してデバッグを行うようにプロジェクトを構成します。If your test SharePoint farm is not on the same computer that is running Visual Studio, (or you are using an SharePoint Online tenancy as your test SharePoint site), configure the project for debugging using the Microsoft Azure Service Bus. For more information, see the Debug and troubleshoot a remote event receiver in a SharePoint Add-in. 詳しくは、「SharePoint アドインでのリモート イベント レシーバーのデバッグとトラブルシューティング」を参照してください。Follow the instructions at Debug and troubleshoot a remote event receiver in a SharePoint Add-in.

  2. リモート イベント レシーバーのサービスのコード ファイル (RemoteEventReceiver1.svc.cs) で、コンテンツを次のコードで置き換えます。In the code file for the service of the remote event receiver (that is, RemoteEventReceiver1.svc.cs), replace the contents with the following code. このコードでは、次のタスクを実行します。This code performs the following tasks:

    • 有効なクライアント コンテキスト オブジェクトを取得します。Gets a valid client context object.

    • EventLog という名前のリストが存在しない場合は、発生するリモート イベントの名前が含まれるリストを作成します。If a list that's named EventLog doesn't already exist, creates one to contain the names of the remote events that occur.

    • 日時のタイム スタンプを含むイベントのエントリをリストに追加します。Adds an entry to the list for the event, including a time and date stamp.

      注意

      この記事が書かれた時点では、レシーバーが作成されると Office Developer Tools for Visual Studio によって、必要なアセンブリすべてへの参照が追加されましたが、以降のバージョンのツールではこうした処理が実行されない可能性があります。Note At the time this article was written the Office Developer Tools for Visual Studio add references to all the needed assemblies when the receiver is created, but later versions of the tools may not. If you get compiler errors, simply add the missing references; for example, you may need to add references to System.ServiceModel or System.ComponentModel.DataAnnotations. コンパイル エラーが発生する場合には、欠落している参照を追加します。たとえば、System.ServiceModel または System.ComponentModel.DataAnnotations への参照の追加が必要になる場合があります。At the time this article was written the vstoshort add references to all the needed assemblies when the receiver is created, but later versions of the tools may not. If you get compiler errors, simply add the missing references; for example, you may need to add references to System.ServiceModel or 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. Home.aspx.cs で、SPHostUrl のすべてのインスタンスを SPAppWebUrl に変更します。In Home.aspx.cs, change all instances of SPHostUrl to SPAppWebUrl.

    たとえば、sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);sharepointUrl = new Uri(Request.QueryString["SPAppWebUrl"]); に変更します。For example, sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]); should be changed to sharepointUrl = new Uri(Request.QueryString["SPAppWebUrl"]);.

イベント ハンドラーを実行およびテストするRun and test the event handler

次に示す手順で、ハンドラーをテストします。Test your handler with the following procedure.

  1. F5 キーを選択してプロジェクトを実行します。Choose the F5 key to run the project.

  2. アドインを信頼するように指示するプロンプトが表示されたら、それに従います。Trust the add-in when prompted to do so. SharePoint アドインが実行され、使用可能なリストの表が表示されます。これには、List1 が含まれます。Your SharePoint Add-in runs, and a table of available lists appears and includes List1.

  3. List1 の ID を選択します。Choose the ID of List1. その ID は [リスト項目を取得] ボックスにコピーされます。That ID is copied to the Retrieve List Items box.

  4. [リスト項目を取得] ボタンを選択します。Choose the Retrieve List Items button. 項目を含まない List1 が表示されます。List1 appears with no items in it.

  5. [項目の追加] ボックスで「最初の項目」を指定し、[項目の追加] ボタンを選択します。In the Add Item box, specifyFirst Item, and then choose the Add Item button. [ 最初の項目] という名前のリスト項目が List1 に追加され、これによってリモート イベント レシーバーが起動し、EventLog リストにエントリが追加されます。A list item that's named First Item is added to List1, which causes the remote event receiver to fire and add an entry to the EventLog list.

  6. [リストの更新] ボタンを選択してリストの表に戻ります。Choose the Refresh Lists button to return to the table of lists. 表には、EventLog という名前の新しいリストが表示されます。In the table, a new list that's named EventLog appears.

  7. EventLogListID GUID 値を選択し、[リスト項目を取得] ボタンを選択します。Choose the ListID GUID value for EventLog, and then choose the Retrieve List Items button. List1 に項目を追加したときに発生した Handle ItemAdding イベントのエントリを含む EventLog の表が表示されます。A table for EventLog appears with an entry for the Handle ItemAdding event that occurred when you added the item to List1.

Visual Studio を使用してイベント ハンドラーを追加または削除するAdd or remove event handlers using Visual Studio

  1. ソリューション エクスプローラーで、リモート イベント レシーバーのプロジェクト ノードを選択します。In Solution Explorer, choose the project node for the remote event receiver.

  2. [プロパティ] ウィンドウで、処理するイベントのプロパティを True に設定します。In the Properties pane, set the properties for the events that you want to handle to True.

    たとえば、ユーザーがリスト項目を追加したときに応答するには、 Handle ItemAdding プロパティの値を True に設定します。そのイベントを処理しないようにするには、そのプロパティの値を False に設定します。For example, if you want to respond whenever a user adds a list item, set the value of the Handle ItemAdding property to True. If you don't want to handle that event, set the value of that property to False.

    Visual Studio での SharePoint リモート イベントSharePoint remote events in Visual Studio

    Visual Studio での SharePoint リモート イベント

  3. イベントを追加した場合は、前のイベントで追加したのと同様に、コード ファイルにイベント処理コードを追加します。If you added an event, add the event-handling code to the code file for the web service as you did with previous events.

    別の種類のイベントを処理するには、別のリモート イベント レシーバーを SharePoint アドインに追加します。たとえば、あるリモート イベント レシーバーでリスト項目イベントを処理する場合、そのレシーバーに別のリスト項目イベントを追加できます。ただし、リスト イベントを処理するには、別のリモート イベント レシーバーを追加する必要があります。To handle a different type of event, add another remote event receiver to the SharePoint Add-in. For example, if a remote event receiver handles list item events, you can add another list item event to it. But you must add another remote event receiver if you want to handle list events.

運用環境のリモート レシーバー イベントの URL とホストの制限URL and hosting restrictions for production remote event receivers

このリモート イベント レシーバーは、クラウドか、オンプレミス サーバー (SharePoint サーバーとしても使用されているものは除く) でホストできます。The remote event receiver can be hosted in the cloud or on an on-premises server that is not also being used as a SharePoint server. 運用環境のレシーバー URL で特定のポートを指定することはできません。The URL of a production receiver cannot specify a particular port. つまり、HTTPS のポート 443 (推奨) と HTTP のポート 80 のいずれかを使用する必要があります。SharePoint requires that there be no explicit port in the URL of the handler in production. This means that you must use either port 443 for HTTPS, which we recommend, or port 80 for HTTP. HTTPS を使用し、レシーバー サービスがオンプレミスでホストされ、アドインが SharePoint Online 上にある場合、ホスティング サーバーには、証明機関からの公的に信頼された証明書が必要となります。If you are using HTTPS and the receiver service is hosted on-premises, but the add-in is on SharePoint Online, the hosting server must have a publicly trusted certificate from a certificate authority. (自己署名証明書が有効になるのは、アドインがオンプレミスの SharePoint ファームにある場合のみです。)(A self-signed certificate works only if the add-in is on an on-premises SharePoint farm.)

関連項目See also