PnP プロビジョニングエンジンとコアライブラリ

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

PnP プロビジョニングエンジンはプロビジョニングフレームワークの心臓部で、その基礎となるのは OfficeDevPnP.Core ライブラリです。プロビジョニングエンジンはコアライブラリの一部で、コアライブラリの拡張機能を活用してプロビジョニングタスクを実装します。

注:

PnP プロビジョニングフレームワーク & PnP プロビジョニングエンジンは、アクティブなコミュニティがサポートを提供するオープンソースソリューションです。 Microsoft からのオープンソースツールのサポート SLA はありません。

SharePoint CSOM/REST オブジェクトモデルの拡張メソッドで構成されるコアライブラリにより、プロビジョニングテンプレートの列挙と取得、テンプレートの格納、新規および既存のサイトへのテンプレートの適用といったプロビジョニングタスクが可能になります。また、プロビジョニングタスクの自動化や、コード化されたロジックをプロビジョニングルーチンに導入することも可能となります。

注:

プロビジョニングテンプレートの作成、永続化、適用に関するビデオチュートリアルを視聴するには、「PnP プロビジョニングエンジンの入門」にアクセスしてください。

PnP プロビジョニングエンジン

PnP プロビジョニングエンジンは、リモートプロビジョニングタスクを実行および自動化するコアライブラリ内のクラスを構造化した実装です。 SharePoint アドインモデルを備えた新しい Microsoft ランドスケープでは、SharePoint Online、SharePoint、Office 365 のプロビジョニングソリューションでクライアント側オブジェクトモデル (CSOM) とプロビジョニングフレームワークを使用してサイト成果物をプロビジョニングするようになりました。

PnP プロビジョニングエンジンでは、サイト列、コンテンツタイプ、リストの定義、構成、ページのデザインをモデル化することができます。既存のサイトデザイン機能をポイントしたり、手でデザインを作成したり、または両方の方法を組み合わせたりして、これらの機能をデザインすることができ、他にもさまざまなことが可能になります。必要に応じて、保存や再利用できるプロビジョニングテンプレートとしてデザインを保持できます。

使用しているサイトデザインをプロビジョニングテンプレートとして抽出する方法は、2 つあります。 1 つは Windows PowerShell スクリプト (PnP.PowerShell) を使用する方法、もう 1 つはコアライブラリ (OfficeDevPnP.Core) によって提供される拡張メソッドを実装する CSOM/REST コードを使用する方法です。

Windows PowerShell スクリプトを使用してプロビジョニングテンプレートを抽出する

プロビジョニングエンジンで Windows PowerShell スクリプトを使用するには、最初に、PnP.PowerShell コマンドレットをダウンロードしてインストールしなければなりません。 Windows PowerShell を実行するために必要なものすべて (ダウンロードとインストールに関する手順、Windows PowerShell コマンドの資料を含む) は、GitHub の PnP PowerShell コマンドリポジトリにあります。

注:

PnP PowerShell コマンドリポジトリには、SharePoint 2013 用、SharePoint 2016 用、SharePoint 2019 用、SharePoint Online 用の 4 つのバージョンが含まれています。

注:

PnP PowerShell はオープンソースソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープンソースツールのサポート SLA はありません。

コマンドレットをインストールする推奨方法は、PowerShell ギャラリーを使用することです。

Install-Module -Name PnP.PowerShell

SharePoint オンプレミスのバージョンをインストールする場合は、名前の「オンライン」をそれぞれのバージョンの SharePoint に置き換えます。

最新バージョンへのリンクは次のとおりです。

CSOM コードを使用してプロビジョニングテンプレートを抽出する

CSOM/REST コードを使用してプロビジョニングテンプレートを抽出するには、Visual Studio または他の開発環境を使用して開発プロジェクトを作成します。コンソール、Windows アプリケーション、SharePoint アドインなどの任意の種類のプロジェクトを作成できます。開発プロジェクトの作成後、NuGet パッケージとして入手可能なコアライブラリをインストールする必要があります。

注:

コアライブラリ NuGet パッケージを見つけてインストールする方法の手順、およびリモートプロビジョニングサンプルのコンソールアプリケーションに関するチュートリアルについては、「コンソールアプリケーションのプロビジョニングサンプル」に記されています。コアライブラリには、SharePoint Online、およびオンプレミスの SharePoint を対象としたバージョンの 2 つがあることに注意してください。

CSOM の使用法についての詳細な手順は「コンソールアプリケーションのプロビジョニングサンプル」に記載されていますが、概要は次のとおりです。

SharePoint Online への接続を作成します。
ClientContext インスタンスを作成し、Web オブジェクトの参照を取得します。
コアライブラリの拡張メソッド GetProvisioningTemplate を使用して、ProvisioningTemplate オブジェクトを抽出します。
テンプレートプロバイダーおよびシリアル化フォーマッタを使用して、任意のファイル場所にプロビジョニングテンプレートインスタンスを保存します。

注:

テンプレートプロバイダーとシリアル化フォーマッタオブジェクトはカスタマイズ可能であるため、任意の永続ストレージやシリアル化形式を実装できます。標準の PnP のプロビジョニングエンジンは、ファイルシステム、SharePoint、Azure Blob ストレージテンプレートプロバイダーのサポートを提供します。 XML と JSON のシリアル化フォーマッタもサポートします。

「PnP プロビジョニングスキーマ」という記事では、XML シリアル化出力の例を確認でき、XML シリアル化スキーマについての詳細説明もあります。さらに、このスキーマとそのドキュメントを GitHub の「SharePoint/PnP-Provisioning-Schema」で入手することもできます。 Channel 9 のビデオ「PnP プロビジョニングエンジンスキーマの詳細」で、このスキーマを紹介して説明しています。

ただし重要な点として、プロビジョニングエンジンは、シリアル化形式に依存しないドメインモデルをサポートすることに注意してください。実際のところ、プロビジョニングエンジンはあらゆるシリアル化形式から完全に分離されています。したがって、開発者が手動で自由に ProvisioningTemplate インスタンスを定義できます。

モデルサイトをポイントすることも、PnP プロビジョニングスキーマに照らして検証する XML ドキュメントを作成することも、あるいは .NET コードを作成してオブジェクト階層を構成することもできます。さらに、これらの方法を組み合わせることも可能です。また、モデルサイトを使用してプロビジョニングテンプレートをデザインしてから XML ファイルに保存し、何らかのメモリ内カスタマイズを行うと同時にコード内で ProvisioningTemplate インスタンスを処理することもできます。

GetProvisioningTemplate を使用してテンプレートを抽出するコードサンプル

「コンソールアプリケーションのプロビジョニングサンプル」は、GetProvisioningTemplate メソッドの使用方法を説明しています。このサンプルでは、プロビジョニングテンプレートをエクスポートするプロセスが次のコードブロック内で行われます。

ProvisioningTemplateCreationInformation ptci = new ProvisioningTemplateCreationInformation(ctx.Web);

// Create FileSystemConnector, so that we can store composed files somewhere temporarily 
ptci.FileConnector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
ptci.PersistComposedLookFiles = true;
ptci.ProgressDelegate = delegate (String message, Int32 progress, Int32 total)
{

// Use this to simply output progress to the console application UI
Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
};

// Execute actual extraction of the tepmplate
ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);

プロビジョニングテンプレートを適用する

コアライブラリの拡張メソッドを使用してプロビジョニングテンプレートを適用する場合、ここに示す例と同様のコードブロックを使用します。この例では、Web タイプの ApplyProvisioningTemplate 拡張メソッドを使用して、ターゲットサイトにテンプレートを適用します。

using (var context = new ClientContext(destinationUrl))
{
  context.Credentials = new SharePointOnlineCredentials(userName, password);
  Web web = context.Web;
  context.Load(web, w => w.Title);
  context.ExecuteQueryRetry();

  // Configure the XML file system provider
  XMLTemplateProvider provider =
  new XMLFileSystemTemplateProvider(
    String.Format(@"{0}\..\..\",
    AppDomain.CurrentDomain.BaseDirectory),
    "");

  // Load the template from the XML stored copy
  ProvisioningTemplate template = provider.GetTemplate(
    "<template name>.xml");

  // Apply the template to another site
  Console.WriteLine("Start: {0:hh.mm.ss}", DateTime.Now);

  // We can also use Apply-PnPProvisioningTemplate
  web.ApplyProvisioningTemplate(template);

  Console.WriteLine("End: {0:hh.mm.ss}", DateTime.Now);
}

PnP コアライブラリ

コアライブラリ (OfficeDevPnP.Core) は、PnP プロビジョニングフレームワークをサポートする CSOM/REST オブジェクトモデルで、PnP プロビジョニングエンジンを使用できるようにします。コアライブラリはいくつかの名前空間で構成されていて、一連の拡張メソッドが含まれています。これらのメソッドは、SharePoint オブジェクトモデルを拡張し、リモートプロビジョニング、エンティティー、タイマージョブ、プロビジョニングテンプレート、プロビジョニングフレームワーク全体の処理用オブジェクトをサポートします。表 1 に、コアライブラリの名前空間についてまとめます。

表 1. OfficeDevPnP.Core ライブラリの名前空間

名前空間	説明
OfficeDevPnP.Core
OfficeDevPnP.Core.AppModelExtensions	追加メソッドを使用して既存タイプを拡張する .NET クラス。
OfficeDevPnP.Core.Entities	AppModelExtensions の拡張メソッドからより複雑なオブジェクトを提供および取得するクラス。
OfficeDevPnP.Core.Enums	プロビジョニング操作をサポートする列挙セット。
OfficeDevPnP.Core.Extensions	文字列操作などに役立つメソッドなど、SharePoint に関連しない拡張メソッド。
OfficeDevPnP.Core.Framework.ObjectHandlers.TokenDefinitions	テンプレートオブジェクト内の特定のコンテンツを置換するためのトークン。
OfficeDevPnP.Core.Framework.Provisioning.Connectors	テンプレートとアセットが格納されている各種データソースに接続するコネクター。
OfficeDevPnP.Core.Framework.Provisioning.Extensibility	拡張プロバイダーコード。拡張プロバイダーを使用すると、エンジンでネイティブサポートされない機能を追加できます。
OfficeDevPnP.Core.Framework.Provisioning.Model	テンプレートデータモデルオブジェクト。テンプレートは、実際の C# コードに抽出されるか、逆シリアル化されます。この名前空間には、この構造のクラスが含まれます。
OfficeDevPnP.Core.Framework.Provisioning.ObjectHandlers	テンプレートの抽出と作成の両方をサポートする各種 SharePoint 要素のハンドラー。
OfficeDevPnP.Core.Framework.Provisioning.Providers	テンプレートプロバイダーベースの名前空間。テンプレートプロバイダーを使用して、コードベースのモデルを特定形式にシリアル化または逆シリアル化します。
OfficeDevPnP.Core.Framework.Provisioning.Providers.Json	コードベースのテンプレートと JSON 形式との間でシリアル化または逆シリアル化を行うための JSON テンプレートプロバイダー。
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml	コードベースのテンプレートと XML 形式との間でシリアル化または逆シリアル化を行うための XML テンプレートプロバイダー。
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml.V201503	v201503 バージョンのスキーマの自動生成スキーマファイル。
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml.V201505	v201505 バージョンのスキーマの自動生成スキーマファイル。
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml.V201508	v201508 バージョンのスキーマの自動生成スキーマファイル。

PnP プロビジョニングエンジンとコアライブラリ

PnP プロビジョニングエンジン

Windows PowerShell スクリプトを使用してプロビジョニングテンプレートを抽出する

CSOM コードを使用してプロビジョニングテンプレートを抽出する

GetProvisioningTemplate を使用してテンプレートを抽出するコードサンプル

プロビジョニングテンプレートを適用する

PnP コアライブラリ

関連項目

その他のリソース

PnP プロビジョニング エンジンとコア ライブラリ

PnP プロビジョニング エンジン

Windows PowerShell スクリプトを使用してプロビジョニング テンプレートを抽出する

CSOM コードを使用してプロビジョニング テンプレートを抽出する

GetProvisioningTemplate を使用してテンプレートを抽出するコード サンプル

プロビジョニング テンプレートを適用する

PnP コア ライブラリ

関連項目

その他のリソース

PnP プロビジョニングエンジンとコアライブラリ

PnP プロビジョニングエンジン

Windows PowerShell スクリプトを使用してプロビジョニングテンプレートを抽出する

CSOM コードを使用してプロビジョニングテンプレートを抽出する

GetProvisioningTemplate を使用してテンプレートを抽出するコードサンプル

プロビジョニングテンプレートを適用する

PnP コアライブラリ