コンソールアプリケーションのプロビジョニングサンプル

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

新しいアドインモデルをサポートするために Office 365 Developer Patterns and Practices プログラム (PnP) で導入されたプロビジョニングフレームワークを使用すると、ユーザーは、

サイトモデルを指すだけでカスタムサイトテンプレートを作成でき、
そのモデルをプロビジョニングテンプレートとして永続化し、
そのカスタムテンプレートを必要に応じて既存のサイトコレクションに適用することができます。

注:

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

このサンプルでは、PnP のコアプロビジョニングライブラリのクラスを実装する基本的なコンソールアプリケーションを作成します。これらのクラスの実装により、PnP プロビジョニングエンジンが以下の必要なプロビジョニングタスクを実行することが可能になります。

サイトのカスタマイズを設計してモデル化します。新しいサイトデザインにすることも、既存のサイトをポイントして、それをプロビジョニングテンプレートとして保存することもできます。
サイトモデルをプロビジョニングテンプレートとして保存して永続化し、再利用できるようにします。
プロビジョニングテンプレートを新規または既存のサイトコレクションに適用します。

注:

このサンプルチュートリアルは、現在 GitHub の「PnP プロビジョニングエンジンの入門」で入手できるサンプルと対になるものです。このサンプルのコード (Program.cs) とソリューションファイルは、ダウンロードできます。 Microsoft Channel 9 のサイトの「PnP プロビジョニングエンジンの入門」にはこのプロセス (コードは若干異なります) について説明する 20 分間のビデオもあります。

Visual Studio プロジェクトの作成と準備

はじめに、Visual Studio プロジェクトを作成します。このサンプルでは、簡略化するために、プロビジョニングフレームワークの PnP コアライブラリを使用して PnP プロビジョニングエンジンを実装する基本的なコンソールアプリケーションを作成します。ただし、このサンプルソリューションをサポートするには、PnP コアライブラリ用のプロビジョニングフレームワークをダウンロードしてインストールする必要があります。

Visual Studio を開いてから、[ファイル]>[新規]>[プロジェクト] を選択します。
新規プロジェクトウィザードで、[Visual C#] を選択してから、[コンソールアプリケーション] を選択します。
プロジェクトに Program という名前を付けてから、[OK] を選択します (任意の名前を付けることができますが、このサンプルチュートリアルではプロジェクト名は Program とします)。
PnP コアライブラリをダウンロードしてインストールします。これは NuGet パッケージとして「SharePointPnPCore パッケージ」から入手できます。

注:

このライブラリには、次の 3 つのバージョンがあります。 1 つ目のバージョンは、SharePoint Online と Office 365 をターゲットにした SharePointPnPCoreOnline ライブラリです。その他のバージョンは、SharePointPnPCore2013 および SharePointPnPCore2016 です。そして、それぞれが SharePoint オンプレミスバージョン 2013 および 2016 をターゲットにします。
「NuGet クライアントインストーラー」にアクセスして NuGet クライアントをインストールします。
NuGet クライアントがインストールされたら、NuGet パッケージマネージャーを実行します。 Visual Studio のソリューションエクスプローラーで References ノードを右クリックしてから、[NuGet パッケージの管理] を選択します。
パッケージマネージャーで [参照] を選択し、検索語として「SharePoint PnP」を入力して、SharePointPnPCoreOnline ライブラリが表示されるようにします。
指示に従って SharePointPnPCoreOnline ライブラリをダウンロードしてインストールします。

After the PnP Core library is referenced in your Visual Studio project, all library members are available to you as extension methods on existing object instances, for example, web and list instances.

Program.cs ファイルに以下のすべての using ステートメントが含まれていることを確認します。

using Microsoft.SharePoint.Client;
using OfficeDevPnP.Core.Framework.Provisioning.Connectors;
using OfficeDevPnP.Core.Framework.Provisioning.Model;
using OfficeDevPnP.Core.Framework.Provisioning.ObjectHandlers;
using OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml;
using System;
using System.Net;
using System.Security;
using System.Threading;

プロビジョニングテンプレートの作成、抽出、および永続化

プロジェクトがセットアップされたら、サイトのカスタマイズを作成できます。これは、手動で実行することも、デザインを流用するサイトを指すことで実行することもできます。選択したサイトデザインをプロビジョニングテンプレートとして保存するだけです。両方のアプローチの組み合わせを使用することもできます。このサンプルの目的では、既存のサイトを指して、作成済みの外観とサイト成果物 (ただし、コンテンツではない) をプロビジョニングテンプレートとして保存するだけです。

まず、プロビジョニング　テンプレートのモデルにするサイトに接続する必要があります。ユーザー名、パスワード、ソース URL などの接続情報を収集することから開始します。

ユーザーから接続情報を収集します。プログラムの Main ルーチンでは、次の 3 つの簡単な作業を行っています。これらは、接続情報の収集、プロビジョニングテンプレートの取得、およびプロビジョニングテンプレートの適用です。面倒な作業は、次に定義する GetProvisioningTemplate メソッドと ApplyProvisioningTemplate メソッドによって行われます。

static void Main(string[] args)
{
  ConsoleColor defaultForeground = Console.ForegroundColor;

  // Collect information
  string templateWebUrl = GetInput("Enter the URL of the template site: ", false, defaultForeground);
  string targetWebUrl = GetInput("Enter the URL of the target site: ", false, defaultForeground);
  string userName = GetInput("Enter your user name:", false, defaultForeground);
  string pwdS = GetInput("Enter your password:", true, defaultForeground);
  SecureString pwd = new SecureString();
  foreach (char c in pwdS.ToCharArray()) pwd.AppendChar(c);

  // GET the template from existing site and serialize
  // Serializing the template for later reuse is optional
  ProvisioningTemplate template = GetProvisioningTemplate(defaultForeground, templateWebUrl, userName, pwd);

  // APPLY the template to new site from
  ApplyProvisioningTemplate(targetWebUrl, userName, pwd, template);

  // Pause and modify the UI to indicate that the operation is complete
  Console.ForegroundColor = ConsoleColor.White;
  Console.WriteLine("We're done. Press Enter to continue.");
  Console.ReadLine();
}

プライベート GetInput メソッドを作成し、これを使用して必要なユーザー資格情報を取得します。

private static string GetInput(string label, bool isPassword, ConsoleColor defaultForeground)
{
  Console.ForegroundColor = ConsoleColor.Green;
  Console.WriteLine("{0} : ", label);
  Console.ForegroundColor = defaultForeground;

  string value = "";

  for (ConsoleKeyInfo keyInfo = Console.ReadKey(true); keyInfo.Key != ConsoleKey.Enter; keyInfo = Console.ReadKey(true))
  {
    if (keyInfo.Key == ConsoleKey.Backspace)
    {
      if (value.Length > 0)
      {
        value = value.Remove(value.Length - 1);
        Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
        Console.Write(" ");
        Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
      }
    }
    else if (keyInfo.Key != ConsoleKey.Enter)
    {
      if (isPassword)
      {
        Console.Write("*");
      }
      else
      {
        Console.Write(keyInfo.KeyChar);
      }
      value += keyInfo.KeyChar;
    }
  }
  Console.WriteLine("");

  return value;
}

プロビジョニングテンプレートのモデルとなるサイトを指します。 1 行のコードを使用してソースサイトで GET を実行しながら、定義した GET メソッドである GetProvisioningTemplate() を確認します。

private static ProvisioningTemplate GetProvisioningTemplate(ConsoleColor defaultForeground, string webUrl, string userName, SecureString pwd)
{
  using (var ctx = new ClientContext(webUrl))
  {
    // ctx.Credentials = new NetworkCredentials(userName, pwd);
    ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
    ctx.RequestTimeout = Timeout.Infinite;

    // Just to output the site details
    Web web = ctx.Web;
    ctx.Load(web, w => w.Title);
    ctx.ExecuteQueryRetry();

    Console.ForegroundColor = ConsoleColor.White;
    Console.WriteLine("Your site title is:" + ctx.Web.Title);
    Console.ForegroundColor = defaultForeground;

    ProvisioningTemplateCreationInformation ptci
            = new ProvisioningTemplateCreationInformation(ctx.Web);

    // Create FileSystemConnector to store a temporary copy of the template
    ptci.FileConnector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
    ptci.PersistComposedLookFiles = true;
    ptci.ProgressDelegate = delegate(String message, Int32 progress, Int32 total)
    {
        // Only to output progress for console UI
        Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
    };

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

    // We can serialize this template to save and reuse it
    // Optional step
    XMLTemplateProvider provider =
            new XMLFileSystemTemplateProvider(@"c:\temp\pnpprovisioningdemo", "");
    provider.SaveAs(template, "PnPProvisioningDemo.xml");

    return template;
  }
}

以前のコードスニペットでは、ProvisioningTemplateCreationInformation 変数 (pcti) も定義しました。この変数により、テンプレートと共に保存できる成果物に関する情報を格納できます。

ファイルシステムコネクターオブジェクトを作成し、別のサイトに適用するプロビジョニングテンプレートの一時的なコピーを格納できるようにします。

注:

この手順は省略できます。 XML にプロビジョニングテンプレートをシリアル化する必要はありません。この段階で、テンプレートは単なる C# コードです。シリアル化が省略可能であるだけでなく、必要なシリアル化形式を何でも使用できます。
次の 1 行のコードだけを使用して、プロビジョニングテンプレートの抽出を実行します。
```
ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);
```
(オプション) プロビジョニングテンプレートのシリアル化されたバージョンを保存して再利用できるようにします。プロビジョニングテンプレートは任意の形式でシリアル化することができます。このサンプルでは、PnPProvisioningDemo.xml という名前の XML ファイルにシリアル化しました。ファイル自体は、ファイルシステムの場所に配置された XMLFileSystemTemplateProvider オブジェクトです。

新規または既存のサイトへのプロビジョニングテンプレートの適用

プロビジョニングテンプレートを抽出、保存、永続化したら、次の最後の手順は、そのプロビジョニングテンプレートを新しい SharePoint サイトコレクションに適用することです。これを行うには、ApplyProvisioningTemplate メソッドを使用します。

対象サイトの資格情報を取得します。

// ctx.Credentials = new NetworkCredentials(userName, pwd);
ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
ctx.RequestTimeout = Timeout.Infinite;

コンパニオンメソッド ProvisioningTemplateApplyingInformation を使用して、ProvisioningTemplateCreationInformation メソッドによって格納されたサイト成果物をキャプチャします。

ProvisioningTemplateApplyingInformation ptai = new ProvisioningTemplateApplyingInformation();
ptai.ProgressDelegate = delegate(String message, Int32 progress, Int32 total)
{
  Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
};

アセットのファイルコネクタへの関連付けを取得します。

// Associate file connector for assets
FileSystemConnector connector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
template.Connector = connector;

(省略可能) プロビジョニングテンプレートはオブジェクトインスタンスであるため、実行時にサイトアーティファクトをカスタマイズするコードを作成できます。このインスタンスでは、新しい「contact」リストを追加します。
```
// Because the template is actual object, we can modify this using code as needed
template.Lists.Add(new ListInstance()
{
  Title = "PnP Sample Contacts",
  Url = "lists/PnPContacts",
  TemplateType = (Int32)ListTemplateType.Contacts,
  EnableAttachments = true
});
```
1 行のコードを再び使用して、新しいサイトにプロビジョニングテンプレートを適用します。
```
web.ApplyProvisioningTemplate(template, ptai);
```

ApplyProvisioningTemplate() メソッドの実装全体は以下のとおりです。

private static void ApplyProvisioningTemplate(string targetWebUrl, string userName, SecureString pwd, ProvisioningTemplate template)
{
  using (var ctx = new ClientContext(targetWebUrl))
  {
    // ctx.Credentials = new NetworkCredentials(userName, pwd);
    ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
    ctx.RequestTimeout = Timeout.Infinite;

    Web web = ctx.Web;

    ProvisioningTemplateApplyingInformation ptai = new ProvisioningTemplateApplyingInformation();
    ptai.ProgressDelegate = delegate (String message, Int32 progress, Int32 total)
    {
      Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
    };

    // Associate file connector for assets
    FileSystemConnector connector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
    template.Connector = connector;

    // Because the template is actual object, we can modify this using code as needed
    template.Lists.Add(new ListInstance()
    {
      Title = "PnP Sample Contacts",
      Url = "lists/PnPContacts",
      TemplateType = (Int32)ListTemplateType.Contacts,
      EnableAttachments = true
    });

    web.ApplyProvisioningTemplate(template, ptai);
  }
}

コンソールアプリケーションのプロビジョニングサンプル

Visual Studio プロジェクトの作成と準備

プロビジョニングテンプレートの作成、抽出、および永続化

新規または既存のサイトへのプロビジョニングテンプレートの適用

関連項目

その他のリソース

コンソール アプリケーションのプロビジョニング サンプル

Visual Studio プロジェクトの作成と準備

プロビジョニング テンプレートの作成、抽出、および永続化

新規または既存のサイトへのプロビジョニング テンプレートの適用

関連項目

その他のリソース

コンソールアプリケーションのプロビジョニングサンプル

プロビジョニングテンプレートの作成、抽出、および永続化

新規または既存のサイトへのプロビジョニングテンプレートの適用