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

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

Le moteur de transformation de page est généré à l’aide de .NET et est distribué en tant que 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 une 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}");
        }
    }
}

Questions fréquentes (FAQ)

Je souhaite définir les propriétés de mappage

Les propriétés de mappage sont définies sur le comportement de mappage des lecteurs (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);

Pour en savoir plus sur les propriétés de mappage possibles, consultez l’article Liste des transformations de composants WebPart .

Je souhaite transformer des pages en une autre collection de sites

Le comportement de transformation par défaut consiste à effectuer 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 pour un transfert intersites. Consultez la colonne Prise en charge intersites dans la liste transformation de composants WebPart pour en savoir plus.

Je souhaite transformer les pages de publication

La transformation de page de publication sera toujours une transformation intersites, car la combinaison de pages modernes avec des pages de publication n’est pas prise en charge. 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}");
          }
      }
    }
}

Remarque

Tous les composants WebPart ne se prêtent pas bien pour un transfert intersites. Consultez la colonne Prise en charge intersites dans la liste transformation de composants 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 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 souhaite utiliser les fonctionnalités de journalisation

Par défaut, il existe trois observateurs de journaux possibles (Console, Markdown et MarkdownToSharePoint). Les deux derniers créent un rapport basé sur MD et les placent sur disque ou dans SharePoint en tant que page moderne, tandis que le premier génère simplement des messages de console. L’exemple ci-dessous montre comment utiliser les enregistreurs d’événements à 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

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