Transformation de pages de site moderne à l’aide de .NET
Important
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, veuillez le signaler dans la liste des problèmes de PnP Framework GitHub.
Le moteur de transformation de page est créé à l’aide de .NET et distribué en tant que package nuget. Une fois le package nuget ajouté, 2 fichiers supplémentaires sont ajoutés à votre solution :

Notes
Le package nuget PnP Framework contient une version .NET Standard 2.0 et une version .NET 5.0, ce qui vous permet d’incorporer la transformation de page dans n’importe quel projet .NET.
Les fichiers webpartmapping.xml et webpartmapping_latestfrompackage.xml représentent le modèle de transformation qui décrit le déroulement de la transformation. Vous pouvez ajuster le fichier webpartmapping.xml selon vos besoins en y ajoutant, par exemple, des mappages supplémentaires avec vos propres composants WebPart. Si vous installez plus tard une version mise à jour du package nuget, votre fichier webpartmapping.xml ne sera pas remplacé par défaut, contrairement au fichier webpartmapping_latestfrompackage.xml. Vous pouvez utiliser ce dernier pour comparer le dernier mappage prêt à l’emploi avec votre mappage et intégrer les modifications dont vous avez besoin.
Dès que le fichier de mappage est en place, vous pouvez utiliser l’extrait de code ci-dessous (provenant de l’exemple Modernization.PageTransformation sur GitHub) pour transformer toutes les pages dans un site donné :
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}");
}
}
}
FAQ
Je souhaite définir les propriétés de mappage
Les propriétés de mappage sont définies pour stimuler le comportement de mappage (par exemple, configurer l’utilisation de l’éditeur de script communautaire). Vous pouvez configurer des propriétés de mappage comme indiqué dans l’exemple de code ci-dessous :
PageTransformationInformation pti = new PageTransformationInformation(page)
{
// If target page exists, then overwrite it
Overwrite = true,
};
pti.MappingProperties["UseCommunityScriptEditor"] = "true";
pageTransformator.Transform(pti);
Pour en savoir plus sur les propriétés de mappage possibles, consultez l’article de la liste de transformations de partie Web.
Je souhaite transformer des pages en une autre collection de sites
Le comportement de transformation par défaut consiste à faire une transformation sur place, ce qui signifie que la page moderne est créée au même emplacement que la page classique. Toutefois, vous pouvez également créer la version moderne de la page dans une autre collection de sites en fournissant un objet de contexte client pour la collection de sites cible.
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}");
}
}
}
}
Notes
Les composants Web Parts ne se prêtent pas tous bien pour un transfert entre sites, consultez la colonne de prise en charge de sites croisés dans la liste de transformations de composants Web Part pour en savoir plus.
Je souhaite transformer des pages de publication
La transformation de page de publication sera toujours une transformation entre sites, car le mélange de pages modernes avec des pages de publication n’est pas pris en temps. L’exemple ci-dessous montre comment toutes les pages de publication commençant par un « a » sont transformées en pages modernes dans le https://contoso.sharepoint.com/sites/mycommunicationsite site. Cet exemple montre également comment fournir un fichier de mappage de mise en page personnalisé.
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}");
}
}
}
}
Notes
Les composants Web Parts ne se prêtent pas tous bien pour un transfert entre sites, consultez la colonne de prise en charge de sites croisés dans la liste de transformations de composants Web Part pour en savoir plus.
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.
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();
}
}
Notes
- Cette fonctionnalité prend SharePoint 2013, 2016 et 2019 comme source. La cible est toujours SharePoint Online
- Il est important d’exécuter votre code sur un ordinateur capable 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)
Je veux utiliser les fonctionnalités de journalisation
Par défaut, il existe trois observateurs de journaux possibles (Console, Markdown et MarkdownToSharePoint). Ces deux derniers créent un rapport md et les placent sur disque ou dans SharePoint en tant que page moderne, tandis que le premier produit simplement des messages de console. L’exemple ci-dessous montre comment utiliser les enregistreurs de journaux à partir 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();
}
}
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 activée. Pour y remédier, utilisez l’exemple de script PowerShell PnP ci-dessous :
$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
Notes
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.
Voir aussi
- Moderniser vos sites SharePoint classiques
- Exemple Modernization.PageTransformation sur GitHub
- Enregistrement YouTube du webinaire du SIG du 3 mai - démonstration d’une transformation de page
- Présentation et configuration du modèle de transformation de page
- Expériences de composant WebPart classique et moderne