SharePoint Framework 拡張機能のテナント全体の展開

  • [アーティクル]

SharePoint Framework (SPFx) 機能拡張のテナント全体への展開オプションは、アプリケーション カスタマイザーとリスト ビュー コマンド セット向けにサポートされています。 これにより、テナント アプリ カタログ マネージャーに、既定で機能拡張をテナント全体でアクティブ化するか、サイトで使用される Web/リスト テンプレートに基づいてアクティブ化するかを管理するための簡単なオプションが提供されます。

注:

SharePoint Framework 機能拡張は、サイトの作成時に使用された実際のサイト テンプレートとは関係なく、モダン エクスペリエンスによってサポートされます。

開発者が標準的な SharePoint Framework Yeoman パッケージを使用して、新しい SharePoint Framework 拡張ソリューションを作成する場合、ソリューション パッケージにオートメーションが含まれ、テナント全体で拡張機能をアクティブにします。

警告

SharePoint Framework v1.6 から、テナント スコープの展開オプションを使用すると、既定のスキャフォールディングによって、テナント全体で機能拡張をアクティブ化するためのサンプル ファイルが SharePoint ソリューションに自動的に作成されます。

SharePoint Framework ソリューションは、テナント全体への展開機能を使用して、機能拡張をテナント全体で自動的にアクティブ化できるようにするために、SharePoint Framework ソリューションのテナント スコープ ソリューションの展開を使用するように構成する必要があります。 これは、package-solution.json の skipFeatureDeployment 属性をtrueとして設定する必要があることを意味します。

アプリ カタログ サイト コレクションからテナント全体への展開を制御する

アプリ カタログ サイト コレクションは、SharePoint アドインと SharePoint Framework コンポーネントをテナントに展開するために使用されます。 このサイト コレクションは、テナント管理者が作成し、実際のコンテンツ サイト コレクションのエンド ユーザーが利用できるようにするカスタマイズを管理するために使用します。

アプリ カタログ サイト コレクションには、テナント全体の機能拡張リストが含まれています。このリストは、テナントでの SharePoint Framework 機能拡張のアクティブ化を管理するために使用できます。 このリストには、アプリ カタログ サイトの [サイト コンテンツ] ページからアクセスできます。

特定の SharePoint Framework 機能拡張は、テナント全体の機能拡張リストにエントリを追加することで、テナント レベルでアクティブ化できます。 それぞれのエントリのターゲットは、機能要件に応じて特定の Web テンプレートにすることも、リストの種類にすることもできます。

これらのリスト固有の構成は、実行時にエンド ユーザーがコンテンツ サイト コレクションのページにアクセスしたときに解決されます。 つまり、このリストに適用された変更は、テナント内の既存のサイトと新しいサイトの両方で利用可能になるということです。

SharePoint Framework ソリューションにはソリューションが追加されるときに、テナント ワイド拡張機能リストに自動的にエントリーを自動的に追加するオートメーションを含めることができます。

重要

特定のテナントのテナント全体の機能拡張リストに最初のエントリが追加された後で、機能が使用できるようになるまでに最大で 20 分かかる場合があります。

テナント全体への展開リストの説明

コンポーネント ID がエントリを追加できるようにするには、テナントに存在する必要があります。

Column 種類 説明
Title String エントリのタイトル。 登録の際にわかりやすいエントリにしてください。
Component Id Guid コンポーネントのマニフェスト ID。 GUID 形式にする必要があります。また、アプリ カタログにコンポーネントが存在している必要があります。
Component Properties String 省略可能なコンポーネントのプロパティ。
Web Template String 機能拡張のターゲットを特定の Web テンプレートのみにするために使用できます。 指定可能な値については、次に示す表を参照してください。
List template int 数値形式のリストの種類。 指定可能な値は、次に示す表を参照してください。
Location String エントリの場所。 アプリケーション カスタマイザーおよびリスト ビュー コマンド セットに応じた、さまざまなサポートの場所があります。
Sequence int レンダリングでのエントリのシーケンス。
ホストのプロパティ 文字列 プレースホルダーに割り当てられている高さなどのサーバー側の追加構成。
無効 ブール型 エントリが有効であるか、無効であるか。

[Web Template] 列では、任意の Web テンプレート定義が技術的にサポートされます。 次の表では、最も一般的に使用されるテンプレートを定義しています。

テンプレート Web テンプレート ID
グループに関連付けられたチーム サイト GROUP#0
コミュニケーション サイト SITEPAGEPUBLISHING#0
グループのないモダン チーム サイト STS#3
クラシック チーム サイト STS#0
クラシック発行サイト BLANKINTERNET#0

[リスト テンプレート] 列では、任意のリスト ID が技術的にサポートされています。ただし、モダン エクスペリエンスのサポートはクラシック リストタイプの部分集合に限られます。

リスト リスト ID
カスタム リスト 100
ドキュメント ライブラリ 101

サポートされる場所の値は次のとおりです。 これらは、コンポーネントの種類に対して固有です。

Value コンポーネントの種類 説明
ClientSideExtension.ApplicationCustomizer アプリケーション カスタマイザー アプリケーション カスタマイザーに必要です。
ClientSideExtension.ListViewCommandSet.ContextMenu リスト ビュー コマンド セット リスト内のアイテムに対するコンテキスト メニューに [リスト ビュー] ボタンを表示します。
ClientSideExtension.ListViewCommandSet.CommandBar リスト ビュー コマンド セット リストのコマンド バーに [リスト ビュー] ボタンを表示します。
ClientSideExtension.ListViewCommandSet リスト ビュー コマンド セット コンテキスト メニューとコマンド バーの両方に [リスト ビュー] ボタンを表示します。

注:

技術的には、このリストによって、サイトからページがレンダリングされるときに Web またはリストの UserCustomAction コレクションに自動的に追加される動的エントリを定義します。 リストの情報はキャッシュされ、そのコンテンツは実行時にレンダリングするページの一部として出力されます。

ソリューション パッケージからテナント全体への展開を自動化する

選択した最初のコンポーネントタイプが拡張子の場合、SharePoint Framework ジェネレーターはファイル ./sharepoint/assets/ClientSideInstance.xml を新しいソリューションに追加します。

SharePoint クライアント側ソリューション ジェネレーター

ClientSideInstance.xml は、package-solution.json ファイル内で skipFeatureDeployment 属性が true に設定されている場合に、アプリ カタログでのソリューションのアクティブ化で考慮されます。

このファイルには、既定で次の構造が含まれています。 ClientSideComponentInstance 要素では、ソリューション パッケージがアプリ カタログに追加されたときに、自動的にテナント全体の展開リストにエントリを追加するように SharePoint に指示します。

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientSideComponentInstance
      Title="MyAppCust"
      Location="ClientSideExtension.ApplicationCustomizer"
      ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
      Properties="{&quot;testMessage&quot;:&quot;Test message&quot;}">
  </ClientSideComponentInstance>
</Elements>

SharePoint Framework ソリューションの作成時に選択したターゲット環境として [SharePoint Online のみ (最新)] を選択した場合、ClientSideInstance.xml ファイルも package-solution.json で参照されるため、ソリューションをパッケージ化するときに *.sppkg ファイルの内部に含まれます。

重要

別のターゲット環境を選択した場合、ClientSideInstance.xml ファイルはプロジェクトに追加されますが、package-solution.json ファイルには含まれません。 SharePoint Server 2019 (SharePoint Framework v1.4 が含まれます。詳細については、サポートされている機能を参照してください) はテナント スコープの展開をサポートしていますが、テナント全体の展開 (SharePoint Framework v1.6で追加されました。詳細については、拡張機能のテナント全体の展開を参照してください) はサポートしていません。

このファイルが package-solution.json で参照されている場合、生成された *.sppkg ファイルを SharePoint Server 2019 テナント アプリ カタログにアップロードすると、例外がスローされます。

注:

このファイルを *.sppkg ファイルに存在させたくない場合は、 package-solution.json ファイルを更新することで、パッケージ化プロセスから簡単に削除できます。

ClientSideComponentInstance 要素でサポートされる属性は次のとおりです。

属性 必須 説明
Title はい エントリのタイトル。 登録の際にわかりやすいエントリにしてください。
Location はい 機能拡張の登録に応じたエントリの場所
ComponentId はい コンポーネントのマニフェスト ID
Properties はい コンポーネントの省略可能なプロパティ。 これは、xml レベルで必須の属性である点に注意してください。必要なプロパティがない場合は、空の文字列として設定できます。 適切に値をエンコードすることで、プロパティの値を xml 形式で指定できるようにする必要もあります。
ListTemplateId いいえ 機能拡張をアクティブ化する必要のあるリスト テンプレートの種類の ID (省略可能)
WebTemplateId いいえ 機能拡張をアクティブ化する必要のあるサイトの種類を定義するための Web テンプレート ID (省略可能)
Sequence いいえ 機能拡張のアクティブ化の順序 (省略可能)。 複数の機能拡張が同じスコープでアクティブ化される場合に使用します。
HostProperties いいえ プレースホルダーに対して事前に割り当てられている高さの定義など、オプションのサーバー側構成。

次の xml 定義は、省略可能な値を登録の一環として使用できるようにする方法を示しています。

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientSideComponentInstance
      Title="MyAppCust"
      Location="ClientSideExtension.ApplicationCustomizer"
      ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
      Properties="{&quot;testMessage&quot;:&quot;Test message&quot;}"
      ListTemplateId="100"
      WebTemplateId="GROUP#0"
      Sequence="10"
      HostProperties="{&quot;preAllocatedApplicationCustomizerTopHeight&quot;:&quot;50&quot;,&quot;preAllocatedApplicationCustomizerBottomHeight&quot;:&quot;50&quot;}">
  </ClientSideComponentInstance>
</Elements>

管理者がその中に ClientSideInstance.xml ファイルを含むソリューションを App Catalog に追加すると、自動構成の存在が確実にわかっていることを確認するための特定の警告メッセージが表示されます。

テナント アプリ カタログに展開された SharePoint Framework パッケージを信頼する

ソリューションの展開後、管理者はテナント全体の機能拡張リストから展開の設定を変更できます。