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:

  • イベントは、 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 で イベント前カスタム ハンドラは、常に同期的に実行されます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.

  • イベントは、 SharePointインフラストラクチャがイベントを独自に処理した後に作動します。After events are triggered after the SharePoint infrastructure does any of its own handling of the event. SharePointでは、 リモートの後イベント ハンドラは、リスト項目とリスト項目イベントの場合、常に非同期的に実行します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 のイベントは、通常、アドイン Web の機能に登録され、簡単な XML マークアップが付いています。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"で終わるイベントは前(同期)イベントであり、 "ed"で終わるイベントは後(非同期)イベントです。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 (synchronous) 後(非同期)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 (synchronous) 後(非同期)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() は "後" イベントを処理します。これは非同期的に実行され、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 では異なる構成になっているため、別々のカテゴリのコンポーネントとして扱われます。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. これは イベントですが、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.

  • app-instance-relative 初期設定を設定する。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 イベントと同様、後イベントですが、本質的には同期的であり、エラーをキャッチして 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 メッセージには、 状態 の値を持つことができる 持続するCancelWithError、または CancelWithoutError というプロパティを持ちます。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. いずれかの キャンセル 状態は、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.

SharePoint がハンドラから 30 秒以内に結果メッセージを受信しない場合は、ハンドラが再度呼び出されます。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 にリストを追加するアドイン イベント ハンドラの詳細な例については、「SharePointアドインでのアドインイベント受信者の作成」をご参照下さい。また、コード サンプルについては、 「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 イベントが失敗すると、アドイン Web が存在する場合は SharePoint はこれを削除します。 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. つまり、リモート イベント レシーバを登録する場合は、呼び出す Web サービスを SharePoint に指示する必要があります。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