Знакомство с подсистемой подготовки PnP
В этой статье представлен модуль подготовки PnP, который был первоначально выпущен в апреле 2015 г. в рамках проекта OfficeDev PnP и ежемесячно обновляется в соответствии расписанием выпусков основной библиотеки Office Dev PnP.
Примечание.
Платформа подготовки PnP & подсистема подготовки PnP — это решения с открытым кодом, в которых активное сообщество предоставляет поддержку. SLA для поддержки инструмента с открытым исходным кодом со стороны Майкрософт отсутствует.
Цель
Начнем с основной цели — создания модуля подготовки. С появлением Microsoft Office 365 и Microsoft SharePoint Online разработчики столкнулись с новой моделью облачных надстроек как новым способом создания настраиваемых программных решений для Microsoft SharePoint, SharePoint Online и Office 365 в целом. Однако, хотя в прошлом разработчики предоставляли настраиваемые артефакты с помощью инфраструктуры возможностей на основе CAML/XML, либо с помощью решений с кодом полного доверия (FTC), либо с решениями для песочницы, подготовка артефактов в новой модели облачной надстройки должна быть выполнена с помощью метода "удаленная подготовка". Что означает удаленная подготовка? Это означает использование одного из доступных API (REST или CSOM) для подготовки артефактов вместо использования инфраструктуры возможностей.
Что делать, если вы хотите смоделировать и подготовить артефакты с помощью тестовой и производственной среды, или что делать, если вы хотите автоматизировать подготовку артефактов, просто потому, что вы хотите продать настройки нескольким клиентам? Аналогичным образом, что делать, если вы хотите определить настраиваемый шаблон сайта, который можно повторно использовать в нескольких экземплярах сайтов, таких как сайты, ориентированные на клиента или сайты, ориентированные на проекты?
Используя новый механизм подготовки PnP, можно смоделировать сайт, настроив конструктор столбцов сайта, типов контента, определений и экземпляров списков, страниц и многого другого с помощью веб-браузера. После этого можно экспортировать все, что вы сделали, в формат шаблона подготовки (XML, JSON или контейнер, называемый файлом PnP), и применить этот шаблон к максимальному количеству целевых сайтов.
Однако что, если вы хотите подготовить другие артефакты, такие как Microsoft Teams? Или пользователей Azure AD? Модуль подготовки PnP может сделать всю работу за вас.
Два типа шаблонов
В основном существует два типа шаблонов, которые понимает механизм: Шаблоны сайтов (также называемые шаблонами подготовки) и расширенная версия: Шаблоны клиентов.
Когда был представлен модуль, единственным доступным типом шаблона был шаблон сайта. Через несколько лет был представлен шаблон клиента, который отличается способностью подготавливать артефакты за пределами сайтов SharePoint. Шаблон клиента, например, позволяет подготовить группу Microsoft Teams, пользователей Azure AD, дизайны сайтов и сценарии сайтов, темы с областью действия клиента и т. д. В отличие от шаблонов сайта, вы можете создать так называемую "последовательность" в шаблоне клиента и создать семейства сайтов.
Вкратце: шаблон клиента — это шаблон сайта, который может содержать артефакты для подготовки к уровню клиента.
Создайте шаблона сайта
Как уже было сказано, самый простой способ создать настраиваемый шаблон подготовки — это создать новое семейство веб-сайтов в SharePoint Online, настроить артефакты (столбцы сайта, типы контента, списки, страницы и т. д.) и сохранить результат в качестве шаблона подготовки.
Допустим, вы определили пример сайта с настраиваемой домашней страницей:
Помимо настраиваемой домашней страницы вы создали несколько событий в готовом списке событий:
Чтобы экспортировать этот сайт в качестве шаблона подготовки, можно использовать код PowerShell или CSOM с некоторыми методами расширения, которые предоставляются основной библиотекой OfficeDev PnP.
Использование командлетов PowerShell
Примечание.
В этой статье основное внимание уделяется использованию PnP PowerShell для работы с модулем подготовки. Если вы предпочитаете использовать C#, см. статью Подсистема подготовки PnP и основная библиотека.
Примечание.
PnP PowerShell — это решение с открытым исходным кодом, поддержка которого предоставляется активным сообществом. Для инструментов с открытым исходным кодом не существует соглашения об уровне обслуживания в отношении поддержки корпорацией Майкрософт.
Чтобы использовать командлеты PowerShell для SharePoint Online или SharePoint, перейдите к обзору PnP PowerShell и установите модуль SharePoint PnP PowerShell.
После подключения среды PowerShell к SharePoint Online с помощью командлета Connect-PnPOnline можно использовать следующий командлет PowerShell:
Get-PnPSiteTemplate -Out "PnP-Provisioning-File.xml"
Аргумент –Out указывает командлету, где сохранить шаблон подготовки.
Результатом извлечения и сохранения шаблона является, в зависимости от расширения, используемого в командлете (в настоящее время мы поддерживаем XML и .pnp) файла. Если вы выбрали сохранение шаблона в формате XML, он будет выглядеть примерно так, как показано ниже (обратите внимание, что шаблон не является полным и является лишь примером структуры XML):
Примечание.
Есть много параметров конфигурации, которые можно установить для извлечения шаблона. Объяснение этого можно найти в статье Настройка подсистемы подготовки PnP.
<?xml version="1.0"?>
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2019/09/ProvisioningSchema">
<pnp:Preferences Generator="OfficeDevPnP.Core, Version=3.14.1910.1, Culture=neutral, PublicKeyToken=null" />
<pnp:Templates ID="CONTAINER-TEMPLATE-8F4D883BE25B442FB9F889C351D3EA0B">
<pnp:ProvisioningTemplate ID="TEMPLATE-8F4D883BE25B442FB9F889C351D3EA0B" Version="1" BaseSiteTemplate="SITEPAGEPUBLISHING#0" Scope="RootSite">
<pnp:WebSettings RequestAccessEmail="" NoCrawl="false" WelcomePage="SitePages/Home.aspx" SiteLogo="{hosturl}{site}/SiteAssets/__sitelogo___sitelogo_theperspective.png"/>
<pnp:Navigation AddNewPagesToNavigation="true" CreateFriendlyUrlsForNewPages="true">
<pnp:CurrentNavigation NavigationType="StructuralLocal">
<pnp:StructuralNavigation RemoveExistingNodes="true">
<pnp:NavigationNode Title="Who we are" Url="http://linkless.header/" IsExternal="true"/>
<pnp:NavigationNode Title="What's happening" Url="http://linkless.header/" IsExternal="true"/>
<pnp:NavigationNode Title="Find it" Url="http://linkless.header/" IsExternal="true"/>
</pnp:StructuralNavigation>
</pnp:CurrentNavigation>
</pnp:Navigation>
<pnp:Lists>
<pnp:ListInstance Title="Events" Description="" DocumentTemplate="" TemplateType="106" Url="Lists/Events" MinorVersionLimit="0" MaxVersionLimit="0" DraftVersionVisibility="0" TemplateFeatureID="00bfea71-ec85-4903-972d-ebe475780106" ContentTypesEnabled="true" EnableFolderCreation="false" DefaultDisplayFormUrl="{site}/Lists/Events/DispForm.aspx" DefaultEditFormUrl="{site}/Lists/Events/EditForm.aspx" DefaultNewFormUrl="{site}/Lists/Events/NewForm.aspx" ImageUrl="/_layouts/15/images/itevent.png?rev=44" IrmExpire="false" IrmReject="false" IsApplicationList="false" ValidationFormula="" ValidationMessage="">
</pnp:ListInstance>
<pnp:DataRows KeyColumn="Title" UpdateBehavior="Overwrite">
<pnp:DataRow>
<pnp:DataValue FieldName="Title">Thanksgiving</pnp:DataValue>
<pnp:DataValue FieldName="fAllDayEvent">true</pnp:DataValue>
<pnp:DataValue FieldName="EventDate">2019-11-28 00:00:00</pnp:DataValue>
<pnp:DataValue FieldName="EndDate">2019-11-28 23:59:00</pnp:DataValue>
</pnp:DataRow>
<pnp:DataRow>
<pnp:DataValue FieldName="Title">In the design lab with Carlos Slattery</pnp:DataValue>
<pnp:DataValue FieldName="Location">Contoso HQ</pnp:DataValue>
<pnp:DataValue FieldName="fAllDayEvent">false</pnp:DataValue>
<pnp:DataValue FieldName="EventDate">2020-01-02 10:00:00</pnp:DataValue>
<pnp:DataValue FieldName="EndDate">2020-01-02 12:00:00</pnp:DataValue>
</pnp:DataRow>
</pnp:DataRows>
</pnp:Lists>
<pnp:ClientSidePages>
<pnp:ClientSidePage PromoteAsNewsArticle="false" PromoteAsTemplate="false" Overwrite="true" Layout="Home" EnableComments="false" Title="Home" ThumbnailUrl="" PageName="Home.aspx" LCID="0">
<pnp:Header Type="Default" LayoutType="FullWidthImage" TextAlignment="Center" ShowTopicHeader="false" ShowPublishDate="false" TopicHeader="" AlternativeText="" Authors="[]" AuthorByLine="[]" AuthorByLineId="-1" />
<pnp:Sections>
<pnp:Section Order="1" Type="OneColumnVerticalSection" VerticalSectionEmphasis="Soft">
<pnp:Controls>
<pnp:CanvasControl WebPartType="News" JsonControlData="{"id": "8c88f208-6c77-4bdb-86a0-0c47b4316588", "instanceId": "1ac6db3e-eb95-4d5d-a991-28ee34772313", ..." ControlId="8c88f208-6c77-4bdb-86a0-0c47b4316588" Order="1" Column="1" />
<pnp:CanvasControl WebPartType="News" JsonControlData="{"id": "8c88f208-6c77-4bdb-86a0-0c47b4316588", "instanceId": "e5fc83c0-3350-4eea-9606-6627646a0a4b", "title": "News", "description": "..." ControlId="8c88f208-6c77-4bdb-86a0-0c47b4316588" Order="2" Column="1" />
<pnp:CanvasControl WebPartType="Custom" JsonControlData="{"id": "868ac3c3-cad7-4bd6-9a1c-14dc5cc8e823", "instanceId": "c1524d29-ab2a-44a3-809e-c01c3762c4ee", "title": "Weather", "description":..." ControlId="868ac3c3-cad7-4bd6-9a1c-14dc5cc8e823" Order="1" Column="2" />
</pnp:Controls>
</pnp:Section>
<pnp:Section Order="2" Type="OneColumn">
<pnp:Controls>
<pnp:CanvasControl WebPartType="CallToAction" JsonControlData="{"id": "df8e44e7-edd5-46d5-90da-aca1539313b8", "instanceId": "b022816d-c9de-4989-aa10-9b44bec4a872", "title": "Call to action", "description": "Call to action", "dataVersion&..." Order="1" Column="1" />
</pnp:Controls>
</pnp:Section>
<pnp:Section Order="3" Type="ThreeColumn">
<pnp:Controls>
<pnp:CanvasControl WebPartType="Image" JsonControlData="{"id": "d1d91016-032f-456d-98a4-721247c305e8", "instanceId": "984b089c-ca62-4f92-89c0-1ce0e1cb6c03", "title": "Image", "description": "Image", "dataVersion": "1.8", "..." ControlId="d1d91016-032f-456d-98a4-721247c305e8" Order="1" Column="1" />
<pnp:CanvasControl WebPartType="Text" ControlId="5755396c-b272-4c0f-8e8d-eb41d218a10e" Order="2" Column="1">
<pnp:CanvasControlProperties>
<pnp:CanvasControlProperty Key="Text" Value="<p><span class="fontColorThemePrimary"><span class="fontSizeMediumPlus"><strong>BREATHTAKING VIDEOS &amp; PHOTOS</strong></span></span></p>

<p>..." />
</pnp:CanvasControlProperties>
</pnp:CanvasControl>
<pnp:CanvasControl WebPartType="Button" JsonControlData="{"id": "0f087d7f-520e-42b7-89c0-496aaf979d58", "instanceId": "deb39e2b-11a0-4141-8ac1-1078fe7cc392", "title": "..." ControlId="0f087d7f-520e-42b7-89c0-496aaf979d58" Order="3" Column="1" />
<pnp:CanvasControl WebPartType="Image" JsonControlData="{"id": "d1d91016-032f-456d-98a4-721247c305e8", "instanceId": "e0b59b5b-8a5a-406e-9deb-6e6f9de4bd3b", "title": "Image", ..." ControlId="d1d91016-032f-456d-98a4-721247c305e8" Order="1" Column="2" />
</pnp:Controls>
</pnp:Section>
</pnp:Sections>
</pnp:ClientSidePage>
</pnp:ClientSidePages>
<pnp:Header Layout="Compact" MenuStyle="MegaMenu" BackgroundEmphasis="Strong" />
<pnp:Footer Enabled="true" RemoveExistingNodes="false" />
</pnp:ProvisioningTemplate>
</pnp:Templates>
</pnp:Provisioning>
Как видите, элементы XML довольно понятны. Схема XML, используемая в примере, ссылается на версию схемы подготовки PnP 201909, которая была определена вместе с сообществом PnP SharePoint и которую можно найти на GitHub в разделе PnP-Provisioning-Schema. В том же репозитории также можно найти автоматически созданный документ markdown (MD), описывающий основные элементы, типы и атрибуты, доступные для определения шаблона подготовки XML вручную.
Вы можете определить ProvisioningTemplate вручную, используя сайт модели, или составив XML-документ, который проверяется на соответствие схеме XSD для PnP, или просто написав код .NET и построив иерархию объектов. Вы даже можете использовать сочетание этих подходов: можно разработать шаблон подготовки с помощью модельного сайта и сохранить его в XML-файле и выполнить некоторые настройки в памяти при обработке экземпляра ProvisioningTemplate в коде.
Применение шаблона подготовки
Теперь, когда вы знаете, что такое шаблон подготовки, вы готовы к его применению к целевому сайту.
Допустим, вы создали еще одно новое семейство информационных сайтов в SharePoint Online, как показано на следующем рисунке.
По умолчанию сайт будет выглядеть, как на следующем рисунке, который является макетом по умолчанию для информационного сайта.
Теперь вы можете применить настраиваемый шаблон сайта с помощью командлета PnP PowerShell
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/targetcommunicationsite"
Invoke-PnPSiteTemplate -Path "PnP-Provisioning-File.xml"
Аргумент –Path относится к исходному файлу шаблона, который командлет автоматически применяет к сайту, подключенному в данный момент (подразумевается командлет Connect-PnPOnline).
Примечание.
Эмпирическое правило заключается в следующем: при применении шаблона сайта, целевой сайт должен быть создан и работать. Если вы хотите создать сайт «на лету» с помощью шаблона, необходимо будет создать шаблон клиента. Дополнительные сведения о шаблонах клиентов см. ниже.
Применение шаблона клиента
Шаблон клиента очень похож на шаблон сайта с дополнительными элементами, один из которых является фундаментальным — последовательность.
Последовательность — это конфигурация одного или нескольких семейств веб-сайтов, которые необходимо создать. Ознакомьтесь со следующим фрагментом шаблона:
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2019/09/ProvisioningSchema" Author="John White" Generator="Human being" Version="1.0" Description="Home Site" DisplayName="The Perspective">
<pnp:Sequence ID="sequence">
<pnp:SiteCollections>
<pnp:SiteCollection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="pnp:CommunicationSite" ProvisioningId="MAIN" SiteDesign="Topic" Title="My New Site" Description="" Url="/sites/mynewsite" IsHubSite="false" Owner="user@domain.com">
<pnp:Templates>
<pnp:ProvisioningTemplateReference ID="MAIN-TEMPLATE"/>
</pnp:Templates>
</pnp:SiteCollection>
</pnp:SiteCollections>
</pnp:Sequence>
<pnp:Templates ID="SITE-TEMPLATES">
<pnp:ProvisioningTemplate ID="MAIN-TEMPLATE" Version="1" BaseSiteTemplate="SITEPAGEPUBLISHING#0" Scope="RootSite">
<pnp:Header Layout="Compact" MenuStyle="MegaMenu" BackgroundEmphasis="Strong" />
Как видите, последовательность определяется на том же уровне, что и элемент <pnp:Templates />. Последовательность может содержать один или несколько сайтов, а также определять дочерние сайты. Для каждого сайта можно обращаться к одному или нескольким шаблонам, которые будут применяться после создания сайта. Вы обращаетесь к шаблону по его идентификатору, и в этом примере шаблоны находятся в том же XML-файле.
Чтобы применить шаблон клиента к клиенту введите:
Connect-PnPOnline https://yourtenant.sharepoint.com
Invoke-PnPTenantTemplate -Path "yourtenanttemplate.xml"
Дополнительные сведения о шаблонах клиентов см. в разделе Шаблоны клиента подготовки PnP.
Дополнительные статьи
Это всего лишь вводная статья. Важно понимать, что при использовании модуля подготовки PnP можно также предоставлять таксономии и использовать переменные и маркеры, которые можно заменять во время выполнения, в зависимости от того, подготовка чего идет (например, идентификаторов списков, параметров или идентификаторов терминов). Вы можете вызвать модуль подготовки из служб заданий таймера, надстроек, размещаемых у поставщика, внешних сайтов и т.д. Наконец, вы можете использовать механизм подготовки PnP для перемещения артефактов из тестовых или промежуточной сред в производственные среды.
Обязательно ознакомьтесь с другими статьями для более сложных тем.
Требования и подведение итогов
Для воспроизведения модуля подготовки PnP в локальной среде, необходимо иметь как минимум установленный накопительный пакет обновления SharePoint 2013 за март 2015 года, поскольку этот модуль использует некоторые возможности клиентской объектной модели, которые недоступны в предыдущих версиях продукта. Если вы ориентированы на SharePoint Online, требования автоматически будут выполнены благодаря модели "Программное обеспечение как услуга".
Воспроизводите модуль подготовки PnP, поделитесь с нами своими отзывами и наслаждайтесь будущим модели надстроек SharePoint и удаленной подготовки!