SharePoint アドインのイベントを処理する

カスタム コードによって、プロバイダー向けのホスト型アドインにおける次の 3 つのカテゴリのイベントを処理できます。

• リスト イベント。Web サイト上におけるリストの追加、削除など。
• リスト項目イベント。リスト内の項目の編集など。
• アドイン イベント。アドインのインストールなど。

SharePoint ホスト型の SharePoint アドインではイベント処理をサポートしていませんが、ワークフローをトリガーするようにイベントを設定することにより、ワークフローを一種のリストまたはリスト項目のイベント ハンドラーに転換することができます。 詳細については、「SharePoint のワークフロー」を参照してください。 ワークフローはアドイン イベントではトリガーできないため、アドイン イベントは SharePoint ホスト型アドインでは処理できません。

以下の 2 種類のイベントがあります。

• before イベントは、SharePoint インフラストラクチャがそれ自体の任意のイベント (コンテンツ データベースへの変更の確定など) を処理する前にトリガーされます。 SharePoint では、カスタムの before イベント ハンドラーは常に同期的に実行されます。 主な目的として、それらはイベントのキャンセルに使用できます。 たとえば、アドインにリストの削除機能がある場合、イベントを削除するリストのハンドラーは、特定の条件が適合しない場合に削除をキャンセルすることができます。 イベントが一連のイベントの一部である場合、キャンセルするとその後のイベントがすべて妨げられます。 たとえば、ItemAdding イベントのハンドラーがイベントをキャンセルすると、通常はその後に発生する ItemAdded イベントはトリガーされません。

• after イベントは、SharePoint インフラストラクチャがそれ自体のいずれかのイベントを処理した後にトリガーされます。 SharePoint では、リスト イベントおよびリスト項目イベントに対してリモート after イベント ハンドラーが常に非同期で実行されます。 (アプリ イベントは例外です。) 主な目的として、それらはイベントの記録に使用できます。

リスト イベントおよびリスト項目イベントを処理する

リストとリスト アイテムのイベントを処理するには、リモート イベント レシーバー (RER) を作成します。これは、SharePoint ファームまたは SharePoint Online に対して外部で実行される Web サービスです。 RER サービスの URL は、処理するイベントに登録されます。 ハンドラーを登録するには、次の 2 つの方法があります。

• ホスト Web 内のイベントは CSOM (クライアント側オブジェクト モデル) または SharePoint REST API でプログラムによって登録されます。 この作業は通常、アドインまたはアドイン イベントのハンドラー内の "初回実行" ロジックで実行されます。 (アドイン イベントの概要については、この記事で後述する「アドイン イベントの処理」を参照してください。) プログラムによってリスト イベントを登録するコード サンプルについては、SharePoint/PnP/Samples/Core.EventReceivers を参照してください。

• アドイン Web 内のイベントは通常、簡単な XML マークアップをいくつか使用してアドイン Web の機能に登録されます。 マークアップとサービスの作成方法について詳しくは、「SharePoint アドインでリモート イベント レシーバーを作成する」に記されています。また、プログラムによってアドイン Web イベントを登録することもできます。

アドインは、以下のリスト イベントとドキュメント ライブラリ イベントを処理できます。 「ing」で終わるイベントは before (同期) イベントであり、「ed」で終わるイベントは after (非同期) イベントです。

フィールド更新イベントは、リスト上のフィールド (列) のプロパティ (並べ替えが可能かどうかなど) の変更を対象とし、フィールド内のデータの変更は対象としていません。

アドインは、以下のリスト項目イベントを処理できます。

Visual Studio で作業していて、RER を SharePoint アドイン プロジェクトに追加する場合、Visual Studio の Office Developer Tools は次を行います。

• リモート イベント レシーバーを SharePoint アドインに追加したときに指定したイベントを処理するために、RemoteEventReceiver1.svc などの Web サービス ファイルが Web アプリケーションに追加されます。 この Web サービスにはリモート イベントを処理するためのコード ファイルが含まれています。

  リモート イベント レシーバーを作成したら、イベントを処理するコードを Web アプリケーション サービスのコード ファイルに追加します。 既定で、処理コードを追加するコード ファイルには次の 2 つのメソッドが含まれています。

  • ProcessEvent() は「before」イベント (前述の表の左側のイベントなど) を処理して、イベントをキャンセルするか、続行するかを報告するオブジェクトを SharePoint に返します。

  • ProcessOneWayEvent() は"after" イベントを処理します。 非同期的に実行され、SharePoint に何も返しません。

  登録されているイベントが発生すると、SharePoint はサービスから適切なオブジェクトを呼び出し、コードに関する何らかのコンテキスト情報を提供するオブジェクトを渡します。 たとえば、イベントの種類 (この記事で前述した 2 つの表のいずれか) が識別されると、コードはそのイベントに適したロジックに分岐できます。

• リモート イベント レシーバーのプロジェクト 項目が SharePoint アドイン プロジェクトに追加されます。 リモート イベント レシーバー用の Elements.xml ファイルは、Web アプリケーション内の Web サービスと、指定されたリモート イベントを参照します。 次の例は、リスト項目の追加および削除に対応する Elements.xml ファイルです。

  <?xml version="1.0" encoding="utf-8"?>
  <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers ListTemplateId="104">
      <Receiver>
          <Name>RemoteEventReceiver1ItemAdding</Name>
          <Type>ItemAdding</Type>
          <SequenceNumber>10000</SequenceNumber>
          <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url>
      </Receiver>
      <Receiver>
          <Name>RemoteEventReceiver1ItemDeleting</Name>
          <Type>ItemDeleting</Type>
          <SequenceNumber>10000</SequenceNumber>
          <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url>
      </Receiver>
  </Receivers>
  </Elements>
  

リモート イベント レシーバーが処理するイベントを変更するには、ソリューション エクスプローラーを開いてリモート イベント レシーバーの [プロパティ] ウィンドウを開きます。[SharePoint イベント] ノードを展開して、処理するイベントのみ True に設定します。

アドイン イベントの処理

アドイン イベントはリモート Web サービスによっても処理されますが、リスト RER およびリスト項目 RER とは異なる方法でアドイン パッケージ内に構成されているため、別のカテゴリのコンポーネントとして扱われます。 アドイン イベントの場合、リモート Web サービスはアドイン Web 機能ではなくアドイン マニフェストに登録されます。 アドインに、アドイン Web は必要ではありません。 次のセクションでは、3 つのアドイン イベントについて説明します。

AppInstalled イベント

AppInstalled イベントは、アドインのインストール時に SharePoint が処理する必要のあるものすべてが完了した直後、ユーザーにインストールが完了したと通知される前に実行されます。 このイベントは after イベントですが、SharePoint はハンドラーを同期的に 実行します。 ハンドラーが完了するまでアドインは使用できず、ハンドラーはインストールをキャンセルすることができます (これにより、インストールの一部として SharePoint によって処理されたものすべてがロールバックされます)。 実際、ベスト プラクティスとしては、ハンドラー内のエラーを検出し、SharePoint にインストールのロールバックを指示するようにします。 詳細については、「アドイン イベント ハンドラーにロールバック ロジックと "既に実行" ロジックを含める」を参照してください。

このイベントは、アドイン インストールのキャンセル以外に、次のような多くの目的に使用できます。

• リストやサブ Web などのホスト Web 機能を使用して宣言的にインストールできない SharePoint コンポーネントをホスト Web にインストールします。

• ホスト Web またはアドイン Web にリスト イベント ハンドラーとリスト項目イベント ハンドラーをプログラムによって登録します。

• アプリ インスタンス関連の初期設定値を設定します。 たとえば、使用するアドインには、アドインのインスタンスごとに異なる設定を保持するアドイン Web プロパティ バッグを設定できます。 AppInstalled ハンドラーは、ホスト Web のサイトの種類 (チーム サイトやブログ サイトなど) に基づいて、異なる値をプロパティ バッグに書き込むことができます。

  注:

  アドインがテナント スコープを使用してインストールされたかどうかを調べる優れた方法は、ホスト Web が AppCatalog サイトかどうかを確認することです。 「 SharePoint アドインのテナントと展開スコープ」を参照してください。

• アドインのリモート Web アプリケーションで、アプリ インスタンス関連構成 (データベースに対するテーブルの追加など) を実行します。

AppUninstalling イベント

アドインがホスト Web から削除された場合、AppUninstalling イベントは実行 されません 。 アドインの削除では、アドインがユーザーのごみ箱に移動するだけです。 AppUninstalling イベントがトリガーされる前に、他に 2 つの手順が必要です。 最初に、ユーザーはごみ箱からアドインを削除、つまり第 2 段階のごみ箱に移動する必要があります。 2 つ目は、 ユーザーが 2 番目のステージのごみ箱からアドインを削除する必要があります。 この最後のタスクは、AppUninstalling イベントをトリガーします。 AppUninstalling イベントは同期イベントであり、これによってアンインストールをキャンセルし、アドインを第 2 段階のごみ箱に残すことができます。

このイベントのハンドラーの主な目的は、AppInstalled (または AppUpdated) ハンドラーで展開したものを削除またはリサイクルすることです。 SharePoint では、これらを削除、またはごみ箱に移動することはできません。これらは、少なくともアドインのコンポーネントとして認識されていないためです。 通常は、これらを削除することをお勧めします。 しかし、アドインが削除された後も、有用なものは削除しない場合、たとえば、AppInstalled ハンドラーで作成したリストや Web サイトをまだ使用する予定の場合は、AppUninstalling ハンドラー内でこれを削除しないでください。

AppUpgraded イベント

AppUpgraded イベントは、新しいバージョンへのアドインの更新時に SharePoint が処理する必要のあるものすべてが完了した直後、ユーザーに更新が完了したと通知される前に実行されます。 AppInstalled イベントと同様、これは after イベントですが、本質的には同期イベントであり、エラーを検出し、SharePoint に更新をロールバックするよう通知するのがベスト プラクティスです。

このイベントのハンドラーが実行可能な事柄の例をいくつか以下に記します。

• ホスト Web のアドイン コンポーネントの追加、変更、削除

• アドイン Web 機能の宣言型更新セマンティクスでは実行できないものをアドイン Web で実行します。 たとえば、宣言型更新マークアップでは何も削除できませんが、AppUpgraded ハンドラーではプログラムによって削除できます。

• アドインの Web アプリケーションまたはリモート データベースでアプリ - インスタンス関連コンポーネントに変更を加えます。

アドイン イベント ハンドラーの作成の詳細については、「SharePoint アドインでアドイン イベント レシーバーを作成する」を参照してください。

アドイン イベント ハンドラーにロールバック ロジックと "既に実行" ロジックを含める

3 つのアドイン イベントのいずれかを処理しているときに SharePoint でエラーが発生した場合、イベントがキャンセルされ、イベントに関連して加えられた変更がロールバックされます。 使用しているアドイン イベント ハンドラーは、実装しているイベントの一部がエラーになったとき、イベントをそのまま続行して破損状態にならないよう、イベント全体をロールバックする必要があるため、このシステムと統合する必要があります。 使用しているハンドラーに通常求められる動作：

• SharePoint にエラーが発生したことを通知します。 Web サービスを処理するアドイン イベントによって SharePoint に返される SOAP メッセージには、Continue、CancelWithError、CancelWithoutError のいずれかの値の Status プロパティがあります。 いずれかの Cancel ステータスが SharePoint にイベントをロールバックするよう通知します。

• ハンドラーがエラーになる前の時点で完了している部分までロールバックします。 通常、SharePoint ではハンドラーが何を処理したか認識できないため、これは自動的にはできません。 これは汎用的なルールではありません。 たとえば、アドインのインストールがキャンセルされると、SharePoint はアドイン Web 全体を削除するため、AppInstalled イベント ハンドラーはアドイン Web に対して実行した部分まで戻ることのできるポイントはありません。 ただし、通常はアドインのホスト Web またはリモート コンポーネントに対して実行した部分まではロールバックする必要があります。

30 秒以内に SharePoint に対して結果メッセージが送信されない場合、ハンドラーは再度呼び出されます。 3 回の試行の後に中止され、イベントがロールバックされます。つまり、全部で 4 回試行されます。 ハンドラーを呼び出すたびに、コードが最初から再試行されます。 ただし、ホスト Web 上へのリストの作成など、一般的にはハンドラーが完了したものをやり直す必要はなく、ハンドラーがタイムアウトするまでロールバック ロジックが完了したかどうか、またはトリガーされたかどうかも判断できません。このため、ハンドラー ロジックはアクションが完了したかどうかを最初に確認し、再試行しても問題がないかどうかを確認するまで何もアクションを実行しないようにします。

次の図に示すように、SharePoint UI にインストールと更新のエラーが表示される場合があります。

インストール エラーの詳細を取得

アドイン イベント ハンドラーのアーキテクチャ ストラテジ

擬似コードで表されるハンドラーは、通常、次のような構造にする必要があります。 Try セクションでエラーが発生した場合は、Catch と Rollback セクションを呼び出す必要があります。 (これは、言語とフレームワークに応じて自動的に発生する可能性があります)。

Try
    If X not already done,
        Do X.
Catch
    Send cancel message to SharePoint.
    If X not already undone,
        Undo X.

ただし、ロールバックと "既に完了" ロジックを Web サービスに実装すると、ハンドラーの動作が遅くなることがあります。 通常、インストールとロールバックのロジックはどちらも、SharePoint ホスト Web またはバックエンド データベースなど、Web サービスから多かれ少なかれリモートであるような何らかの変更を加えます。 インストールとロールバックのコードが Try セクションと Catch セクションの間で分割されている場合、サービスは、リモート コンポーネントに対してそれぞれ呼び出し、各セクションでの呼び出しが複数回になることがあります。

ベスト プラクティスとしては通常、Try セクションでハンドラーから呼び出されるプロシージャで、リモート コンポーネント自体にインストールとロールバックのロジックを実装します。 そのプロシージャは成功または失敗のメッセージを返し、レポートが失敗した場合は Try セクションのコードによって Catch セクションが呼び出されます (つまり、例外をスローします)。 Catch セクションで実行されることは SharePoint への通知だけです。 これはハンドラー委任戦略と呼ばれます。 次の疑似コードは、その戦略を示しています。

Try
    Call the "Do X" procedure on remote platform.
    If remote platform reports failure, call Catch.
Catch
    Send cancel message to SharePoint.

リモート システムで実行される "Do X" プロシージャには、以下のようなロールバックと "既に実行" ロジックを入れます。

Try
    If X not already done,
        Do X.
        Set success flag to true.
Catch
    If X was done before error,
        Undo X.
    Set success flag to false.
Send
    Return success flag to the event handler.

たとえば、ハンドラーが SQL Server データベースでアクションを実行する必要がある場合、ストアド プロシージャを SQL Server にインストールし、TRY-CATCH ブロックを使用してインストール - ロールバック ロジックを実装し、IF-ELSE ブロックを使用して "既に実行" ロジックを実装します。

SharePoint アドイン モデルでは、SharePoint にカスタム サーバー側コードを保存し、それを CSOM (クライアント側オブジェクト モデル) から呼び出す方法を提供していません。 ただし、CSOM では try-catch ロジックと if-then-else ロジックをバンドルし、それを実行のためにサーバーに送信する方法を提供しています。

ホスト Web にリストを追加するためにハンドラー委任戦略を使用するアドイン イベント ハンドラーの詳細な例については、「harePoint アドインでアドイン イベント レシーバーを作成する」を参照してください。コード サンプルについては、SharePoint/PnP/Samples/Core.AppEvents.HandlerDelegation を参照してください。

ハンドラー委任戦略は常に使用できるわけではありません。 たとえば、ハンドラーがデータベースと SharePoint ホスト Web など複数のコンポーネントを呼び出す場合、一方が正常に完了しても、もう一方がエラーになる場合があります。 このシナリオでは、最初のコンポーネントをハンドラー委任戦略で指定した場合、そのコンポーネントのロールバック ロジックは実行されません。 この理由から、コンポーネントを同期的に呼び出すと、後で呼び出された一方だけがハンドラー委任戦略を使用できます。 非同期的に呼び出す場合は、どちらにもこの戦略を使用できません。

ハンドラー委任戦略を使用しないアドイン イベント ハンドラーのサンプルについては、「 SharePoint/PnP/Samples/Core.AppEvents」を参照してください。

複数のセキュリティ ゾーンをサポートするアドインにあるリモート イベント レシーバー

複数のセキュリティ ゾーンをサポートしていてリモート イベント レシーバーを持つアドインを設計する方法には、いくつかの制限があります。

リモート イベント レシーバーに関してよく寄せられる質問

リモート イベント レシーバーの使用に関してよく寄せられる質問を以下に示します。

リモート イベント レシーバーと SharePoint 2010 のイベント レシーバーにはどのような違いがありますか?

SharePoint 2010 では、イベント レシーバーは (完全に信頼できる、またはサンドボックスにある) SharePoint サーバーでコードを実行することにより、SharePoint リスト、サイト、その他の SharePoint オブジェクトで発生したイベントを処理します。 この種のイベント レシーバーは SharePoint にも、やはりあります。 ただし、SharePoint では、リモート イベント レシーバーもサポートされており、イベントがトリガーされたときに実行されるコードが Web サービスでホストされています。 つまり、リモート イベント レシーバーを登録する場合は、SharePoint にどの Web サービスを呼び出すかを通知する必要もあります。

次のコード サンプルの最初の例 (SharePoint ソリューション) では、イベント ハンドラーを使用して機能を実装します。 2 番目の例 (SharePoint アドイン) では、リモート イベント レシーバーを使用して同じ機能を実装します。

SharePoint ソリューション

    // Trigger an event when an item is added to the SharePoint list.
    Public class OnPlantUpdated : SPItemEventReceiver
    {
    Public override void ItemAdding (SPItemEventProperties properties)
    {
    Properties.After.Properties.ChangedProperties.Add("Image",CreateLink(properties));
    Properties.status =SPEventReceiverStatus.Continue;
    }

    /// When an item updates, run the following.
    Public override void ItemUpdating(SPItemEventProperties properties)
    {
    Properties.AfterProperties.ChangedProperties.Add("Image",CreateLink9properties));
    Properties.Status= SPEventReceiverStatus.Continue;
    }

SharePoint アドイン

    /* Trigger an event when an item is added to the SharePoint list*/
    Public class OnPlantUpdated : IRemoteEventService
    {
    public SPRemoteEventResult ProcessEvent (SPRemoteEventProperties properties)
    {
    SPRemoteEventResult result =new SPRemoteEventResult();
    If (properties.EventType == SPRemoteEventType.ItemAdding ||  
                properties.EventType == SPRemoteEventType.ItemUpdating)
    {
    // Add code that runs when an item is added or updated.
    }

完全なコード サンプルについては、「リモート イベント レシーバーを使用してリスト項目プロパティを追加する」を参照してください。

コード サンプルの詳細なデモについては、「SharePoint イベント レシーバーをリモート イベント レシーバーに移行する」を参照してください。

詳細については、「SPRemoteEventType 列挙型」をご覧ください。

リモート イベント レシーバーは、どのように動作しますか?

次の図は、リモート イベント レシーバーの動作を示しています。

• ユーザーが SharePoint で操作を実行します (例: リスト項目の編集)。

• 次に SharePoint は、登録された Web サービスと通信します。 リスト項目のプロパティの更新や、バックエンド システムの更新など、いくつかの操作を実行できます。

• また、Web サービスはアクセス制御サービス (ACS) との通信も行い、SharePoint へのコールバックを行うために、独自に署名したトークンを要求します。 このトークンを使用して Web サービス内から、リスト項目またはバックエンド システムに対する以前の操作に応じたリモート操作を実行できます。

  SharePoint でのエモート イベント レシーバーの動作

  

リモート イベント レシーバーをデバッグするにはどうすればよいですか?

「SharePoint アドインでのリモート イベント レシーバーのデバッグとトラブルシューティング」を参照してください。

リモート イベント レシーバーからクライアント側 (JavaScript) のコードを実行できますか?

いいえ、リモート イベント レシーバーからクライアント側 (JavaScript) のコードを実行することはできません。

リモート イベント レシーバーをホストできる URL に制限はありますか?

このリモート イベント レシーバーは、クラウドか、オンプレミス サーバー (SharePoint サーバーとしても使用されているものは除く) でホストできます。 運用環境のレシーバー URL で特定のポートを指定することはできません。 つまり、HTTPS のポート 443 (推奨) と HTTP のポート 80 のいずれかを使用する必要があります。 HTTPS を使用し、レシーバー サービスがオンプレミスでホストされ、アドインが SharePoint Online 上にある場合、ホスティング サーバーには、証明機関からの公的に信頼された証明書が必要となります。 (自己署名証明書が有効になるのは、アドインがオンプレミスの SharePoint ファームにある場合のみです。)

SharePoint 2010 イベント ハンドラーは、アップグレード後に SharePoint で動作しますか?

イベント ハンドラーを含む SharePoint 2010 ソリューション パッケージがカスタマイズに応じて SharePoint にアップグレードされる場合、ソリューション パッケージは変更を加えなくても動作できます。 これにはイベント ハンドラーも含まれます。 SharePoint 2010 ソリューションが SharePoint で SharePoint アドインに改造される場合、イベント ハンドラーをリモート イベント レシーバーとして書き換える必要があります。 「SharePoint イベント レシーバーをリモート イベント レシーバーに移行する」を参照してください。

関連項目

• SharePoint アドインでリモート イベント レシーバーを作成する
• SharePoint アドインでアドイン イベント レシーバーを作成する
• SharePoint アドインでのリモート イベント レシーバーのデバッグとトラブルシューティング
• SharePoint アドインの開発