Compartir a través de

Transformación a páginas de sitio modernas con PowerShell

  • 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 también puede usarse en PowerShell. Esto permite que se puedan integrar en un script de modernización de sitio que, además de la transformación de página, también realiza otras acciones como instalar la solución, conectando el sitio a un grupo de Microsoft 365 y aplicando la personalización de marca del espacio empresarial. Puede encontrar un buen ejemplo de un script del proceso de modernización en el artículo de conexión de grupo de Microsoft 365.

Nota:

El siguiente script muestra cómo transformar páginas. Requiere la versión 1.3.* de PnP PowerShell* (febrero de 2021) o posterior. Tenemos otros scripts de muestra (por ejemplo, para transformar la página de publicación o para transformar a partir del SharePoint local) disponibles en nuestro repositorio de scripts de GitHub.

<# 

.Synopsis

    Converts all classic wiki and web part pages in a site. 
    You need to install PnP PowerShell: https://pnp.github.io/powershell/

    Sample includes:
        - Conversion of wiki and web part pages
        - Connecting to MFA or supplying credentials
        - Includes Logging to File, log flushing into single log file        

.Example

    Convert-WikiAndWebPartPages.ps1 -SourceUrl "https://contoso.sharepoint.com/sites/classicteamsite" -TakeSourcePageName:$true

.Notes
    
    Useful references:
        - https://aka.ms/sppnp-pagetransformation
        - https://aka.ms/sppnp-powershell
#>

[CmdletBinding()]
param (

    [Parameter(Mandatory = $true, HelpMessage = "Url of the site containing the pages to modernize")]
    [string]$SourceUrl,

    [Parameter(Mandatory = $false, HelpMessage = "Modern page takes source page name")]
    [bool]$TakeSourcePageName = $false,    

    [Parameter(Mandatory = $false, HelpMessage = "Supply credentials for multiple runs/sites")]
    [PSCredential]$Credentials,

    [Parameter(Mandatory = $false, HelpMessage = "Specify log file location, defaults to the same folder as the script is in")]
    [string]$LogOutputFolder = $(Get-Location)
)
begin
{
    Write-Host "Connecting to " $SourceUrl
    
    if($Credentials)
    {
        Connect-PnPOnline -Url $SourceUrl -Credentials $Credentials
        Start-Sleep -s 3
    }
    else
    {
        Connect-PnPOnline -Url $sourceUrl -Interactive
        Start-Sleep -s 3
    }
}
process 
{    
    Write-Host "Ensure the modern page feature is enabled..." -ForegroundColor Green
    Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web -Force

    Write-Host "Modernizing wiki and web part pages..." -ForegroundColor Green
    # Get all the pages in the site pages library. 
    # Use paging (-PageSize parameter) to ensure the query works when there are more than 5000 items in the list
    $pages = Get-PnPListItem -List sitepages -PageSize 500

    Write-Host "Pages are fetched, let's start the modernization..." -ForegroundColor Green
    Foreach($page in $pages)
    { 
        $pageName = $page.FieldValues["FileLeafRef"]
        
        if ($page.FieldValues["ClientSideApplicationId"] -eq "b6917cb1-93a0-4b97-a84d-7cf49975d4ec" ) 
        { 
            Write-Host "Page " $page.FieldValues["FileLeafRef"] " is modern, no need to modernize it again" -ForegroundColor Yellow
        } 
        else 
        {
            Write-Host "Processing page $($pageName)" -ForegroundColor Cyan
            
            # -TakeSourcePageName:
            # The old pages will be renamed to Previous_<pagename>.aspx. If you want to 
            # keep the old page names as is then set the TakeSourcePageName to $false. 
            # You then will see the new modern page be named Migrated_<pagename>.aspx

            # -Overwrite:
            # Overwrites the target page (needed if you run the modernization multiple times)
            
            # -LogVerbose:
            # Add this switch to enable verbose logging if you want more details logged

            # KeepPageCreationModificationInformation:
            # Give the newly created page the same page author/editor/created/modified information 
            # as the original page. Remove this switch if you don't like that

            # -CopyPageMetadata:
            # Copies metadata of the original page to the created modern page. Remove this
            # switch if you don't want to copy the page metadata

            ConvertTo-PnPPage -Identity $page.FieldValues["ID"] `
                                -Overwrite `
                                -TakeSourcePageName:$TakeSourcePageName `
                                -LogType File `
                                -LogFolder $LogOutputFolder `
                                -LogSkipFlush `
                                -KeepPageCreationModificationInformation `
                                -CopyPageMetadata
        }
    }

    # Write the logs to the folder
    Write-Host "Writing the conversion log file..." -ForegroundColor Green
    Save-PnPPageConversionLog

    Write-Host "Wiki and web part page modernization complete! :)" -ForegroundColor Green
}
end
{
    Disconnect-PnPOnline
}

Opciones para el cmdlet ConvertTo-PnPPage

El cmdlet ConvertTo-PnPPage es el cmdlet clave para modernizar una página determinada. La tabla siguiente enumera los parámetros de línea de comandos que puede usar para controlar la transformación de página a través de este cmdlet.

Parámetro Valor predeterminado Compatible con Descripción
Identidad (*) Todos los tipos de página El nombre de la página (por ejemplo, paginaA.aspx) para la wiki, el elemento web y las páginas de publicación o el título del blog para las páginas de blog clásicas. En el caso de las páginas de blog clásicas, se usará la primera página de blog en la que el título comienza con la Identity proporcionada. También puede especificar el id. (valor entero) de la página.
Biblioteca Páginas wiki o de elementos web La biblioteca que contiene la página. Use este parámetro -Library cuando la página de elementos web o wiki resida fuera de la biblioteca SitePages predeterminada.
Carpeta Wiki/elemento web/páginas de publicación Cuando la página que quiere transformar reside en una carpeta, puede especificar esa carpeta (por ejemplo, -Folder "Folder1/SubFolder").
WebPartMappingFile Todos los tipos de página La transformación de página se controla mediante un archivo de asignación. El cmdlet tiene un archivo de asignación predeterminado incrustado, pero también puede especificar un archivo de asignación de elementos web personalizado (webpartmapping.xml) para adaptarlo a sus necesidades de transformación de página (por ejemplo, transformar a elementos web personalizados de terceros). Para ello, especifique la ruta de acceso al archivo mediante el parámetro -WebPartMappingFile.
Overwrite $false Todos los tipos de página Cuando se añade -Overwrite, el marco de transformación de página sobrescribirá la página de destino si es necesario. De forma predeterminada el nuevo nombre de la página tiene un prefijo de Migrated_, lo que implica que si ya existe Migrated_YourPage.aspx (normalmente por un intento de transformación de página anterior) se sobrescribirá.
ReplaceHomePageWithDefault $false Páginas wiki o de elementos web El comportamiento predeterminado es transformar la página principal del sitio en una página moderna como cualquier otra página normal. Si utiliza -ReplaceHomeWithDefault, la página principal de un sitio se transformará en una página de inicio "predeterminada" moderna, como la que obtendría con un sitio de grupo moderno recién creado.
TakeSourcePageName $false Páginas wiki o de elementos web El comportamiento predeterminado es asignar a la página moderna creada un nombre que comienza con el prefijo Migrated_ y permitir que la página original conserve el nombre original. Cuando -TakeSourcePageName se especifica, la nueva página obtiene el nombre de la página original y a la página original se le asigna un nombre con el prefijo Previous_. Establezca esta opción si está seguro de que quiere seguir con la página moderna ya que le asegurará que todos los vínculos que apunten a la página original ahora den como resultado la carga de la nueva página.
ClearCache $false Todos los tipos de página Para optimizar el rendimiento, se almacenan en caché determinados datos (por ejemplo, la lista de elementos web modernos disponibles y la lista calculada de campos para los que copiar los metadatos) después de la primera ejecución. Esta caché será válida durante toda la sesión de PowerShell a menos que use el modificador -ClearCache. Al reiniciar la sesión de PowerShell también se borra la caché.
SkipItemLevelPermissionCopyToClientSidePage $false Todos los tipos de página De forma predeterminada, los permisos de nivel de elemento se copian en la página moderna, use el -SkipItemLevelPermissionCopyToClientSidePage para evitar esto.
CopyPageMetadata $false Wiki/elementoweb/páginas del blog El comportamiento predeterminado es no copiar los metadatos de la página (las columnas adicionales agregadas a la biblioteca de páginas del sitio). Cuando se especifica -CopyPageMetadata, los valores de los campos de metadatos personalizados de la página que se van a transformar se copian en la página nueva. En la página de la versión de octubre de 2019, la copia de metadatos funciona también en las transformaciones entre sitios.
TargetWebUrl (**) Transformación entre sitios Si quiere crear las páginas modernas transformadas en otra colección de sitios, especifique la dirección URL a dicha colección de sitios. Consulte la lista de transformación de elementos web para saber qué elementos web se transforman en una transformación entre colecciones de sitios.
TargetConnection (**) Transformación entre sitios Permite una definición más flexible del destino mediante un objeto de conexión. Esto permite, por ejemplo, llevar a cabo una transformación de la transformación de espacio empresarial cruzado de local a en línea.
UseCommunityScriptEditor $false Todos los tipos de página Use -UseCommunityScriptEditor si instaló el editor de scripts de la comunidad y quiere usarlo durante la transformación. Consulte el artículo lista de transformación de elementos web para obtener más información.
SummaryLinksToHtml $false Todos los tipos de página Use -SummaryLinksToHtml si prefiere transformar el elemento web de vínculos de resumen en un HTML hospedado en el elemento web de texto en lugar de la transformación predeterminada que usa el elemento web de vínculos rápidos. Consulte el artículo lista de transformación de elementos web para obtener más información.
LogType Ninguno Todos los tipos de página Use -LogType para el registro habilitado: File iniciará sesión en el disco, SharePoint creará una página de registro en la biblioteca de SharePoint SitePages, Console enviará datos de salida a la consola.
LogFolder Todos los tipos de página Si LogType se establece en File, puede usar -LogFolder para especificar la carpeta donde se creará el registro.
LogVerbose $false Todos los tipos de página Use -LogVerbose para generar un registro detallado.
LogSkipFlush $false Todos los tipos de página De forma predeterminada, cada llamada cmdlet genera un único archivo de registro, use el parámetro -LogSkipFlush para acumular entradas del registro. Tenga en cuenta que tendrá que terminar con una llamada sin LogSkipFlush para conservar las entradas del archivo de registro montado.
DontPublish $false Todos los tipos de página Use la opción -DontPublish para no publicar la página moderna creada.
KeepPageCreationModificationInformation $false Todos los tipos de página Use el parámetro -KeepPageCreationModificationInformation si desea tomar el control de las propiedades de la página autor/editor/creado/modificado. Esta opción solo funciona cuando la página de origen está en el mismo espacio empresarial SPO que el destino de la página moderna.
PostAsNews $false Todos los tipos de página Use el parámetro -PostAsNews si quiere publicar la página moderna que creó como noticia en el sitio. Esto también significa que la página se publicará incluso si en su configuración ha deshabilitado la publicación.
SetAuthorInPageHeader $false Wiki/webpart/páginas del blog Utilice el parámetro -SetAuthorInPageHeader si quiere rellenar el autor en el encabezado de la página creada. El autor será configurado como (asignado por el usuario) autor de la página de origen.
DisablePageComments $false Todos los tipos de página Use -DisablePageComments si desea deshabilitar la opción de comentarios en la página creada
PublishingPage $false Páginas de publicación Configurar el parámetro -PublishingPage si está transformando una página de publicación. Para las wiki, las páginas de blog clásicas y los elementos web este parámetro debe omitirse o establecerse como falso.
PageLayoutMapping Páginas de publicación Mediante -PageLayoutMapping, puede especificar la ruta de acceso del archivo de asignación de diseño de página que se usará para las transformaciones de la página de publicación cuando esta use un diseño de página no prediseñado
TargetPageName Wiki/elementoweb/páginas del blog Use el parámetro -TargetPageName para reemplazar el nombre de la página moderna Esto es necesario, por ejemplo, para evitar que se reemplace la página home.aspx existente si se produce una transformación cruzada de una página de inicio de un sitio de grupo clásico a un sitio de comunicación moderno.
PublishingTargetPageName Páginas de publicación Usar el parámetro -PublishingTargetPageName para reemplazar el nombre de la página moderna
TargetPageFolder Todos los tipos de página Utilice el parámetro -TargetPageFolder para especificar una carpeta de destino para la página moderna. Tenga en cuenta que si una carpeta se creó automáticamente (por ejemplo, porque se estaba transformando desde una biblioteca de páginas wiki adicional), entonces la carpeta especificada por este parámetro se combinará con la carpeta generada automáticamente (a menos que especifique -TargetPageFolderOverridesDefaultFolder). Puede especificar una carpeta de la siguiente forma: MyFolder o MyFolder/SubFolder cuando quiera crear una estructura de carpetas anidada. Si especifica <root> como valor, podrá dirigirse a la raíz de la biblioteca de SitePages de destino
TargetPageFolderOverridesDefaultFolder $false Todos los tipos de página Si usa el parámetro -TargetPageFolderOverridesDefaultFolder, puede forzar la transformación de página para que use la carpeta especificada a través de -TargetPageFolder, independientemente de si se ha creado una carpeta automáticamente.
UrlMappingFile Transformación entre sitios El archivo con asignación de URL personalizada le permite hacer más cosas que la asignación de URL predeterminada. Consulte el artículo de asignación de URL para obtener más información.
SkipUrlRewriting $false Transformación entre sitios Durante la transformación de páginas de publicación, las direcciones se reescriben para ser válidas en la colección de sitios de destino, pero usando el -SkipUrlRewriting puede deshabilitar la reescritura de la URL Consulte el artículo de asignación de URL para obtener más información.
SkipDefaultUrlRewriting Transformación entre sitios Cuando use una asignación de dirección URL personalizada y desee deshabilitar la lógica de reescritura de la dirección URL predeterminada, establezca el parámetro -SkipDefaultUrlRewriting.
AddTableListImageAsImageWebPart $true Todos los tipos de página Las imágenes que residen en una tabla o lista también se crean como elementos web de imágenes independientes, debajo de la tabla o la lista. Use el parámetro -AddTableListImageAsImageWebPart para evitar que se creen estos elementos web de imágenes separados.
BlogPage $false Páginas de blog Configurar el parámetro -BlogPage si está transformando una página de blog clásica. Para las wiki, las páginas de publicación y los elementos web este parámetro debe omitirse o establecerse como falso.
UserMappingFile Todos los tipos de página Archivo con información sobre la asignación de usuarios. Consulte el artículo de Asignación de usuarios para obtener más información.
LDAPConnectionString Todos los tipos de página Cadena de conexión LDAP para consultar Active Directory. Consulte el artículo de Asignación de usuarios para obtener más información.
SkipUserMapping $false Todos los tipos de página Omite la asignación de usuarios. La asignación de usuarios está desactivada para las transformaciones de SPO a menos que especifique un archivo de asignación. Para SharePoint local la asignación de usuarios está siempre activada, a menos que establezca este indicador. Consulte el artículo de Asignación de usuarios para obtener más información.
TermMappingFile Transformación entre sitios El archivo con asignación de términos personalizada le permite hacer más cosas que la asignación de términos predeterminada. Consulte el artículo de Asignación de términos para obtener más información.
SkipTermStoreMapping $false Transformación entre sitios Durante la transformación de páginas, los términos se asignan para que sean válidos en la colección de sitios de destino, pero si usa el parámetro -SkipTermStoreMapping puede deshabilitar la asignación de términos. Consulte el artículo de Asignación de términos para obtener más información.

(*) Parámetro de línea de comandos obligatorio / (**) Obligatorio cuando se estableció el parámetro -PublishingPage o -BlogPage (ya sea -TargetWebUrl o -TargetConnection)

Preguntas más frecuentes

Cómo transformar páginas de publicación

El ejemplo anterior muestra la transformación de página local, para transformar páginas de publicación necesita una sintaxis ligeramente diferente. El siguiente ejemplo muestra cómo modernizar la página mypage.aspx y crear una versión moderna de ella en un sitio de comunicación. Durante esta transformación, la transformación de página usará la asignación de diseño de página integrada si la página está usando un diseño de página predeterminado, o bien, generará una asignación de diseño de página en el momento para diseños de página personalizados:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite

Si usa diseños de página personalizados, se recomienda encarecidamente ajustar el archivo de asignación de diseño de página utilizado antes de usarlo. Para hacerlo, siga estos pasos:

Genere un archivo de asignación de diseño de página personalizado

Use el PowerShell de PnP para analizar los diseños de página existentes y generar un archivo de asignación:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

Export-PnPPageMapping -CustomPageLayoutMapping -Folder c:\temp

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.

Si desea generar los archivos de asignación para los diseños de página OOB, especifique el modificador AnalyzeOOBPageLayouts.

Ajuste el archivo de asignación generado

Abra el archivo de asignación creado y revise cada asignación:

  • Establezca los valores de fila y columna correctamente para elementos web, zonas de elementos web y elementos web fijos para que el contenido se muestre en la parte correcta en la página moderna. Puede tener tantas filas como quiera, cada fila será una sección en la página moderna. Los valores de columna están restringidos a 1, 2 o 3, lo que equivale a las opciones de columna posibles en una página moderna
  • Defina los campos que sea necesario transformar como metadatos
  • Revise la asignación de campos generada para los elementos web
  • Revise la asignación de campos generada para el encabezado

Use el archivo de asignación personalizada

Usar el archivo de asignación personalizada es sencillo mediante el parámetro PageLayoutMapping:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -PageLayoutMapping c:\temp\mypagelayouts.xml

Ejemplos de scripts para transformar páginas de publicación (locales) en páginas modernas en SharePoint Online

Consulte los scripts de https://github.com/SharePoint/sp-dev-modernization/tree/dev/Scripts/PageTransformation para empezar.

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. Para hacer esto, debe usar PnP PowerShell para SharePoint Online para conectarse a su portal local, como se muestra en la siguiente secuencia de comandos:

# Setup connection the target site - must be SPO and must be a modern site
$target = Connect-PnPOnline https://contoso.sharepoint.com/sites/moderncommunicationsite -ReturnConnection

# Connect to your on-premises portal
$source = Connect-PnPOnline https://portal2013.pnp.com/sites/classicportal -TransformationOnPrem -CurrentCredentials -ReturnConnection

# Convert a classic page living in the on-premises portal to a modern page in SharePoint Online. Dependent images and videos are copied as well from on-premises to online during this process.
ConvertTo-PnPPage -Identity "page1.aspx" -PublishingPage -TargetConnection $target -LogVerbose -LogType File -LogFolder c:\temp -Connection $source

Nota:

  • Esta característica es compatible con SharePoint 2013, 2016 y 2019 como entorno de origen. El entorno de destino es siempre SharePoint Online. Es posible realizar la transformación desde SharePoint 2010, pero esto requiere la versión heredada de PnP PowerShell
  • El equipo que ejecuta el script de PowerShell debe poder conectarse tanto con el servidor de SharePoint local como con el entorno de SharePoint Online.
  • Este enfoque también se puede usar para transformar páginas en espacios empresariales (siempre que tenga sentido).

Usar las características de registro

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

# Convert a series of pages, logs are not yet written
ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -LogSkipFlush -LogType SharePoint -LogVerbose
ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -LogSkipFlush -LogType SharePoint -LogVerbose

# persist the log data from all previous page transformations to the defined log
Save-PnPPageConversionLog

Transforme una página en la raíz del sitio (es decir, fuera de una biblioteca)

Es posible que algunos sitios antiguos tengan páginas de elementos Web fuera de una biblioteca. Para modernizarlas indique que la página se encuentra en la raíz del sitio en -Folder "<root>", como se muestra a continuación:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/sitetomodernize -Interactive

ConvertTo-PnPPage -Identity pageinroot.aspx -Overwrite -Folder "<root>"

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:

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

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

Vea también