SharePoint アセットとソリューション パッケージのプロビジョニングProvision SharePoint assets with your solution package

場合によっては、クライアント側のソリューション パッケージと同時に SharePoint リストやドキュメント ライブラリをプロビジョニングして、リストやライブラリを Web パーツなどのクライアント側コンポーネントで使用できるようにする必要があります。At times, you may need to provision a SharePoint list or a document library along with your client-side solution package so that that list or library is available for your client-side components, such as web parts. SharePoint Framework toolchain allows you to package and deploy SharePoint items with your client-side solution package. These items are then provisioned when the client-side solution is installed on a site. SharePoint Framework ツールチェーンを使用すると、SharePoint アイテムとクライアント側のソリューション パッケージをパッケージ化して展開できます。SharePoint Framework toolchain allows you to package and deploy SharePoint items with your client-side solution package. これらのアイテムは、クライアント側のソリューションがサイトにインストールされたときにプロビジョニングされます。These items are then provisioned when the client-side solution is installed on a site.

プロビジョニング オプションに関する詳細は、SharePoint PnP YouTube Channel にある SharePoint PnP の Web キャストもご覧ください。You can also find details on the provisioning options from a SharePoint PnP webcast available from SharePoint PnP YouTube Channel.

Screenshot of the YouTube video player for this tutorial

JavaScript コードを使用してアイテムをプロビジョニングするProvisioning items using JavaScript code

Web パーツなどのコンポーネントで JavaScript コードを使用して SharePoint アイテムを作成できますが、そのコンポーネントを使用する現在のユーザーのコンテキストに限定されます。While it is possible to create SharePoint items using JavaScript code in your component, such as web parts, it is limited to the context of the current user using that component. ユーザーが SharePoint アイテムを作成したり変更したりするための十分な権限を持っていない場合、JavaScript コードはこれらのアイテムをプロビジョニングしません。If the user doesn't have sufficient permissions to create or modify SharePoint items, the JavaScript code does not provision those items. そのような場合、昇格されたコンテキストで SharePoint アイテムをプロビジョニングするときには、ソリューション パッケージと同時にアイテムをパッケージ化して展開する必要があります。In such cases, when you want to provision SharePoint items in an elevated context, you must package and deploy the items along with your solution package.

ソリューションの SharePoint アイテムをプロビジョニングするCreate SharePoint items in your solution

クライアント側のソリューション パッケージと同時に、次に示す SharePoint アセットをプロビジョニングできます。The following SharePoint assets can be provisioned along with your client-side solution package:

  • フィールドFields
  • コンテンツ タイプContent types
  • インスタンスの一覧表示List instances
  • カスタム スキーマを使用するリスト インスタンスList instances with custom schema

フィールドFields

フィールドまたはサイトの列は、ユーザーが列を追加したリストのアイテムまたはコンテンツタイプに対して管理する必要がある属性 (またはメタデータの一部) を表します。これは再利用可能な列定義 (またはテンプレート) であり、複数の SharePoint サイト間で複数のリストに割り当てることができます。サイトの列は作業のやり直しを減らし、サイトとリストとの間でメタデータの一貫性を保つために役立ちます。A field or a site column represents an attribute, or piece of metadata, that the user wants to manage for the items in the list or content type to which they added the column. It is a reusable column definition, or template, that you can assign to multiple lists across multiple SharePoint sites. Site columns decrease rework and help you ensure consistency of metadata across sites and lists.

たとえば、Customer という名前のサイト列を定義するとします。For example, suppose you define a site column named Customer. ユーザーはその列をリストに追加して、コンテンツ タイプでそれを参照することができます。Users can add that column to their lists and reference it in their content types. これにより、列がどこに表示されても、(少なくとも最初は) 列に同じ属性があることが保証されます。This ensures that the column has the same attributes—at least to start with—wherever it appears.

「Field 要素 (フィールド)」ドキュメントのスキーマと属性を参照して、ソリューションの新しいフィールドを定義できます。You can refer to the schema and attributes in the Field Element documentation to define a new field in your solution.

新しい DateTime フィールドの例を次に示します。Below is an example of a new DateTime field:

<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>

コンテンツ タイプContent types

コンテンツ タイプは、SharePoint のリストまたはドキュメント ライブラリにあるアイテムまたはドキュメントのカテゴリに対する、メタデータ (列)、動作、およびその他の設定をまとめて再利用できるようにしたものです。コンテンツ タイプを使用することで、情報のカテゴリに対する設定を再利用可能な方法で一元的に管理できるようになります。A content type is a reusable collection of metadata (columns), behavior, and other settings for a category of items or documents in a SharePoint list or document library. Content types enable you to manage the settings for a category of information in a centralized, reusable way.

たとえば、次のような 3 種類のドキュメントがあるビジネスの状況を考えてみましょう。経費明細書、発注書、請求書です。For example, imagine a business situation in which you have three different types of documents: expense reports, purchase orders, and invoices. これらのドキュメントには共通の特徴があります。すべて財務報告書で、通貨の値を持つデータが含まれています。All three types of documents have some characteristics in common; for one thing, they are all financial documents and contain data with values in currency. とはいえ、それぞれのドキュメントには独自のデータ要件、独自のドキュメント テンプレート、独自のワークフローがあります。Yet each type of document has its own data requirements, its own document template, and its own workflow.

このビジネス上の問題に対する 1 つの解決策は、4 つのコンテンツ タイプを作成することです。One solution to this business problem is to create four content types. 最初のコンテンツ タイプである Financial Document は、組織のすべての財務報告書に共通するデータ要件をカプセル化します。For example, you can define a list instance Finance Documents with a content type Financial Document that could encapsulate data requirements that are common to all financial documents in the organization. 残りの 3 つ、Expense Report、Purchase Order、Invoice は、Financial Document から共通の要素を継承します。The remaining three, Expense Report, Purchase Order, and Invoice, could inherit common elements from Financial Document. さらに、メタデータの特定のセット、新しいアイテムの作成に使用するドキュメント テンプレート、アイテムを処理する特定のワークフローなど、それぞれのタイプに特有の特徴を定義することができます。In addition, they could define characteristics that are unique to each type, such as a particular set of metadata, a document template to be used in creating a new item, and a specific workflow for processing an item.

「ContentType 要素 (コンテンツ タイプ)」ドキュメントのスキーマと属性を参照して、ソリューションの新しいコンテンツ タイプを定義できます。You can refer to the schema and attributes in the Content Type Element documentation to define a new content type in your solution.

コンテンツ タイプの例を次に示します。Below is an example of a content type:

<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> 

リスト インスタンスList instances

リストは SharePoint サイトの主要な基本機能です。これにより、チームは情報を収集、追跡、共有できます。多くのアプリケーションが、データ保存のためにサイトで作成されたリストに依存して、それらの動作を実装しています。リスト インスタンスは、既知の識別子を持つ定義済みの SharePoint リストです。アイテムをカスタマイズしてこれらのリストに追加したり、既に使用可能なリスト テンプレートから追加のリストを作成したり、選択した設定と列のみを使用してカスタム リストを作成することができます。Lists are a key, underlying feature of a SharePoint site. They enable teams to gather, track, and share information. Many applications rely on lists created at the site for data storage to implement their behaviors. A list instance is a predefined SharePoint list that has a well-known identifier. You can customize and add items to these lists, create additional lists from the list templates that are already available, and create custom lists with just the settings and columns that you choose.

SharePoint には、連絡先リスト、予定表、タスク リストなど、いくつかのリスト テンプレートが用意されています。SharePoint provides several list templates such as contact list, calendar, task list, and more. これらのテンプレートを使用して、Web パーツや他のコンポーネント用に新しいリスト インスタンスを作成できます。You can use these templates to create new list instances for your web parts or other components. たとえば、Document Library テンプレートに基づいてリスト インスタンスの Finance Documents を定義して、関連するドキュメントを Web パーツに格納できます。SharePoint provides several list templates such as contact list, calendar, task list and more. You can use these templates to create new list instances for your web parts or other components. For example, you can define a list instance Finance Documents based on the Document Library template to store associated documents with your web part.

「ListInstance 要素 (リスト インスタンス)」ドキュメントのスキーマと属性を参照して、ソリューションのリスト インスタンスを定義できます。You can refer to the schema and attributes in the List Instance Element documentation to define a list instance in your solution.

リスト インスタンス定義の例を次に示します。Below is an example of a list instance definition:

<ListInstance 
    FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
    Title="Finance Records" 
    Description="Finance documents"
    TemplateType="101"
    Url="Lists/FinanceRecords">
</ListInstance>

カスタム スキーマを使用するリスト インスタンスList instances with custom schema

カスタム リスト スキーマ定義を使用すると、フィールド、コンテンツ タイプ、およびリスト インスタンスで使用されるビューを定義できます。You can use a custom list schema definition to define your fields, content types and views used in your list instance. リスト インスタンスのカスタム スキーマを参照するには、ListInstance 要素の CustomSchema 属性を使用します。You will use the attribute in the list instance element to reference a custom schema for the list instance.

たとえば、組織のすべての財務報告書に共通するデータ要件をカプセル化する、コンテンツ タイプが Financial Document のリスト インスタンス Finance Documents を定義できます。For example, you can define a list instance Finance Documents with a content type Financial Document that could encapsulate data requirements that are common to all financial documents in the organization.

カスタム スキーマを使用するリスト インスタンス定義の例を次に示します。Below is an example of a list instance definition that uses a custom schema:

<ListInstance 
    CustomSchema="schema.xml"
    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
    Title="Cost Centers" 
    Description="Cost Centers"
    TemplateType="100"
    Url="Lists/CostCenters">
</ListInstance>


次に、以前に定義したリスト インスタンスのコンテンツ タイプを定義するカスタム スキーマの定義を示します。And the custom schema definition that defines a content type for the list instance defined above:

<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 アイテムを作成するCreate SharePoint items in your solution

ソリューション パッケージは、「SharePoint のフィーチャー」を使用して、SharePoint アイテムをパッケージ化し、プロビジョニングします。The solution package uses SharePoint Features to package and provision the SharePoint items. フィーチャーとは、プロビジョニングする SharePoint アイテムを 1 つ以上含むコンテナーです。A Feature is a container that includes one or more SharePoint items to provision. フィーチャーには Feature.xml ファイルと 1 つ以上の要素のマニフェスト ファイルが含まれています。A Feature contains a Feature.xml file and one or more element manifest files. これらの XML ファイルは、フィーチャー定義とも呼ばれます。These XML files are also known as Feature definitions.

通常、クライアント側のソリューション パッケージには、1 つのフィーチャーが含まれています。Typically, a client-side solution package contains one feature. このフィーチャーは、ソリューションがサイトにインストールされるとアクティブ化されます。This feature is activated when the solution is installed on a site. サイト管理者はフィーチャーではなくソリューション パッケージをインストールすることに注意してください。Typically, a client-side solution package contains one feature. This feature is activated when the solution is installed in a site. It is important to note that the site administrators install your solution package and not the feature.

フィーチャーは、主に次の XML ファイルを使用して構築されます。A feature is primarily constructed by using the following XML files:

要素のマニフェスト ファイルElement Manifest File

要素のマニフェスト ファイルには、SharePoint アイテムの定義が含まれ、フィーチャーがアクティブ化されたときに実行されます。The element manifest file contains the SharePoint item definitions and is executed when the feature is activated. たとえば、要素のマニフェストには、新しいフィールド、コンテンツ タイプ、またはリスト インスタンスを作成するための XML 定義が含まれます。For example, the XML definitions to create a new field, content type, or list instance is in the element manifest.

新しい DateTime フィールドを定義する、要素のマニフェスト ファイルの例を次に示します。Below is an example of an element manifest file that defines a new DateTime field.

<?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>

要素ファイルElement File

サポートされるファイルで要素のマニフェストに付随するものは、要素ファイルです。Any supported files that accompany the element manifest are element files. たとえば、リスト インスタンスのスキーマは、要素のマニフェストで定義されたリスト インスタンスに関連付けられた要素ファイルです。Any supported files that accompany the element manifest will be an element file. For example, the list instance schema is an element manifest that is associated with a list instance that is defined in an element manifest.

カスタム リスト インスタンスのスキーマの例を次に示します。Below is an example of a custom list instance schema:

<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>

アップグレード アクション ファイルUpgrade Actions File

名前からわかるように、これは、ソリューションがサイトで更新されるときのアップグレード アクションが含まれるファイルです。As its name suggests, this is the file that includes any upgrade actions when the solution is updated on the site. アップグレード アクションの一部として、アクションは 1 つまたは複数の要素のマニフェストを含むように指定することもできます。As part of the upgrade actions, the action could specify to include one or more element manifests as well. たとえば、アップグレードで新しいフィールドを追加する必要がある場合、フィールド定義は要素のマニフェストとして使用可能であり、アップグレード アクション ファイルに関連付けられます。For example, if the upgrade requires a new field to be added, the field definition is available as an element manifest and is associated in the upgrade actions file.

アップグレード中に要素のマニフェスト ファイルを適用するアップグレード アクション ファイルの例を次に示します。Below is an example of an upgrade action file that applies an element manifest file during the upgrade:

<ApplyElementManifests>
      <ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>

SharePoint フィーチャーを構成するConfigure the SharePoint feature

XML ファイルを含めるには、まず、プロジェクトの config フォルダーの下にある package-solution.json 構成ファイルで、フィーチャーの構成を定義する必要があります。In order to include the XML files, you will need to first define the feature configuration in the package-solution.json configuration file underneath the config folder in your project. package-solution.json にはクライアント側のソリューション パッケージに関する主要なメタデータ情報が含まれており、ソリューションを .sppkg ファイルにパッケージ化する package-solution gulp タスクを実行するときに参照されます。The package-solution.json contains the key metadata information about your client-side solution package and is referenced when you run the package-solution gulp task which packages your solution into a .sppkg file.

{
  "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 オブジェクトには、フィーチャーに関するメタデータが含まれています。The features JSON object contains the metadata about the feature, as shown in the following table.

プロパティProperty 説明Description
idid 機能の一意の識別子 (GUID)Unique identifier (GUID) of the feature
titletitle 機能のタイトルTitle of the feature
descriptiondescription 機能の説明Description of the feature
assetsassets 機能で使用される XML ファイルの配列An array of XML files used in the feature
elementManifestselementManifests assets プロパティ内で定義される要素のマニフェスト ファイルの配列Defined within the assets property, an array of element manifest files
elementFileselementFiles assets プロパティ内で定義される要素ファイルの配列Defined within the assets property, an array of element files
upgradeActionsupgradeActions assets プロパティ内で定義されるアップグレード アクション ファイルの配列Defined within the assets property, an array of upgrade action files

フィーチャーの XML ファイルを作成するCreate the feature XML files

ツールチェーンは、クライアント側のソリューション プロジェクトの特別なフォルダー (sharepoint\assets) の下の構成で定義されている XML ファイルを検索します。The toolchain looks for the XML files as defined in the configuration underneath a special folder - sharepoint\assets - in your client-side solution project.

クライアント側のソリューション プロジェクトのフィーチャーの XML ファイル

package-solution.json で定義された構成は、package-solution gulp タスクが実行されたときに XML ファイルを適切な機能の XML ファイルにマップします。The configurations defined in the package-solution.json is what maps the XML files here to its appropriate feature XML file when the package-solution gulp task is executed.

SharePoint アイテムをパッケージ化するPackage SharePoint items

package-solution.json でフィーチャーを定義し、それぞれの機能の XML ファイルを作成した後に、次に示す gulp タスクを使用して、SharePoint アイテムと .sppkg パッケージをパッケージ化できます。Once you have defined your feature in the package-solution.json and created the respective feature XML files, you can use the following gulp task to package the SharePoint items along with your .sppkg package.

gulp package-solution

このコマンドは、1 つ以上のクライアント側コンポーネント (Web パーツなど) のマニフェストと、package-solution.json 構成ファイルで参照されるフィーチャーの XML ファイルをパッケージ化します。The command above will package one or more client-side component manifests, such as web parts, along with the feature XML files referenced in the package-solution.json configuration file.

注意

--ship フラグを使用すると、コンポーネントの縮小版をパッケージ化できます。You can use the --ship flag to package minified versions of your components.

SharePoint アイテムをアップグレードするUpgrade SharePoint items

クライアント側のソリューションのアップグレード時には、新しい SharePoint アイテムを含めるか、既存の SharePoint アイテムを更新します。You may include new SharePoint items or update existing SharePoint items when you upgrade your client-side solution. SharePoint アイテムのプロビジョニングにはフィーチャーが使用されるので、フィーチャーの UpgradeActions XML ファイルを使用してアップグレード アクションのリストを定義します。Since provisioning SharePoint items uses features, you will be using the feature upgrade actions XML file to define a list of upgrade actions.

package-solution.jsonupgradeActions JSON オブジェクト配列は、フィーチャーのアップグレード アクションに関連付けられているフィーチャーの XML ファイルを参照します。The upgradeActions JSON object array in the package-solution.json references the feature XML file(s) associated with the upgrade actions for your feature. 少なくとも、アップグレード アクション ファイルは、フィーチャーのアップグレード時に実行される要素のマニフェスト XML ファイルを定義します。At the least, an upgrade action file will define the element manifest XML file that will be executed when upgrading the feature.

SharePoint Framework ソリューションをアップグレードしているときは、アップグレード アクションが含まれていたソリューションとフィーチャーの両方のバージョン属性も更新する必要があります。When you are upgrading a SharePoint Framework solution, you must also update version attributes for both the solution and the feature where the upgrade actions have been included. ソリューションのバージョンが上がることは、利用可能な新しいバージョンのパッケージがあることを SharePoint エンド ユーザーに対して示します。A solution version increase indicates to SharePoint end users that there is a new version of the package available. フィーチャー要素のバージョンが上がることは、アップグレード アクションで定義されているタスクが、ソリューションのアップグレードの一部として処理されることを示します。A feature element version increase ensures that the tasks defined in the upgrade actions are being processed as part of the solution upgrade.

アップグレード中に要素のマニフェスト ファイルを適用するアップグレード アクション ファイルの例を次に示します。Below is an example of an upgrade action file that applies an element manifest file during the upgrade:

<ApplyElementManifests>
      <ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>


これは、アップグレード中にプロビジョニングされる新しい Currency フィールドを定義する、対応する element-v2.xml です。And the corresponding element-v2.xml which defines a new Currency Field to be provisioned during the upgrade:

<?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>


サブ要素Sub-elements

クライアント側のソリューションのアップグレード アクションでは、次のサブ要素がサポートされています。Upgrade actions in client-side solutions support the following sub elements:

AddContentTypeFieldAddContentTypeField

既存のプロビジョニングされたコンテンツ タイプに新しいフィールドを追加します。変更をサイト コンテンツ タイプからサイト内のすべての子リストおよびコンテンツ タイプに伝達します。次に例を示します。Adds a new field to an existing provisioned content type. Propagates the change from the site content type to all child lists and content types within the site. For example:

<AddContentTypeField 
     ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7" 
     FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}" 
     PushDown="TRUE" />

ApplyElementManifestsApplyElementManifests

既存の機能に新しい要素を追加します。Add a new element to an existing feature フィーチャーがアップグレードされると、指定された要素のマニフェストで参照される、非宣言型の要素がすべてプロビジョニングされます。Adds a new element to an existing Feature. When a Feature is upgraded, provisions all non-declarative elements that are referenced in the specified element manifests.

VersionRangeVersionRange

指定したアップグレード アクションが適用されるバージョンの範囲を指定します。Specifies a version range to which specified upgrade actions apply.

関連項目See also