SharePoint アセットとソリューション パッケージのプロビジョニング
場合によっては、クライアント側のソリューション パッケージと同時に SharePoint リストやドキュメント ライブラリをプロビジョニングして、リストやライブラリを Web パーツなどのクライアント側コンポーネントで使用できるようにする必要があります。 SharePoint Framework ツールチェーンを使用すると、SharePoint アイテムとクライアント側のソリューション パッケージをパッケージ化して展開できます。 これらのアイテムは、クライアント側のソリューションがサイトにインストールされたときにプロビジョニングされます。
プロビジョニング オプションに関する詳細は、Microsoft 365 プラットフォーム コミュニティ (PnP) YouTube チャンネルにある SharePoint PnP の Web キャストも参照してください。
JavaScript コードを使用してアイテムをプロビジョニングする
Web パーツなどのコンポーネントで JavaScript コードを使用して SharePoint アイテムを作成できますが、そのコンポーネントを使用する現在のユーザーのコンテキストに限定されます。 ユーザーが SharePoint アイテムを作成したり変更したりするための十分な権限を持っていない場合、JavaScript コードはこれらのアイテムをプロビジョニングしません。 そのような場合、昇格されたコンテキストで SharePoint アイテムをプロビジョニングするときには、ソリューション パッケージと同時にアイテムをパッケージ化して展開する必要があります。
ソリューションの SharePoint アイテムをプロビジョニングする
クライアント側のソリューション パッケージと同時に、次に示す SharePoint アセットをプロビジョニングできます。
- フィールド
- コンテンツ タイプ
- インスタンスの一覧表示
- カスタム スキーマを使用するリスト インスタンス
フィールド
フィールドまたはサイトの列は、ユーザーが列を追加したリストのアイテムまたはコンテンツタイプに対して管理する必要がある属性 (またはメタデータの一部) を表します。 これは再利用可能な列定義 (またはテンプレート) であり、複数の SharePoint サイト間で複数のリストに割り当てることができます。 サイトの列は作業のやり直しを減らし、サイトとリストとの間でメタデータの一貫性を保つために役立ちます。
たとえば、Customer という名前のサイト列を定義するとします。 ユーザーはその列をリストに追加して、コンテンツ タイプでそれを参照することができます。 これにより、列がどこに表示されても、(少なくとも最初は) 列に同じ属性があることが保証されます。
「Field 要素 (フィールド)」ドキュメントのスキーマと属性を参照して、ソリューションの新しいフィールドを定義できます。
新しい DateTime フィールドの例を次に示します。
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
コンテンツ タイプ
コンテンツ タイプは、SharePoint のリストまたはドキュメント ライブラリにあるアイテムまたはドキュメントのカテゴリに対する、メタデータ (列)、動作、およびその他の設定をまとめて再利用できるようにしたものです。 コンテンツ タイプを使用することで、情報のカテゴリに対する設定を再利用可能な方法で一元的に管理できるようになります。
たとえば、次のような 3 種類のドキュメントがあるビジネスの状況を考えてみましょう。経費明細書、発注書、請求書です。 これらのドキュメントには共通の特徴があります。すべて財務報告書で、通貨の値を持つデータが含まれています。 とはいえ、それぞれのドキュメントには独自のデータ要件、独自のドキュメント テンプレート、独自のワークフローがあります。
このビジネス上の問題に対する 1 つの解決策は、4 つのコンテンツ タイプを作成することです。 最初のコンテンツ タイプである Financial Document は、組織のすべての財務報告書に共通するデータ要件をカプセル化します。 残りの 3 つ、Expense Report、Purchase Order、Invoice は、Financial Document から共通の要素を継承します。 さらに、メタデータの特定のセット、新しいアイテムの作成に使用するドキュメント テンプレート、アイテムを処理する特定のワークフローなど、それぞれのタイプに特有の特徴を定義することができます。
「ContentType 要素 (コンテンツ タイプ)」ドキュメントのスキーマと属性を参照して、ソリューションの新しいコンテンツ タイプを定義できます。
コンテンツ タイプの例を次に示します。
<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
Name="Cost Center"
Group="Financial Content Types"
Description="Financial Content Type">
<FieldRefs>
<FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
<FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
</FieldRefs>
</ContentType>
リスト インスタンス
リストは SharePoint サイトの主要な基本機能です。 これにより、チームは情報を収集、追跡、共有できます。 多くのアプリケーションが、データ保存のためにサイトで作成されたリストに依存して、それらの動作を実装しています。 リスト インスタンスは、既知の識別子を持つ定義済みの SharePoint リストです。 アイテムをカスタマイズしてこれらのリストに追加したり、既に使用可能なリスト テンプレートから追加のリストを作成したり、選択した設定と列のみを使用してカスタム リストを作成することができます。
SharePoint には、連絡先リスト、予定表、タスク リストなど、いくつかのリスト テンプレートが用意されています。 これらのテンプレートを使用して、Web パーツや他のコンポーネント用に新しいリスト インスタンスを作成できます。 たとえば、Document Library テンプレートに基づいてリスト インスタンスの Finance Documents を定義して、関連するドキュメントを Web パーツに格納できます。
「ListInstance 要素 (リスト インスタンス)」ドキュメントのスキーマと属性を参照して、ソリューションのリスト インスタンスを定義できます。
リスト インスタンス定義の例を次に示します。
<ListInstance
FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
Title="Finance Records"
Description="Finance documents"
TemplateType="101"
Url="Lists/FinanceRecords">
</ListInstance>
カスタム スキーマを使用するリスト インスタンス
カスタム リスト スキーマ定義を使用すると、フィールド、コンテンツ タイプ、およびリスト インスタンスで使用されるビューを定義できます。 リスト インスタンスのカスタム スキーマを参照するには、ListInstance 要素の CustomSchema 属性を使用します。
たとえば、組織のすべての財務報告書に共通するデータ要件をカプセル化する、コンテンツ タイプが Financial Document のリスト インスタンス Finance Documents を定義できます。
カスタム スキーマを使用するリスト インスタンス定義の例を次に示します。
<ListInstance
CustomSchema="schema.xml"
FeatureId="00bfea71-de22-43b2-a848-c05709900100"
Title="Cost Centers"
Description="Cost Centers"
TemplateType="100"
Url="Lists/CostCenters">
</ListInstance>
次に、以前に定義したリスト インスタンスのコンテンツ タイプを定義するカスタム スキーマの定義を示します。
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
<MetaData>
<ContentTypes>
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
</ContentTypes>
<Fields></Fields>
<Views>
<View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
<XslLink Default="TRUE">main.xsl</XslLink>
<JSLink>clienttemplates.js</JSLink>
<RowLimit Paged="TRUE">30</RowLimit>
<Toolbar Type="Standard" />
<ViewFields>
<FieldRef Name="LinkTitle"></FieldRef>
<FieldRef Name="SPFxAmount"></FieldRef>
<FieldRef Name="SPFxCostCenter"></FieldRef>
</ViewFields>
<Query>
<OrderBy>
<FieldRef Name="ID" />
</OrderBy>
</Query>
</View>
</Views>
<Forms>
<Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
<Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
<Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
</Forms>
</MetaData>
</List>
ソリューションの SharePoint アイテムを作成する
ソリューション パッケージは、「SharePoint のフィーチャー」を使用して、SharePoint アイテムをパッケージ化し、プロビジョニングします。 フィーチャーとは、プロビジョニングする SharePoint アイテムを 1 つ以上含むコンテナーです。 フィーチャーには Feature.xml ファイルと 1 つ以上の要素のマニフェスト ファイルが含まれています。 これらの XML ファイルは、フィーチャー定義とも呼ばれます。
通常、クライアント側のソリューション パッケージには、1 つのフィーチャーが含まれています。 このフィーチャーは、ソリューションがサイトにインストールされるとアクティブ化されます。 サイト管理者はフィーチャーではなくソリューション パッケージをインストールすることに注意してください。
フィーチャーは、主に次の XML ファイルを使用して構築されます。
要素のマニフェスト ファイル
要素のマニフェスト ファイルには、SharePoint アイテムの定義が含まれ、フィーチャーがアクティブ化されたときに実行されます。 たとえば、要素のマニフェストには、新しいフィールド、コンテンツ タイプ、またはリスト インスタンスを作成するための XML 定義が含まれます。
新しい DateTime フィールドを定義する、要素のマニフェスト ファイルの例を次に示します。
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
</Elements>
要素ファイル
サポートされるファイルで要素のマニフェストに付随するものは、要素ファイルです。 たとえば、リスト インスタンスのスキーマは、要素のマニフェストで定義されたリスト インスタンスに関連付けられた要素ファイルです。
カスタム リスト インスタンスのスキーマの例を次に示します。
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
<MetaData>
<ContentTypes>
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
</ContentTypes>
</MetaData>
</List>
アップグレード アクション ファイル
名前からわかるように、これは、ソリューションがサイトで更新されるときのアップグレード アクションが含まれるファイルです。 アップグレード アクションの一部として、アクションは 1 つまたは複数の要素のマニフェストを含むように指定することもできます。 たとえば、アップグレードで新しいフィールドを追加する必要がある場合、フィールド定義は要素のマニフェストとして使用可能であり、アップグレード アクション ファイルに関連付けられます。
アップグレード中に要素のマニフェスト ファイルを適用するアップグレード アクション ファイルの例を次に示します。
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
SharePoint フィーチャーを構成する
XML ファイルを含めるには、まず、プロジェクトの config フォルダーの下にある package-solution.json 構成ファイルで、フィーチャーの構成を定義する必要があります。 package-solution.json にはクライアント側のソリューション パッケージに関する主要なメタデータ情報が含まれており、ソリューションを .sppkg ファイルにパッケージ化する package-solution gulp タスクを実行するときに参照されます。
{
"solution": {
"name": "hello-world-client-side-solution",
"id": "26364618-3056-4b45-98c1-39450adc5723",
"version": "1.1.0.0",
"features": [{
"title": "hello-world-client-side-solution",
"description": "hello-world-client-side-solution",
"id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
"version": "1.1.0.0",
"assets": {
"elementManifests": [
"elements.xml"
],
"elementFiles":[
"schema.xml"
],
"upgradeActions":[
"upgrade-actions-v1.xml"
]
}
}]
},
"paths": {
"zippedPackage": "solution/hello-world.sppkg"
}
}
次の表で示されているように、features JSON オブジェクトには、フィーチャーに関するメタデータが含まれています。
| プロパティ | 説明 |
|---|---|
| id | 機能の一意の識別子 (GUID) |
| title | 機能のタイトル |
| description | 機能の説明 |
| assets | 機能で使用される XML ファイルの配列 |
| elementManifests | assets プロパティ内で定義される要素のマニフェスト ファイルの配列 |
| elementFiles | assets プロパティ内で定義される要素ファイルの配列 |
| upgradeActions | assets プロパティ内で定義されるアップグレード アクション ファイルの配列 |
フィーチャーの XML ファイルを作成する
ツールチェーンは、クライアント側のソリューション プロジェクトの特別なフォルダー (sharepoint\assets) の下の構成で定義されている XML ファイルを検索します。
package-solution.json で定義された構成は、package-solution gulp タスクが実行されたときに XML ファイルを適切な機能の XML ファイルにマップします。
SharePoint アイテムをパッケージ化する
package-solution.json でフィーチャーを定義し、それぞれの機能の XML ファイルを作成した後に、次に示す gulp タスクを使用して、SharePoint アイテムと .sppkg パッケージをパッケージ化できます。
gulp package-solution
このコマンドは、1 つ以上のクライアント側コンポーネント (Web パーツなど) のマニフェストと、package-solution.json 構成ファイルで参照されるフィーチャーの XML ファイルをパッケージ化します。
注:
--ship フラグを使用すると、コンポーネントの縮小版をパッケージ化できます。
SharePoint アイテムをアップグレードする
クライアント側のソリューションのアップグレード時には、新しい SharePoint アイテムを含めるか、既存の SharePoint アイテムを更新します。 SharePoint アイテムのプロビジョニングにはフィーチャーが使用されるので、フィーチャーの UpgradeActions XML ファイルを使用してアップグレード アクションのリストを定義します。
package-solution.json の upgradeActions JSON オブジェクト配列は、フィーチャーのアップグレード アクションに関連付けられているフィーチャーの XML ファイルを参照します。 少なくとも、アップグレード アクション ファイルは、フィーチャーのアップグレード時に実行される要素のマニフェスト XML ファイルを定義します。
SharePoint Framework ソリューションをアップグレードしているときは、アップグレード アクションが含まれていたソリューションとフィーチャーの両方のバージョン属性も更新する必要があります。 ソリューションのバージョンが上がることは、利用可能な新しいバージョンのパッケージがあることを SharePoint エンド ユーザーに対して示します。 フィーチャー要素のバージョンが上がることは、アップグレード アクションで定義されているタスクが、ソリューションのアップグレードの一部として処理されることを示します。
アップグレード中に要素のマニフェスト ファイルを適用するアップグレード アクション ファイルの例を次に示します。
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
これは、アップグレード中にプロビジョニングされる新しい Currency フィールドを定義する、対応する element-v2.xml です。
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
Name="Amount"
DisplayName="Amount"
Type="Currency"
Decimals="2"
Min="0"
Required="FALSE"
Group="Financial Columns" />
</Elements>
サブ要素
クライアント側のソリューションのアップグレード アクションでは、次のサブ要素がサポートされています。
AddContentTypeField
既存のプロビジョニングされたコンテンツ タイプに新しいフィールドを追加します。 変更をサイト コンテンツ タイプからサイト内のすべての子リストおよびコンテンツ タイプに伝達します。 以下に例を示します。
<AddContentTypeField
ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
PushDown="TRUE" />
ApplyElementManifests
既存の機能に新しい要素を追加します。 フィーチャーがアップグレードされると、指定された要素のマニフェストで参照される、非宣言型の要素がすべてプロビジョニングされます。
VersionRange
指定したアップグレード アクションが適用されるバージョンの範囲を指定します。