Пример подготовки консольного приложения

Статья
04/08/2023

Для поддержки новой модели надстроек в программе Patterns and Practices (PnP) для разработчиков Office 365 появилась платформа подготовки, которая позволяет пользователям выполнять следующее:

Создание пользовательских шаблонов сайтов с помощью указания модели сайта.
Сохранение модели в качестве шаблона подготовки.
Применение настраиваемого шаблона для нового или существующего семейства веб-сайтов по мере необходимости.

Примечание.

Платформа подготовки PnP & подсистема подготовки PnP — это решения с открытым кодом, в которых активное сообщество предоставляет поддержку. SLA для поддержки инструмента с открытым исходным кодом со стороны Майкрософт отсутствует.

В этом примере мы создаем базовое консольное приложение, которое реализует классы в основной библиотеке подготовки PnP, чтобы позволить подсистеме подготовки PnP выполнить следующие необходимые задачи подготовки:

Проектирование и моделирование персональной настройки сайта. Это может быть новый дизайн сайта, или вы можете указать существующий сайт и сохранить его как шаблон подготовки.
Сохранение и поддержание модели сайта как шаблона подготовки для повторного использования.
Применение шаблона подготовки для нового или уже существующего семейства веб-сайтов.

Примечание.

Данный пример с пошаговым руководством дополняет шаблон, доступный в настоящее время на портале GitHub в разделе Начало работы с модулем подготовки PnP. Код (Program.cs) и файлы решения для примера доступны для скачивания. Также доступно 20-минутное видео данного процесса (с немного отличающимся кодом) на сайте Microsoft Channel 9 (Начало работы с модулем подготовки PnP).

Создание и подготовка проекта Visual Studio

В начале создайте проект Visual Studio. В этом примере для удобства мы создадим базовое консольное приложение, которое реализует модуль подготовки PnP с помощью основной библиотеки PnP платформы подготовки. Для поддержки примера решения, тем не менее, мы должны скачать и установить платформу подготовки для основной библиотеки PnP.

Откройте Visual Studio и выберите File>New>Project.
В мастере создания проекта выберите Visual C#, а затем нажмите Console Application.
Укажите имя Program для проекта и нажмите кнопку OK. (Вы можете присвоить проекту любое имя, но будьте внимательны: в этом руководстве будет использоваться имя проекта Program.)
Скачайте и установите основную библиотеку PnP, которая доступна в виде пакета NuGet в пакетах SharePointPnPCore.

Примечание.

Существует три версии библиотеки. Первая версия – это библиотека SharePointPnPCoreOnline, которая предназначена для SharePoint Online и Office 365. Другие версии — это SharePointPnPCore2013 и SharePointPnPCore2016, которые предназначены для локальных версий SharePoint 2013 и 2016 соответственно.
Установите клиент NuGet, перейдя к установщику клиента NuGet.
После установки клиента NuGet запустите диспетчер пакетов NuGet. Дважды щелкните узел References в обозревателе решений Visual Studio, а затем нажмите Manage NuGet Packages.
В диспетчере пакетов нажмите Browse, а затем введите поисковый запрос SharePoint PnP, чтобы открыть библиотеку SharePointPnPCoreOnline.
Следуйте инструкциям, чтобы скачать и установить библиотеку SharePointPnPCoreOnline.

После того как вы создали ссылку на основную библиотеку PnP в проекте Visual Studio, все члены библиотеки доступны вам в качестве методов расширения для существующих экземпляров объектов, например web и list.

Убедитесь, что файл 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 выполняются три простых действия: собираем сведения о подключении, получаем (GET) шаблон подготовки и применяем (APPLY) его. Эти задачи выполняют методы 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;
}

Укажите сайт, который мы будем использовать как модель для нашего шаблона подготовки. Для выполнения операции 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#. Сериализация не только является необязательной, но вы также можете использовать любой формат сериализации.
Извлеките шаблон подготовки с помощью одной строки кода:
```
ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);
```
(Необязательно.) Сохраните сериализованную версию шаблона подготовки для ее повторного использования. Вы можете выполнить сериализацию шаблона подготовки в любом формате, который вы предпочитаете. В этом примере мы выполнили сериализацию в XML-файл с именем PnPProvisioningDemo.xml. Сам файл — это объект XMLFileSystemTemplateProvider, для которого мы предоставляем расположение в файловой системе.

Применение шаблона подготовки для нового или уже существующего сайта

После того как мы извлекли и сохранили шаблон подготовки, следующим и конечным шагом будет применение шаблона подготовки для нового семейства веб-сайтов SharePoint с помощью метода ApplyProvisioningTemplate.

Получите учетные данные для конечного сайта.

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

Получите артефакты сайта, которые были сохранены с помощью метода ProvisioningTemplateCreationInformation, используя сопутствующий метод ProvisioningTemplateApplyingInformation.
```
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);
```

Весь метод реализации 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);
  }
}

См. также

Удаленная подготовка PnP

Поделиться через

Пример подготовки консольного приложения

Создание и подготовка проекта Visual Studio

Создание, извлечение и поддержание шаблона подготовки

Применение шаблона подготовки для нового или уже существующего сайта

См. также

Дополнительные ресурсы