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は ホストウェブ を使用してプログラム的に登録されます。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.

注意

このサンプルでは、​​Visual Studio用のOffice開発ツールによって生成された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アドインに追加され、リストアイテムイベントは、アドインWeb機能に含まれている受信者のElements.xmlファイルで参照されます。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サイトとしてSharePoint Onlineテナントを使用している場合)は、Microsoft Azure Service Busを使用してデバッグ用にプロジェクトを構成します。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.

      注意

      この記事が書かれた時点で、Visual Studio用のOffice Developer Toolsには、受信者の作成時に必要なすべてのアセンブリへの参照が含まれていましたが、それ以降のバージョンのツールには含まれない可能性があります。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 アドインが実行され、使用可能なリストのテーブルが表示されます。これには、 リスト1 が含まれます。Your SharePoint Add-in runs, and a table of available lists appears and includes List1.

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

  4. リストアイテムを取得する ボタンを選択します。Choose the Retrieve List Items button. 項目を含まない リスト1 が表示されます。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. リストID のGUID値 イベントログを選択し、さらにリストアイテムを取得する ボタンを選択します。Choose the ListID GUID value for EventLog, and then choose the Retrieve List Items button. リスト1 に項目を追加したときに発生した 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