Share via

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

  • Статья

Важно!

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

Подсистема преобразования страниц создается с помощью .NET и распространяется в виде пакета Nuget . Добавив пакет Nuget, вы увидите, что к решению добавлены еще 2 файла:

Файлы решения для преобразования страниц

Примечание.

Пакет nuget PnP Framework содержит версию .NET Standard 2.0 и .NET 5.0, что позволяет внедрять преобразование страницы в любой проект .NET.

Файлы webpartmapping.xml и webpartmapping_latestfrompackage.xml представляют модель преобразования, описывающую конфигурацию преобразования. Как правило, пользователи меняют файл webpartmapping.xml в соответствии со своими потребностями (например, добавляют сопоставления для собственных веб-частей). Если позже вы установите обновленную версию пакета Nuget, то файл webpartmapping.xml не будет заменен по умолчанию, в отличие от файла webpartmapping_latestfrompackage.xml. Последний файл позволит сравнить последнее готовое сопоставление с собственным и принять нужные изменения.

Подготовив файл сопоставления, вы можете использовать приведенный ниже фрагмент (взятый из примера Modernization.PageTransformation на сайте GitHub), чтобы преобразовать все страницы на определенном сайте.

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);

Дополнительные сведения о возможных свойствах сопоставления см. в статье список преобразований веб-частей .

Я хочу преобразовать страницы в другое семейство веб-сайтов

Поведение преобразования по умолчанию выполняет преобразование на месте, то есть современная страница создается в том же расположении, что и классическая страница. Однако можно также создать современную версию страницы в другом семействе веб-сайтов, предоставив объект контекста клиента для целевого семейства веб-сайтов.

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}");
          }
      }
    }
}

Примечание.

Не все веб-части хорошо подходят для переноса между сайтами. Дополнительные сведения см. в столбце Поддержканескольких сайтов в списке преобразований веб-частей .

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

Преобразование страниц публикации всегда будет преобразованием между сайтами, так как смешивание современных страниц со страницами публикации не поддерживается. Ниже показано, как все страницы публикации, начиная с "a", преобразуются в https://contoso.sharepoint.com/sites/mycommunicationsite современные страницы сайта. В этом примере также показано, как предоставить файл сопоставления пользовательского макета страницы.

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}");
          }
      }
    }
}

Примечание.

Не все веб-части хорошо подходят для переноса между сайтами. Дополнительные сведения см. в столбце Поддержканескольких сайтов в списке преобразований веб-частей .

Чтение страницы публикации в локальной среде 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, так и к среде SharePoint Online.
  • Этот подход также можно использовать для преобразования страниц в клиентах (если это имеет смысл)

Я хочу использовать функции ведения журнала

По умолчанию существует три возможных наблюдателя журнала (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 — это решение с открытым исходным кодом, поддержка которого предоставляется активным сообществом. Для инструментов с открытым исходным кодом не существует соглашения об уровне обслуживания в отношении поддержки корпорацией Майкрософт.

См. также