Преобразование современных страниц сайта с помощью .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}");
          }
      }
    }
}

Примечание.

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

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

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

См. также

• Модернизация классических сайтов SharePoint
• Пример Modernization.PageTransformation на сайте GitHub
• Запись видеоконференции специальной группы за 3 мая, содержащая пример преобразования страницы, на YouTube
• Общие сведения о модели преобразования страниц и ее настройке
• Возможности классических и современных веб-частей