プロバイダー向けのホスト型アドインにカスタムボタンを含める

[アーティクル]
04/08/2023

これは、プロバイダーホスト型の SharePoint アドインの開発の基本に関する記事のシリーズの 3 番目です。SharePoint アドインとこのシリーズの前の記事 (プロバイダーホスト型の SharePoint アドインの作成を始めるにある記事) をよく理解しておいてください。

注:

プロバイダーホスト型アドインに関するこのシリーズに沿って作業してきた場合は、このトピックでも引き続き使用できる Visual Studio ソリューションを既に所有しています。また、「SharePoint_Provider-hosted_Add-Ins_Tutorials」でリポジトリをダウンロードして BeforeRibbonButton.sln ファイルを開くこともできます。

SharePoint アドインには、カスタムアクションを組み込むことができます。これは、カスタムメニュー項目またはリボンボタンを指す SharePoint の用語です。この記事では、SharePoint のリストをリモートデータベースと同期するカスタムボタンを作成する方法について説明します。

ホスト Web サイト上にカスタムリストを作成する

カスタムボタンは、ローカルストアの従業員を記録する特定のリストのリボン上に配置します。このシリーズの後半の記事では、プログラム的にホスト Web サイトにカスタムリストを追加する方法について説明します。

Fabrikam Hong Kong ストアのホームページから、[サイトコンテンツ]>[アドインを追加]>[カスタムリスト] に移動します。
[カスタムリストの追加] ダイアログで、「現地の従業員」を名前として指定し、[作成] を選択します。
[サイトコンテンツ] ページで、[現地の従業員] リストを開きます。
リボンの [リスト] タブで、[リストの設定] を選択します。
[リストの設定] ページの [列] セクションで、[タイトル] 列を選択します。
[列の編集] フォームで、[列名] を「Title」から「名前」に変更し、[OK] を選択します。
[設定] ページで、[列の作成] を選択します。
[列の作成] フォームで、以下を実行します。
1. [列名] には、「企業 DB に追加済み」と入力します。
2. タイプを [はい/いいえ (チェックボックス)] に設定します。
3. [既定値] を [いいえ] に設定します。
4. [OK] を選択します。 [設定] ページに戻ります。
[サイトコンテンツ] を選択して、[サイトコンテンツ] ページを開きます。新しいリストのタイルがあります。それを開きます。
[新しいアイテム] をクリックして、アイテム作成フォームで名前を入力します。ただし、[企業 DB に追加済み] は選択しないでください。 [保存] を選択します。リストは、次のようになります。

図 1. 1 つの項目を含むローカル従業員リスト

カスタムボタンを追加する

このセクションでは、リストのリボンにボタンを配置するアドインのマークアップを含めます。ユーザーがリストで従業員を強調表示しボタンを選択すると、従業員の名前が企業のデータベースに追加され、その従業員の [企業 DB に追加済み] フィールドは、No から Yes に切り替えられます。

Visual Studio が開いている場合は、一度閉じてから Chain Store ソリューションをもう一度開き、Visual Studio が新しいリストを検出できるようにする必要があります (管理者として Visual Studio を実行します)。
注:

Visual Studio のスタートアッププロジェクトの設定は、ソリューションが開かれるたびに、既定値に戻される傾向があります。このシリーズ記事のサンプルソリューションを再開した直後は、次の手順を必ず実行してください。
1. ソリューションエクスプローラーの上部にあるソリューションノードを右クリックして、[スタートアッププロジェクトの設定] を選択します。
2. 3 つすべてのプロジェクトが [アクション] 列で [開始] に設定されていることを確認します。
ソリューションエクスプローラーで [ChainStore] プロジェクトを右クリックして、[追加]>[新しいアイテム] を選択します。
[新しいアイテムの追加] ダイアログで、[リボンのカスタムアクション] を選択し、「AddEmployeeToCorpDB」という名前を付けて、[追加] を選択します。

ダイアログボックスが開き、次の 3 つの質問がたずねられます。次のように回答してください。

質問	この回答を入力：
カスタムアクションの公開先はどこにしますか?	ホスト Web
カスタムアクションのスコープ先はどこにしますか?	リストインスタンス
どの特定項目をカスタムアクションのスコープ先にしますか	現地の従業員

[次へ] を選択すると、さらに 3 つの質問が表示されます。

質問	この回答を入力：
コントロールの位置はどこですか	リボンリストアイテムアクション
ボタンコントロールのラベルテキストは何ですか?	企業 DB への追加
ボタンコントロールによる移動先はどこですか?	ChainStoreWeb\Pages\EmployeeAdder.aspx (これは、分離コードが従業員をデータベースに追加するページです)

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

カスタムアクションを定義する elements.xml ファイルがプロジェクトに追加され、開かれます。ほとんどの場合、このファイルをブラックボックスとして扱うことができます。このシリーズの後の記事まで、このファイルを変更する必要はありません。ここでは、以下の点だけに注意してください。
- CommandUIDefinition 要素の Location 属性には、値 Ribbon.ListItem.Actions.Controls_children があります。この 2 番目の部分 ListItem は、ボタンが配置されるリボンのタブを識別します (ただし、タブの正確な表示名ではない可能性があります)。 3 番目の部分 Actions は、ボタンが配置されるリボンのセクションの名前です。
- CommandUIHandler 要素の CommandAction 属性は、プレースホルダー ~remoteAppUrl で始まります。これは、ボタンが配置されたときにリモート Web アプリケーションの URL に置き換わります。
- いくつかのクエリパラメーターが、かっこ "{ }" で囲まれたプレースホルダーの値で CommandAction 値に追加されています。これらのプレースホルダーは、実行時に解決されます。そのうちの 1 つは、リボンのカスタムボタンを選択する前にユーザーが選択したリストアイテムの ID となることに注意してください。
ChainStoreWeb プロジェクトで、Pages/EmployeeAdder.aspx ファイルを開きます。これには UI が含まれていないことに注意してください。アドインは、このページを一種の Web サービスとして使用します。これは、ASP.NET System.Web.UI.Page クラスが System.Web.IHttpHandler を実装し、ページが要求されたときに Page_Load イベントが自動的に実行されるためです。
分離コードファイル Pages/EmployeeAdder.aspx.cs を開きます。従業員をリモートデータベースに追加するメソッド AddLocalEmployeeToCorpDB が既に存在しています。そのメソッドは SharePointContext オブジェクトを使用してホスト Web の URL を取得し、アドインはそれをそのテナントの識別子として使用します。 Page_Load メソッドが最初に実行する必要があるのは、このオブジェクトの初期化です。アドインの開始ページの読み込み時にオブジェクトが作成されて、セッションにキャッシュされるため、次のコードを Page_Load メソッドに追加してください。 (SharePointContext オブジェクトは SharePointContext.cs ファイルで定義されています。このファイルは Office Developer Tools for Visual Studio がアドインソリューションの作成時に生成したものです。)
```
spContext = Session["SPContext"] as SharePointContext;
```
AddLocalEmployeeToCorpDB メソッドは、従業員の名前をパラメーターと見なすため、次の行を Page_Load メソッドに追加してください。 GetLocalEmployeeName メソッドは後の手順で作成します。
```
// Read from SharePoint 
string employeeName = GetLocalEmployeeName();
```
この行の下に、AddLocalEmployeeToCorpDB メソッドの呼び出しを追加します。
```
// Write to remote database 
AddLocalEmployeeToCorpDB(employeeName);
```
名前空間 Microsoft.SharePoint.Clientのファイルに using ステートメントを追加します。 (Office Developer Tools for Visual Studio には、 作成時に ChainStoreWeb プロジェクトに Microsoft.SharePoint.Client アセンブリが含まれていました)。
続いて、次のメソッドを EmployeeAdder クラスに追加します。 SharePoint .NET クライアント側オブジェクトモデル (CSOM) については、MSDN の他の場所で詳細に説明されているため、この一連の記事の閲読を終えた後に調べてみることをお勧めします。この記事では、ListItem クラスは SharePoint リスト内のアイテムを表すことと、アイテム内のフィールドの値は "indexer" 構文で参照できることに注意してください。また、フィールド名を「名前」に変更していても、コードはフィールドを「Title」として参照していることにも注意してください。これはコード内では、フィールドは常に表示名ではなく内部名で参照されるためです。フィールドの内部名は、フィールドの作成時に設定され、決して変更できません。 TODO1 については、後の手順で説明します。
```
private string GetLocalEmployeeName()
{
  ListItem localEmployee;

  // TODO1: Initialize the localEmployee object by getting  
  // the item from SharePoint.

  return localEmployee["Title"].ToString();
}
```
このコードでは、SharePoint から取得できるようになる前に、リストアイテムの ID を必要とします。次の宣言を spContext オブジェクトの宣言のすぐ下にある、EmployeeAdder クラスに追加します。
```
private int listItemID;
```
続いて、次のメソッドを EmployeeAdder クラスに追加し、クエリパラメーターからリストアイテムの ID を取得します。
```
private int GetListItemIDFromQueryParameter()
{
  int result;
  Int32.TryParse(Request.QueryString["SPListItemId"], out result);
  return result;
}
```
listItemID 変数を初期化するには、spContext 変数を初期化する行のすぐ下の Page_Load メソッドに次の行を追加します。
```
listItemID = GetListItemIDFromQueryParameter();
```

GetLocalEmployeeName で、TODO1 を次のコードに置き換えます。当面はこのコードを単なるブラックボックスと見なし、カスタムボタンの処理に専念します。このコードについては、SharePoint クライアント側オブジェクトモデルについて扱っている、このシリーズの次の記事で詳しく説明します。

using (var clientContext = spContext.CreateUserClientContextForSPHost())
{
  List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
  localEmployee = localEmployeesList.GetItemById(listItemID);
  clientContext.Load(localEmployee);
  clientContext.ExecuteQuery();
}

メソッド全体は次のようになります。

private string GetLocalEmployeeName()
{
  ListItem localEmployee;

  using (var clientContext = spContext.CreateUserClientContextForSPHost())
  {
    List localEmployeesList = clientContext.Web.Lists.GetByTitle("Local Employees");
    selectedLocalEmployee = localEmployeesList.GetItemById(listItemID);
    clientContext.Load(selectedLocalEmployee);
    clientContext.ExecuteQuery();
  }
  return localEmployee["Title"].ToString();
}

EmployeeAdder ページは実際にはレンダリングしないため、以下を Page_Load メソッドの最後の行として追加します。これにより、ブラウザーは [現地の従業員] リストのリストビューページに戻ります。

// Go back to the Local Employees page
Response.Redirect(spContext.SPHostUrl.ToString() + "Lists/Local%20Employees/AllItems.aspx", true);

Page_Load メソッド全体は次のようになります。

protected void Page_Load(object sender, EventArgs e)
{
  spContext = Session["SPContext"] as SharePointContext;
  listItemID = GetListItemIDFromQueryParameter();

  // Read from SharePoint
  string employeeName = GetLocalEmployeeName();

  // Write to remote database
  AddLocalEmployeeToCorpDB(employeeName);

  // Go back to the preceding page
  Response.Redirect(spContext.SPHostUrl.ToString() + "Lists/Local%20Employees/AllItems.aspx", true);
}

ホスト Web リストを読み取るアクセス許可を要求する

これまで見てきたように、SharePoint は、アドインのインストール時に、そのアドインにホスト Web へのアクセス許可を付与するように求めます。 F5 キーを選択するたびにアドインが再インストールされてきました。ここまでは、アドインに必要なアクセス許可は最小限でしたが、GetLocalEmployeeName メソッドでは、ホスト Web サイトのリストを読み取るアクセス許可が必要になります。アドインは、アドインマニフェストを使用して、必要なアクセス許可を SharePoint に通知します。以下の手順を実行します。

ソリューションエクスプローラーで、ChainStore プロジェクトの AppManifest.xml ファイルを開きます (アドインは以前「アプリ」と呼ばれていたため、このファイルは AppManifest と呼ばれます)。マニフェストデザイナーが開きます。
[アクセス許可] タブを開き、[スコープ] 列の下の空のセルを選択して、ドロップダウンから [リスト] を選択します。
[アクセス許可] フィールドで、ドロップダウンから [読み取り] を選択します。
[プロパティ] フィールドを空のままにし、ファイルを保存します。 [アクセス許可] タブは次のようになります。

図 2. [アクセス許可] タブ

アドインを実行してボタンをテストする

F5 キーを使用して、アドインを展開して実行します。 Visual Studio は、IIS Express でリモート Web アプリケーションをホストして、SQL Express で SQL データベースをホストします。また、テスト用 SharePoint サイトにアドインを一時的にインストールして、すぐにアドインを実行します。開始ページが表示される前に、アドインへのアクセス許可を付与するように求められます。ここでは、次のスクリーンショットに示されているように、プロンプトにドロップダウンが表示され、アプリが読み取る必要があるリストを選択できます。

図 3. SharePoint アドインのアクセス許可プロンプト
リストから [現地の従業員] を選択して、[信頼する] を選択します。
アドインの開始ページが開いたら、上部のクロムコントロールにある [サイトに戻る] リンクを選択します。
Web サイトのホームページから、[サイトコンテンツ]>[現地の従業員] に移動します。リストビューページが開きます。
数名の従業員をリストに追加します。 [企業 DB に追加済み] チェックボックスは選択しないでください。
リボンで、[アイテム] タブを開きます。タブの [アクション] セクションに、カスタムボタン [企業 DB に追加] があります。
リストからアイテムを選択します。ページとリボンは、次のように表示されます。

図 4. ローカル従業員一覧
リストからアイテムを選択後、[企業 DB に追加] を選択します。
EmployeeAdder ページの Page_Load メソッドがそのページにリダイレクトするため、再読み込みされているように見えます。
ブラウザーの戻るボタンを 2 回押して、アドインの開始ページに移動します。
[従業員の表示] を選択すると、追加した従業員が従業員のリストに入力されます。次のようになります。

図 5. アドインのスタートページの会社の従業員の一覧
デバッグセッションを終了するには、ブラウザーウィンドウを閉じるか、Visual Studio でデバッグを停止します。 F5 キーを選択するたびに、Visual Studio は以前のバージョンのアドインを取り消し、最新のバージョンをインストールします。
このアドインおよび他の記事の Visual Studio ソリューションを操作し、それが終了したら前回のアドインを取り消すとよいでしょう。 ソリューションエクスプローラーでプロジェクトを右クリックして、[取り消し] を選択します。

次の手順

次の記事では、コーディングからは少し離れて、SharePoint クライアント側オブジェクトモデルの概要について簡単に説明します。

プロバイダー向けのホスト型アドインにカスタム ボタンを含める

ホスト Web サイト上にカスタム リストを作成する

カスタム ボタンを追加する