Compartir a través de

Transformación a páginas de sitio modernas mediante .NET

  • Artículo

Importante

La modernización de SharePoint PnP es parte de PnP Framework y evoluciona continuamente; eche un vistazo a las notas de versión para mantenerse al día con los últimos cambios. Si tiene algún problema, preséntelo en la lista de problemas de GitHub para PnP Framework.

El motor de transformación de página se compila mediante .NET y se distribuye como un paquete nuget . Cuando haya agregado el paquete de nuget, verá que 2 archivos adicionales se agregan a la solución:

archivos sobre la solución de transformación de página

Nota:

El paquete nuget de PnP Framework contiene una versión de .NET Standard 2.0 y una versión de .NET 5.0, lo que le permite insertar la transformación de página en cualquier proyecto de .NET.

La webpartmapping.xml y webpartmapping_latestfrompackage.xml representan el modelo de transformación que describe cómo se producirá la transformación. Normalmente retocará el archivo webpartmapping.xml según sus necesidades, por ejemplo, agregando asignaciones adicionales a sus propios elementos web. Si instala una versión actualizada del paquete nuget más adelante, su webpartmapping.xml no se sobrescribirá de forma predeterminada, pero webpartmapping_latestfrompackage.xml se sobrescribirá. Puede usar este último archivo para comparar la asignación de fábrica más reciente con su asignación y encargarse de los cambios que necesite.

Con el archivo de asignación en su lugar, ahora puede usar el siguiente fragmento (procedente del ejemplo Modernization.PageTransformation en GitHub) para transformar todas las páginas de un sitio determinado:

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

Preguntas más frecuentes

Quiero establecer las propiedades de asignación

Las propiedades de asignación se establecen para controlar el comportamiento de asignación (por ejemplo, configurar el uso del editor de scripts de la comunidad). Puede configurar propiedades de asignación como se muestra en el código de ejemplo siguiente:

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

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

pageTransformator.Transform(pti);

Consulte el artículo de la lista de transformación de elementos web para obtener más información sobre las posibles propiedades de asignación.

Quiero transformar páginas en otra colección de sitios

El comportamiento de transformación predeterminado es realizar una transformación local, lo que significa que la página moderna se crea en la misma ubicación que la página clásica. Sin embargo, también puede crear la versión moderna de la página en otra colección de sitios proporcionando un objeto de contexto de cliente para la colección de sitios 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}");
          }
      }
    }
}

Nota:

No todos los elementos web se prestan bien para una transferencia entre sitios, consulte la columna Compatibilidad entre sitios en la lista de transformación de elementos web para obtener más información.

Quiero transformar páginas de publicación

La transformación de página de publicación siempre será una transformación entre sitios, ya que no se admite la combinación de páginas modernas con páginas de publicación. En el ejemplo siguiente se muestra cómo todas las páginas de publicación que comienzan por una "a" se transforman en páginas modernas del https://contoso.sharepoint.com/sites/mycommunicationsite sitio. En este ejemplo también se muestra cómo proporcionar un archivo de asignación de diseño 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}");
          }
      }
    }
}

Nota:

No todos los elementos web se prestan bien para una transferencia entre sitios, consulte la columna Compatibilidad entre sitios en la lista de transformación de elementos web para obtener más información.

Lea la página de publicación en SharePoint local y cree una página moderna en SharePoint Online

Cuando quiera traer los portales de publicación clásicos locales, primero puede mover el portal completo desde el nivel local hacia un portal clásico en SharePoint Online y luego realizar el trabajo de modernización. Sin embargo, a menudo es más fácil leer directamente la página de publicación clásica desde su portal local de SharePoint y crear la versión moderna en 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();
    }
}

Nota:

  • Esta característica admite SharePoint 2013, 2016 y 2019 como origen. El destino siempre es SharePoint Online
  • Es importante ejecutar el código en una máquina que pueda conectarse al servidor de SharePoint local como al entorno de SharePoint Online.
  • Este enfoque también se puede usar para transformar páginas en espacios empresariales (siempre que tenga sentido).

Quiero usar las características de registro

De forma predeterminada, hay tres posibles observadores de registro (Console, Markdown y MarkdownToSharePoint). Los dos últimos crean un informe basado en MD y los colocan en el disco o en SharePoint como una página moderna, mientras que el primero simplemente genera mensajes de consola. En el ejemplo siguiente se muestra cómo puede usar los registradores de .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();
    }
}

Las páginas de sitio modernas no funcionan en el sitio en el que quiero transformar páginas

De forma predeterminada, la capacidad de la página de sitio moderno está habilitada en la mayoría de los sitios, pero es posible que se haya desactivado posteriormente. Si es así, el escáner de modernización de SharePoint le indicará qué sitios desactivaron la característica de página moderna. Para solucionar esto, use la siguiente secuencia de comandos de 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

Nota:

PnP PowerShell es una solución de código abierto con una comunidad activa que ofrece su soporte. No hay ningún contrato de nivel de servicio para el soporte de la herramienta de código abierto de Microsoft.

Vea también