プロバイダー向けのホスト型アドインに SharePoint の外観を付ける

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

これは、プロバイダーホストの SharePoint アドイン開発の基本に関する記事シリーズの 2 番目となるものです。まず、SharePoint アドインに関するトピックと、以下に示す、このシリーズの概要記事を理解しておいてください。

プロバイダーホスト型 SharePoint アドインの作成を始める

このシリーズの先行する記事では、開発環境を設定する方法と、Visual Studio を使用して、SharePoint データをアドインのリモート Web アプリケーションで公開する、最初の "Hello World" レベルのアドインを作成する方法について説明しました。

この記事では、既に作成されている SharePoint アドインソリューションから開始します。これには、ASP.NET Web フォームのアプリケーションと SQL Azure のデータベースが含まれています。これら一連の記事では SharePoint アドインにのみ焦点を合わせることを意図しているので、これらを作成しました。このシリーズの各記事において、アドインに SharePoint の機能と統合性をさらに追加することになります。

基本アドインの理解

このシリーズで ASP.NET や T SQL のプログラミングを学習することはありませんが、リモートコンポーネントの SharePoint への統合を始める前に、リモートコンポーネントについて少しは知っておく必要があります。アドインのシナリオでは、小売店のチェーンと、それぞれの小売店では親会社の SharePoint Online サブスクリプション上にチーム web サイトを有している状態を想定しています。ストアがアドインをチーム web サイト上にインストールすると、アドインにより、自身の SharePoint のデータとエクスペリエンスを親会社のデータベースのデータと統合することが可能になります。アドインの各インスタンスは企業のデータベース上に自身のテナント権を有し、ユーザーは自身のストアに関連した企業データとのみ対話することができます。

チェーンの 2 つのストア用のチームサイトを作成する

自身の SharePoint Online サイトのホームページを開き、[クイック起動] にあるサイトコンテンツのリンクを選択します。 サイトコンテンツのページで、新しいサブサイトのリンクが表示されるまで下にスクロールし、それを選択します。
[新しい SharePoint サイト] ページで、次の値を入力して新規チームサイト用のフォームに記入します (以下のスクリーンショットも参照)。
- タイトル: Fabrikam Hong Kong Store
- URL: hongkong
図 1. 新しい SharePoint サブサイトを作成するためのフォーム
その他の設定はすべて既定のままにしておき、[作成] を選択します。

アドインを探索する

SharePoint_Provider-hosted_Add-Ins_Tutorialsにアクセスし、[ZIP をダウンロード] ボタンをクリックしてリポジトリをデスクトップにダウンロードします。ファイルを解凍します。
Visual Studio を管理者として起動し、BeforeSharePointUI.sln を開きます。ソリューションには 3 つのプロジェクトがあります。
- ChainStore: SharePoint アドインプロジェクト
- ChainStoreWeb: リモート Web アプリケーション
- ChainCorporateDB: SQL Azure データベース。
ChainStore プロジェクトを選択し、プロパティ ウィンドウにおいて[サイト URL] プロパティには Hong Kong チームサイトの完全 URL である https://{YOUR_SHAREPOINT_DOMAIN}/hongkong/ を設定します (最後の "/" 文字も必ず含めること)。 [保存] を選択します。 このプロセス中のある時点で、SharePoint Online サブスクリプションにサインインするようにダイアログ表示されます。
ソリューションエクスプローラーの上部にあるソリューションノードを右クリックして、[スタートアッププロジェクト] を選択します。
3 つすべてのプロジェクトが [アクション] 列で [開始] に設定されていることを確認します。
F5 キーを使用して、アドインを展開して実行します。 Visual Studio は、IIS Express でリモート Web アプリケーションをホストして、SQL Express で SQL データベースをホストします。また、テスト用 SharePoint サイトにアドインを一時的にインストールして、すぐにアドインを実行します。開始ページが表示される前に、アドインへのアクセス許可を付与するように求められます。
アドインの開始ページは図 2 のようになります。最上部には、アドインがインストールされている SharePoint Web サイトの名前があります。これは、Visual Studio 用 Office Developer Tools によって生成されるいくつかのサンプルコードの副作用です。これは、後のステップで変更します。このページには、企業の注文、在庫、従業員の各 SQL データベーステーブルのデータを確認できる領域があります。これらのテーブルは、最初は空です。

図 2. チェーンストアアドインのスタートページ
ページ下部の [注文フォーム] のリンクを選択し、注文フォームを開きます。フォーム上でいくつかの値を入力した後、[注文] を選択します。図 3 のスクリーンショットに例を示します。何も起こらなかったように見えますが、ボタンの背後にあるコードにより、入力された値が SQL データベースのパラメーター化された保存プロシージャに引き渡されます。パラメーター化された保存プロシージャを使用することにより、データベースを SQL インジェクション攻撃から保護します。

図 3. 注文フォーム
ブラウザーの [戻る] ボタンを使用して開始ページに戻り、[注文を表示] ボタンを選択します。開始ページが最新情報に更新され、図 4 のスクリーンショットのように、自分の注文がページに表示されます。

図 4. [注文の表示] を選択した後のスタートページ

テーブルには [テナント] フィールドがあり、その値としてテスト用 SharePoint web サイトの URL が入っています。これは、時にテナント権とも呼ばれる SharePoint Online サブスクリプションのことを示しているのではありません。そうではなく、アドインの各インスタンスは企業データベース内では別々のテナントです。特定の SharePoint ホスト Web 上ではアドインを 1 インスタンスしかインストールできないため、ホスト Web の URL をデータベース内でのテナント識別子として使用できます。 (ホスト Web とアドイン Web の区別の復習には、「SharePoint アドイン」を参照してください。)

アドイン内のすべてのストアドプロシージャには、データベースに対して書き込みや読み取りを行う場合の識別子の値が含まれています。これにより、ユーザーが [注文を表示] (または [在庫を表示] あるいは [従業員を表示]) を選択した場合に、ユーザーのストアに関連したデータだけがデータベースから取得されることが保証されます。また、この設計により、ユーザーによる注文や従業員補充は自分のストアに対してのみ行えることが保証されます。

リモート Web アプリケーションは、SharePoint がアドインを起動する際に開始ページの URL に追加するクエリ文字列パラメーターから、ホスト Web の URL を取得します。 SSL を使用しているため、このクエリ文字列はインターネットを経由してリモート web アプリケーションに到達するまで暗号化されています。
デバッグセッションを終了するには、ブラウザーウィンドウを閉じるか、Visual Studio でデバッグを停止します。 F5 を選択するたびに、Visual Studio によって、以前のバージョンのアドインが取り消され、最新のバージョンがインストールされます。
既定では、アドインは Visual Studio のデバッグセッションの合間も SharePoint ホスト Web 上にインストールされたままとなります。アドインのインストール後にエンドユーザーがそれを起動する方法を調べるには、お使いのブラウザーで Fabrikam Hong Kong の SharePoint web サイトを開き、サイトコンテンツのページに移動します。アドインのタイルが、以下のスクリーンショットのように表示されます。

図 5. チェーンストアアドインの [起動] タイル

アドインのアイコンと名前が示された、サイトコンテンツページ上のチェーンストアアドイン用の起動タイル。

注:

タイルを選択しても、デバッグ停止時に Visual Studio が IIS Express セッションを閉じるので、開始ページは開かれません。

Visual Studio を、各デバッグセッションごとに企業データベースを再構築するようにを構成する

既定では、Visual Studio は SQL Express データベースを再構築 しません 。したがって、1 回のデバッグセッションでデータベースに追加した注文その他のアイテムは、後のセッションでもデータベースに残ったままです。 F5 を選択するたびに空のデータベースで開始した方が簡単なので、以下のステップのようにします。

ChainCorporateDB プロジェクトを右クリックして、[プロパティ] を選択します。
[デバッグ] タブを開き、[データベースを常に再作成する] オプションを有効にします。

リモート Web アプリケーションに SharePoint の外観を与える

シナリオによってはリモートページ独自のブランド化を行いますが、ほとんどの場合は、ユーザーが依然として SharePoint を使用しているかのように感じるように、SharePoint の UI を模倣する必要があります。

SharePoint のクロムとトップバーを開始ページに追加する

ソリューションエクスプローラーで、ChainStoreWeb>ページ に移動し、CorporateDataViewer.aspx ファイル (アドインの開始ページ) を開きます。

見出しセクションには、JavaScript のライブラリを読み込むスクリプトがあります。その下に、以下のスクリプトを追加します。このスクリプトは、/_layouts/15/ フォルダーのすべての SharePoint Web サイトにあるSP.UI.Controls.js ファイルを読み込みます。このファイルは他の機能に加え、SharePoint CSS ライブラリの読み込みを行います。

  <script type="text/javascript">
    var hostweburl;

    // Load the SharePoint resources.
    $(document).ready(function () {

        // Get the URI decoded add-in web URL.
        hostweburl =
            decodeURIComponent(
                getQueryStringParameter("SPHostUrl")
        );

        // The SharePoint js files URL are in the form:
        // web_url/_layouts/15/resource.js
        var scriptbase = hostweburl + "/_layouts/15/";

        // Load the js file and continue to the 
        // success handler.
        $.getScript(scriptbase + "SP.UI.Controls.js")
    });

    // Function to retrieve a query string value.
    function getQueryStringParameter(paramToRetrieve) {
        var params =
            document.URL.split("?")[1].split("&amp;");
        var strParams = "";
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
        }
    }
</script>

ページの本文セクションの上部に、次のマークアップを追加します。これにより、ページにクロムコントロールと呼ばれる SharePoint のトップバーが追加されます。このマークアップの詳細は、この記事の後の方で、改訂されたアドインをテストするときに明らかになります (いくつかのプロパティ名には "app" の文字列が含まれていますが、これは、アドインは以前は「アプリ」と呼ばれていたからです)。

  <!-- Chrome control placeholder. Options are declared inline.  -->
<div 
    id="chrome_ctrl_container"
    data-ms-control="SP.UI.Controls.Navigation"  
    data-ms-options=
        '{  
            "appHelpPageUrl" : "Help.aspx",
            "appIconUrl" : "/Images/AppIcon.png",
            "appTitle" : "Chain Store",
            "settingsLinks" : [
                {
                    "linkUrl" : "Account.aspx",
                    "displayName" : "Account settings"
                },
                {
                    "linkUrl" : "Contact.aspx",
                    "displayName" : "Contact us"
                }
            ]
         }'>
</div>

H1 ヘッダーとページ本体内のハイパーリンクは SharePoint の CSS ライブラリで定義されたスタイルを自動的に使用するので、変更する必要はありません。 SharePoint スタイルの使用方法を示すため、3 つの GridView コントロールの列見出しを SharePoint の「すべて大文字」スタイルに設定します。そうするために、各コントロールに HeaderStyle-CssClass 属性を追加し、その値を ms-uppercase に設定します。次に例を示します。同様の変更を 3 つすべての GridView コントロールに行います。
```
  <asp:GridView ID="ordersGridView" runat="server" CellPadding="5" GridLines="None" 
HeaderStyle-CssClass="ms-uppercase" />
```
クロムコントロールはアドインのアイコンを使用するので、リモート Web サーバー上にはアイコンファイルの 2 個目のコピーが必要です。 ソリューションエクスプローラーで、ChainStore プロジェクト内の AppIcon.png のファイルを右クリックして、[コピー] を選択します。
ChainStoreWeb プロジェクト内の [画像] フォルダーを右クリックし、[貼り付け] を選択します。
CorporateDataViewer.aspx.cs ファイルを開きます。
CorporateDataViewer クラスは SharePointContext タイプのプライベートメンバーを宣言します。このクラスは、プロジェクト作成時に Visual Studio 用 Office Developer Tools が生成した SharePointContext.cs ファイルの中で定義されています。これは、ASP.NET の HttpContextBase クラスのようなものと考えられますが、ホスト Web の URL などの SharePoint コンテキスト情報を追加したものです。

Page_Load メソッドでは、using ステートメントは、リモートの開始ページに SharePoint ホスト Web の名前を書き込みます。これはサンプルコードなので、using ステートメント全体を削除します (ただし、spContext 変数を初期化する行は残します)。メソッドは、次のようになります。
```
  protected void Page_Load(object sender, EventArgs e)
{
    spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
}
```
SharePoint UI を必要とする ASP.NET ファイルが他に 4 つあります。
- Account.aspx
- Contact.aspx
- Help.aspx
- OrderForm.aspx
注:

プロジェクトに残っている aspx ファイル EmployeeAdder.aspx は実際にレンダリングされることはないので、この UI は変更しません。詳しくは、このシリーズの以降の記事で学習します。

これらのページにクロムコントロールは必要ありません。 SharePoint CSS ライブラリへのアクセスが必要なだけです。これら 4 ファイルのそれぞれにおいて、以下のマークアップを見出し要素に追加します。
```
  <link type="text/css" rel="stylesheet" 
href="<%= spContext.SPHostUrl.ToString() + "_layouts/15/defaultcss.ashx" %>" />
```
このステップと次のステップは、注文フォームのページとアカウントのページに関しては既に行われているので、連絡先のページとヘルプのページにのみ適用されます。各ページにオブジェクトを spContext 取得するには、3 つの aspx ページのファイルの背後にある *.aspx.cs コードを開きます。それぞれにおいて、Page クラスに以下のメンバーを追加します。
```
  protected SharePointContext spContext;
```
Page_Load メソッドを次のバージョンに置き換えます。オブジェクトはセッションキャッシュから取得されます。これは、初めて作成されたときにアドインのスタートページの Page_Load メソッドによりキャッシュされたものです。
```
  protected void Page_Load(object sender, EventArgs e)
{
    spContext = Session["SPContext"] as SharePointContext;
}
```
OrderForm.aspx ページを開きます。最上部のラベル要素において、注文という語句の <b> 要素を ms-accentText CSS クラスを参照する span タグに置き換えます。完了時には、ラベル コントロールは全体として以下のようになるはずです。
```
  <asp:Label ID="lblOrderPrompt" runat="server"
         Text="Enter a supplier, product, and quantity; and then press <span class='ms-accentText'>Place Order</span>.">
</asp:Label>
```

アドインを実行して新しい SharePoint UI をテストする

F5 キーを使用して、アドインを展開して実行します。 Visual Studio は、IIS Express でリモート Web アプリケーションをホストして、SQL Express で SQL データベースをホストします。また、テスト用 SharePoint サイトにアドインを一時的にインストールして、すぐにアドインを実行します。開始ページが表示される前に、アドインへのアクセス許可を付与するように求められます。
アドインの開始ページが開くと、SharePoint ページのように見えるようになります。 注文フォームのリンクを選択します。これも、SharePoint のフォームのように見えます。

図 6. Segoe フォントと強調表示された注文フォーム
注文を作成し、[注文する] を選択します。
ブラウザーの [戻る] ボタンを使用してアドインの開始ページに戻り、[注文を表示] を選択します。ページは以下の表示に似たものになっているはずです。列見出しがすべて大文字になっていることに注意してください。

図 7. Chrome コントロールを含むスタートページ
クロムコントロールの末尾にある [? ] アイコンを選択します。シンプルなヘルプのページが開きます。ブラウザーの [戻る] ボタンを選択します。
クロムコントロール上の歯車アイコンを選択します。アカウントページと連絡先ページへのリンクがあるメニューが開きます。アカウントページを開き、ブラウザーの [戻る] ボタンを使用して開始ページに戻ります。連絡先ページについても同様にします。
クロムコントロール上の [サイトに戻る] ボタンを選択します。ホスト Web のホームページである Hong Kong store のチームサイトが開きます。
トップバーの歯車アイコンをクリックしてから [外観の変更] を選択します。
ダイアログ表示に従い、サイトを代替の「外観」のいずれかに変更します。
[サイトコンテンツ] ページに移動し、そのタイルからチェーン店アプリを起動します。カスタムページは選択した外観になります。次のスクリーンショットは、[ナチュラル] で構成された外観を表しています。

図 8. Nature で構成された外観のスタートページと注文フォーム

自然構成外観の緑がかった色の、アドインの開始ページと注文フォーム。

サイトの外観を、オフィス と呼ばれる既定値に戻します。
デバッグセッションを終了するには、ブラウザーウィンドウを閉じるか、Visual Studio でデバッグを停止します。 F5 キーを押すたびに、Visual Studio によって、以前のバージョンのアドインが取り消され、最新のバージョンがインストールされます。
このアドインおよび他の記事の Visual Studio ソリューションを操作し、それが終了したら前回のアドインを取り消すとよいでしょう。 ソリューションエクスプローラーでプロジェクトを右クリックして、[取り消し] を選択します。

次の手順

この時点でアドインは SharePoint に似ていますが、依然として単なる Web アプリケーションで、SharePoint と実際に統合しておらず、SharePoint 内のタイルから起動できません。次の記事「プロバイダー向けのホスト型アドインにカスタムボタンを含める」で、カスタムリボンボタンから起動するカスタムコマンドを追加します。

プロバイダー向けのホスト型アドインに SharePoint の外観を付ける

基本アドインの理解

チェーンの 2 つのストア用のチーム サイトを作成する