通过

使用 PowerShell 转换为新式网站页面

  • 项目

重要

SharePoint PnP 新式化框架是 PnP 框架的一部分，且在不断演进，请查看发行说明了解最新更改的最新信息。 如果遇到问题，请在 PnP 框架 GitHub 问题列表中提出问题。

另外还可以从 PowerShell 使用页面转换引擎。 这使得它可以集成到除页面转换之外还可以执行其他诸多操作（例如，安装解决方案，将网站连接到 Office 365 组，以及应用租户品牌）的网站现代化脚本中。 若要查看完整现代化脚本的优秀示例，可访问 Office 365 组连接文章。

注意

以下脚本显示如何转换页面。 它需要 PnP PowerShell 版本1.3.*（2021 年 2 月）或更高版本。 我们的 GitHub 脚本位置提供了其他示例脚本（例如，用于转换发布页面、用于从本地 SharePoint 转换）。

<# 

.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 cmdlet 的选项

ConvertTo-PnPPage cmdlet 是新式化给定页面的关键 cmdlet。 下表列出了可用于通过此 cmdlet 控制页面转换的命令行参数。

参数 默认值 支持 说明
Identity (*) 所有页面类型 Wiki、Web 部件和发布页面的页面名称（例如 pageA.aspx）或经典博客页面的博客标题。 如果是经典博客页面，将Identity使用标题以提供的第一个博客页面，或者你也可以指定该页面的ID（整数值）。
库 Wiki/Web 部件页面 存放页面的库。 如果你的 Wiki 或 Web 部件页位于默认 SitePages 库，请使用此 -Library 参数。
文件夹 Wiki/Web 部件/发布页面 如果想要打印的页面在文件夹中实时转换，则你可以指定该文件（如 -Folder "Folder1/SubFolder"）。
WebPartMappingFile 所有页面类型 页面转换由映射文件驱动。 cmdlet 已嵌入默认的映射文件，但您也可以指定自定义的 Web 部件映射文件 (webpartmapping.xml)，以满足你的页面转换需求（例如，转换成第三方自定义 Web 部件）。 可以通过利用 -WebPartMappingFile 参数指定文件路径来完成此操作。
覆盖 $false 所有页面类型 若添加 -Overwrite，页面转换框架将在必要时覆盖目标页面。 默认情况下，新页面名称带有前缀 Migrated_，这意味着若 Migrated_YourPage.aspx 已存在（通常来自之前的页面转换工作），则会将其覆盖。
ReplaceHomePageWithDefault $false Wiki/Web 部件页面 默认行为是将网站主页转换为类似任何其他常规页面的新式页面。 如果使用 -ReplaceHomeWithDefault，则会将网站主页转换为“默认”的全新新式主页，这样你将获得一个新创建的新式团队网站。
TakeSourcePageName $false Wiki/Web 部件页面 默认行为是为所创建的新式页面提供以 Migrated_ 前缀开头的名称，并允许原始页面保留其现有名称。 如果指定 -TakeSourcePageName，新创建的页面将具有原始页面的名称，而原始页面会使用 Previous_ 前缀重命名。 若确定以后要使用新式页面则设置此选项，因为此选项会确保指向原始页面的所有链接如今会加载新的新式页面。
ClearCache $false 所有页面类型 要优化性能，需在第一次执行之后缓存某些数据（例如可用新式 Web 部件的列表，计算得出的为其复制元数据的字段列表）。 此缓存将在完整 PowerShell 会话期间保持有效状态，除非你使用 -ClearCache switch。 重启 PowerShell 会话时还会清除缓存。
SkipItemLevelPermissionCopyToClientSidePage $false 所有页面类型 默认情况下，项目级权限将复制到现代页，使用 -SkipItemLevelPermissionCopyToClientSidePage 阻止此操作。
CopyPageMetadata $false Wiki/Web 部件/博客页面 默认行为是不复制页面元数据（因此，向网页库添加其他列）。 如果指定了 -CopyPageMetadata，则将要转换的页面的自定义元数据字段的值复制到新创建的页面。 自 2019 年 10 月版本起，页面元数据副本也可以在跨站转换中使用。
TargetWebUrl (**) 跨站转换 如果要在另一个网站集中创建已转换的新式页面，请指定该其他网站集的 URL。 请参阅 Web 部件转换列表一文，以了解要在跨网站集合转换中转换的 Web 部件。
TargetConnection （**） 跨站转换 允许通过连接对象更灵活地定义目标。 例如，这允许对从本地到在线的转换执行跨租户转换。
UseCommunityScriptEditor $false 所有页面类型 如果你已安装社区脚本编辑器并希望在转换期间使用它，请使用 -UseCommunityScriptEditor。 请参阅 Web 部件转换列表一文，以了解更多信息。
SummaryLinksToHtml $false 所有页面类型 如果你希望将 SummaryLinks Web 部件转换为文本 Web 部件中托管的 HTML 而不是使用 QuickLinks Web 部件的默认转换，请使用 -SummaryLinksToHtml。 请参阅 Web 部件转换列表一文，以了解更多信息。
LogType 无 所有页面类型 使用 -LogType 启用日志记录：File 会记录到磁盘，SharePoint 会在 SharePoint SitePages 库中创建日志页面，Console 会将数据输出到控制台。
LogFolder 所有页面类型 如果 LogType 设置为 File，可使用 -LogFolder 指定创建日志的文件夹。
LogVerbose $false 所有页面类型 使用 -LogVerbose 可生成详细日志。
LogSkipFlush $false 所有页面类型 默认情况下，每个 cmdlet 调用都生成一个唯一日志文件，使用 -LogSkipFlush 参数可积累日志条目。 请注意，必须以不使用 LogSkipFlush 的调用结束，才能暂留已汇编的日志文件条目。
DontPublish $false 所有页面类型 使用 -DontPublish 选项可不发布已创建的新式页面。
KeepPageCreationModificationInformation $false 所有页面类型 如果要接管“作者/编辑者/已创建/已修改”页面属性，请使用 -KeepPageCreationModificationInformation 参数。 仅当源页面与新式页面的目标位置位于同一 SPO 租户中时，此选项才适用。
PostAsNews $false 所有页面类型 如果要将创建的新式页面作为新闻发布在网站上，请使用 -PostAsNews 参数。 这也意味着将发布页面，即使已将其配置为跳过发布也是如此。
SetAuthorInPageHeader $false Wiki/Web 部件/博客页面 如果要在创建的页面的标题中填充作者，则使用 -SetAuthorInPageHeader 参数。 会将作者设置为（用户映射的）源页面作者。
DisablePageComments $false 所有页面类型 若要对已创建的页面禁用注释选项，请使用 -DisablePageComments
PublishingPage 类 $false 发布页面 若要转换发布页面，请设置 -PublishingPage 参数。 对于 Wiki、Web 部件和经典博客页面，此参数必须省略或设置为 false。
PageLayoutMapping 发布页面 通过 -PageLayoutMapping，可以指定在发布页面使用非现成页面布局时，将用于发布页面转换的页面布局映射文件的路径
TargetPageName Wiki/Web 部件/博客页面 使用 -TargetPageName 参数替代新式页面的默认名称。 例如，如果要将经典团队网站主页通过跨站转换的方式转换为新式通信网站，则需要使用此参数来防止覆盖现有 home.aspx 页面。
PublishingTargetPageName 发布页面 使用 -PublishingTargetPageName 参数替代新式页面的名称
TargetPageFolder 所有页面类型 使用 -TargetPageFolder 参数指定新式页面的目标文件夹。 请注意，如果自动创建了文件夹（例如从其他 Wiki 页面库进行转换时），此参数指定的文件夹将与自动生成的文件夹合并（除非指定 -TargetPageFolderOverridesDefaultFolder）。 可以指定如下所示的文件夹：MyFolder；要创建嵌套的文件夹结构时，可指定类似 MyFolder/SubFolder 的文件夹。 将 <root> 指定为一个值，使你能够以目标网站页面库的根为目标
TargetPageFolderOverridesDefaultFolder $false 所有页面类型 使用 -TargetPageFolderOverridesDefaultFolder 参数，可以强制页面转换以使用通过 -TargetPageFolder 指定的文件夹，而不考虑是否存在自动创建的文件夹
UrlMappingFile 跨站转换 具有自定义 URL 映射定义的文件允许你执行的不仅仅是默认的 URL 映射。 请参阅 URL 映射文章，了解详细信息。
SkipUrlRewriting $false 跨站转换 在发布页面转换期间，系统将重写 URL 以使其在目标网站集中有效，但使用 -SkipUrlRewriting，可以禁用 URL 重写。 请参阅 URL 映射文章，了解详细信息。
SkipDefaultUrlRewriting 跨站转换 如果你使用自定义 URL 映射，并且想要禁用默认 URL 重写逻辑，请设置 -SkipDefaultUrlRewriting 参数。
AddTableListImageAsImageWebPart $true 所有页面类型 表格/列表中的图像也在该表格/列表下创建为单独的图像 Web 部件。 使用 -AddTableListImageAsImageWebPart 参数可停止创建这些单独的图像 Web 部件。
BlogPage $false 博客页面 若要转换经典博客页面，请设置 -BlogPage 参数。 对于 Wiki、Web 部件和发布页面，此参数必须省略或设置为 false。
UserMappingFile 所有页面类型 包含用户映射信息的文件。 请参阅用户映射一文了解详细信息。
LDAPConnectionString 所有页面类型 用于查询 Active Directory 的 LDAP 连接字符串。 请参阅用户映射一文了解详细信息。
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 是一种开放源代码解决方案，其中包含为其提供支持的活动社区。 没有用于 Microsoft 开放源代码工具支持的 SLA。

如果想要为 OOB 页面布局生成映射文件，则请指定 AnalyzeOOBPageLayouts 开关。

优化生成的映射文件

打开“创建的映射文件”并查看每个映射：

  • 为 Web 部件、Web 部件区域和固定 Web 部件正确设置行和列值，以便内容显示在新式页面上的正确位置。 你可以拥有任意数量的行，每行将是新式页面上的一部分。 列值限制为 1、2 或 3，这转换为新式页面中可能的列选项
  • 定义需要转换为元数据的字段
  • 查看生成的字段到 Web 部件的映射
  • 查看生成的字段到列标题的映射

使用自定义映射文件

通过 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

转换位于网站根部（因此位于库外面）的页面

某些较旧的网站中可能含有位于库外面的 Web 部件页面。 如果想要对它们进行现代化，则需要通过 -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

另请参阅