Transformation des pages de site moderne à l’aide de PowerShell

  • Article

Importante

La modernisation de SharePoint PnP fait partie du Framework PnP et est en constante évolution, consultez les notes de publication pour rester à jour sur les dernières modifications. Si vous rencontrez des problèmes, signalez-les dans la liste de problèmes GitHub relative aux outils PnP.

Le moteur de transformation de page peut également être utilisé sur PowerShell. Ainsi, il peut être intégré dans un script de modernisation de site qui peut réaliser d’autres actions, en plus de la transformation de page, notamment l’installation de solution, la connexion du site à un groupe Microsoft 365 et la personnalisation d’un client. Un bon exemple de script de modernisation complète est disponible dans l’article connexion à un groupe Microsoft 365.

Remarque

Le script ci-dessous décrit comment transformer des pages. Il nécessite la version 1.3.* (février 2021) ou une version ultérieure de PnP PowerShell. D’autres exemples de scripts (par exemple, pour transformer la page de publication, pour transformer à partir de SharePoint locaux) sont disponibles dans notre emplacement de scripts 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
}

Options de l’applet de commande ConvertTo-PnPPage

L’applet de commande ConvertTo-PnPPage est l’applet de commande clé pour moderniser une page donnée. Le tableau ci-dessous liste les paramètres de ligne de commande que vous pouvez utiliser pour contrôler la transformation de page via cet applet de commande.

Parameter Par défaut Pris en charge pour Description
Identité (*) Tous les types de pages Le nom de la page (par exemple, pageA.aspx) pour les pages wiki, de composant WebPart et de publication ou le titre de blog pour les pages de blog classiques. En cas de pages de blog classiques, la première page de blog dans laquelle le titre commence par le Identity fourni est utilisée ou vous pouvez également spécifier l’id (valeur entière) de la page.
Bibliothèque Pages Wiki/Composant WebPart Bibliothèque contenant la page. Utilisez ce paramètre -Library lorsque votre site wiki ou page de composants WebPart se situe en dehors de la bibliothèque SitePages par défaut.
Dossier Pages wiki/webPart/publication Lorsque la page que vous voulez transformer se trouve dans un dossier, vous pouvez spécifier ce dossier (par exemple, -Folder "Folder1/SubFolder").
WebPartMappingFile Tous types de pages La transformation de page est menée par un fichier de mappage. L’applet de commande a un fichier de mappage par défaut incorporé, mais vous pouvez également spécifier votre fichier de mappage composant web personnalisé (webpartmapping.xml) pour adapter vos besoins de transformation de page (par exemple, transformer en composants WebPart personnalisés tiers). Pour cela, spécifiez le chemin d’accès au fichier via le paramètre-WebPartMappingFile.
Remplacer $false Tous types de pages Lorsque vous ajoutez -Overwrite, l’infrastructure de transformation de page remplace la page cible si nécessaire. Par défaut, le nouveau nom de page comporte le préfixe Migrated_, ce qui implique que si Migrated_YourPage.aspx existe déjà (provient généralement d’une action précédente de transformation de page), il est remplacé.
ReplaceHomePageWithDefault $false Pages Wiki/Composant WebPart Le comportement par défaut consiste à transformer la page d’accueil de votre site en une page moderne comme n’importe quelle autre page normale. Si vous utilisez -ReplaceHomeWithDefault, la page d’accueil d’un site est transformée en page d’accueil moderne « par défaut » prête à l’emploi, c’est-à-dire celle que pourriez obtenir avec un site d’équipe moderne créé récemment.
TakeSourcePageName $false Pages Wiki/Composant WebPart Le comportement par défaut consiste à attribuer à la page moderne créée un nom qui commence par le préfixe Migrated_ et à laisser son nom existant à la page d’origine. Lorsque -TakeSourcePageName est spécifiée, la page créée récemment prend le nom de la page d’origine et la page d’origine est renommée avec un préfixe Previous_. Définissez cette option si vous êtes sûr de vouloir continuer avec la page moderne, car elle permet de s’assurer que tous les liens pointant vers la page d’origine mènent désormais vers la nouvelle page moderne en cours de chargement.
ClearCache $false Tous les types de pages Pour optimiser les performances, certaines données (par exemple, liste des composants WebPart modernes disponibles, liste calculée des champs pour laquelle copier des métadonnées) sont mises en cache après la première exécution. Ce cache reste valide pendant la session PowerShell complète, sauf si vous utilisez le commutateur -ClearCache. Le redémarrage de votre session PowerShell efface également le cache.
SkipItemLevelPermissionCopyToClientSidePage $false Tous types de pages Par défaut, les autorisations au niveau de l’élément sont copiées sur la page moderne, utilisez -SkipItemLevelPermissionCopyToClientSidePage pour éviter cela.
CopyPageMetadata $false Pages wiki/webPart/blog Le comportement par défaut consiste à ne pas copier les métadonnées de page (colonnes supplémentaires ajoutées à la bibliothèque de pages de site). Lorsque -CopyPageMetadata est spécifié, les valeurs des champs de métadonnées personnalisés de la page à transformer sont copiées dans la page nouvellement créée. Depuis la version d'octobre 2019, la copie des métadonnées de la page de publication fonctionne également dans les transformations entre sites.
TargetWebUrl (**) Transformation entre sites Si vous voulez créer les pages modernes transformées dans une autre collection de sites, spécifiez l’URL à cette autre collection. Consultez l’article Liste de transformation des composants WebPart pour mieux comprendre quels sont les composants WebPart qui sont transformés dans une transformation croisée de collections de sites.
TargetConnection (**) Transformation entre sites Permet une définition plus souple de la cible via un objet de connexion. Cela permet par exemple d’effectuer une transformation entre clients de local à en ligne.
UseCommunityScriptEditor $false Tous types de pages Utilisez -UseCommunityScriptEditor si vous avez installé l’éditeur de script Communauté et que vous souhaitez l’utiliser pendant la transformation. Consultez l’article Liste de transformation des composants WebPart pour en savoir plus.
SummaryLinksToHtml $false Tous types de pages Utilisez -SummaryLinksToHtml si vous préférez transformer le composant WebPart SummaryLinks en code HTML hébergé dans le composant WebPart texte au lieu de la transformation par défaut à l’aide du composant WebPart QuickLinks. Consultez l’article Liste de transformation des composants WebPart pour en savoir plus.
LogType Aucun Tous types de pages Utilisez -LogType pour activer la journalisation : File effectuera la journalisation sur le disque, SharePoint créera une page de journal dans la bibliothèque SitePages de SharePoint, Console affichera les données sur la console.
LogFolder Tous types de pages Si LogType est défini sur File, vous pouvez utiliser -LogFolder pour spécifier le dossier dans lequel le journal est créé.
LogVerbose $false Tous types de pages Utilisez -LogVerbose pour générer un journal détaillé.
LogSkipFlush $false Tous types de pages Par défaut chaque cmdlet génère un fichier journal unique. Utilisez le paramètre -LogSkipFlush pour accumuler les entrées du journal. Notez que vous devrez terminer par un appel sans LogSkipFlush pour conserver les entrées de fichier journal assemblées.
DontPublish $false Tous types de pages Utilisez l’option -DontPublish ne pas publier la page moderne créée.
KeepPageCreationModificationInformation $false Tous types de pages Utilisez le paramètre -KeepPageCreationModificationInformation si vous souhaitez utiliser les propriétés de page auteur/éditeur/créée/modifiée. Cette option fonctionne uniquement lorsque la page source se trouve dans le même client SPO que la destination cible de la page moderne.
PostAsNews $false Tous types de pages Utilisez le paramètre -PostAsNews si vous souhaitez publier la page moderne créée sous la forme d’actualités sur le site. Cela implique également que la page sera publiée, même si vous avez configuré pour ignorer la publication.
SetAuthorInPageHeader $false Pages Wiki/webPart/blog Utilisez le paramètre -SetAuthorInPageHeader si vous voulez indiquer l’auteur dans l’en-tête de la page créée. L’auteur de la page source (mappé par l’utilisateur) est alors la valeur définissant l’auteur.
DisablePageComments $false Tous types de pages Utilisez -DisablePageComments si vous voulez désactiver l’option de commentaires sur la page créée.
PublishingPage $false Pages de publication Définissez le paramètre -PublishingPage si vous transformez une page de publication. Pour les pages wiki, de composants WebPart et de blog, ce paramètre doit être omis ou définis sur false.
PageLayoutMapping Pages de publication Via -PageLayoutMapping, vous pouvez spécifier le chemin du fichier de mappage de mise en page que vous utiliserez pour vos transformations de page de publication lorsque la page de publication utilise une mise en page non prête à l’emploi.
TargetPageName Pages wiki/webPart/blog Utilisez le paramètre -TargetPageName pour remplacer le nom par défaut de la page moderne. Cette action est nécessaire par exemple pour empêcher le remplacement de la page home. aspx existante si vous transformez une page d’accueil de site d’équipe classique en site de communication moderne.
PublishingTargetPageName Pages de publication Utilisez le paramètre -PublishingTargetPageName pour remplacer le nom de la page moderne.
TargetPageFolder Tous les types de pages Utilisez le paramètre -TargetPageFolder pour spécifier un dossier cible pour la page moderne. Notez que si un dossier a été créé automatiquement (par exemple, si vous avez effectué une transformation à partir d’une bibliothèque de pages wiki supplémentaires), le dossier spécifié par ce paramètre est combiné avec le dossier généré automatiquement (sauf si vous spécifiez -TargetPageFolderOverridesDefaultFolder). Vous pouvez spécifier un dossier comme suit : MyFolder ou MyFolder/SubFolder quand vous voulez créer une structure de dossiers imbriqués. Le fait de spécifier <root> en tant que valeur vous permet de cibler la racine de la bibliothèque de pages de sites cible
TargetPageFolderOverridesDefaultFolder $false Tous les types de pages Le paramètre -TargetPageFolderOverridesDefaultFolder vous permet de forcer la transformation de page de façon de façon à utiliser le dossier spécifié via -TargetPageFolder, qu’il y ait ou non un dossier créé automatiquement.
UrlMappingFile Transformation entre sites Un fichier avec des définitions de mappage d’URL personnalisées vous permet de faire plus que le simple mappage d’URL par défaut. Pour plus d’informations, voir l’article sur le mappage d’URL.
SkipUrlRewriting $false Transformation entre sites Pendant la transformation de page de publication, les URL sont réécrites de sorte qu’elles soient valides dans la collection de sites cibles. Cependant, vous pouvez désactiver la réécriture d’URL à l’aide de -SkipUrlRewriting. Pour plus d’informations, voir l’article sur le mappage d’URL.
SkipDefaultUrlRewriting Transformation entre sites Si vous utilisez un mappage d’URL personnalisé et que vous voulez désactiver la logique de réécriture d’URL par défaut, configurez le paramètre -SkipDefaultUrlRewriting.
AddTableListImageAsImageWebPart $true Tous types de pages Les images contenues dans un tableau ou une liste étaient également créées sous forme de composants WebPart image distincts sous le tableau ou la liste. Utilisez le paramètre -AddTableListImageAsImageWebPart pour arrêter la création de ces composants WebPart image distincts.
BlogPage $false Pages de blog Définissez le paramètre -BlogPage si vous transformez une page de blog classique. Pour les pages de wiki, de composants WebPart et de publication, ce paramètre doit être omis ou définis sur false.
UserMappingFile Tous les types de pages Fichier avec des informations de mappage d’utilisateur. Pour plus d’informations, consultez l’article Mappage d’utilisateur.
LDAPConnectionString Tous les types de pages Chaîne de connexion LDAP pour adresser des requêtes à Active Directory. Pour plus d’informations, consultez l’article Mappage d’utilisateur.
SkipUserMapping $false Tous les types de pages Ignore le mappage d’utilisateur. Pour les transformations SPO, le mappage d’utilisateur est désactivé, sauf si vous spécifiez un fichier de mappage. Pour SharePoint local, le mappage d’utilisateur est toujours activé, sauf si vous définissez cet indicateur. Pour plus d’informations, consultez l’article Mappage d’utilisateur.
TermMappingFile Transformation intersite Un fichier avec des définitions de mappage de termes personnalisées vous permet de faire plus que le simple mappage d’URL par défaut. Pour plus d’informations, consultez l’article Mappage de termes.
SkipTermStoreMapping $false Transformation intersite Pendant la transformation de page, les termes sont mappés de sorte qu’ils soient valides dans la collection de sites cibles. Cependant, vous pouvez désactiver le mappage de termes à l’aide du paramètre -SkipTermStoreMapping. Pour plus d’informations, consultez l’article Mappage de termes.

(*) Paramètre de ligne de commande obligatoire / (**) Obligatoire quand le paramètre -PublishingPage ou -BlogPage a été défini sur (-TargetWebUrl ou -TargetConnection)

FAQ

Comment transformer les pages de publication

L’exemple ci-dessus illustre la transformation de page en place, pour transformer des pages de publication vous devez utiliser une syntaxe légèrement différente. L’exemple ci-dessous montre comment moderniser la page mypage.aspx et en créer une version moderne dans un site de communication. Au cours de cette transformation, la transformation de page utilisera soit la mise en page intégrée si la page utilise une mise en page prête à l'emploi, soit elle générera une mise en page à la volée pour des mises en page personnalisées :

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 vous utilisez des mises en page personnalisées, il est vivement recommandé de redéfinir le fichier de mappage de mise en page utilisé avant de l’utiliser. Pour ce faire, procédez comme suit :

Générer un fichier de mappage de mise en page personnalisé

Utiliser PowerShell Plug and Play pour analyser vos mises en page existantes et générer un fichier de mappage :

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

Export-PnPPageMapping -CustomPageLayoutMapping -Folder c:\temp

Remarque

PnP PowerShell est une solution open source pour laquelle un support est assuré par la communauté active. Il n’existe pas de contrat SLA Microsoft pour le support technique relatif à cet outil open source.

Si vous voulez générer les fichiers de mappage pour des dispositions de page OOB, spécifiez le commutateur AnalyzeOOBPageLayouts.

Optimiser le fichier de mappage généré

Ouvrez le fichier de mappage créé et examinez chaque mappage :

  • Définir les valeurs de ligne et de colonne correctement pour les composants WebPart, les zones de composants WebPart et les composants WebPart fixes afin que le contenu s’affiche au bon emplacement dans la page moderne. Vous pouvez avoir autant de lignes que vous le souhaitez, chaque ligne sera une section dans la page moderne. Les valeurs de colonne sont limitées à 1, 2 ou 3, ce qui correspond aux options de colonne disponibles dans une page moderne
  • Définir les champs devant être transformé en tant que métadonnées
  • Passez en revue le mappage généré des champs vers des composants WebPart
  • Passez en revue le mappage généré des champs vers des en-têtes

Utiliser le fichier de mappage personnalisé

Il est simple d’utiliser le fichier de mappage personnalisé nettoyé via le paramètre 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

Exemples de scripts pour la transformation (locale) de pages de publication vers des pages modernes dans SharePoint Online

Consultez les scripts dans https://github.com/SharePoint/sp-dev-modernization/tree/dev/Scripts/PageTransformation pour commencer.

Lisez la page de publication dans SharePoint local et créez la page moderne dans SharePoint Online

Lorsque vous voulez transférer vos portails de publication locaux classiques, vous pouvez commencer par transférer le portail complet depuis un portail local vers un portail classique dans SharePoint Online, puis effectuer la modernisation. Cependant, il est souvent plus facile de lire directement la page de publication classique à partir de votre portail SharePoint local et de créer la version moderne dans SharePoint Online. Pour ce faire, vous devez utiliser PowerShell PnP pour SharePoint Online pour vous connecter à votre portail local, comme illustré dans le script ci-dessous :

# 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

Remarque

  • Cette fonctionnalité prend en charge SharePoint 2013, 2016 et 2019 en tant qu’environnement source. L’environnement cible est toujours SharePoint Online. Une transformation à partir de SharePoint 2010 est possible, mais cela requiert l’ancienne version PnP PowerShell
  • L’ordinateur exécutant le script PowerShell doit être en mesure de se connecter au serveur SharePoint local en tant qu’environnement SharePoint Online.
  • Cette approche peut également être utilisée pour la transformation de page au sein des clients (chaque fois qu’il serait judicieux de le faire)

Utiliser les fonctionnalités de journalisation

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

Transformer une page qui se trouve à la racine du site (à l’extérieur d’une bibliothèque)

Certains sites plus anciens peuvent avoir des pages de composants WebPart qui résident en dehors d’une bibliothèque. Si vous voulez les moderniser, vous devez indiquer que la page se trouve à la racine du site via -Folder "<root>", comme illustré ci-dessous :

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

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

Les pages du site moderne ne fonctionnent pas sur le site pour lequel je souhaite transformer les pages.

Par défaut, la fonctionnalité de page de site moderne est activée sur la plupart des sites, mais elle a peut-être été désactivée par la suite. Si tel est le cas, le scanneur de modernisation SharePoint vous indiquera les sites pour lesquels la fonctionnalité de page moderne est désactivée. Pour y remédier, utilisez l’exemple de script PowerShell PnP ci-dessous :

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

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

Voir aussi