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

Преобразование в современные страницы сайтов с помощью PowerShell

  • Статья

Важно!

Модернизация SharePoint PnP является частью платформы PnP и постоянно развивается. См. заметки о выпуске, чтобы быть в курсе последних изменений. Если у вас возникнут проблемы, внесите данные о них в список проблем в GitHub на платформе PnP.

Подсистему преобразования страниц также можно использовать из PowerShell. Благодаря этому ее можно интегрировать в сценарий модернизации сайта, который не только преобразует страницу, но также выполняет другие задачи, например установку решения, подключение сайта к группе Microsoft 365 и применение фирменной символики клиента. Хороший пример сценария комплексной модернизации можно найти в статье Подключение к группе Microsoft 365.

Примечание.

В приведенном ниже сценарии показано, как преобразовывать страницы. Для него требуется PnP PowerShell версии 1.3.* (февраль 2021 г.) или более поздней версии. Существуют дополнительные примеры скриптов (например, для преобразования страницы публикации, для преобразования из локальной среды SharePoint), доступные в нашем расположении скриптов GitHub.

<# 

.Synopsis

    Converts all classic wiki and web part pages in a site. 
    You need to install PnP PowerShell: https://pnp.github.io/powershell/

    Sample includes:
        - Conversion of wiki and web part pages
        - Connecting to MFA or supplying credentials
        - Includes Logging to File, log flushing into single log file        

.Example

    Convert-WikiAndWebPartPages.ps1 -SourceUrl "https://contoso.sharepoint.com/sites/classicteamsite" -TakeSourcePageName:$true

.Notes
    
    Useful references:
        - https://aka.ms/sppnp-pagetransformation
        - https://aka.ms/sppnp-powershell
#>

[CmdletBinding()]
param (

    [Parameter(Mandatory = $true, HelpMessage = "Url of the site containing the pages to modernize")]
    [string]$SourceUrl,

    [Parameter(Mandatory = $false, HelpMessage = "Modern page takes source page name")]
    [bool]$TakeSourcePageName = $false,    

    [Parameter(Mandatory = $false, HelpMessage = "Supply credentials for multiple runs/sites")]
    [PSCredential]$Credentials,

    [Parameter(Mandatory = $false, HelpMessage = "Specify log file location, defaults to the same folder as the script is in")]
    [string]$LogOutputFolder = $(Get-Location)
)
begin
{
    Write-Host "Connecting to " $SourceUrl
    
    if($Credentials)
    {
        Connect-PnPOnline -Url $SourceUrl -Credentials $Credentials
        Start-Sleep -s 3
    }
    else
    {
        Connect-PnPOnline -Url $sourceUrl -Interactive
        Start-Sleep -s 3
    }
}
process 
{    
    Write-Host "Ensure the modern page feature is enabled..." -ForegroundColor Green
    Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web -Force

    Write-Host "Modernizing wiki and web part pages..." -ForegroundColor Green
    # Get all the pages in the site pages library. 
    # Use paging (-PageSize parameter) to ensure the query works when there are more than 5000 items in the list
    $pages = Get-PnPListItem -List sitepages -PageSize 500

    Write-Host "Pages are fetched, let's start the modernization..." -ForegroundColor Green
    Foreach($page in $pages)
    { 
        $pageName = $page.FieldValues["FileLeafRef"]
        
        if ($page.FieldValues["ClientSideApplicationId"] -eq "b6917cb1-93a0-4b97-a84d-7cf49975d4ec" ) 
        { 
            Write-Host "Page " $page.FieldValues["FileLeafRef"] " is modern, no need to modernize it again" -ForegroundColor Yellow
        } 
        else 
        {
            Write-Host "Processing page $($pageName)" -ForegroundColor Cyan
            
            # -TakeSourcePageName:
            # The old pages will be renamed to Previous_<pagename>.aspx. If you want to 
            # keep the old page names as is then set the TakeSourcePageName to $false. 
            # You then will see the new modern page be named Migrated_<pagename>.aspx

            # -Overwrite:
            # Overwrites the target page (needed if you run the modernization multiple times)
            
            # -LogVerbose:
            # Add this switch to enable verbose logging if you want more details logged

            # KeepPageCreationModificationInformation:
            # Give the newly created page the same page author/editor/created/modified information 
            # as the original page. Remove this switch if you don't like that

            # -CopyPageMetadata:
            # Copies metadata of the original page to the created modern page. Remove this
            # switch if you don't want to copy the page metadata

            ConvertTo-PnPPage -Identity $page.FieldValues["ID"] `
                                -Overwrite `
                                -TakeSourcePageName:$TakeSourcePageName `
                                -LogType File `
                                -LogFolder $LogOutputFolder `
                                -LogSkipFlush `
                                -KeepPageCreationModificationInformation `
                                -CopyPageMetadata
        }
    }

    # Write the logs to the folder
    Write-Host "Writing the conversion log file..." -ForegroundColor Green
    Save-PnPPageConversionLog

    Write-Host "Wiki and web part page modernization complete! :)" -ForegroundColor Green
}
end
{
    Disconnect-PnPOnline
}

Параметры командлета ConvertTo-PnPPage

Командлет ConvertTo-PnPPage — это ключевой командлет для модернизации данной страницы. В приведенной ниже таблице перечислены параметры командной строки, которые можно использовать для управления преобразованием страницы с помощью этого командлета.

Параметр По умолчанию Поддержка Описание
Identity (*) Все типы страниц Имя страницы (например, pageA.aspx) для страниц вики-сайтов, веб-частей и страниц публикации или название блога для страниц классических блогов. В классических блогах используйте первую страницу, на которой название начинается с указанного параметра Identity, или укажите идентификатор (целое значение) страницы.
Library Страницы вики-сайтов или веб-частей Библиотека, содержащая страницу. Используйте параметр -Library, если страница вики-сайта или веб-части находится за пределами стандартной библиотеки SitePages.
Folder Страницы вики-сайтов, веб-частей или страницы публикации Если страница, которую требуется преобразовать, находится в папке, вы можете указать эту папку (например, -Folder "Folder1/SubFolder").
WebPartMappingFile Все типы страниц Преобразование страницы управляется файлом сопоставления. Командлет содержит встроенный файл сопоставления по умолчанию, но можно также указать пользовательский файл сопоставления веб-части (webpartmapping.xml), соответствующий требованиям преобразования страницы (например, преобразование для сторонних пользовательских веб-частей). Для этого нужно указать путь к файлу с помощью параметра -WebPartMappingFile.
Overwrite $false Все типы страниц Если вы добавляете параметр -Overwrite, платформа преобразования страниц будет при необходимости перезаписывать целевую страницу. По умолчанию в имени новой страницы используется префикс Migrated_, и затем подразумевается, что если файл Migrated_YourPage.aspx уже существует (обычно из предыдущей попытки преобразования страницы), он будет перезаписан.
ReplaceHomePageWithDefault $false Страницы вики-сайтов или веб-частей Действие по умолчанию состоит в преобразовании домашней страницы сайта в современную страницу аналогично любой другой обычной странице. При использовании параметра -ReplaceHomeWithDefault домашняя страница сайта будет преобразована в готовую современную домашнюю страницу "по умолчанию", аналогичную создаваемой для современного сайта группы.
TakeSourcePageName $false Страницы вики-сайтов или веб-частей Действие по умолчанию состоит в присвоении созданной современной странице имени, которое начинается с префикса Migrated_, с сохранением для исходной страницы существующего имени. Если задан параметр -TakeSourcePageName, созданной странице присваивается имя исходной страницы, а исходная страница переименовывается с помощью префикса Previous_. Задайте этот параметр, если вы уверены, что хотите продолжать работу с современной страницей, так как это приведет к тому, что все ссылки, указывающие на исходную страницу, станут указывать на загружаемую современную страницу.
ClearCache $false Все типы страниц Для оптимизации производительности определенные данные (например, список доступных современных веб-частей, вычисляемый список полей для копирования метаданных) кэшируются после первого выполнения. Этот кэш остается допустимым в течение всего сеанса PowerShell, если не используется параметр -ClearCache. Перезапуск сеанса PowerShell также удаляет кэш.
SkipItemLevelPermissionCopyToClientSidePage $false Все типы страниц По умолчанию разрешения на уровне элемента копируются на современную страницу. Чтобы избежать этого, используйте -SkipItemLevelPermissionCopyToClientSidePage.
CopyPageMetadata $false Страницы вики-сайтов, веб-частей или блога По умолчанию метаданные страницы не копируются (поэтому добавляются дополнительные столбцы в библиотеку страниц сайта). Если указан параметр -CopyPageMetadata, значения настраиваемых полей метаданных страницы, предназначенной для преобразования, копируются на созданную страницу. В выпуске за октябрь 2019 г. копия метаданных страницы также поддерживается при преобразованиях между сайтами.
TargetWebUrl (**) Преобразование между сайтами Если нужно создать преобразованные современные страницы в другом семействе веб-сайтов, укажите URL-адрес другого семейства веб-сайтов. Общие сведения о том, какие веб-части преобразуются при выполнении преобразования между семействами веб-сайтов, см. в статье со списком преобразования веб-частей.
TargetConnection (**) Преобразование между сайтами Обеспечивает более гибкое определение целевого элемента с помощью объекта подключения. Это позволяет, к примеру, перейти из локального клиента в сетевой.
UseCommunityScriptEditor $false Все типы страниц Используйте параметр -UseCommunityScriptEditor, если вы установили редактор скриптов сообщества и хотите использовать его во время преобразования. Дополнительные сведения см. в статье со списком преобразования веб-частей.
SummaryLinksToHtml $false Все типы страниц Используйте параметр -SummaryLinksToHtml, если нужно преобразовать веб-часть SummaryLinks в HTML-код, размещенный в веб-части "Текст", вместо преобразования по умолчанию с помощью веб-части QuickLinks. Дополнительные сведения см. в статье со списком преобразования веб-частей.
LogType Нет Все типы страниц Используйте параметр -LogType при включенном ведении журнала: File выполняет запись журнала на диск, SharePoint создает страницу журнала в библиотеке SitePages SharePoint, Console выводит данные на консоль.
LogFolder Все типы страниц Если параметру LogType присвоено значение File, можно использовать -LogFolder, чтобы указать папку, где будет создан журнал.
LogVerbose $false Все типы страниц Используйте параметр -LogVerbose для создания подробного журнала.
LogSkipFlush $false Все типы страниц По умолчанию каждый вызов командлета создает уникальный файл журнала, и с помощью параметра -LogSkipFlush можно собирать записи журнала. Обратите внимание, что потребуется завершить вызов без параметра LogSkipFlush, чтобы сохранить собранные записи файла журнала.
DontPublish $false Все типы страниц Используйте параметр -DontPublish, чтобы не публиковать созданную современную страницу.
KeepPageCreationModificationInformation $false Все типы страниц Если нужно принять свойства "Автор", "Редактор", "Создано", "Изменено", используйте параметр -KeepPageCreationModificationInformation. Этот параметр поддерживается, только если исходная страница находится в том же клиенте SPO, что и конечное расположение современной страницы.
PostAsNews $false Все типы страниц Если нужно опубликовать созданную современную страницу в качестве новости на сайте, используйте параметр -PostAsNews. Это также означает, что страница будет опубликована, даже если вы настроили пропуск публикации.
SetAuthorInPageHeader $false Страницы вики-сайтов, веб-частей или блога Используйте параметр -SetAuthorInPageHeader, если вы хотите заполнить данные автора в заголовке созданной страницы. Автор будет задан как автор исходной страницы (сопоставленный пользователем).
DisablePageComments $false Все типы страниц Используйте параметр -DisablePageComments, если нужно отключить возможность комментирования на созданной странице
PublishingPage $false Страницы публикации Задайте параметр -PublishingPage, если выполняется преобразование страницы публикации. Для страниц вики-сайтов, веб-частей и страниц классических блогов этот параметр должен быть опущен или ему должно быть присвоено значение false.
PageLayoutMapping Страницы публикации С помощью параметра -PageLayoutMapping можно указать путь к файлу сопоставления макетов страниц, который используется для преобразования страницы публикации, если для страницы публикации применяется нестандартный макет
TargetPageName Страницы вики-сайтов, веб-частей или блога Используйте параметр -TargetPageName, чтобы переопределить имя по умолчанию для современной страницы. Это необходимо, например, чтобы предотвратить перезапись существующей страницы home.aspx, если выполняется межсайтовое преобразование классической домашней страницы сайта группы в современный информационный сайт.
PublishingTargetPageName Страницы публикации Используйте параметр -PublishingTargetPageName, чтобы переопределить имя для современной страницы
TargetPageFolder Все типы страниц Используйте параметр -TargetPageFolder, чтобы указать целевую папку для современной страницы. Обратите внимание, что при автоматическом создании папки (например, при преобразовании из дополнительной библиотеки вики-страниц) папка, определенная этим параметром, будет объединена с автоматически созданной папкой (если не указать -TargetPageFolderOverridesDefaultFolder). Эту папку можно задать следующим образом: MyFolder или MyFolder/SubFolder, если необходимо создать вложенную структуру папки. Указание <root> в качестве значения позволяет выбрать корневую папку конечной библиотеки SitePages
TargetPageFolderOverridesDefaultFolder $false Все типы страниц Параметр -TargetPageFolderOverridesDefaultFolder позволяет использовать для преобразование страниц папку, указанную в -TargetPageFolder, независимо от того, существует ли автоматически созданная папка
UrlMappingFile Преобразование между сайтами Файл с определениями пользовательских сопоставлений URL-адресов позволяет не только сопоставлять URL-адреса по умолчанию. Дополнительные сведения см. в статье Сопоставление URL-адресов.
SkipUrlRewriting $false Преобразование между сайтами Во время преобразования страниц публикации URL-адреса перезаписываются в допустимый формат для целевого семейства веб-сайтов, но с помощью параметра -SkipUrlRewriting можно отключить перезапись URL-адресов. Дополнительные сведения см. в статье Сопоставление URL-адресов.
SkipDefaultUrlRewriting Преобразование между сайтами Если используется пользовательское сопоставление URL-адресов и необходимо отключить стандартную логику переопределения URL-адресов, установите параметр -SkipDefaultUrlRewriting.
AddTableListImageAsImageWebPart $true Все типы страниц Изображения, находящиеся внутри таблицы или списка, также создавались как отдельные веб-части изображений под этой таблицей или списком. Чтобы прекратить создание этих отдельных веб-частей изображений, используйте параметр -AddTableListImageAsImageWebPart.
BlogPage $false Страницы блога Задайте параметр -BlogPage, если выполняется преобразование классической страницы блога. Для страниц вики-сайтов, веб-частей и страниц публикации этот параметр должен быть опущен или ему должно быть присвоено значение false.
UserMappingFile Все типы страниц Файл со сведениями о сопоставлении пользователей. Дополнительные сведения см. в статье Сопоставление пользователей.
LDAPConnectionString Все типы страниц Строка подключения LDAP для запроса к Active Directory. Дополнительные сведения см. в статье Сопоставление пользователей.
SkipUserMapping $false Все типы страниц Пропустить сопоставление пользователей. Для преобразований SPO сопоставление пользователей отключено, если вами не указан файл сопоставления. Для локальной версии SharePoint сопоставление всегда включено, если вами не установлен этот флажок. Дополнительные сведения см. в статье Сопоставление пользователей.
TermMappingFile Преобразование между сайтами Файл с определениями пользовательских сопоставлений терминов позволяет не только сопоставлять термины по умолчанию. Дополнительные сведения см. в статье Сопоставление терминов.
SkipTermStoreMapping $false Преобразование между сайтами Во время преобразования страниц термины сопоставляются в допустимом формате для целевого семейства веб-сайтов, но с помощью параметра -SkipTermStoreMapping можно отключить сопоставление терминов. Дополнительные сведения см. в статье Сопоставление терминов.

(*) Обязательный параметр командной строки / (**) Обязательный, если задан параметр -PublishingPage или -BlogPage (-TargetWebUrl или -TargetConnection)

Вопросы и ответы

Как преобразовать страницы публикации

В примере выше показано преобразование страницы на месте. Для преобразования страниц публикации потребуется немного другой синтаксис. В примере ниже показано, как модернизировать страницу mypage.aspx и создать ее современную версию на информационном сайте. Во время этого преобразования страницы используется либо встроенное сопоставление макетов страниц, если для страницы применяется стандартный макет, либо сопоставление для пользовательских макетов страниц создается во время выполнения:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite

Если используются пользовательские макеты страниц, настоятельно рекомендуется отрегулировать используемый файл сопоставления макетов страниц перед его применением. Для этого выполните указанные ниже действия.

Создайте пользовательский файл сопоставления макетов страниц

С помощью PnP PowerShell проанализируйте существующие макеты страниц и создайте файл сопоставления:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

Export-PnPPageMapping -CustomPageLayoutMapping -Folder c:\temp

Примечание.

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

Если вам нужно создать файлы сопоставления для стандартных макетов страниц, укажите параметр AnalyzeOOBPageLayouts.

Настройка созданного файла сопоставления

Откройте созданный файл сопоставления и просмотрите каждое сопоставление:

  • Правильно задайте значения строк и столбцов для веб-частей, зон веб-частей и фиксированных веб-частей, чтобы содержимое отображалось в правильном месте на современной странице. Можно использовать любое количество строк, каждая из которых представляет раздел на современной странице. Для столбцов могут использоваться только значения 1, 2 или 3, преобразуемые в возможные варианты столбцов на современной странице
  • Определите поля, которые нужно преобразовать как метаданные
  • Просмотрите созданные сопоставления полей с веб-частями
  • Просмотрите созданные сопоставления полей с заголовками

Использование пользовательского файла сопоставления

Очищенный пользовательский файл сопоставления удобно использовать с помощью параметра PageLayoutMapping:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -PageLayoutMapping c:\temp\mypagelayouts.xml

Примеры скриптов для преобразования (локальных) страниц публикации в современные страницы в SharePoint Online

Чтобы приступить к работе, ознакомьтесь со скриптами на сайте https://github.com/SharePoint/sp-dev-modernization/tree/dev/Scripts/PageTransformation.

Чтение страницы публикации в локальной среде SharePoint и создание современной страницы в SharePoint Online

Если вы хотите сохранить классические локальные порталы публикаций, сначала переместите весь портал из локальной среды в классический портал в SharePoint Online, а затем модернизируйте его. Тем не менее, часто бывает удобнее просмотреть классические страницы публикации на локальном портале SharePoint и создавать современную версию в SharePoint Online. Для этого необходимо использовать PnP PowerShell для SharePoint Online, чтобы подключиться к локальному порталу, как показано в приведенном ниже скрипте.

# Setup connection the target site - must be SPO and must be a modern site
$target = Connect-PnPOnline https://contoso.sharepoint.com/sites/moderncommunicationsite -ReturnConnection

# Connect to your on-premises portal
$source = Connect-PnPOnline https://portal2013.pnp.com/sites/classicportal -TransformationOnPrem -CurrentCredentials -ReturnConnection

# Convert a classic page living in the on-premises portal to a modern page in SharePoint Online. Dependent images and videos are copied as well from on-premises to online during this process.
ConvertTo-PnPPage -Identity "page1.aspx" -PublishingPage -TargetConnection $target -LogVerbose -LogType File -LogFolder c:\temp -Connection $source

Примечание.

  • Эта функция поддерживает SharePoint 2013, 2016 и 2019 в качестве исходной среды. Целевой средой всегда является SharePoint Online. Преобразование из SharePoint 2010 возможно, но для этого необходима устаревшая версия PnP PowerShell
  • Компьютер, на котором выполняется сценарий PowerShell, должен быть в состоянии подключиться как к локальному серверу SharePoint, так и к среде SharePoint Online
  • Этот подход также можно использовать для преобразования страниц в клиентах (если это имеет смысл)

Использование функций ведения журнала

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

# Convert a series of pages, logs are not yet written
ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -LogSkipFlush -LogType SharePoint -LogVerbose
ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -LogSkipFlush -LogType SharePoint -LogVerbose

# persist the log data from all previous page transformations to the defined log
Save-PnPPageConversionLog

Преобразование страниц, находящихся в корне сайта (за пределами библиотеки)

В некоторых старых сайтах страницы веб-частей могут храниться за пределами библиотеки. Если вам нужно модернизировать страницу, следует указать, что она хранится в корне сайта, с помощью параметра -Folder "<root>", как показано ниже.

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/sitetomodernize -Interactive

ConvertTo-PnPPage -Identity pageinroot.aspx -Overwrite -Folder "<root>"

Современные страницы сайта не поддерживаются на сайте, на котором я хочу преобразовать страницы

По умолчанию современные страницы включены на большинстве сайтов, но эта функция может быть отключена. Вы можете узнать, на каких сайтах отключены современные страницы, используя сканер модернизации SharePoint. Чтобы исправить это, используйте приведенный ниже скрипт PnP PowerShell.

Connect-PnPOnline -Url "<your web url>" -Interactive

# Enable modern page feature
Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web

См. также