Share via

Transformando em páginas de sites modernas usando o .NET

  • Artigo

Importante

A modernização do SharePoint PnP faz parte da Estrutura PnP e está em constante evolução, verifique as notas de versão para se manter atualizado sobre as alterações mais recentes. Se você tiver problemas, registre-o na lista de problemas do GitHub sobre Estrutura PnP.

O mecanismo de transformação de página é criado usando o .NET e é distribuído como um pacote nuget . Depois de adicionar o pacote NuGet, você verá que outros dois arquivos serão adicionados à sua solução:

arquivos da solução da transformação de página

Observação

O pacote nuget do PnP Framework contém uma versão do .NET Standard 2.0 e uma versão do .NET 5.0, permitindo que você insira transformação de página em qualquer projeto do .NET.

A webpartmapping.xml e a webpartmapping_latestfrompackage.xml representam o modelo de transformação que descreve como a transformação acontecerá. Normalmente, você irá ajustar o arquivo webpartmapping.xml de acordo com suas necessidades, por exemplo, incluindo outros mapeamentos a suas próprias web parts. Se posteriormente você instalar ou atualizar a versão do pacote NuGet, a webpartmapping.xml não será substituída por padrão, mas a webpartmapping_latestfrompackage.xml será. Você pode usar este último arquivo para comparar o mapeamento mais recente com seu mapeamento e controlar as alterações que precisar.

Depois de estabelecer o arquivo de mapeamento, será possível usar o trecho a seguir (retirado do exemplo Modernization.PageTransformation no GitHub) para transformar todas as páginas em um site:

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

Perguntas frequentes

Quero definir propriedades de mapeamento

As propriedades de mapeamento são definidas como comportamento de mapeamento de unidade (por exemplo, configurar o uso do editor de scripts da comunidade). Você pode configurar propriedades de mapeamento, como mostrado no código de exemplo abaixo:

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

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

pageTransformator.Transform(pti);

Consulte o artigo da lista de transformação da Web Part para saber mais sobre as possíveis propriedades de mapeamento.

Quero transformar páginas em outra coleção de sites

O comportamento de transformação padrão está fazendo uma transformação in loco, o que significa que a página moderna é criada no mesmo local que a página clássica. No entanto, você também pode criar a versão moderna da página em outra coleção de sites fornecendo um objeto de contexto do cliente para a coleção de sites de destino.

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

Observação

Nem todas as web parts se prestam bem para uma transferência entre sites, verifique a coluna de suporte de site cruzado na lista de transformação da Web Part para saber mais.

Quero transformar páginas de publicação

A transformação de página de publicação sempre será uma transformação entre sites, pois a combinação de páginas modernas com páginas de publicação não tem suporte. O exemplo abaixo mostra como todas as páginas de publicação começando com um "a" são transformadas em páginas modernas no https://contoso.sharepoint.com/sites/mycommunicationsite site. Este exemplo também mostra como fornecer um arquivo de mapeamento de layout de página personalizado.

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

Observação

Nem todas as web parts se prestam bem para uma transferência entre sites, verifique a coluna de suporte de site cruzado na lista de transformação da Web Part para saber mais.

Leia a página de publicação no SharePoint local e crie uma página moderna no SharePoint Online

Quando você quiser trazer seus portais de publicação no local clássicos, primeiro poderá mover o portal completo do local para um portal clássico no SharePoint Online, e depois fazer o trabalho de modernização. No entanto, geralmente é mais fácil ler diretamente a página de publicação clássica a partir do seu portal no local do SharePoint e criar a versão moderna no 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();
    }
}

Observação

  • Esse recurso dá suporte ao SharePoint 2013, 2016 e 2019 como origem. O destino é sempre o SharePoint Online
  • É importante executar seu código em um computador que seja capaz de se conectar ao servidor local do SharePoint como ao ambiente do SharePoint Online
  • Essa abordagem também pode ser usada para a transformação de página em locatários (sempre que isso fizer sentido)

Quero usar os recursos de log

Por padrão, há três possíveis observadores de log (Console, Markdown e MarkdownToSharePoint). Os dois últimos criam um relatório baseado em MD e os colocam em disco ou no SharePoint como uma página moderna, enquanto o primeiro simplesmente gera mensagens de console. O exemplo abaixo mostra como você pode usar os madeireiros do .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();
    }
}

As páginas de site modorno não funcionam no site em que quero transformar páginas

Por padrão, o recurso de página de site moderno está habilitado na maioria dos sites, mas talvez ele tenha sido desabilitado posteriormente. Se esse for o caso, o verificador de modernização do SharePoint informará quais sites desativaram o recurso de página moderna. Para corrigir isso, use o exemplo abaixo de script do PowerShell PnP:

$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

Observação

O PnP PowerShell é uma solução de software livre com uma comunidade ativa de suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.

Confira também