Transformation en pages de site modernes à l’aide de .NET

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, veuillez le signaler dans la liste des problèmes de PnP Framework GitHub.

Le moteur de transformation de page est construit à l’aide de .NET et est distribué sous forme de package nuget . Une fois le package nuget ajouté, 2 fichiers supplémentaires sont ajoutés à votre solution :

fichiers de la solution de transformation de page

Remarque

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 piloter le comportement du mappage (par exemple, configurer l’utilisation de l’éditeur de script de la communauté). Vous pouvez configurer les 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);

Consultez l’article sur la liste de transformation des composants WebPart pour en savoir plus sur les propriétés de mappage possibles.

Je souhaite transformer des pages en une autre collection de sites

Le comportement de transformation par défaut effectue 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}");
          }
      }
    }
}

Remarque

Tous les composants WebPart ne se prêtent pas bien à un transfert intersite, case activée la colonne Support intersite de la liste de transformation du composant WebPart pour en savoir plus.

Je souhaite transformer les pages de publication

La transformation de page de publication sera toujours une transformation intersite, car le mélange de pages modernes avec des pages de publication n’est pas pris en charge. L’exemple ci-dessous montre comment toutes les pages de publication commençant par un « a » sont transformées en pages modernes du 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}");
          }
      }
    }
}

Remarque

Tous les composants WebPart ne se prêtent pas bien à un transfert intersite, case activée la colonne Support intersite de la liste de transformation du composant WebPart 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();
    }
}

Remarque

  • Cette fonctionnalité prend en charge SharePoint 2013, 2016 et 2019 en tant que source. La cible est toujours SharePoint Online
  • Il est important d’exécuter votre code sur un ordinateur capable de se connecter à la fois au serveur SharePoint local et à l’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 souhaite utiliser les fonctionnalités de journalisation

Par défaut, il existe trois observateurs de journal possibles (Console, Markdown et MarkdownToSharePoint). Ces deux derniers créent un rapport basé sur MD et le placent sur disque ou dans SharePoint sous forme de page moderne, tandis que le premier génère simplement des messages de console. L’exemple ci-dessous montre comment utiliser les enregistreurs à 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 il se peut qu’elle ait été désactivée. L’ancien scanner de modernisation de SharePoint peut identifier les sites où la fonctionnalité de page moderne est désactivée. Pour résoudre ce problème, utilisez le script PowerShell PnP suivant :

$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

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.

Voir aussi

  • Last updated on