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

新しいアドイン モデルをサポートするために Office 365 Developer Patterns and Practices プログラム (PnP) で導入されたプロビジョニング フレームワークを使用すると、ユーザーは、To support the new add-in model, the Office 365 Developer Patterns and Practices (PnP) program introduced a provisioning framework that allows users to:

  • サイト モデルを指すだけでカスタム サイト テンプレートを作成でき、Create custom site templates by simply pointing at a site model.
  • そのモデルをプロビジョニング テンプレートとして永続化し、Persist the model as a provisioning template.
  • そのカスタム テンプレートを必要に応じて既存のサイト コレクションに適用することができます。Apply the custom template to existing site collections as needed.

注意

PnP プロビジョニング フレームワーク & PnP プロビジョニング エンジンは、活発なコミュニティによりサポートされているオープン ソース ソリューションです。The PnP Provisioning Framework & PnP Provisioning Engine are open-source solutions with active community providing support for it. Microsoft からのオープン ソース ツールのサポート SLA はありません。There is no SLA for the open-source tool support from Microsoft.

このサンプルでは、PnP のコア プロビジョニング ライブラリのクラスを実装する基本的なコンソール アプリケーションを作成します。これらのクラスの実装により、PnP プロビジョニング エンジンが以下の必要なプロビジョニング タスクを実行することが可能になります。In this sample, we create a basic console application that implements classes in the provisioning PnP Core library to enable the PnP provisioning engine to complete these essential provisioning tasks:

  • サイトのカスタマイズを設計してモデル化します。新しいサイト デザインにすることも、既存のサイトをポイントして、それをプロビジョニング テンプレートとして保存することもできます。Design and model your site customization. This can be a new site design, or you can point to an existing site and save it as a provisioning template.
  • サイト モデルをプロビジョニング テンプレートとして保存して永続化し、再利用できるようにします。Save and persist the site model as a provisioning template so that you can reuse it.
  • プロビジョニング テンプレートを新規または既存のサイト コレクションに適用します。Apply the provisioning template to a new or existing site collection.

注意

このサンプル チュートリアルは、現在 GitHub の「PnP プロビジョニング エンジンの入門」で入手できるサンプルと対になるものです。This sample walkthrough is a companion to a sample currently available on GitHub at Getting Started with the PnP provisioning engine. このサンプルのコード (Program.cs) とソリューション ファイルは、ダウンロードできます。The code (Program.cs) and solution files for the sample are available for download. Microsoft Channel 9 のサイトの「PnP プロビジョニング エンジンの入門」にはこのプロセス (コードは若干異なります) について説明する 20 分間のビデオもあります。There also is a 20-minute video presentation of this process (with slightly different code) available on the Microsoft Channel 9 site, Getting Started with the PnP provisioning engine.

Visual Studio プロジェクトの作成と準備Create and prepare a Visual Studio project

はじめに、Visual Studio プロジェクトを作成します。To begin, create a Visual Studio project. このサンプルでは、簡略化するために、プロビジョニング フレームワークの PnP コア ライブラリを使用して PnP プロビジョニング エンジンを実装する基本的なコンソール アプリケーションを作成します。In this sample, for simplicity, we create a basic console application that implements the PnP provisioning engine by using the PnP Core library of the provisioning framework. ただし、このサンプル ソリューションをサポートするには、PnP コア ライブラリ用のプロビジョニング フレームワークをダウンロードしてインストールする必要があります。To support the sample solution, however, we must download and install the provisioning framework for the PnP Core library.

  1. Visual Studio を開いてから、[ファイル] > [新規] > [プロジェクト] を選択します。Open Visual Studio, and then choose File > New > Project.

  2. 新規プロジェクト ウィザードで、[Visual C#] を選択してから、[コンソール アプリケーション] を選択します。In the New Project Wizard, choose Visual C#, and then choose Console Application.

  3. プロジェクトに Program という名前を付けてから、[OK] を選択します Name the project Program, and then choose OK. (任意の名前を付けることができますが、このサンプル チュートリアルではプロジェクト名は Program とします)。(You can name the project anything you like, but be mindful that this walkthrough will reference the project name as Program.)

  4. PnP コア ライブラリをダウンロードしてインストールします。これは NuGet パッケージとして「SharePointPnPCore パッケージ」から入手できます。Download and install the PnP Core library that is available as a NuGet package at SharePointPnPCore packages.

    注意

    このライブラリには、次の 3 つのバージョンがあります。There are three versions of the library. 1 つ目のバージョンは、SharePoint Online と Office 365 をターゲットにした SharePointPnPCoreOnline ライブラリです。One version is the SharePointPnPCoreOnline library, which targets SharePoint Online and Office 365. その他のバージョンは、SharePointPnPCore2013 および SharePointPnPCore2016 です。そして、それぞれが SharePoint オンプレミス バージョン 2013 および 2016 をターゲットにします。The other versions are SharePointPnPCore2013 and SharePointPnPCore2016 , which target SharePoint on-premises versions 2013 and 2016 respectively.

  5. NuGet クライアント インストーラー」にアクセスして NuGet クライアントをインストールします。Install the NuGet client by going to the NuGet client installer.

  6. NuGet クライアントがインストールされたら、NuGet パッケージ マネージャー を実行します。After the NuGet client is installed, run the NuGet Package manager. Visual Studio の ソリューション エクスプローラーReferences ノードを右クリックしてから、[NuGet パッケージの管理] を選択します。Right-click the References node in the Visual Studio Solution Explorer, and then select Manage NuGet Packages.

  7. パッケージ マネージャーで [参照] を選択し、検索語として「SharePoint PnP」を入力して、SharePointPnPCoreOnline ライブラリが表示されるようにします。In the Package Manager, choose Browse, and then enter the search term SharePoint PnP to expose the SharePointPnPCoreOnline library.

  8. 指示に従って SharePointPnPCoreOnline ライブラリをダウンロードしてインストールします。Follow directions to download and install the SharePointPnPCoreOnline library, following the given directions.

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

  9. Program.cs ファイルに以下のすべての using ステートメントが含まれていることを確認します。Ensure that your Program.cs file contains all of the following using statements.

    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;
    

プロビジョニング テンプレートの作成、抽出、および永続化Create, extract, and persist the provisioning template

プロジェクトがセットアップされたら、サイトのカスタマイズを作成できます。After your project is set up, you can create your site customizations. これは、手動で実行することも、デザインを流用するサイトを指すことで実行することもできます。You can do this manually or by pointing to a site whose design you wish to use. 選択したサイト デザインをプロビジョニング テンプレートとして保存するだけです。両方のアプローチの組み合わせを使用することもできます。Simply save the chosen site design as a provisioning template, or you can use a mix of both approaches. このサンプルの目的では、既存のサイトを指して、作成済みの外観とサイト成果物 (ただし、コンテンツではない) をプロビジョニング テンプレートとして保存するだけです。For the purpose of this sample, we will simply point to an existing site and save its composed look and site artifacts (but not its content) as a provisioning template.

まず、プロビジョニング テンプレートのモデルにするサイトに接続する必要があります。ユーザー名、パスワード、ソース URL などの接続情報を収集することから開始します。To begin, we need to connect to the site that we wish to model as our provisioning template. Let's start by gathering connection information, including user name, password, and the source URL.

  1. ユーザーから接続情報を収集します。Collect connection information from the user. プログラムの Main ルーチンでは、次の 3 つの簡単な作業を行っています。これらは、接続情報の収集、プロビジョニング テンプレートの取得、およびプロビジョニング テンプレートの適用です。In the program's Main routine, we do three simple things: collect connection information, GET the provisioning template, and APPLY the provisioning template. 面倒な作業は、次に定義する GetProvisioningTemplate メソッドと ApplyProvisioningTemplate メソッドによって行われます。The heavy lifting is done by the GetProvisioningTemplate and ApplyProvisioningTemplate methods that we define next.

    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();
    }
    
  2. プライベート GetInput メソッドを作成し、これを使用して必要なユーザー資格情報を取得します。Create and use a private GetInput method to obtain the required user credentials.

    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;
    }
    
  3. プロビジョニング テンプレートのモデルとなるサイトを指します。Point to the site that's the model for our provisioning template. 1 行のコードを使用してソース サイトで GET を実行しながら、定義した GET メソッドである GetProvisioningTemplate() を確認します。While doing the GET on the source site with a single line of code, look at GetProvisioningTemplate(), which is the GET method we defined.

    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) も定義しました。In the previous code snippet, we also defined a ProvisioningTemplateCreationInformation variable, pcti. この変数により、テンプレートと共に保存できる成果物に関する情報を格納できます。The variable gives us the option to store information about artifacts that we can save along with the template.

  4. ファイル システム コネクター オブジェクトを作成し、別のサイトに適用するプロビジョニング テンプレートの一時的なコピーを格納できるようにします。Create a file system connector object so that we can store a temporary copy of the provisioning template that we're going to apply to another site.

    注意

    この手順は省略できます。This step is optional. XML にプロビジョニング テンプレートをシリアル化する必要はありません。It's not required that you serialize the provisioning template to XML. この段階で、テンプレートは単なる C# コードです。At this stage, the template is simply C# code. シリアル化が省略可能であるだけでなく、必要なシリアル化形式を何でも使用できます。Not only is serialization optional, but you also can use whatever serialization format you wish.

  5. 次の 1 行のコードだけを使用して、プロビジョニング テンプレートの抽出を実行します。Execute the extraction of the provisioning template by using only this single line of code:

    ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);
    
  6. (オプション) プロビジョニング テンプレートのシリアル化されたバージョンを保存して再利用できるようにします。(Optional) Save and store a serialized version of the provisioning template so that you can reuse it. プロビジョニング テンプレートは任意の形式でシリアル化することができます。You can serialize the provisioning template in whichever format you prefer. このサンプルでは、PnPProvisioningDemo.xml という名前の XML ファイルにシリアル化しました。In this sample, we serialized to an XML file named PnPProvisioningDemo.xml. ファイル自体は、ファイル システムの場所に配置された XMLFileSystemTemplateProvider オブジェクトです。The file itself is an XMLFileSystemTemplateProvider object for which we provided a file system location.

新規または既存のサイトへのプロビジョニング テンプレートの適用Apply the provisioning template to a new or existing site

プロビジョニング テンプレートを抽出、保存、永続化したら、次の最後の手順は、そのプロビジョニング テンプレートを新しい SharePoint サイト コレクションに適用することです。これを行うには、ApplyProvisioningTemplate メソッドを使用します。After we extract, save, and persist the provisioning template, the next and final step is to apply the provisioning template to a new SharePoint site collection by using the ApplyProvisioningTemplate method.

  1. 対象サイトの資格情報を取得します。Obtain credentials to the target site.

    // ctx.Credentials = new NetworkCredentials(userName, pwd);
    ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
    ctx.RequestTimeout = Timeout.Infinite;
    
  2. コンパニオン メソッド ProvisioningTemplateApplyingInformation を使用して、ProvisioningTemplateCreationInformation メソッドによって格納されたサイト成果物をキャプチャします。Capture site artifacts that were stored using the ProvisioningTemplateCreationInformation method by using the companion method, ProvisioningTemplateApplyingInformation.

    ProvisioningTemplateApplyingInformation ptai = new ProvisioningTemplateApplyingInformation();
    ptai.ProgressDelegate = delegate(String message, Int32 progress, Int32 total)
    {
      Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
    };
    
  3. アセットのファイル コネクタへの関連付けを取得します。Get an association to the file connector for the assets.

    // Associate file connector for assets
    FileSystemConnector connector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
    template.Connector = connector;
    
  4. (省略可能) プロビジョニング テンプレートはオブジェクト インスタンスであるため、実行時にサイト アーティファクトをカスタマイズするコードを作成できます。このインスタンスでは、新しい「contact」リストを追加します。(Optional) Because the provisioning template is an object instance, we can write code to customize site artifacts on the fly. In this instance, we're adding a new "contact" list.

    // 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
    });
    
  5. 1 行のコードを再び使用して、新しいサイトにプロビジョニング テンプレートを適用します。Apply the provisioning template to the new site, again using one line of code.

    web.ApplyProvisioningTemplate(template, ptai);
    
  6. ApplyProvisioningTemplate() メソッドの実装全体は以下のとおりです。The whole ApplyProvisioningTemplate() method implementation is below.

    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);
      }
    }
    

関連項目See also