SharePoint Foundation 2010 のイベント レシーバーを使用する (1/2)

  • [アーティクル]

概要:  Microsoft SharePoint Foundation 2010 のイベント レシーバーを使用すると、SharePoint オブジェクトで特定のアクションが発生したときにユーザー設定コードで応答できます。この記事では、イベントを使用して SharePoint アプリケーションを拡張する方法について、実際的な例で説明します。

最終更新日: 2015年3月9日

適用対象: Business Connectivity Services | Open XML | SharePoint Designer 2010 | SharePoint Foundation 2010 | SharePoint Online | SharePoint Server 2010 | Visual Studio

この記事の内容
SharePoint Foundation 2010 のイベントの基礎知識
SharePoint Foundation 2010 のイベントを操作する
Visual Studio 2010 のイベント レシーバー テンプレートを使用する
参考資料

提供元:  Ali Badereddin、Microsoft Corporation | Nick Gattuccio、Microsoft Corporation

目次

  • SharePoint Foundation 2010 のイベントの基礎知識

  • SharePoint Foundation 2010 のイベントを操作する

  • Visual Studio 2010 のイベント レシーバー テンプレートを使用する

  • 参考資料

SharePoint Foundation 2010 のイベントの基礎知識

Microsoft SharePoint Foundation 2010 のイベント レシーバーは、簡単に言うと、指定された SharePoint オブジェクトでトリガー アクションが発生したときに呼び出されるメソッドです。トリガー イベントには、追加、更新、削除、移動、チェックイン、チェックアウトなどのアクションがあります。イベントをリッスンする SharePoint オブジェクト (イベント レシーバー ホスト) には、サイト コレクション、サイト、リスト、ワークフローなどのオブジェクトがあります。

SharePoint 開発者にとって、イベントは有用なツールです。ユーザーが SharePoint サイトに影響を与えるアクションを実行したときに、そのアクションをトラップして、ユーザー設定コードで応答できます。たとえば、特定のドキュメント ライブラリに新しいドキュメントやファイルが追加されたときにプロジェクト マネージャーに警告が送られるようにするには、プロジェクト マネージャーに電子メール通知を送信するイベント レシーバー コードを作成し、そのコードをドキュメント ライブラリの項目追加アクションにバインドします。SharePoint Foundation 2010 では、SharePoint イベントをきわめて柔軟に検知して応答できます。

注意

Microsoft Visual Studio 2010 には、この記事で説明するタスクの多くを自動的に実行する SharePoint イベント レシーバー プロジェクト テンプレートが用意されています。イベント パイプライン全体で発生するアクションを詳細に説明するために、ここでは Visual Studio 2010 のイベント レシーバー プロジェクト テンプレートを使用しません。ただし、Visual Studio 2010 を使用してイベント レシーバーを作成する方法の簡単な概要と、テンプレートの使用例を示します。

イベントは Windows SharePoint Services 2.0 で最初に導入されましたが、当初はドキュメント ライブラリでのみサポートされていました。当時の SharePoint イベントは、イベント シンクと呼ばれていました。Windows SharePoint Services 3.0 で SharePoint イベントのインフラストラクチャが現在の形となり、マネージ イベント レシーバーを使用するようになりました。

イベント レシーバーは、さまざまな点でイベント シンクよりも優れています。より使いやすく、イベントの種類が多く、リスト、コンテンツ タイプ、ワークフロー、およびサイトでサポートされています。SharePoint Foundation 2010 では、新しいリスト イベントと Web イベントが導入されました。さらに、サイト コレクションがイベント ホストとして機能するようになり、After イベントを同期できるようになり、イベントの取り消しと偽装が強化されました。

SharePoint イベントのしくみ: 必要なすべての知識が 1 段落でわかる

SharePoint イベント レシーバーは、SharePoint オブジェクト (イベント ホスト) にバインドされ、イベント レシーバー コードをトリガーすることでユーザー アクションに応答します。イベント レシーバー コードは、マネージ アセンブリ、つまりグローバル アセンブリ キャッシュに展開される .dll ファイルにコンパイルされます。

イベント レシーバーを使用する場面

SharePoint で実行される操作に動作を追加する必要がある場合は、イベント レシーバーを使用して、特定の操作が行われるたびにユーザー設定コードをトリガーします。表 1 に、ユーザー設定コードを割り当てることができるさまざまな操作を示します。

表 1. イベント レシーバーから利用できる操作

オブジェクト

操作

サイト コレクション

  • 削除

Web

  • 作成

  • URL の変更

  • 削除

リスト

  • 作成

  • 削除

  • 電子メールの受信

フィールド

  • 作成

  • 更新

  • 削除

項目

  • 作成

  • 更新

  • 削除

  • チェックイン

  • チェックアウト

  • ファイルの移動

  • ファイルの変換

  • 添付ファイルの追加

  • 添付ファイルの削除

ワークフロー

  • 開始

  • 完了

  • 延期

イベント レシーバーとは

イベント レシーバーは、SharePoint オブジェクトで特定のトリガー アクションが発生したときに、SharePoint イベントに応答するマネージ コードです。トリガー アクションには、追加、更新、削除、移動、チェックイン、チェックアウトなどのアクティビティがあります。

イベント レシーバーを作成するには、イベント レシーバー基本クラスの 1 つを継承します。SharePoint には 5 つのイベント レシーバー基本クラスがあります (次のセクションの表 2 を参照)。それぞれの基本クラスは、指定されたイベント ホストとイベントしかサポートしないことに注意してください。サポートするホストの種類に適したイベント レシーバー基本クラスを選択する必要があります。

イベント レシーバー クラスでイベント レシーバーを作成したら、レシーバーをマネージ アセンブリにコンパイルし、グローバル アセンブリ キャッシュ (GAC) に配置します。最後に、イベント レシーバーを適切なイベント ホストにバインドします。後で、イベントのバインドと、イベントをバインドするさまざまな方法について説明します。

イベント ホストとは

イベント ホストは、イベントを待機する共通の SharePoint オブジェクト、つまり SharePoint イベントを「リッスン」するイベント レシーバーを持つオブジェクトです。これらの SharePoint イベント ホスト オブジェクトの種類には、SharePoint サイト コレクション、サイト、リストなど、共通のオブジェクトのインスタンスが含まれます。各イベント ホストの種類には、継承できる特定のイベント レシーバー基本型があります。

表 2 に、イベント レシーバー基本クラスと、各レシーバーをサポートするイベント ホストの種類、およびそれらがサポートするイベントを示します。

表 2. イベント レシーバー基本クラスと、サポートされるイベント

イベント レシーバー基本クラス

使用できるイベント ホストの種類

サポートされるイベント

SPWebEventReceiver

  • SPSite

  • SPWeb

  • SiteDeleting

  • SiteDeleted

  • WebAdding

  • WebProvisioned

  • WebDeleting

  • WebDeleted

  • WebMoving

  • WebMoved

SPListEventReceiver (リスト)

  • SPSite

  • SPWeb

  • ListAdding

  • ListAdded

  • ListDeleting

  • ListDeleted

SPListEventReceiver (フィールド)

  • SPSite

  • SPWeb

  • SPList

  • SPContentType

  • FieldAdding

  • FieldAdded

  • FieldDeleting

  • FieldDeleted

  • FieldUpdating

  • FieldUpdated

SPItemEventReceiver

  • SPSite

  • SPWeb

  • SPList

  • SPContentType

  • ItemAdding

  • ItemAdded

  • ItemDeleting

  • ItemDeleted

  • ItemUpdating

  • ItemUpdated

  • ItemFileConverted

  • ItemFileMoving

  • ItemFileMoved

  • ItemCheckingIn

  • ItemCheckedIn

  • ItemCheckingOut

  • ItemCheckedOut

  • ItemAttachmentAdding

  • ItemAttachmentAdded

  • ItemAttachmentDeleting

  • ItemAttachmentDeleted

SPEmailEventReceiver

  • SPSite

  • SPWeb

  • SPList

  • EmailReceived

SPWorkflowEventReceiver

  • SPSite

  • SPWeb

  • SPList

  • SPContentType

  • WorkflowStarting

  • WorkflowStarted

  • WorkflowCompleted

  • WorkflowPostponed

SharePoint イベント モデルの主要な概念

イベント モデルの基本要素、つまりイベント レシーバー、イベント ホスト、およびイベント自体に加えて、SharePoint イベント モデルには次のような主要な概念があります。

Before イベント

Before イベントは、現在要求されている操作が行われる前に発生します。たとえば、ItemAdding イベントは、SharePoint リストに項目が追加される前に発生する Before イベントです。

見方を変えると、Before イベントは、SharePoint がコンテンツ データベースに書き込む前にアクションが行われるときに発生します。このため、イベント レシーバーには、データがデータベースにコミットされる前にタスクを実行する機会が与えられます。Before イベントの有効な活用例が、データ検証の実行です。Before イベントはデータのコミット前に発生するからです。また、たとえばデータ検証が失敗した場合に、Before (同期) イベントを使用してユーザー アクションを取り消すこともできます。

Before イベントによってトリガーされるイベント レシーバー コードは、そのコードをトリガーしたユーザー アクションを実行しているコードと同じスレッドで実行されます。このため、Before イベントは常に同期イベントになります。Before イベントは、メンバー名の末尾の「-ing」という接尾辞で見分けることができます (ItemAdding、ListAdding など)。

After イベント

After イベントは、現在要求されている操作が行われた後で発生します。たとえば、ItemAdded イベントは、SharePoint リストに項目が追加された後で発生する After イベントです。

After イベントがトリガーするイベント レシーバーは、ユーザー アクションがコンテンツ データベースにコミットされた後で実行されます。イベント レシーバーが呼び出すコードは、コンテンツ データベースが変更された後で実行されます。このため、ユーザーが特定のアクションを完了した後で発生するロジックを実行できます。

After イベントは、同期または非同期に実行できます。同期 After イベントは、トリガー アクションが発生するのと同じスレッドで実行されます。一方、非同期 After イベントは、独立したスレッドで実行されます。

After イベントは、メンバー名の末尾の「-ed」という接尾辞で見分けることができます (ItemDeleted、WebProvisioned など)。

同期イベント

同期イベントは、トリガー アクションが実行されているのと同じスレッドで実行されます。たとえば、ユーザーが SharePoint ユーザー インターフェイスから項目を追加すると、イベントが完全に実行された後でユーザーに制御が戻り、項目が追加されたことが表示されます。

Before イベントはすべて同期イベントです。

非同期イベント

非同期イベントは、トリガー アクションよりも後に発生するイベントで、トリガー アクションが実行されているスレッドとは別のスレッドで実行されます。たとえば、ユーザーが SharePoint ユーザー インターフェイスを使用してドキュメント ライブラリに項目を追加すると、イベントの実行が開始してからユーザーに制御が戻ります。ただし、項目が追加されたことがユーザーに表示される前に、イベント レシーバーの実行が終了するという保証はありません。

イベントのバインド

イベントのバインド (イベントの登録) を行うには、サーバー オブジェクト モデルまたはフィーチャー XML を使用します。後のセクションで、SharePoint Foundation のイベントのバインドについて詳細に説明します。

イベントの取り消し

イベントの取り消しを使用すると、アクションが終了する前に、Before イベントでイベント レシーバー操作を取り消すことができます。たとえば、ItemAdding イベント レシーバーに、項目を追加するアクションを取り消すコードを記述します。ユーザーが項目を追加しようとすると、操作が取り消されて、項目はリストに追加されません。操作を取り消すときは、必ずユーザーにエラー メッセージを表示するか、ユーザーを特定の URL にリダイレクトしてカスタム エラー メッセージを示してください。

イベント レシーバー シーケンス

イベント レシーバー シーケンスは、イベントが複数のイベント レシーバーをトリガーする場合に、イベント レシーバーが実行される順序を指定します。たとえば、同じリストに 2 つの ItemAdded イベント レシーバーが (1 つは Assembly "1" から、もう 1 つは Assembly "2" から) バインドされている場合、小さい方のシーケンス番号でバインドされているイベント レシーバーが最初に実行されます。実際的な例としては、既にシステム イベント レシーバーがバインドされているシステム リストにイベント レシーバーを追加する場合があります。この場合は、新しいイベント レシーバーのシーケンス番号の方が大きくなるように割り当てます。

SharePoint イベント パイプライン

図 1 は、同期と順序付けに関して SharePoint イベントがどのように発生するかを示しています。

図 1. SharePoint イベント パイプライン

SharePoint イベント パイプライン

次の点に注意してください。

  • 同期イベント レシーバーは、イベントのバインド中に指定されたシーケンス番号に基づいて順番に呼び出されます。これは同期 Before イベントと同期 After イベントの両方に当てはまります。

  • 非同期 After イベント レシーバーのスレッドは、シーケンス番号に基づいて順番に開始されます。ただし、それと同じ順序で終了するという保証はありません。

  • 非同期 After イベントは、関連するユーザー アクションが実行された後でいつでも開始できます。Web 要求の完了前でも、完了と同時にでも、完了後でも開始できます。

ユーザーが SharePoint ユーザー インターフェイスでアクションを開始した後、SharePoint Foundation がユーザー アクションを実行する前に、同期 Before イベントが発生します。同期 Before イベントが複数ある場合は、シーケンス番号で指定された順序で発生します。同様に、同期 After イベントは SharePoint Foundation がユーザー アクションを実行した後で発生します。これらのイベントも、シーケンス番号で指定された順序で発生します。このように、同期イベントはすべて、ユーザー アクションが実行されるスレッドと同じスレッドで処理されます。

これに対し、非同期 After イベントは別のスレッドで処理されます。

SharePoint Foundation 2010 のイベントを操作する

SharePoint イベントを作成するには、基本的に 2 つの手順を実行します。最初に、イベントに関連付ける操作を識別し、適切なイベント レシーバー基本クラスを継承し、イベント レシーバーのユーザー設定コードを記述します。次に、イベントを適切な SharePoint イベント ホストにバインドします (この手順をイベントの登録ともいいます)。

イベント レシーバー コードを記述し、厳密な名前で署名されたアセンブリにコンパイルした後で、イベントをイベント ホストにバインドするには 2 つの方法があります。1 つは SharePoint オブジェクト モデルの API を使用する方法、もう 1 つは SharePoint ソリューションのフィーチャー XML を使用する方法です。この 2 つの方法について詳細に説明します。

オブジェクト モデルの使用とソリューションの使用

SharePoint イベントのバインドにオブジェクト モデル (OM) を使用する場合とソリューションを使用する場合の違いを簡単に言うと、次のようになります。OM の手法は柔軟性に優れ、開発が容易ですが、展開と保守は複雑です。ソリューションの手法は柔軟性に劣り、開発は複雑ですが、展開と保守ははるかに容易です。

OM の手法を使用すると、SharePoint オブジェクト モデル全体を自在に操作できます。イベント レシーバー コードを記述し、GAC に展開するアセンブリにコンパイルし、アセンブリのイベントを SharePoint イベント ホストにバインドするコードを実行します。

この手法は開発モードの最中は便利です。イベント レシーバー コードとイベントのバインドをテストして変更を加え、プロジェクトをリビルドして再展開するのが容易だからです。しかし、コードを開発プラットフォームから運用環境に移行すると、この簡潔さが失われます。すべてを手動で展開しなければならないからです。つまり、イベント レシーバー コード (マネージ アセンブリ) を運用環境の個々のフロントエンド Web サーバーにコピーしなければなりません。その後、フロントエンド Web サーバーの 1 つで実行可能ファイルを実行し、さらに各フロントエンド Web サーバーで iisreset を実行して IIS ワーカー プロセス (w3wp.exe) のキャッシュを更新する必要があります。大規模な運用環境では、これはきわめてわずらわしい (しかもリスクを伴う) 作業になることがあります。

SharePoint ソリューションの手法では、イベント レシーバー定義をバインドする方法が異なります。さらに、イベント レシーバー コードをソリューション ファイルと共に展開 (.wsp) パッケージに含めることで、サーバー ファーム全体にわたる展開がはるかに容易で確実になり、フィーチャーをアクティブ化するだけでイベント レシーバー定義を利用できるようになります。ソリューションの手法のもう 1 つの重要な利点は、イベント レシーバーを部分的に信頼されたコード (つまり、サンドボックス ソリューション) に実装できることです。これにより、サイト コレクション レベルの管理者がイベント レシーバーを追加できます (SharePoint 2010 の前は、ファーム管理者だけがイベント レシーバーを追加できました)。

展開に必要な手順は, .wsp ファイルを使った SharePoint ソリューションの展開に通常使用する手順と変わりません。1 つの展開コマンドを実行すると、フィーチャーがアクティブ化された後で、レシーバー アセンブリとイベントのバインドがすべてのフロントエンド Web サーバーに展開されます。

Visual Studio 2010 では、この作業がさらに容易になります。Visual Studio を使用すると、オブジェクト モデルの手法の柔軟性と、ソリューションの手法の効率性の両方を獲得できます。以下の各セクションではイベント レシーバーを操作しながら、Visual Studio 2010 によって作業が大幅に簡略化された部分に焦点を当てます。

サーバー オブジェクト モデルを使用する

サーバー オブジェクト モデルを使用するときは、イベント コードの作成、イベントのバインド、およびイベント コードの修正や変更という 3 つの主要な作業に携わることになります。以下の各セクションで、それぞれの手順について詳細に説明します。

注意

以下の例では Visual Studio を使用しますが、Visual Studio 2010 に付属する SharePoint プロジェクト テンプレートは使用しません。したがって、以下のサンプルを再現するときは Visual Studio 2008 と Visual Studio 2010 のどちらを使用してもかまいません。

オブジェクト モデルを使用してイベントを作成する

カスタム イベント レシーバーを作成するときの最初の手順は、イベント レシーバー基本クラスの 1 つをオーバーライドすることです。前の表 2 で 5 つの SharePoint イベント レシーバー基本クラスの一覧を示しましたが、それらはすべてコア イベント レシーバー基本クラスの SPEventReceiverBase を継承します。

イベント レシーバーを作成するには

  1. Visual Studio 2008 または Visual Studio 2010 で、C# クラス ライブラリ プロジェクトを作成し、MyReceiverAssembly などの名前を付けます。

    重要なメモ重要

    Visual Studio 2010 を使用する場合は、必ず Microsoft .NET Framework 3.5 をターゲットに設定してください。その理由は、SharePoint 2010 が .NET Framework 3.5 に依存するからです。この設定は、図 2 に示すように、プロジェクトのプロパティの [アプリケーション] タブにあります。

    図 2. .NET Framework 3.5 をターゲットに設定する

    .NET Framework 3.5 の選択

  2. プロジェクトのプロパティの [ビルド] タブで、図 3 に示すように、[プラットフォーム ターゲット] を [x64] または [Any CPU] に設定します。[x86] は選択しないでください。

    図 3. 適切なプラットフォームをターゲットに設定する

    適切なプラットフォームの選択

  3. プロジェクトのプロパティの [署名] タブで、[アセンブリの署名] を選択します。

  4. [厳密な名前のキー ファイルを選択してください] をクリックし、[新規作成] をクリックします。

  5. [厳密な名前キーの作成] ダイアログ ボックスの [キー ファイル] ボックスに、任意の名前を入力します。[キーファイルをパスワードで保護する] チェック ボックスをオフにし、[OK] をクリックします。

  6. クラスの名前を、たとえば MyReceiverClass などに変更します。

  7. Microsoft.SharePoint.dll への参照を追加します。

  8. クラス内に次のステートメントを挿入して Microsoft.SharePoint 名前空間への参照を作成します。

    using Microsoft.SharePoint;

  9. 作成するイベントに応じて、SPEventReceiverBase の適切なサブクラスを継承します (表 2 を参照)。たとえば、ItemAdded イベントを作成してバインドする場合は、次のように SPItemEventReceiver 基本クラスを継承します。

    Public class MyReceiverClass : SPItemEventReceiver

  10. 実装するイベントのメソッドを定義します。「public override」と入力してから Space キーを押す方法を利用すると便利です。Visual Studio では、図 4 に示すように、クラスで使用できるイベントが IntelliSense によって表示されます。

    図 4. 使用できるイベントを IntelliSense で表示する

    IntelliSense を使って利用可能なイベントを表示する

    ItemAdded イベントを選択した場合、メソッド定義は次のようになります。

    Public override void ItemAdded(SPItemEventProperties properties)
{
    base.ItemAdded(Properties;
}

  11. クラス ライブラリを DLL にビルドします。

  12. DLL を GAC に配置します。%WINDIR%\assembly フォルダーに移動して、アセンブリをフォルダーにドラッグします。

    "アクセスが拒否されました" というエラー メッセージが表示されたり、その他の問題でアセンブリをキャッシュにドロップできない場合は、次の手順を実行します。

    1. コンピューターに Visual Studio 2010 の SharePoint 開発者ツールがインストールされていることを確認します。

    2. Visual Studio のコマンド プロンプトを起動します。

    3. 「gacutil /i」と入力し、その後ろにアセンブリのパスを入力します。この操作が成功すると、"アセンブリが正しくキャッシュに追加されました" というメッセージが表示されます。

    4. アセンブリが追加されたことを確認するには、コマンド プロンプトで次のコマンドを入力し、アセンブリ キャッシュの指定したディレクトリ (この例では、MyReceiverAssembly という名前のキャッシュ ディレクトリ) にあるすべてのアセンブリを表示します。

      gacutil /l MyReceiverAssembly

オブジェクト モデルを使用してイベントをバインドする

SharePoint Foundation オブジェクト モデルを使用すると、EventReceivers プロパティを持つ任意のオブジェクトをバインド (登録) できます。EventReceivers プロパティは SPEventReceiverDefinitionCollection 型で、これによってイベント ホストへのイベント レシーバー定義の追加が容易になります。次に示すのは、このプロパティを持ち、イベント ホストとして機能する SharePoint オブジェクトの一覧です。

イベント レシーバーをバインドするには

  1. Visual Studio 2008 または Visual Studio 2010 で、C# コンソール アプリケーション プロジェクトを作成し、RegisterEvents などの名前を付けます。

    重要なメモ重要

    Visual Studio 2010 を使用する場合は、必ず Microsoft .NET Framework 3.5 をターゲットに設定してください。その理由は、SharePoint 2010 が .NET Framework 3.5 に依存するからです。この設定は、前の図 2 に示すように、プロジェクトのプロパティの [アプリケーション] タブにあります。

  2. Microsoft.SharePoint.dll への参照を追加します。

  3. クラス内に次のステートメントを挿入して Microsoft.SharePoint 名前空間への参照を作成します。

    using Microsoft.SharePoint;

  4. 次のように、SPEventReceiverDefinition 型の新しい項目を、指定したオブジェクトの EventReceivers コレクションに追加します。

    SPEventReceiverDefinition def = list.EventReceivers.Add();

  5. 前の手順で作成したアセンブリの完全な名前を取得するには、GAC に移動し、アセンブリを見つけてアセンブリ エントリを右クリックし、[プロパティ] をクリックします。図 5 のようなプロパティ ウィンドウが表示されます。

    図 5. GAC のアセンブリのプロパティ

    GAC のアセンブリ プロパティ

  6. プロパティ ウィンドウの値をコピーして、完全な名前、バージョン、カルチャ、および公開キー トークンを指定します。この例では、ソース コードは次のようになります。

    def.Assembly = "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral,PublicKeyToken=12e5e5525fb3d28a";

  7. Class プロパティを設定します。Class プロパティは、イベント レシーバーを含むクラスの完全修飾クラス名を「名前空間.クラス」の形式で表します。この例では、ソース コードは次のようになります。

    def.Class = "MyReceiverAssembly.MyReceiverClass";

  8. Type プロパティを設定します。この例では、ソース コードは次のようになります。

    def.Type = SPEventReceiverType.ItemAdded;

  9. Name プロパティを設定します。このプロパティは省略可能です。イベント レシーバー定義の名前を指定することも、値を無視することもできます。この例では、ソース コードは次のようになります。

    def.Name = "My ItemAdded Event Receiver";

  10. Synchronization プロパティを設定します。このプロパティは省略可能です。このプロパティに値を指定しない場合、プロパティは Default (つまり SPEventReceiverSynchronization.Default) に設定されます。既定の動作は、Before イベントでは同期、After イベントでは非同期になります。この例では、ソース コードは次のようになります。

    def.Synchronization = SPEventReceiverSynchronization.Synchronous;

  11. SequenceNumber プロパティを設定します。このプロパティは省略可能です。イベント レシーバー定義に複数のイベントがあるときは、このプロパティを使用してイベントが発生する順序を設定します。この値を設定しない場合は、既定値の 10000 になります。この値を設定するときは、0 ～ (216)-1 の間の任意の値を選択できます。

  12. 次のステートメントを追加して、イベント レシーバー定義を SharePoint コンテンツ データベースに保存します。

    def.Update();

次に示すのは、ここまでの手順の完全なソース コードです。このコードを実行すると、イベントが https://localhost サイトの Tasks リストに登録されます。リストで新しい項目を作成すると、ItemAdded イベントがトリガーされます。

using (SPSite site = new SPSite("https://localhost"))
{
    using (SPWeb web = site.OpenWeb())
    {
        SPList list = web.Lists["Tasks"];
        SPEventReceiverDefinition def = list.EventReceivers.Add();
        def.Assembly = 
          "MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=12e5e5525fb3d28a";
        def.Class = "MyReceiverAssembly.MyReceiverClass";
        def.Type = SPEventReceiverType.ItemAdded;
        def.Name = "My ItemAdded Event Receiver";
        def.Synchronization = SPEventReceiverSynchronization.Synchronous;
        def.SequenceNumber = 1000;
        def.Update();
    }
}

イベントを変更する

SharePoint イベント モデルでは、イベント レシーバー コードの変更と再展開を簡単に行うことができます。次の手順は、MyReceiverAssembly サンプル プロジェクトに変更を加える方法を示しています。

イベント レシーバーを更新するには

  1. Visual Studio で、プロジェクト (MyReceiverAssembly プロジェクトなど) を開き、変更を加えます。

  2. プロジェクトをリビルドし、DLL ファイルの新しいビルドを作成します。

  3. DLL の新しいビルドを GAC に配置します。前の DLL は必ず上書きするか削除してください。

  4. iisreset を実行して IIS キャッシュをクリアし、GAC の新しいバージョンのアセンブリを読み込みます。この操作によって、SharePoint に変更が反映されます。

SharePoint ソリューションを使用する

SharePoint オブジェクト モデルを使用してイベント レシーバーを作成および展開する方法の代わりとなるのが、SharePoint ソリューションを使用する方法です。ここでは、イベント レシーバー ソリューションを手動で作成する手順を順を追って説明します。

実装するイベントを作成する方法は、SharePoint ソリューションを使用する場合も SharePoint オブジェクト モデルを使用する場合も同じです。「オブジェクト モデルを使用してイベントを作成する」の手順に従ってイベントを作成します。

イベントを実装するこの 2 つの方法の実際の違いは、バインドにあります。バインドには、ソリューション (.wsp) ファイルで展開される SharePoint フィーチャーを使用します。

ソリューションを使用してイベントをバインドする

次の手順では、サンプル イベント (MyReceiverAssembly DLL で作成した ItemAdded イベント) を使用する SharePoint フィーチャーを作成し、フィーチャーをアクティブ化する Web サイトの Tasks リストにバインドします。

SharePoint フィーチャーを作成するには

  1. フィーチャーと同じ名前のフォルダーを作成します。

  2. 新しいフォルダーに、feature.xml と eventbinder.xml という 2 つの XML ファイルを作成します。

  3. XML ファイルで IntelliSense を有効にします。ファイルのプロパティにアクセスし、ターゲット スキーマ (.xsd) ファイルへの参照を追加します。ターゲット スキーマ ファイルは …/TEMPLATE/XML/wss.xsd ディレクトリにあります。

    通常は、XML ファイルを開くたびにこのリンクを作成し直す必要があります。ただし、Visual Studio プロジェクトで作業をしている場合は、プロジェクトにスキーマ ファイルを追加するだけで済みます。

    しかし、複数の Visual Studio プロジェクトで大量の CAML ファイルを作成し、それを頻繁に行う場合は、この作業が煩雑になることがあります。代わりに、スキーマを参照する XML ファイルを開くたびに XSD ファイルを読み込む方法があります。これを行うには、次の手順を実行します。

    1. Visual Studio インストール フォルダーで、Catalog.xml という名前の XML ファイルを見つけます。一般に、このフォルダーは C:\Program Files\Microsoft Visual Studio 9.0\Xml\Schemas になります。

    2. 次のタグを追加して、Catalog.xml ファイルから wss.xsd スキーマ ファイルを参照します。href の値が wss.xsd ファイルの正しい場所を参照していることを確認します。

      <Schema href="C:/Program Files/Common Files/Microsoft Shared/Web Server Extensions/12/TEMPLATE/XML/wss.xsd" targetNamespace="https://schemas.microsoft.com/sharepoint/" />

    ヒントヒント

    Visual Studio 2010 を使用する場合は、事実上、手順 3 を省略できます。属性 xmlns="https://schemas.microsoft.com/sharepoint/" を含む XML ファイルを開くと、Visual Studio 2010 によって wss.xsd への参照が自動的に追加され、IntelliSense が有効になります。

  4. feature.xml ファイル内に、<Feature> 要素を作成します。xmlns 属性を "https://schemas.microsoft.com/sharepoint/" に設定し、Id 属性をグローバル一意識別子 (GUID) に設定し、Scope 属性を "Web" に設定し、Title 属性を "EventBinderFeature" に設定します。

    重要なメモ重要

    Id 属性には、有効な GUID を指定する必要があります。これは Visual Studio 内で guidgen.exe を実行して取得できます。

  5. <Feature> 要素内に、<ElementManifests> 要素を追加します。

  6. <ElementManifests> 要素内に、<ElementManifest> 要素を追加します。Location 属性を "eventbinder.xml" に設定します。

  7. eventbinder.xml ファイル内に、<Elements> 要素を作成します。xmlns 属性を "https://schemas.microsoft.com/sharepoint/" に設定します。

  8. <Elements> 要素内に、<Receivers> 要素を追加します。ListUrl 属性を "Tasks" に設定します。

  9. <Receivers> 要素内に、<Receiver> 要素を追加します。

  10. <Receiver> 要素内に、次の各要素を追加し、それぞれに適切な値を設定します。

    • <Assembly>

    • <Class>

    • <Type>

    • <Name>

    • <Synchronization>

    • <SequenceNumber>

前の手順が完了すると、feature.xml ファイルは次のようになります。

<Feature Id="E54C7FF5-1DF3-4B0B-8FFF-DB3185ECE8A6" 
         Scope="Web" 
         Title="Event Binder Feature"
         xmlns="https://schemas.microsoft.com/sharepoint/">
  <ElementManifests>
    <ElementManifest Location="eventbinder.xml" />
  </ElementManifests>
</Feature>

eventbinder.xml ファイルは次のようになります。

<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
  <Receivers ListUrl="Lists/Tasks">
    <Receiver>
      <Assembly>MyReceiverAssembly, Version=1.0.0.0, Culture=Neutral, 
        PublicKeyToken=12e5e5525fb3d28a</Assembly>
      <Class>MyReceiverAssembly.MyReceiverClass</Class>
      <Type>ItemAdded</Type>
      <Name>My ItemAdded Event Receiver</Name>
      <Synchronization>Synchronous</Synchronization>
      <SequenceNumber>1000</SequenceNumber>
    </Receiver>
  </Receivers>
</Elements>

ソリューションをパッケージ化する

イベント レシーバーを SharePoint のインストールに展開するには、ファイルをソリューション パッケージ (.wsp) ファイルにまとめる必要があります。.wsp ファイルとは、簡単に言うと、ファイル名の拡張子が .wsp になったキャビネット (.cab) ファイルです。

ソリューション マニフェスト ファイルに基づいて、SharePoint は .wsp ファイルにパッケージ化されたファイルの処理方法を判断します。たとえば、<FeatureManifest> 要素は、このフォルダーが SharePoint フィーチャーであり、%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES に展開して、サーバー ファームにインストールする必要があることを指定します。同様に、<Assembly> 要素は、このファイルがアセンブリであることを指定します。要素の DeploymentTarget 属性は、アセンブリを GAC に展開するか Web アプリケーションの bin フォルダーに展開するかを示します。

manifest.xml ファイルを次のように準備、作成、および編集します。

ソリューション コンテンツを準備するには

  1. "EventSolution" という名前のフォルダーを作成します。

  2. フィーチャー フォルダー EventBinder を EventSolution フォルダーにコピーします。

  3. アセンブリ MyReceiverAssembly.dll を EventSolution フォルダーにコピーします。

  4. EventSolution フォルダー内に "manifest.xml" という名前の XML ファイルを作成します。

manifest.xml ファイルを編集するには

  1. manifest.xml ファイル内に、<Solution> 要素を作成します。xmlns 属性を "https://schemas.microsoft.com/sharepoint/" に設定し、SolutionId 属性を GUID に設定し、Title 属性を "Event Receiver Solution" に設定します。

  2. <Solution> 要素内に、<FeatureManifests> 要素を追加します。

  3. <FeatureManifests> 要素内に、<FeatureManifest> 要素を追加します。Location 属性を "EventBinder\feature.xml" に設定します。

  4. <Solution> 要素内に、<Assemblies> 要素を追加します。

  5. <Assemblies> 要素内に、<Assembly> 要素を追加します。Location 属性を "MyReceiverAssembly" に設定し、DeploymentTarget 属性を "GlobalAssemblyCache" に設定します。

編集した manifest.xml ファイルは次のようになります。

<Solution SolutionId="11C76135-CEEC-475B-9A93-67E5EF151B3C"
          Title="Event Receiver Solution"
          xmlns="https://schemas.microsoft.com/sharepoint/">
  <FeatureManifests>
    <FeatureManifest Location="EventBinder\feature.xml"/>
  </FeatureManifests>
  <Assemblies>
    <Assembly Location="MyReceiverAssembly" 
              DeploymentTarget="GlobalAssemblyCache">
    </Assembly>
  </Assemblies>
</Solution>

ソリューション コンテンツの準備ができたら、後は Diamond Directive File (DDF) を作成するだけです。DDF には、Microsoft Cabinet Maker (makecab.exe) がファイルを .cab ファイルにパッケージ化および圧縮する方法を識別するための情報が含まれます (DDF ファイル自体は .cab ファイルに入りません)。

DDF を作成するには

  1. EventSolution フォルダー内に、"cab.ddf" という名前のファイルを作成します。

  2. メモ帳などのテキスト エディターで cab.dff を開き、次の情報を追加します。

    ;
.OPTION EXPLICIT
.Set CabinetNameTemplate=MyEventSolution.wsp 
.set DiskDirectoryTemplate=CDROM
.Set CompressionType=MSZIP
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package
manifest.xml manifest.xml
MyReceiverAssembly.dll MyReceiverAssembly.dll
EventBinder\feature.xml EventBinder\feature.xml
EventBinder\EventBinder.xml EventBinder\EventBinder.xml

  3. ファイルを保存します。

重要なメモ重要

DDF の最初の行は必ずセミコロン (;) で開始してください。

OPTION EXPLICIT ディレクティブは、ファイル内のすべての変数を明示的に宣言する必要があることを指定します。UniqueFiles を "ON" に設定すると、出力ファイルが一意になります。既定値は "ON" で、これは同じファイル名を 2 回使用すると、通常は同じファイルが誤って 2 回含まれたことになり、ディスク領域が無駄になるからです。

この DDF の最後の 4 行はファイル マッピングです。各行の最初の名前が入力ファイル、2 番目の名前が出力ファイルです。

ソリューション パッケージ ファイルを作成するには、コマンド プロンプトを開いて、EventSolution フォルダーに移動し、次のコマンドを入力します。

makecab /F cab.ddf

Cabinet Maker によって、EventSolution フォルダーの "Package" サブフォルダーに .wsp ファイルが作成されます。新しいファイルの名前は MyEventSolution.wsp です。

ソリューションを展開する

SharePoint 2010 には、ファーム ソリューションとサンドボックス ソリューションの 2 種類のソリューションがあります。サンドボックス ソリューションを使用すると、サイト コレクションの管理者がサイト コレクション スコープでソリューションをアップロードおよびアクティブ化できます。サンドボックス ソリューションでは、コンピューターから WFE ファイルにアクセスする必要がなくなります。

しかし、当然のことながら、サンドボックス ソリューションを使用すると、実行できるコードが制限されます。たとえば、ここで作成したイベント レシーバーのコードがディスクにアクセスしようとした場合、ソリューションがファーム ソリューションとして展開されていれば、コードは問題なく実行されます。しかし、イベント レシーバーがサンドボックス ソリューションとして展開されていると、ディスクにアクセスしようとしたときに実行時例外がスローされます。

注意

SharePoint 2010 では、Stsadm.exe 管理ツールが Windows PowerShell に取って代わられています。Stsadm でもまだファーム ソリューションを展開できますが、Windows PowerShell を使用することをお勧めします。Stsadm でサンドボックス ソリューションを展開することはできません。

ファーム ソリューションを展開するには

  1. 次の Windows PowerShell コマンドを実行し、ソリューションをファーム ソリューション ストアにアップロードします。

    Add-SPSolution -LiteralPath full_path_to_solution

  2. 次のコマンドを実行してソリューションをアクティブ化します。

    Install-SPSolution solution_name.wsp -GACDeployment

サンドボックス ソリューションを展開するには

  1. 次の Windows PowerShell コマンドを実行し、ソリューションをサイト コレクション ソリューション ギャラリーにアップロードします。

    Add-SPUserSolution -LiteralPath full_path_to_solution -Site siteUrl

  2. 次のコマンドを実行してソリューションをアクティブ化します。

    Install-SPUserSolution solution_name.wsp -Site siteUrl

ソリューションを展開すると、フィーチャーが TEMPLATE\FEATURES フォルダーにコピーされ、マネージ アセンブリが GAC に配置され、その他のファイルが TEMPLATES の下のそれぞれのフォルダーに配置されます。これでフィーチャーをアクティブ化できるようになります。

ソリューションを取り消す必要がある場合は、次のどちらかの Windows PowerShell コマンドを使用します。

  • ファーム ソリューション: Uninstall-SPSolution solution_name.wsp

  • サンドボックス ソリューション: Uninstall-SPUserSolution solution_name.wsp -Site siteUrl

取り消したソリューションは、次のどちらかのコマンドを使用して削除できます。

  • ファーム ソリューション: Remove-SPSolution solution_name.wsp

  • サンドボックス ソリューション: Remove-SPUserSolution solution_name.wsp -Site siteUrl

Visual Studio 2010 のイベント レシーバー テンプレートを使用する

Visual Studio 2010 には、SharePoint イベント レシーバー用の 1 つのテンプレートを含めて、Microsoft Visual Basic と C# の両方の幅広い SharePoint プロジェクト テンプレートが用意されています。プロジェクト テンプレートを使用することで、サイト、リスト、ワークフロー、その他の共通項目など、SharePoint オブジェクトのイベントの処理が簡略化されます。

注意

この記事では、Visual Studio のイベント レシーバー用のプロジェクト テンプレートには焦点を当てません。このプロジェクト テンプレートは、SharePoint イベント モデルで発生するすべての技術的な詳細を、Visual Studio のプロジェクト テンプレートで隠されているものさえ提供するように作られているからです。とは言うのものの、このプロジェクト テンプレートを使用すると基本的なイベント レシーバーをいかに簡単に作成できるかをここで示します。

Visual Studio のイベント レシーバー プロジェクト テンプレートを使用してイベント レシーバー プロジェクトを作成すると、この記事のいくつかの手順は自動的に完了します。これには、アセンブリの作成と署名、イベントのバインド、ソリューションのパッケージ化、展開、およびデバッグ用のフィーチャーの作成などの手順が含まれます。

Visual Studio のイベント レシーバー プロジェクト テンプレートを使用して SharePoint イベント レシーバーを作成するには

  1. Visual Studio 2010 で、SharePoint 2010 イベント レシーバー テンプレートを使用して新しいプロジェクトを作成します。

  2. イベント レシーバー コードの実装に基づいて、SharePoint ソリューションの信頼レベルを選択します。ソリューションにディスク、ネットワーク、またはシステム レベルのアクセスが必要でない場合は、サンドボックス ソリューションを選択することをお勧めします。サンドボックス ソリューションの方が簡単で、使用されることが多いからです。

  3. オーバーライドするイベントを選択します。ここでは、ItemAdded イベントをオーバーライドして、Tasks リストにバインドします。

    • 使用するイベント レシーバーの種類: リスト項目イベント

    • イベント ソースとなる項目: Tasks

    • 処理するイベント: 項目が追加された

  4. [完了] をクリックします。

  5. ItemAdded イベントで、ユーザー設定コードを追加します。

  6. メニュー バーの [ビルド] をクリックし、[ソリューションの配置] をクリックします。

ソリューションがパッケージ化され、追加され、展開されます。イベント レシーバー コードにブレークポイントを設定し、デバッグすることもできます。

SharePoint イベント モデルの実際的な使用例については、この記事の第 2 部「SharePoint Foundation 2010 のイベント レシーバーを使用する (2/2)」を参照してください。

参考資料

詳細については、次のリソースを参照してください。