使用 .NET 转换为新式网站页面

重要

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

页面转换引擎使用 .NET 生成，并作为 nuget 包分发。 添加 nuget 包后，将看到 2 个其他文件被添加到解决方案中：

注意

PnP 框架 nuget 包包含 .NET Standard 2.0 版本和 .NET 5.0 版本，使你能够在任何 .NET 项目中嵌入页面转换。

webpartmapping.xml 和 webpartmapping_latestfrompackage.xml 表示转换模型，它描述此转换将如何发生。 通常会根据需要调整 webpartmapping.xml 文件，例如将其他映射添加到你自己的 Web 部件中。 如果稍后安装 nuget 包的更新版本，则默认不会覆盖 webpartmapping.xml，但会覆盖 webpartmapping_latestfrompackage.xml。 可以使用后一个文件将最新的现成映射与你的映射进行比较，并接受所需的更改。

准备好映射文件后，现在可以使用下面的代码片段（来自 GitHub 上的 Modernization.PageTransformation 示例）来转换给定网站中的所有页面：

string siteUrl = "https://contoso.sharepoint.com/sites/mytestsite";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    var pageTransformator = new PageTransformator(cc);
    var pages = cc.Web.GetPages();
    foreach (var page in pages)
    {
        PageTransformationInformation pti = new PageTransformationInformation(page)
        {
            // If target page exists, then overwrite it
            Overwrite = true,
            // Migrated page gets the name of the original page
            TargetPageTakesSourcePageName = true,
        };

        try
        {
            Console.WriteLine($"Transforming page {page.FieldValues["FileLeafRef"]}");
            pageTransformator.Transform(pti);
        }
        catch(ArgumentException ex)
        {
            Console.WriteLine($"Page {page.FieldValues["FileLeafRef"]} could not be transformed: {ex.Message}");
        }
    }
}

常见问题

我想设置映射属性

映射属性设置为驱动映射行为 (例如配置社区脚本编辑器的使用) 。 可以配置映射属性，如以下示例代码所示：

PageTransformationInformation pti = new PageTransformationInformation(page)
{
    // If target page exists, then overwrite it
    Overwrite = true,
};

pti.MappingProperties["UseCommunityScriptEditor"] = "true";

pageTransformator.Transform(pti);

请参阅 Web 部件转换列表 一文，详细了解可能的映射属性。

我想将页面转换为另一个网站集

默认转换行为执行就地转换，这意味着新式页面是在经典页面所在的同一位置创建的。 但是，还可以通过为目标网站集提供客户端上下文对象，在另一个网站集中创建新式版本的页面。

string siteUrl = "https://contoso.sharepoint.com/sites/mytestsite";
string targetSiteUrl = "https://contoso.sharepoint.com/sites/mytargetsite";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    using (var ccTarget = cc.Clone(targetSiteUrl))
    {  
      var pageTransformator = new PageTransformator(cc, ccTarget);
      var pages = cc.Web.GetPages();
      foreach (var page in pages)
      {
          PageTransformationInformation pti = new PageTransformationInformation(page)
          {
              // If target page exists, then overwrite it
              Overwrite = true,
          };

          try
          {
              Console.WriteLine($"Transforming page {page.FieldValues["FileLeafRef"]}");
              pageTransformator.Transform(pti);
          }
          catch(ArgumentException ex)
          {
              Console.WriteLine($"Page {page.FieldValues["FileLeafRef"]} could not be transformed: {ex.Message}");
          }
      }
    }
}

注意

并非所有 Web 部件都适合跨网站传输，请查看 Web 部件转换列表中的跨网站支持列了解详细信息。

我想转换发布页面

发布页面转换始终是跨网站转换，因为不支持将新式页面与发布页面混合使用。 下面的示例演示如何将网站中 https://contoso.sharepoint.com/sites/mycommunicationsite 以“a”开头的所有发布页面转换为新式页面。 此示例还演示如何提供自定义页面布局映射文件。

string siteUrl = "https://contoso.sharepoint.com/sites/mytestportal";
string targetSiteUrl = "https://contoso.sharepoint.com/sites/mycommunicationsite";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    using (var ccTarget = cc.Clone(targetSiteUrl))
    {  
      var pageTransformator = new PublishingPageTransformator(cc, ccTarget, "C:\\temp\\custompagelayoutmapping.xml");
      var pages = cc.Web.GetPagesFromList("Pages", "a");
      foreach (var page in pages)
      {
          PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
          {
              // If target page exists, then overwrite it
              Overwrite = true,
          };

          try
          {
              Console.WriteLine($"Transforming publishing page {page.FieldValues["FileLeafRef"]}");
              pageTransformator.Transform(pti);
          }
          catch(ArgumentException ex)
          {
              Console.WriteLine($"Page {page.FieldValues["FileLeafRef"]} could not be transformed: {ex.Message}");
          }
      }
    }
}

注意

并非所有 Web 部件都适合跨网站传输，请查看 Web 部件转换列表中的跨网站支持列了解详细信息。

阅读本地 SharePoint 中的发布页面，并在 SharePoint Online 中创建新式页面

如果想要转变你的经典本地发布门户，应首先在 SharePoint Online 中将完整的本地门户移至经典门户，然后再执行现代化操作。 但是，通常来说，直接读取 SharePoint 本地门户中的经典发布页面并在 SharePoint Online 中创建现代版本要更加容易。

string siteUrl = "https://sp.contoso.com/sites/myonpremisesportal";
string targetSiteUrl = "https://contoso.sharepoint.com/sites/mycommunicationsite";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");

// Setup on-premises client context
using (var cc = new ClientContext(siteUrl))
{
    cc.Credentials = CredentialCache.DefaultCredentials;

    // Setup SharePoint Online context
    using (var ccTarget = am.GetSharePointOnlineAuthenticatedContextTenant(targetSiteUrl))
    {  
      var pageTransformator = new PublishingPageTransformator(cc, ccTarget, "C:\\temp\\custompagelayoutmapping.xml");
      
      // Register the log observers
      pageTransformator.RegisterObserver(new MarkdownObserver(folder: "c:\\temp", includeVerbose:true));
      pageTransformator.RegisterObserver(new MarkdownToSharePointObserver(ccTarget, includeVerbose: true));
      
      var pages = cc.Web.GetPagesFromList("Pages", "a");
      foreach (var page in pages)
      {
          PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
          {
              // If target page exists, then overwrite it
              Overwrite = true,
          };

          try
          {
              Console.WriteLine($"Transforming publishing page {page.FieldValues["FileLeafRef"]}");
              pageTransformator.Transform(pti);
          }
          catch(ArgumentException ex)
          {
              Console.WriteLine($"Page {page.FieldValues["FileLeafRef"]} could not be transformed: {ex.Message}");
          }
      }

      // Flush the log data
      pageTransformator.FlushObservers();
    }
}

注意

• 此功能支持 SharePoint 2013、2016 和 2019 作为源。 目标始终是 SharePoint Online
• 在能够作为 SharePoint Online 环境连接到本地 SharePoint 服务器的计算机上运行代码非常重要
• 此方法也可用于跨租户页面转换（任何时候都可以）

我想使用日志记录功能

默认情况下， (Console、Markdown 和 MarkdownToSharePoint) 有三个可能的日志观察程序。 后两个创建基于 MD 的报表，并将其作为新式页面放在磁盘上或 SharePoint 中，而第一个报表只是输出控制台消息。 下面的示例演示如何从 .NET 使用记录器：

string siteUrl = "https://contoso.sharepoint.com/sites/mytestportal";
string targetSiteUrl = "https://contoso.sharepoint.com/sites/mycommunicationsite";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    using (var ccTarget = cc.Clone(targetSiteUrl))
    {  
      var pageTransformator = new PublishingPageTransformator(cc, ccTarget, "C:\\temp\\custompagelayoutmapping.xml");
      
      // Register the log observers
      pageTransformator.RegisterObserver(new MarkdownObserver(folder: "c:\\temp", includeVerbose:true));
      pageTransformator.RegisterObserver(new MarkdownToSharePointObserver(ccTarget, includeVerbose: true));
      
      var pages = cc.Web.GetPagesFromList("Pages", "a");
      foreach (var page in pages)
      {
          PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
          {
              // If target page exists, then overwrite it
              Overwrite = true,
          };

          try
          {
              Console.WriteLine($"Transforming publishing page {page.FieldValues["FileLeafRef"]}");
              pageTransformator.Transform(pti);
          }
          catch(ArgumentException ex)
          {
              Console.WriteLine($"Page {page.FieldValues["FileLeafRef"]} could not be transformed: {ex.Message}");
          }
      }

      // Flush the log data
      pageTransformator.FlushObservers();
    }
}

无法在我要转换的页面所属的网站上使用新式网站页面

默认情况下，大多数网站都启用了新式网站页面功能，但之后可能会关闭。 如果是这种情况，则 SharePoint 现代化扫描程序会告诉你哪些网站已关闭新式页面功能。 若要修正此问题，请使用下面的 PnP PowerShell 脚本示例：

$minimumVersion = New-Object System.Version("1.3.0")
if (-not (Get-InstalledModule -Name PnP.PowerShell -MinimumVersion $minimumVersion -ErrorAction Ignore))
{
    Install-Module PnP.PowerShell -MinimumVersion $minimumVersion -Scope CurrentUser
}
Import-Module PnP.PowerShell -DisableNameChecking -MinimumVersion $minimumVersion

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

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

注意

PnP PowerShell 是一种开放源代码解决方案，其中包含为其提供支持的活动社区。 没有用于 Microsoft 开放源代码工具支持的 SLA。

另请参阅

• 新式化经典 SharePoint 网站
• GitHub 上的 Modernization.PageTransformation 示例
• 5 月 3 日 SIG call 的 YouTube 录制包含页面转换演示
• 了解和配置页面转换模型
• 经典和新式 Web 部件体验