SharePoint アドインのイベントを処理するHandle events in SharePoint Add-ins

カスタム コードによって、プロバイダー向けのホスト型アドインにおける次の 3 つのカテゴリのイベントを処理できます。Your custom code can handle three categories of events in provider-hosted add-ins:

  • リスト イベント。Web サイト上におけるリストの追加、削除など。List events, such as the adding or deleting of a list on a website.
  • リスト項目イベント。リスト内の項目の編集など。List item events, such as the editing of an item in a list.
  • アドイン イベント。アドインのインストールなど。Add-in events, such as the installation of an add-in.

SharePoint ホスト型の SharePoint アドインではイベント処理をサポートしていませんが、ワークフローをトリガーするようにイベントを設定することにより、ワークフローを一種のリストまたはリスト項目のイベント ハンドラーに転換することができます。SharePoint-hosted SharePoint Add-ins do not support event handling, but you can turn a workflow into a kind of list or list item event handler by setting an event to trigger the workflow. See Workflows in SharePoint. Workflows cannot be triggered by add-in events, so add-in events cannot be handled with a SharePoint-hosted add-in. 詳細については、「SharePoint のワークフロー」を参照してください。For more information, see Workflows in SharePoint. ワークフローはアドイン イベントではトリガーできないため、アドイン イベントは SharePoint ホスト型アドインでは処理できません。Workflows cannot be triggered by add-in events, so add-in events cannot be handled with a SharePoint-hosted add-in.

注意

Web サイト イベントとサイト コレクション イベントは SharePoint アドインではサポートされていません。Note Website events and site collection events are not supported in SharePoint Add-ins.

以下の 2 種類のイベントがあります。There are two kinds of events:

  • before イベントは、SharePoint インフラストラクチャがそれ自体の任意のイベント (コンテンツ データベースへの変更の確定など) を処理する前にトリガーされます。Before events are triggered before the SharePoint infrastructure does any of its own handling of the event (including committing changes to the content database). SharePoint では、カスタムの before イベント ハンドラーは常に同期的に実行されます。In SharePoint custom before event handlers always execute synchronously. 主な目的として、それらはイベントのキャンセルに使用できます。Among other purposes, they can be used to cancel the event. たとえば、アドインにリストの削除機能がある場合、イベントを削除するリストのハンドラーは、特定の条件が適合しない場合に削除をキャンセルすることができます。For example, if an add-in has a function for deleting a list, a handler for the list deleting event can cancel the deletion if certain conditions are not met. イベントが一連のイベントの一部である場合、キャンセルするとその後のイベントがすべて妨げられます。If the event is part of a sequence of events, cancelling it prevents any of the later events from occurring at all. たとえば、ItemAdding イベントのハンドラーがイベントをキャンセルすると、通常はその後に発生する ItemAdded イベントはトリガーされません。For example, if your handler for the ItemAdding event cancels the event, the ItemAdded event, which normally comes later, is not triggered.

  • after イベントは、SharePoint インフラストラクチャがそれ自体のいずれかのイベントを処理した後にトリガーされます。After events are triggered after the SharePoint infrastructure does any of its own handling of the event. SharePoint では、リスト イベントおよびリスト項目イベントに対してリモート after イベント ハンドラーが常に非同期で実行されます。In SharePoint, remote after event handlers, for list and list item events, always execute asynchronously. (アプリ イベントは例外です。) 主な目的として、それらはイベントの記録に使用できます。(App events are an exception.) Among other purposes, they can be used to log events.

リスト イベントおよびリスト項目イベントを処理するHandle list and list item events

リスト イベントとリスト項目イベントを処理するには、リモート イベント レシーバー (RER) を作成します。RER は、SharePoint ファームまたは SharePoint オンラインに対して外部的に実行する Web サービスです。RER サービスの URL は、それを処理するイベントに登録されます。ハンドラーを登録するには、次の 2 つの方法があります。To handle list and list item events, you create remote event receivers (RERs), which are web services that run externally to the SharePoint farm or SharePoint Online. The URL of the RER service is registered for the events it handles. There are two ways to register a handler:

  • ホスト Web 内のイベントは CSOM (クライアント側オブジェクト モデル) または SharePoint REST API でプログラムによって登録されます。Events in the host web are registered programmatically with the CSOM (client-side object model) or the SharePoint REST API. この作業は通常、アドインまたはアドイン イベントのハンドラー内の "初回実行" ロジックで実行されます。This task is typically done in "first run" logic in the add-in or in a handler for an add-in event. (アドイン イベントの概要については、この記事で後述する「アドイン イベントの処理」を参照してください。) プログラムによってリスト イベントを登録するコード サンプルについては、SharePoint/PnP/Samples/Core.EventReceivers を参照してください。(For an overview of add-in events, see Handle add-in events later in this article.) For a code sample that programmatically registers a list event, see SharePoint/PnP/Samples/Core.EventReceivers.

  • アドイン Web 内のイベントは通常、簡単な XML マークアップをいくつか使用してアドイン Web の機能に登録されます。Events in the add-in web are usually registered in a feature of the add-in web with some simple XML markup. マークアップとサービスの作成方法について詳しくは、「SharePoint アドインでリモート イベント レシーバーを作成する」に記されています。また、プログラムによってアドイン Web イベントを登録することもできます。Events in the add-in web are usually registered in a Feature of the add-in web with some simple XML markup. Details of how to create the markup and the service are in Create a remote event receiver in SharePoint Add-ins. It is also possible to register add-in web events programmatically.

注意

RER にはファーム ソリューションのイベント レシーバーと同じ目的がありますが、イベント レシーバーの場合、SharePoint サーバーで実行するカスタム コードがあるので SharePoint アドインでは使用できません。Note RERs have the same purpose as event receivers in farm solutions; but event receivers have custom code that runs on the SharePoint servers, so they cannot be used in SharePoint Add-ins.

アドインは、以下のリスト イベントとドキュメント ライブラリ イベントを処理できます。Your add-in can handle the following list and document library events. 「ing」で終わるイベントは before (同期) イベントであり、「ed」で終わるイベントは after (非同期) イベントです。Your add-in can handle the following list and document library events. Events ending in "ing" are before (synchronous) events and those ending in "ed" are after (asynchronous) events.

before (同期)Before (synchronous) after (非同期)After (asynchronous)
ListAddingListAdding ListAddedListAdded
ListDeletingListDeleting ListDeletedListDeleted
FieldAddingFieldAdding FieldAddedFieldAdded
FieldDeletingFieldDeleting FieldDeletedFieldDeleted
FieldUpdatingFieldUpdating FieldUpdatedFieldUpdated

フィールド更新イベントは、リスト上のフィールド (列) のプロパティ (並べ替えが可能かどうかなど) の変更を対象とし、フィールド内のデータの変更は対象としていません。The field update events are about changing the properties of a field (column) on a list, such as whether it is sortable, not about changing the data in the field.

アドインは、以下のリスト項目イベントを処理できます。Your add-in can handle the following list item events.

before (同期)Before (synchronous) after (非同期)After (asynchronous)
ItemAddingItemAdding ItemAddedItemAdded
ItemUpdatingItemUpdating ItemUpdatedItemUpdated
ItemDeletingItemDeleting ItemDeletedItemDeleted
ItemCheckingOutItemCheckingOut ItemCheckedOutItemCheckedOut
ItemCheckingInItemCheckingIn ItemCheckedInItemCheckedIn
ItemUncheckingOutItemUncheckingOut ItemUncheckedOutItemUncheckedOut
ItemAttachmentAddingItemAttachmentAdding ItemAttachmentAddedItemAttachmentAdded
ItemAttachmentDeletingItemAttachmentDeleting ItemAttachmentDeletedItemAttachmentDeleted
ItemFileMovingItemFileMoving ItemFileMovedItemFileMoved
ItemVersionDeleting*ItemVersionDeleting** ItemVersionDeleted*ItemVersionDeleted*
ItemFileConvertedItemFileConverted

注意

*これら 2 つの新しいイベントは Visual Studio UI では使用できない場合があります。*These two new events may not be available in the Visual Studio UI. その場合は、ItemDeleting または ItemDeleted を採用し、手動でその名前を変更してください。*These two new events may not be available in the vsnv UI. If not, pick ItemDeleting or ItemDeleted and then manually change the names.

Visual Studio で作業していて、RER を SharePoint アドイン プロジェクトに追加する場合、Visual Studio の Office Developer Tools は次を行います。When you are working in Visual Studio, and you add a RER to a SharePoint Add-in project, the Office Developer Tools for Visual Studio do the following:

  • Web サービス ファイル (RemoteEventReceiver1.svc など) が Web アプリケーションに追加され、リモート イベント レシーバーを SharePoint アドインに追加したときに指定したイベントを処理します。この Web サービスにはリモート イベントを処理するためのコード ファイルが含まれています。A web service file, such as RemoteEventReceiver1.svc, is added to the web application to handle the events that you specified when you added the remote event receiver to the SharePoint Add-in. The web service contains a code file to handle the remote events.

    リモート イベント レシーバーを作成したら、イベントを処理するコードを Web アプリケーション サービスのコード ファイルに追加します。既定で、処理コードを追加するコード ファイルには次の 2 つのメソッドが含まれています。After you create the remote event receiver, you add code to the code file for the web application service to handle the events. By default, the code file contains two methods to which you add your handling code:

    • ProcessEvent() は「before」イベント (前述の表の左側のイベントなど) を処理して、イベントをキャンセルするか、続行するかを報告するオブジェクトを SharePoint に返します。ProcessEvent() handles "before" events (such as those in the left-hand columns in the tables earlier in the article) and it returns an object to SharePoint that reports on whether it should cancel the event or let it proceed.

    • ProcessOneWayEvent() は「after」イベントを処理します。非同期的に実行され、SharePoint に何も返しません。ProcessOneWayEvent() handles "after" events. It runs asynchronously and does not return anything to SharePoint.

      登録されているイベントが発生すると、SharePoint はサービスから適切なオブジェクトを呼び出し、コードに関する何らかのコンテキスト情報を提供するオブジェクトを渡します。When a registered event occurs, SharePoint calls the appropriate method in your service and passes an object that provides some context information for your code. For example, the event type (from one of the two tables earlier in the article) is identified, so that your code can branch to the logic that is appropriate for the event. たとえば、イベントの種類 (この記事で前述した 2 つの表のいずれか) が識別されると、コードはそのイベントに適したロジックに分岐できます。When a registered event occurs, SharePoint calls the appropriate method in your service and passes an object that provides some context information for your code. For example, the event type (from one of the two tables earlier in the article) is identified, so that your code can branch to the logic that is appropriate for the event.

  • リモート イベント レシーバー用のプロジェクト アイテムが SharePoint アドイン プロジェクトに追加されます。リモート イベント レシーバー用の Elements.xml ファイルは、Web アプリケーション内の Web サービスと、指定されたリモート イベントを参照します。次の例は、リスト項目の追加および削除に対応する Elements.xml ファイルです。A project item for the remote event receiver is added to the SharePoint Add-in project. The Elements.xml file for the remote event receiver references the web service in the web application and the remote events that you specified. The following example shows an Elements.xml file that handles the addition or deletion of a list item.

    <?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 に設定します。To change the events that the remote event receiver handles, open Solution Explorer, open the Properties window for the remote event receiver, expand the SharePoint Events node, and then set only the events that you want to handle to True.

注意

トラブルシューティング情報を含む RER の詳細については、「リモート イベント レシーバーに関してよく寄せられる質問」をご覧ください。For additional information about RERs, including some troubleshooting information, see Remote event receivers FAQ.

アドイン イベントの処理Handle add-in events

アドイン イベントはリモート Web サービスによっても処理されますが、リスト RER およびリスト項目 RER とは異なる方法でアドイン パッケージ内に構成されているため、別のカテゴリのコンポーネントとして扱われます。Add-in events are also handled by remote web services, but they are configured differently in the add-in package from list and list item RERs, so they are treated as a separate category of component. For an add-in event, the remote web service is registered in the add-in manifest, not in an add-in web Feature. The add-in doesn't even have to have an add-in web. There are three add-in events as described in the next sections. アドイン イベントの場合、リモート Web サービスはアドイン Web 機能ではなくアドイン マニフェストに登録されます。For an add-in event, the remote web service is registered in the add-in manifest, not in an add-in web feature. アドインに、アドイン Web は必要ではありません。The add-in doesn't even have to have an add-in web. 次のセクションでは、3 つのアドイン イベントについて説明します。There are three add-in events as described in the next sections.

AppInstalled イベントAppInstalled event

AppInstalled イベントは、アドインのインストール時に SharePoint が処理する必要のあるものすべてが完了した直後、ユーザーにインストールが完了したと通知される前に実行されます。The AppInstalled event runs immediately after SharePoint has finished everything that it needs to do when the add-in is installed, but before the user is notified that installation is complete. ただし、これは after イベントであるため、SharePoint はハンドラーを同期的に実行します。Although this is an after event, SharePoint runs your handler synchronously. ハンドラーが完了するまでアドインは使用できず、ハンドラーはインストールをキャンセルすることができます (これにより、インストールの一部として SharePoint によって処理されたものすべてがロールバックされます)。The add-in is not available for use until after your handler has completed, and your handler can cancel the installation (which causes SharePoint to roll back everything it has done as part of the installation). 実際、ベスト プラクティスとしては、ハンドラー内のエラーを検出し、SharePoint にインストールのロールバックを指示するようにします。In fact, it is a best practice to catch any errors in your handler and instruct SharePoint to roll back the installation. 詳細については、「アドイン イベント ハンドラーにロールバック ロジックと "既に実行" ロジックを含める」を参照してください。Include rollback logic and "already done" logic in your add-in event handlers

注意

アドインをテナント範囲でインストールする場合、それはアドイン カタログのサイト コレクションにインストールされ、その時にのみ AppInstalled イベントが実行されます。When you install an add-in with Tenant scope, it is installed to the add-in catalog site collection and the AppInstalled event runs then and only then. The add-in is visible in multiple web sites in the tenancy, but the event does not run separately for each of these. アドインはテナンシー内の複数の Web サイトに表示されますが、そのそれぞれに対してイベントが個別に実行されることはありません。The add-in is visible in multiple websites in the tenancy, but the event does not run separately for each of these.

このイベントは、アドイン インストールのキャンセル以外に、次のような多くの目的に使用できます。Besides canceling an add-in installation, this event can be used for many other purposes including:

  • リストやサブ Web などのホスト Web 機能を使用して宣言的にインストールできない SharePoint コンポーネントをホスト Web にインストールします。Install SharePoint components to the host web that cannot be declaratively installed with the host web Feature, such as lists or subwebs.

  • ホスト Web またはアドイン Web にリスト イベント ハンドラーとリスト項目イベント ハンドラーをプログラムによって登録します。Programmatically register list and list item event handlers with the host web or add-in web.

  • アプリ インスタンス関連の初期設定値を設定します。Setting app-instance-relative initialization settings. たとえば、使用するアドインには、アドインのインスタンスごとに異なる設定を保持するアドイン Web プロパティ バッグを設定できます。Set app-instance-relative initialization settings. For example, your add-in can have an add-in web property bag for holding settings that vary from one instance of the add-in to another. Your AppInstalled handler can write varying values to the property bag, based on, say, the site type of the host web (such as Team Site or Blog site). AppInstalled ハンドラーは、ホスト Web のサイトの種類 (チーム サイトやブログ サイトなど) に基づいて、異なる値をプロパティ バッグに書き込むことができます。Set app-instance-relative initialization settings. For example, your add-in can have an add-in web property bag for holding settings that vary from one instance of the add-in to another. Your AppInstalled handler can write varying values to the property bag, based on, say, the site type of the host web (such as Team Site or Blog site).

    注意

    アドインがテナント スコープでインストールされたかどうかを調べる優れた方法は、ホスト Web が AppCatalog サイトかどうかを確認することです。Note Checking to see if the host web is an AppCatalog site is a good way to detect whether the add-in has been installed with tenant scope. See Tenancies and deployment scopes for SharePoint Add-ins. SharePoint アドインのテナントと展開スコープ」を参照してください。Tenancies and deployment scopes for SharePoint Add-ins

  • アドインのリモート Web アプリケーションで、アプリ インスタンス関連構成 (データベースに対するテーブルの追加など) を実行します。Perform app-instance-relative configuration in the add-in's remote web application, such as adding a table to a database.

重要

AppInstalled イベントの実装は 30 秒以内に完了する必要があります。完了しない場合、SharePoint インストールのインフラストラクチャでは失敗したと判断されます。Your implementation of the AppInstalled event must complete within 30 seconds or the SharePoint installation infrastructure thinks it has failed. インフラストラクチャはイベント返し、追加で 3 回までコードを最初から繰り返しますThe infrastructure reruns the event and repeats your code from the beginning, up to three additional times. 4 回タイムアウトすると、SharePoint はアドイン全体のインストールをロールバックします。After four timeouts, SharePoint rolls back the entire add-in installation. 実際の関連性全体については、「アドイン イベント ハンドラーにロールバック ロジックと "既に実行" ロジックを含める」を参照してください。The full implications of these facts are discussed in Include rollback logic and "already done" logic in your add-in event handlers.

AppUninstalling イベントAppUninstalling event

AppUninstalling イベントは、アドインがホスト Web から削除されるときには、実行されませんThe AppUninstalling event does not run when the add-in is removed from the host web. アドインの削除では、アドインがユーザーのごみ箱に移動するだけです。Removal of an add-in only moves the add-in to the user's recycle bin. AppUninstalling イベントがトリガーされる前に、他に 2 つの手順が必要です。Two more steps are required before the AppUninstalling event is triggered. 最初に、ユーザーはごみ箱からアドインを削除、つまり第 2 段階のごみ箱に移動する必要があります。First, a user must remove the add-in from the recycle bin, which moves it to the second stage recycle bin. 次に、ユーザーは第 2 段階のごみ箱からアドインを削除する必要がありますSecond, a user must remove the add-in from the second stage recycle bin. この最後の作業によって、AppUninstalling イベントがトリガーされます。This last task triggers the AppUninstalling event. AppUninstalling イベントは同期イベントであり、これによってアンインストールをキャンセルし、アドインを第 2 段階のごみ箱に残すことができます。The AppUninstalling event is synchronous and you can use it to cancel the uninstallation, which would leave the add-in in the second stage recycle bin.

このイベントのハンドラーの主な目的は、AppInstalled (または AppUpdated) ハンドラーで展開したものを削除またはリサイクルすることです。The main purpose of a handler for this event is to delete or recycle things that were deployed with an AppInstalled (or an AppUpdated) handler. SharePoint では、これらを削除、またはごみ箱に移動することはできません。これらは、少なくともアドインのコンポーネントとして認識されていないためです。SharePoint cannot delete these things, or move them to the recycle bin, because it doesn't know about them, at least not as components of the add-in. 通常は、これらを削除することをお勧めします。It is usually a good practice to remove these things. しかし、アドインが削除された後も、有用なものは削除しない場合、たとえば、AppInstalled ハンドラーで作成したリストや Web サイトをまだ使用する予定の場合は、AppUninstalling ハンドラー内でこれを削除しないでください。But you don't want to delete things that still have a useful life after the add-in is gone: if a list or website created by your AppInstalled handler is still going to be used, don't delete it in your AppUninstalling handler.

AppUpgraded イベントAppUpgraded event

AppUpgraded イベントは、新しいバージョンへのアドインの更新時に SharePoint が処理する必要のあるものすべてが完了した直後、ユーザーに更新が完了したと通知される前に実行されます。The AppUpgraded event runs immediately after SharePoint has finished everything that it needs to do when the add-in is updated to a new version, but before the user is notified that updating is complete. Like the AppInstalled event, it is an after event, but is essentially synchronous and it is a best practice to catch errors and notify SharePoint to roll back the update. AppInstalled イベントと同様、これは after イベントですが、本質的には同期イベントであり、エラーを検出し、SharePoint に更新をロールバックするよう通知するのがベスト プラクティスです。The AppUpgraded event runs immediately after SharePoint has finished everything that it needs to do when the add-in is updated to a new version, but before the user is notified that updating is complete. Like the AppInstalled event, it is an after event, but is essentially synchronous and it is a best practice to catch errors and notify SharePoint to roll back the update.

このイベントのハンドラーが実行可能な事柄の例をいくつか以下に記します。Some examples of what a handler for this event can do:

  • ホスト Web のアドイン コンポーネントの追加、変更、削除Add, change, or remove add-in components from the host web.

  • アドイン Web 機能の宣言型更新セマンティクスでは実行できないものをアドイン Web で実行します。Do things in the add-in web that aren't possible with the declarative update semantics in an add-in web Feature. For example, you cannot delete anything with the declarative update markup, but you can do so programmatically in an AppUpgraded handler. たとえば、宣言型更新マークアップでは何も削除できませんが、AppUpgraded ハンドラーではプログラムによって削除できます。Do things in the add-in web that aren't possible with the declarative update semantics in an add-in web Feature. For example, you cannot delete anything with the declarative update markup, but you can do so programmatically in an AppUpgraded handler.

  • アドインの Web アプリケーションまたはリモート データベースでアプリ - インスタンス関連コンポーネントに変更を加えます。Make changes to app-instance-relative components in the add-in's web application or remote database.

アドイン イベント ハンドラーの作成の詳細については、「SharePoint アドインでアドイン イベント レシーバーを作成する」を参照してください。Detailed instructions for creating add-in event handlers is in Create an add-in event receiver in SharePoint Add-ins .

アドイン イベント ハンドラーにロールバック ロジックと "既に実行" ロジックを含めるInclude rollback logic and "already done" logic in your add-in event handlers

3 つのアドイン イベントのいずれかを処理しているときに SharePoint でエラーが発生した場合、イベントがキャンセルされ、イベントに関連して加えられた変更がロールバックされます。If SharePoint encounters an error when processing any of the three add-in events, it cancels the event and rolls back any changes it has made in connection with the event. 使用しているアドイン イベント ハンドラーは、実装しているイベントの一部がエラーになったとき、イベントをそのまま続行して破損状態にならないよう、イベント全体をロールバックする必要があるため、このシステムと統合する必要があります。If SharePoint encounters an error when processing any of the three add-in events, it will cancel the event and roll back any changes it has made in connection with the event. Your add-in event handlers have to integrate with this system because if the part of the event that you are implementing fails, you want the whole event to roll back, rather than continue and leave things in a possibly corrupt state. Here's what your handler usually has to do: 使用しているハンドラーに通常求められる動作:Here's what your handler usually has to do:

  • SharePoint にエラーが発生したことを通知します。Tell SharePoint that an error has occurred. Web サービスを処理するアドイン イベントによって SharePoint に返される SOAP メッセージには、ContinueCancelWithErrorCancelWithoutError のいずれかの値の Status プロパティがあります。Tell SharePoint that an error has occurred. The SOAP message that your add-in event handling web service returns to SharePoint will have a Status property that can have the values of Continue, CancelWithError, or CancelWithoutError. Either Cancel* status tells SharePoint to roll back the event. いずれかの Cancel ステータスが SharePoint にイベントをロールバックするよう通知します。Either Cancel status tells SharePoint to roll back the event.

  • ハンドラーがエラーになる前の時点で完了している部分までロールバックします。Roll back what the handler has already done before the handler encounters the error. 通常、SharePoint ではハンドラーが何を処理したか認識できないため、これは自動的にはできません。SharePoint can't usually do this for you because it doesn't know what your handler did. これは汎用的なルールではありません。This isn't a universal rule. たとえば、アドインのインストールがキャンセルされると、SharePoint はアドイン Web 全体を削除するため、AppInstalled イベント ハンドラーはアドイン Web に対して実行した部分まで戻ることのできるポイントはありません。For example, if an add-in installation is canceled, SharePoint deletes the entire add-in web, so there's no point in an AppInstalled event handler reverting anything it has done to the add-in web. ただし、通常はアドインのホスト Web またはリモート コンポーネントに対して実行した部分まではロールバックする必要があります。But it usually should roll back things it did to the host web or to remote components of the add-in.

注意

前述のポイントは、他の 2 つのアドイン イベントに対する場合と同様に、AppUninstalling イベントに当てはまります。The preceding points apply to the AppUninstalling event as much as to the other two add-in events. たとえば、アンインストール イベントのハンドラーがリモート データベースの行を削除し、エラーが発生した場合、その行を復元する必要があります。For example, if your handler for the uninstalling event deletes a row in a remote database, and then encounters an error, the row needs to be restored. サービスから SharePoint に対してキャンセル メッセージが送信されるため、アドインはごみ箱から削除されません。Because your service sends a cancel message to SharePoint, the add-in is not removed from the recycle bin. そこから復元され、再利用された場合、そのデータベース エントリがなければ作業はエラーになります。If it is restored from there and used again, it may fail to work without that database entry. ただし、AppUninstalling ハンドラーは SharePoint がごみ箱からアドインを削除する前に完了します。However, your AppUninstalling handler completes before SharePoint removes the add-in from the recycle bin. そのため、SharePoint 自体にエラーが発生し、削除をキャンセルする必要がある場合、ハンドラーで処理が完了したものを取り消すことはできません。However, your AppUninstalling handler completes before SharePoint removes the add-in from the recycle bin. So, if SharePoint itself encounters an error and needs to cancel the removal, there is no way for your handler to undo what it has done.

30 秒以内に SharePoint に対して結果メッセージが送信されない場合、ハンドラーは再度呼び出されます。If SharePoint doesn't receive a results message from your handler in 30 seconds, it calls the handler again. 3 回の試行の後に中止され、イベントがロールバックされます。つまり、全部で 4 回試行されます。It gives up entirely and rolls back the event after three retries (four tries in all). ハンドラーを呼び出すたびに、コードが最初から再試行されます。Each time it calls the handler, your code starts again from the beginning. ただし、ホスト Web 上へのリストの作成など、一般的にはハンドラーが完了したものをやり直す必要はなく、ハンドラーがタイムアウトするまでロールバック ロジックが完了したかどうか、またはトリガーされたかどうかも判断できません。このため、ハンドラー ロジックはアクションが完了したかどうかを最初に確認し、再試行しても問題がないかどうかを確認するまで何もアクションを実行しないようにします。If SharePoint doesn't receive a results message from your handler in 30 seconds, it will call the handler again. It gives up entirely, and rolls back the event, after three retries (four tries in all). Each time it calls the handler, your code starts again from the beginning. But you generally don't want your handler to redo things it has already done, such as create a list on the host web, and you can't know if your rollback logic was completed, or even triggered, before the handler timed out. For this reason, your handler logic should not take any action without first checking whether the action has already been done, unless it would be harmless to do it again.

次の図に示すように、SharePoint UI にインストールと更新のエラーが表示される場合があります。Installation and updating errors can be seen in the SharePoint UI, as shown in the following graphic.

インストール エラーの詳細を取得Figure 1. Getting details for install error.

SharePoint のアドイン インストール エラーを確認する手順。

アドイン イベント ハンドラーのアーキテクチャ ストラテジAdd-in event handler architecture strategies

疑似コードに示されているように、通常ハンドラーは以下のように構築されます。Try セクションでエラーが発生すると、Catch と Rollback セクションが呼び出されます (言語とフレームワークによっては自動的に行われる場合があります)。Expressed in pseudo-code, your handler should usually be structured something like the following. If an error occurs in the Try section, the Catch and Rollback section should be invoked. (This may happen automatically depending on the language and framework.)

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

ただし、ロールバックと "既に完了" ロジックを Web サービスに実装すると、ハンドラーの動作が遅くなることがあります。However, implementing your rollback and "already done" logic in your web service can slow down the handler. 通常、インストールとロールバックのロジックはどちらも、SharePoint ホスト Web またはバックエンド データベースなど、Web サービスから多かれ少なかれリモートであるような何らかの変更を加えます。Both your installation and rollback logic usually make changes to something more or less remote from the web service, such as the SharePoint host web or a back-end database. インストールとロールバックのコードが Try セクションと Catch セクションの間で分割されている場合、サービスは、リモート コンポーネントに対してそれぞれ呼び出し、各セクションでの呼び出しが複数回になることがあります。If your installation and rollback code is split between the Try and Catch sections, the service is making separate calls to the remote components, often several such calls in each section.

ベスト プラクティスとしては通常、Try セクションでハンドラーから呼び出されるプロシージャで、リモート コンポーネント自体にインストールとロールバックのロジックを実装します。The best practice is usually to implement the installation and rollback logic on the remote component itself in a procedure that can be called from your handler in your Try section. そのプロシージャは成功または失敗のメッセージを返し、レポートが失敗した場合は Try セクションのコードによって Catch セクションが呼び出されます (つまり、例外をスローします)。The procedure should return a success or failure message, and if it reports failure, code in your Try section invokes the Catch section (by, say, throwing an exception). Catch セクションで実行されることは SharePoint への通知だけです。The only thing the Catch section does is notify SharePoint. これはハンドラー委任戦略と呼ばれます。We'll call this the handler delegation strategy. 次の疑似コードは、その戦略を示しています。The following pseudo-code illustrates the strategy:

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

リモート システムで実行される "Do X" プロシージャには、以下のようなロールバックと "既に実行" ロジックを入れます。The "Do X" procedure, that executes on the remote system, would itself contain the rollback and "already done" logic like the following.

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 ブロックを使用して "既に実行" ロジックを実装します。For example, if your handler needs to take action on an SQL Server database, you can install a stored procedure on the SQL Server that uses a TRY-CATCH block to implement installation-rollback logic. with IF-ELSE blocks to implement "already done" logic.

SharePoint アドイン モデルでは、SharePoint にカスタム サーバー側コードを保存し、それを CSOM (クライアント側オブジェクト モデル) から呼び出す方法を提供していません。The SharePoint add-in model doesn't provide a way to store custom server-side code on SharePoint and invoke it from the CSOM (client-side object model). ただし、CSOM では try-catch ロジックと if-then-else ロジックをバンドルし、それを実行のためにサーバーに送信する方法を提供しています。But the CSOM does provide a way to bundle try-catch and if-then-else logic and send it to the server for execution.

ホスト Web にリストを追加するためにハンドラー委任戦略を使用するアドイン イベント ハンドラーの詳細な例については、「harePoint アドインでアドイン イベント レシーバーを作成する」を参照してください。コード サンプルについては、SharePoint/PnP/Samples/Core.AppEvents.HandlerDelegation を参照してください。The SharePoint add-in model doesn't provide a way to store custom server-side code on SharePoint and invoke it from the CSOM (client-side object model). But the CSOM does provide a way to bundle try-catch and if-then-else logic and send it to the server for execution. For a detailed example of a add-in event handler that uses the handler delegation strategy to add a list to a host web, see Create an add-in event receiver in SharePoint Add-ins. For a code sample, see OfficeDev/PnP/Samples/Core.AppEvents.HandlerDelegation.

ハンドラー委任戦略は常に使用できるわけではありません。You cannot always use the handler delegation strategy. たとえば、ハンドラーがデータベースと SharePoint ホスト Web など複数のコンポーネントを呼び出す場合、一方が正常に完了しても、もう一方がエラーになる場合があります。For example, when your handler is calling out to more than one component, such as to a database and the SharePoint host web, there is a chance that one could complete successfully and the other fail. このシナリオでは、最初のコンポーネントをハンドラー委任戦略で指定した場合、そのコンポーネントのロールバック ロジックは実行されません。In this scenario, the rollback logic for the first component doesn't run if you designed it with the handler delegation strategy. この理由から、コンポーネントを同期的に呼び出すと、後で呼び出された一方だけがハンドラー委任戦略を使用できます。For this reason, if you are calling to the components synchronously, only the last one called can use the handler delegation strategy. 非同期的に呼び出す場合は、どちらにもこの戦略を使用できません。If they are called asynchronously, you can't use that strategy in any of them.

ハンドラー委任戦略を使用しないアドイン イベント ハンドラーのサンプルについては、SharePoint/PnP/Samples/Core.AppEvents を参照してください。For a sample of an add-in event handler that does not use the handler delegation strategy, see SharePoint/PnP/Samples/Core.AppEvents.

ヒント

AppInstalled イベントが失敗した場合、SharePoint はアドイン Web があればこれを削除し、AppUpated イベントが失敗した場合は SharePoint がアドイン Web を更新前の状態に復元します。If the AppInstalled event fails, SharePoint deletes the add-in web if there is one; and if the AppUpated event fails, SharePoint restores the add-in web to its pre-update state. この理由から、ハンドラーがアドイン Web で実行したアクションをロールバックする必要はありません。For this reason, your handlers never need to roll back actions they take on the add-in web. ハンドラーがホスト Web とアドイン Web の両方でアクションを実行する場合、最初にアドイン Web を処理する必要があります。If your handler performs actions on both the host web and the add-in web, it should deal with the add-in web first. これにより、ホスト Web でハンドラー委任戦略を安全に使用できます。Doing so makes it safe to use the handler delegation strategy for the host web. アドイン Web アクションが成功し、ホスト Web アクションが失敗した場合でも、ロールバック ロジックが実行されなくなることはありません。Even if the add-in web actions succeed and the host web actions fail, no rollback logic goes unexecuted.

複数のセキュリティ ゾーンをサポートするアドインにあるリモート イベント レシーバーRemote Event Receivers in add-ins that support multiple security zones

複数のセキュリティ ゾーンをサポートしていてリモート イベント レシーバーを持つアドインを設計する方法には、いくつかの制限があります。Some restrictions on how you design an add-in support multiple security zones and have a remote event receiver. 詳細については、サポート技術情報の記事 kb3135876「既定以外のゾーンでの SharePoint 2013 サイトに、プロバイダーがホストされているアドインを追加することはできません」をご覧ください。For more information, see Knowledge Base article kb3135876 You can't add a provider-hosted add-in to a SharePoint 2013 site in non-default zones.

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

リモート イベント レシーバーの使用に関してよく寄せられる質問を以下に示します。The following are common questions you may have when using remote event receivers.

リモート イベント レシーバーと SharePoint 2010 のイベント レシーバーにはどのような違いがありますか?How are remote event receivers different from event receivers in SharePoint 2010?

SharePoint 2010 では、イベント レシーバーは (完全に信頼できる、またはサンドボックスにある) SharePoint サーバーでコードを実行することにより、SharePoint リスト、サイト、その他の SharePoint オブジェクトで発生したイベントを処理します。In SharePoint 2010, event receivers handle events that occur on SharePoint lists, sites, and other SharePoint objects by running the code on the SharePoint server (either full-trust or in a sandbox). この種のイベント レシーバーは SharePoint にも、やはりあります。This type of event receiver still exists in SharePoint. ただし、SharePoint では、リモート イベント レシーバーもサポートされており、イベントがトリガーされたときに実行されるコードが Web サービスでホストされています。However, SharePoint also supports remote event receivers in which the code that runs when the event is triggered is hosted by a web service. つまり、リモート イベント レシーバーを登録する場合は、SharePoint にどの Web サービスを呼び出すかを通知する必要もあります。This means that if you register a remote event receiver, you also need to tell SharePoint which web service to invoke.

次のコード サンプルの最初の例 (SharePoint ソリューション) では、イベント ハンドラーを使用して機能を実装します。In the following code samples, the first example (SharePoint solutions) implements functionality by using an event handler. 2 番目の例 (SharePoint アドイン) では、リモート イベント レシーバーを使用して同じ機能を実装します。The second example (SharePoint Add-ins) implements the same functionality by using a remote event receiver.

SharePoint ソリューションSharePoint solutions

    // 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 アドインSharePoint Add-ins

    /* 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.
    }

完全なコード サンプルについては、「リモート イベント レシーバーを使用してリスト項目プロパティを追加する」を参照してください。For the complete code sample, see Add list item properties with a remote event receiver.

コード サンプルの詳細なデモについては、「SharePoint イベント レシーバーをリモート イベント レシーバーに移行する」を参照してください。For a detailed demo of the code sample, see Migrating a SharePoint event receiver to a remote event receiver.

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

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

次の図は、リモート イベント レシーバーの動作を示しています。The following figure shows how remote event receivers work:

  • ユーザーが SharePoint で操作を実行します (例: リスト項目の編集)。The user performs an action on SharePoint (for example, edits a list item).

  • 次に SharePoint は、登録された Web サービスと通信します。SharePoint then talks to the registered web service. リスト項目のプロパティの更新や、バックエンド システムの更新など、いくつかの操作を実行できます。SharePoint then talks to the registered web service. You could perform some operations???for example, update a list item property, or update a backend system.

  • また、Web サービスはアクセス制御サービス (ACS) との通信も行い、SharePoint へのコールバックを行うために、独自に署名したトークンを要求します。このトークンを使用して Web サービス内から、リスト項目またはバックエンド システムに対する以前の操作に応じたリモート操作を実行できます。The web service can also talk to the Access Control Service (ACS) to request its own signed token to do a call back to SharePoint. Using this token, you can perform remote actions from within the web service as a result of the earlier operation on the list item or in the backend system.

    SharePoint でのリモート イベント レシーバーの動作方法How remote event receivers work in SharePoint

    SharePoint でのリモート イベント レシーバーの動作方法

リモート イベント レシーバーをデバッグするにはどうすればよいですか?How do I debug remote event receivers?

SharePoint アドインでのリモート イベント レシーバーのデバッグとトラブルシューティング」を参照してください。See Debug and troubleshoot a remote event receiver in a SharePoint Add-in.

リモート イベント レシーバーからクライアント側 (JavaScript) のコードを実行できますか?Can I run client-side (JavaScript) code from remote event receivers?

いいえ、リモート イベント レシーバーからクライアント側 (JavaScript) のコードを実行することはできません。No, you cannot run client-side (JavaScript) code from remote event receivers.

リモート イベント レシーバーをホストできる URL に制限はありますか?Are there any restrictions on where a remote event receiver can be hosted or on its URL?

このリモート イベント レシーバーは、クラウドか、オンプレミス サーバー (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.)

SharePoint 2010 イベント ハンドラーは、アップグレード後に SharePoint で動作しますか?Will a SharePoint 2010 event handler work on SharePoint after I upgrade?

イベント ハンドラーを含む SharePoint 2010 ソリューション パッケージがカスタマイズに応じて SharePoint にアップグレードされる場合、ソリューション パッケージは変更を加えなくても動作できます。If a SharePoint 2010 solution package containing an event handler is upgraded to SharePoint, depending on your customizations, the solution package may work without any modifications. これにはイベント ハンドラーも含まれます。This includes the event handler too. SharePoint 2010 ソリューションが SharePoint で SharePoint アドインに改造される場合、イベント ハンドラーをリモート イベント レシーバーとして書き換える必要があります。If the SharePoint 2010 solution is remodeled into a SharePoint Add-in in SharePoint, the event handler should be rewritten as a remote event receiver. SharePoint イベント レシーバーをリモート イベント レシーバーに移行する」を参照してください。See Migrating a SharePoint event receiver to a remote event receiver.

関連項目See also