Compartilhar via

Transformar em páginas de site modernas usando o PowerShell

  • 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 da página também pode ser usado pelo PowerShell. Isso permite que ele seja integrado em um script de modernização do site que, além da transformação da página, também faz outras coisas como instalar uma solução, conectar o site a um grupo do Microsoft 365 e aplicar a identidade visual do locatário. Um bom exemplo de todo o script de modernização pode ser encontrado no artigo conectado ao grupo do Microsoft 365.

Observação

Os scripts a seguir mostram como transformar as páginas. Requer a versão 1.3.* (Fevereiro de 2021) ou posterior do PnP PowerShell. Há scripts de exemplos adicionais (por exemplo, para transformar páginas de publicação, para transformação do SharePoint local) disponíveis em nosso local de scripts do 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
}

Opções para o cmdlet ConvertTo-PnPPage

O cmdlet ConvertTo-PnPPage é o cmdlet chave para modernizar uma determinada página. A tabela abaixo lista os parâmetros de linha de comando que você pode usar para controlar a transformação de página por meio deste cmdlet.

Parâmetro Padrão Compatível com Descrição
Identidade (*) Todos os tipos de páginas O nome da página (por exemplo, pageA.aspx) para Wiki, Web part e páginas de publicação ou o título do blog para as páginas do blog clássico. No caso das páginas do blog clássico, a primeira página do blog onde o título começa com o Identity fornecido será usada ou, alternativamente, você também poderá especificar o id (valor inteiro) da página.
Biblioteca Páginas wiki/webpart A biblioteca que contém a página. Use este parâmetro -Library quando sua página de wiki ou de Web part residir fora da biblioteca padrão do SitePages.
Pasta Wiki/webpart/páginas de publicação Quando a página que você deseja transformar residir em uma pasta, você poderá especificar essa pasta (por exemplo -Folder "Folder1/SubFolder").
WebPartMappingFile Todos os tipos de página A transformação de página é orientada por um arquivo de mapeamento. O cmdlet tem um arquivo de mapeamento padrão inserido, mas você também pode especificar o arquivo de mapeamento personalizado da web part (webpartmapping.xml) para atender às suas necessidades de transformação da página (por exemplo, transformando-se web parts personalizadas de terceiros). Para fazer isso, especifique o caminho para o arquivo pelo parâmetro -WebPartMappingFile.
Overwrite $false Todos os tipos de página Quando você adiciona -Overwrite, a estrutura de transformação da página substituirá a página de destino, se necessário. Por padrão, o novo nome da página têm um prefixo Migrated_, que sugere que, se já existe Migrated_YourPage.aspx (normalmente a partir de um esforço de transformação de uma página anterior), ela será substituída.
ReplaceHomePageWithDefault $false Páginas wiki/webpart O comportamento padrão é transformar a página inicial do site em uma página moderna como qualquer outra página normal. Se você usar -ReplaceHomeWithDefault, a página inicial do site será transformada em uma página inicial “padrão” pronta para uso, sendo assim a página que você obteria com um site de equipe moderno recém-criado.
TakeSourcePageName $false Páginas wiki/webpart O comportamento padrão é dar à página moderna criada um nome que comece com o prefixo Migrated_ e deixar a página original manter seu nome existente. Quando -TakeSourcePageName é especificada, a página recém-criada fica com o nome da página original e a página original é renomeada com o prefixo Previous_. Defina essa opção se tiver certeza de que deseja avançar com a página moderna, pois isso vai garantir que todos os links que apontam para a página original resultarão agora no carregamento da nova página moderna.
ClearCache $false Todos os tipos de páginas Para otimizar o desempenho de determinados dados (por exemplo, lista de web parts modernas disponíveis, lista calculada de campos para a qual copiar os metadados), eles serão armazenados em cache após a primeira execução. Esse cache permanecerá válido durante a sessão do PowerShell completa, a menos que você use o -ClearCache mudar. Reiniciar sua sessão do PowerShell, além de limpar o cache.
SkipItemLevelPermissionCopyToClientSidePage $false Todos os tipos de página Por padrão, as permissões a nível de item são copiadas para a página moderna; use o -SkipItemLevelPermissionCopyToClientSidePage para evitar isso.
CopyPageMetadata $false Wiki/webpart/páginas de blog O comportamento padrão é não copiar a página de metadados (assim colunas adicionais são adicionadas à biblioteca de páginas de site). Quando -CopyPageMetadata é especificado, os valores dos campos de metadados personalizados da página que será transformada são copiados para a página recém-criada. A partir da cópia de metadados da página de lançamento de outubro de 2019, também funcionando em transformações entre sites.
TargetWebUrl (**) Transformação entre sites Se você deseja criar as páginas modernas e transformadas em outro conjunto de sites, especifique a URL para esse conjunto de sites. Confira o artigo sobre a lista de Web Parts de transformação para entender quais Web Parts serão transformadas em uma transformação de conjunto entre sites.
TargetConnection (**) Transformação entre sites Permite uma definição mais flexível do destino por meio de um objeto de conexão. Isso permite, por exemplo, executar a transformação entre locatários de local para online.
UseCommunityScriptEditor $false Todos os tipos de página Se você já tiver instalado o editor de scripts da comunidade e quiser usá-lo durante a transformação, use -UseCommunityScriptEditor. Para saber mais, confira o artigo sobre a lista de Web Parts de transformação.
SummaryLinksToHtml $false Todos os tipos de página Use -SummaryLinksToHtml se quiser transformar a Web Part Links de Resumo para HTML hospedado na Web Part de texto em vez da transformação padrão usando a Web Part Links Rápidos. Para saber mais, confira o artigo sobre a lista de Web Parts de transformação.
LogType Nenhum Todos os tipos de páginas Use o -LogType para registrar em log habilitado: o File irá logar em disco, o SharePoint criará uma página de log na biblioteca SitePages do SharePoint e o Console produzirá dados para o console.
LogFolder Todos os tipos de página Se LogType estiver definido como File, você poderá usar -LogFolder para especificar a pasta onde o log será criado.
LogVerbose $false Todos os tipos de página Use -LogVerbose para gerar um log detalhado.
LogSkipFlush $false Todos os tipos de página Por padrão, cada chamada de cmdlet gera um arquivo de log exclusivo; use o parâmetro -LogSkipFlush para acumular entradas de log. Observe que você terá que terminar uma chamada sem o LogSkipFlush para persistir as entradas do arquivo de log montado.
DontPublish $false Todos os tipos de página Use a opção -DontPublish para não publicar a página moderna criada.
KeepPageCreationModificationInformation $false Todos os tipos de página Use o parâmetro -KeepPageCreationModificationInformation, se quiser controlar as propriedades de página Autor/Editor/Criado/Modificado. Essa opção funciona apenas quando a página de origem está no mesmo locatário SPO que o destino da página moderna.
PostAsNews $false Todos os tipos de página Use o parâmetro -PostAsNews, se quiser postar a página moderna criada como notícias no site. Isso também implica que a página será publicada, mesmo que você tenha configurado para ignorar a publicação.
SetAuthorInPageHeader $false Página de wiki/webpart/blog Use o parâmetro -SetAuthorInPageHeader se quiser preencher o autor no cabeçalho da página criada. O autor será definido como o autor da página de origem (mapeado pelo usuário).
DisablePageComments $false Todos os tipos de página Use -DisablePageComments se você quiser desabilitar a opção de comentários na página criada
PublishingPage $false Páginas de publicação Defina o parâmetro -PublishingPage se você estiver transformando uma página de publicação. Para páginas de Wiki, Web part e de blogs clássicos, este parâmetro deve ser omitido ou definido como falso.
PageLayoutMapping Páginas de publicação Através do -PageLayoutMapping, você pode especificar o caminho do arquivo de mapeamento de layout de página que você usará para as transformações da página de publicação quando a página de publicação estiver usando um layout de página não pronto para uso
TargetPageName Página de wiki/webpart/blog Use o parâmetro -TargetPageName para substituir o nome padrão da página moderna. Isso é necessário para evitar substituir a página Home.aspx existente ao fazer uma transformação de um site com uma home page de site de equipe clássica para um site de comunicação moderna.
PublishingTargetPageName Páginas de publicação Use o parâmetro -PublishingTargetPageName para substituir o nome da página moderna
TargetPageFolder Todos os tipos de páginas Use o parâmetro -TargetPageFolder para especificar uma pasta de destino para a página moderna. Observe que, se uma pasta for criada automaticamente (por exemplo, porque você estava transformando de uma biblioteca de páginas de wiki extra), a pasta especificada por esse parâmetro será combinada com a pasta gerada automaticamente (a menos que você especifique -TargetPageFolderOverridesDefaultFolder). Você poderá especificar uma pasta como esta: MyFolder ou MyFolder/SubFolder quando desejar criar uma estrutura de pastas aninhada. Especificando o <root> como um valor que permite que você tenha como alvo a raiz da biblioteca das páginas do site de destino
TargetPageFolderOverridesDefaultFolder $false Todos os tipos de páginas Com o parâmetro -TargetPageFolderOverridesDefaultFolder, você pode forçar a transformação da página a usar a pasta especificada por -TargetPageFolder, independentemente de uma pasta ter sido criada automaticamente
UrlMappingFile Transformação entre sites O arquivo com definições de mapeamento de URL personalizadas permitem que você faça mais do que apenas o mapeamento de URL padrão. Confira o artigo mapeamento de URL para saber mais.
SkipUrlRewriting $false Transformação entre sites Durante transformação de páginas de publicação, as URLs de são regravadas para serem válidas no conjunto de sites de destino, mas, usando -SkipUrlRewriting, você pode desabilitar a regravação de URLs. Confira o artigo mapeamento de URL para saber mais.
SkipDefaultUrlRewriting Transformação entre sites Quando você usa um mapeamento de URL personalizado e deseja desabilitar a lógica de reescrita da URL padrão, defina o parâmetro -SkipDefaultUrlRewriting.
AddTableListImageAsImageWebPart $true Todos os tipos de páginas As imagens que ficam dentro de uma tabela/lista também eram criadas como Web Parts de imagem separadas abaixo dessa tabela/lista. Use o parâmetro -AddTableListImageAsImageWebPart para interromper a criação dessas Web Parts de imagens separadas.
BlogPage $false Páginas de blog Defina o parâmetro -BlogPage se você estiver transformando uma página de blog clássica. Para páginas Wiki, Web part e de publicação, este parâmetro deve ser omitido ou definido como falso.
UserMappingFile Todos os tipos de páginas Arquivo com informações de mapeamento do usuário. Confira o artigo Mapeamento de usuário para saber mais.
LDAPConnectionString Todos os tipos de páginas Cadeia de conexão LDAP para consultar o diretório ativo. Confira o artigo Mapeamento de usuário para saber mais.
SkipUserMapping $false Todos os tipos de páginas Ignora o mapeamento de usuário. Para transformações SPO, o mapeamento de usuário está desativado, a menos que você especifique um arquivo de mapeamento. Para mapeamento de usuário do SharePoint local está sempre ativado, a menos que você defina esse sinalizador. Confira o artigo Mapeamento de usuário para saber mais.
TermMappingFile Transformação entre sites O arquivo com definições de mapeamento de termo personalizadas permite que você faça mais do que apenas o mapeamento de termo padrão. Confira o artigo Mapeamento de termo para saber mais.
SkipTermStoreMapping $false Transformação entre sites Durante a transformação de páginas, os termos são mapeados para validação no conjunto de sites de destino, mas, usando o parâmetro -SkipTermStoreMapping, você pode desabilitar o mapeamento de termos. Confira o artigo Mapeamento de termo para saber mais.

(*) Parâmetro obrigatório de linha de comando / (**) Parâmetro obrigatório quando o -PublishingPage ou o -BlogPage for definido (seja -TargetWebUrl ou -TargetConnection)

Perguntas frequentes

Como faço para transformar as páginas de publicação?

O exemplo acima mostra a transformação de páginas no local; para transformar páginas de publicação você precisará de uma sintaxe ligeiramente diferente. O exemplo abaixo mostra como modernizar a página mypage.aspx e criar uma versão moderna para ela em um site de comunicação. Durante essa transformação, a transformação de página usará o mapeamento de layout de página interno, se a página estiver usando um layout de página pronto para uso, ou gerará rapidamente um mapeamento de layout de página para layouts 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

Se você estiver usando layouts de página personalizados, é altamente recomendável ajustar o arquivo de mapeamento de layout de página antes de usá-lo. Para isso, siga estas etapas:

Gere um arquivo de mapeamento de layout de página personalizado

Use o PnP do PowerShell para analisar seus layouts de página existentes e gerar um arquivo de mapeamento:

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

Export-PnPPageMapping -CustomPageLayoutMapping -Folder c:\temp

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.

Se você deseja gerar os arquivos de mapeamento para layouts de página prontos para uso, especifique o switch AnalyzeOOBPageLayouts.

Ajuste o arquivo de mapeamento gerado

Abra o arquivo de mapeamento criado e revise cada mapeamento:

  • Defina os valores de linha e coluna corretamente para web parts, zonas de web parts e web parts fixas, para que o conteúdo apareça no lugar correto na página moderna. Você pode ter quantas linhas quiser; cada linha será uma seção na página moderna. Os valores das colunas são restritos a 1, 2 ou 3, o que se traduz nas opções de coluna possíveis em uma página moderna
  • Defina os campos que precisam ser transformados como metadados
  • Revise o mapeamento de campos para web parts gerado
  • Revise o mapeamento de campos para cabeçalho gerado

Use o arquivo de mapeamento personalizado

Através do parâmetro PageLayoutMapping, é simples usar o arquivo limpo de mapeamento personalizado:

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

Scripts de exemplo para transformar páginas de publicação (locais) em páginas modernas no SharePoint Online

Confira os scripts no https://github.com/SharePoint/sp-dev-modernization/tree/dev/Scripts/PageTransformation para começar.

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. Para fazer isso, você precisa usar o PnP PowerShell para SharePoint Online para se conectar ao seu portal no local, como mostrado no script abaixo:

# 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

Observação

  • Esse recurso é compatível com o Microsoft Office SharePoint Online 2013, 2016 e 2019 como um ambiente de origem. O Ambiente de destino é sempre o SharePoint Online. A transformação a partir do Microsoft Office SharePoint Online 2010 é possível, mas isso requer a versão antiga do PnP PowerShell
  • O computador que executa o script do PowerShell precisa ser capaz de se conectar com ambos os servidores do SharePoint local e com o 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)

Usar os recursos de registro em log

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

Transformar uma página que reside na raiz do site (portanto, fora da biblioteca)

Alguns sites mais antigos podem ter páginas de Web parts residindo fora de uma biblioteca. Se você quiser modernizá-los, precisará indicar que a página reside na raiz do site por meio de -Folder "<root>", conforme mostrado abaixo:

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

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

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 Microsoft Office SharePoint Online informará quais sites desativaram o recurso de página moderna. Para corrigir isso, use o exemplo abaixo de script do PowerShell PnP:

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

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

Confira também