SharePoint アドイン モデル内のイベント レシーバーとリスト イベント レシーバー

  • [アーティクル]

新しい SharePoint アドイン モデルでは、SharePoint のイベントを処理するための方法が完全信頼コードを使用していたものと異なっています。

一般的な完全信頼コード (FTC)/ファーム ソリューション シナリオでは、イベント レシーバーとリスト イベント レシーバーが SharePoint

サーバー側オブジェクト モデル コードで作成され、ソリューション経由で展開されていました。 このシナリオでは、イベント レシーバー コードは SharePoint サーバー上で実行されます。

SharePoint アドイン モデル シナリオでは、イベント レシーバーは SharePoint の外部にある Web サービスの内部で作成され、SharePoint に登録されます。 これらはリモート イベント レシーバー (RER) と呼ばれます。 このシナリオでは、Web サービスがホストされる Web サーバーでイベント レシーバー コードが実行されます。

重要

2017 年 1 月時点で、SharePoint Online は、"-ed" リモート イベント レシーバーの代わりに使用できるリスト Webhook をサポートしています。 Webhook の詳細については、「SharePoint Webhook の概要」を参照してください。 また、sp-dev-samples GitHub リポジトリからいくつかの Webhook サンプルを入手することもできます。

基本ガイドライン

イベント レシーバーの作成については、経験に基づく次のような大まかなガイドラインが提供されています。

  • イベント レシーバーを実装するサービス エンドポイントは、匿名ユーザーによるアクセスが可能になっている必要があります。
  • アドイン Web に追加されたイベント レシーバーにより、アクセス トークンを返すことができます。
  • ホスト Web に追加されたイベント レシーバーは、アプリ アクセス トークンを使用するアプリ コンテキストから適用され、ホスト Web 内の操作がエンド ユーザー駆動型 (ItemAdded など) である場合に、アクセス トークンを返します。
  • AppInstalled イベントは 30 秒以内に完了する必要があります。または、SharePoint は失敗したと見なします。 SharePoint はイベントを 3 回再実行し、4 回目の実行後に SharePoint はアドインのインストールが失敗したと見なします
  • ItemAdded のような通常のイベントにも 30 秒のタイムアウトがあるが、再試行のメカニズムはない
  • SharePointOnlineCredentials やその他の手段などにより、アプリ コンテキストなしでホスト Web に追加されたイベント レシーバーではアクセス トークンが返されず、アプリ専用アクセス トークンでホスト Web にアクセスする必要があります。
  • ホスト Web へのイベント レシーバーの追加はサポートされています。
    • これは CSOM/REST API によってのみ可能であり、Visual Studio のウィザードで行うことはできません。
  • SharePoint では、特定のイベント用に構成されたイベント レシーバー エンドポイントが必ず呼び出されます。 ただし、イベント レシーバー エンドポイント内のコードは SharePoint サーバー上で実行されないため、必ず実行されるという保証はありません。

次に例を示します。

イベント レシーバーのエンド ポイント URL を使用できない場合、イベント レシーバー コードは実行されません。 さまざまな理由により、URL を使用できないことがあります。 最も一般的な理由としては、エンドポイント URL の登録時の構成ミス、URL の解決時の DNS の問題、エンド ポイントをホストしている Web サイトがシャットダウンされているか、操作できない状態であることが含まれます。

また、適切に記述されていないイベント レシーバー コードにバグがある場合、バグが発生し、イベントを再実行する必要があることを SharePoint に通知する方法はありません。 SharePoint リストに接続されているイベント レシーバーで、この問題をある程度回避することができます。 この方法について詳しくは、以下を参照してください。

  • イベント レシーバーで大量のコードが実行される場合は、非同期パターンを使用する必要があります。
  • イベント レシーバーでのタイムアウトの詳細については、次の MSDN 記事を参照してください。 (記事でタイムアウトを検索します)。 SharePoint 用アドインのイベントを処理する (MSDN 記事)
  • イベント レシーバーで SharePoint リストを操作する場合は、高品質の処理を保証するため、イベント レシーバーと共に特定の変更追跡メカニズムを使用することをお勧めします。

イベント レシーバーのデバッグ

イベント レシーバーをデバッグするには、Azure と Visual Studio でいくつかの異なる点を構成する必要があります。 次の記事では、ステップ バイ ステップの手順と、デバッグに関連する詳細情報を示します。

その他の例

  • Core.EventReceivers (O365 PnP サンプル)
    • このサンプルは、SharePoint アドインで AppInstalled イベントを使用してホスト Web で追加処理 (たとえば、ホスト Web 内のリストにイベント レシーバーを接続する) を実行する方法を示しています。
  • Core.AppEvents.HandlerDelegation (O365 PnP サンプル)
    • このサンプルは、AppInstalled および AppUninstalling イベント用のハンドラーを次のように実装する方法を示しています。
      1. ハンドラーでエラーが発生した場合に使用するロールバック ロジックを組み込みます。
      2. ハンドラーの処理が失敗するか完了に 30 秒以上かかる場合に SharePoint で 3 回まで再試行が行われるという動作に対応するための "完了済み" ロジックを組み込みます。
      3. ハンドラー委任戦略を使用して、ハンドラー Web サービスから SharePoint への呼び出しを最小限にします。
      4. CSOM クラスの ExceptionHandlingScope と ConditionalScope を使用します。
  • Core.AppEvents (O365 PnP サンプル)
    • このサンプルは、AppInstalled および AppUninstalling イベント用のハンドラーを次のように実装する方法を示しています。
      1. ハンドラーでエラーが発生した場合に使用するロールバック ロジックを組み込みます。
      2. ハンドラーの処理が失敗するか完了に 30 秒以上かかる場合に SharePoint で 3 回まで再試行が行われるという動作に対応するための "完了済み" ロジックを組み込みます。

PnP サンプル

適用対象

  • Office 365 マルチテナント (MT)
  • Office 365 専用 (D)
  • SharePoint 2013 オンプレミス