Freigeben über

Transformieren in moderne Websiteseiten mit .NET

  • Artikel

Wichtig

SharePoint PnP Modernization ist ein Bestandteil des PnP-Framework und wird ständig weiterentwickelt. Sehen Sie sich die Versionshinweise an, um bezüglich der aktuellsten Änderungen auf dem neuesten Stand zu bleiben. Wenn Sie Probleme feststellen, öffnen Sie bitte ein Ticket in der GitHub-Problemliste im PnP-Framework.

Das Seitentransformationsmodul wird mit .NET erstellt und als Nuget-Paket verteilt. Nachdem Sie das Nuget-Paket hinzugefügt haben, werden zwei weitere Dateien zu Ihrer Lösung hinzugefügt:

Dateien der Seitentransformationslösung

Hinweis

Das PnP Framework-Nuget-Paket enthält eine .NET Standard 2.0-Version und eine .NET 5.0-Version, mit der Sie die Seitentransformation in jedes .NET-Projekt einbetten können.

webpartmapping.xml und webpartmapping_latestfrompackage.xml geben das Transformationsmodell an, das beschreibt, wie die Transformation erfolgen soll. Sie müssen in der Regel die webpartmapping.xml-Datei basierend auf Ihren Bedürfnissen optimieren, indem Sie zum Beispiel zusätzliche Zuordnungen zu Ihren eigenen Webparts hinzufügen. Wenn Sie später eine aktualisierte Version des Nuget-Pakets installieren, wird Ihre webpartmapping.xml-Datei standardmäßig nicht überschrieben, die webpartmapping_latestfrompackage.xml-Datei jedoch schon. Sie können die letztgenannte Datei verwenden, um die neueste vorkonfigurierte Zuordnung mit Ihrer Zuordnung zu vergleichen, und die benötigten Änderungen übernehmen.

Mit der Zuordnungsdatei können Sie jetzt den nachfolgenden Codeausschnitt verwenden (aus dem Modernization.PageTransformation-Beispiel auf GitHub), um alle Seiten in einer bestimmten Website umzuwandeln:

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}");
        }
    }
}

Häufig gestellte Fragen

Ich möchte Zuordnungseigenschaften festlegen

Zuordnungseigenschaften werden auf laufwerksgesteuertes Zuordnungsverhalten festgelegt (z. B. Konfigurieren der Verwendung des Community-Skript-Editors). Sie können Zuordnungseigenschaften wie im folgenden Beispielcode dargestellt konfigurieren:

PageTransformationInformation pti = new PageTransformationInformation(page)
{
    // If target page exists, then overwrite it
    Overwrite = true,
};

pti.MappingProperties["UseCommunityScriptEditor"] = "true";

pageTransformator.Transform(pti);

Weitere Informationen zu den möglichen Zuordnungseigenschaften finden Sie im Artikel zur Webparttransformationsliste.

Ich möchte Seiten in eine andere Websitesammlung umwandeln

Das Standardtransformationsverhalten ist eine direkte Transformation, d. h., die moderne Seite wird an derselben Stelle wie die klassische Seite erstellt. Sie können jedoch auch die moderne Version der Seite in einer anderen Websitesammlung erstellen, indem Sie ein Clientkontextobjekt für die Zielwebsitesammlung bereitstellen.

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}");
          }
      }
    }
}

Hinweis

Nicht alle Webparts eignen sich gut für eine websiteübergreifende Übertragung. Weitere Informationen finden Sie in der Spalte zur websiteübergreifenden Unterstützung in der Webparttransformationsliste.

Ich möchte Veröffentlichungsseiten transformieren

Die Veröffentlichungsseitentransformation ist immer eine websiteübergreifende Transformation, da das Mischen moderner Seiten mit Veröffentlichungsseiten nicht unterstützt wird. Das folgende Beispiel zeigt, wie alle Veröffentlichungsseiten, die mit einem "a" beginnen, in moderne Seiten auf der Website transformiert https://contoso.sharepoint.com/sites/mycommunicationsite werden. Dieses Beispiel zeigt auch, wie Sie eine benutzerdefinierte Seitenlayout-Zuordnungsdatei bereitstellen.

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}");
          }
      }
    }
}

Hinweis

Nicht alle Webparts eignen sich gut für eine websiteübergreifende Übertragung. Weitere Informationen finden Sie in der Spalte zur websiteübergreifenden Unterstützung in der Webparttransformationsliste.

Lesen Sie die Veröffentlichungsseite in lokalem SharePoint und erstellen Sie die moderne Seite in SharePoint Online

Wenn Sie Ihre klassischen lokalen Veröffentlichungsportale übernehmen möchten, verschieben Sie zuerst das gesamte Portal vom lokalen in ein klassisches Portal in SharePoint Online und modernisieren sie es dann. Häufig ist es jedoch einfacher, die klassische Veröffentlichungsseite direkt von Ihrem lokalen SharePoint-Portal aus zu lesen und die moderne Version in SharePoint Online zu erstellen.

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();
    }
}

Hinweis

  • Dieses Feature unterstützt SharePoint 2013, 2016 und 2019 als Quelle. Ziel ist immer SharePoint Online
  • Es ist wichtig, Ihren Code auf einem Computer auszuführen, der eine Verbindung mit dem lokalen SharePoint-Server als SharePoint Onlineumgebung herstellen kann.
  • Diese Vorgehensweise kann auch für die mandantenübergreifende Seitentransformation verwendet werden (wenn dies sinnvoll wäre)

Ich möchte die Protokollierungsfunktionen verwenden

Standardmäßig gibt es drei mögliche Protokollwahrer (Konsole, Markdown und MarkdownToSharePoint). Die beiden letzteren erstellen einen MD-basierten Bericht und platzieren sie auf dem Datenträger oder in SharePoint als moderne Seite, während die erste einfach Konsolenmeldungen ausgibt. Das folgende Beispiel zeigt, wie Sie die Protokollierung von .NET verwenden können:

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();
    }
}

Moderne Websiteseiten funktionieren nicht auf der Website, auf der ich Seiten transformieren möchte

Die Funktion für moderne Websiteseiten ist standardmäßig für die meisten Websites aktiviert, wurde aber vielleicht danach deaktiviert. Wenn dies der Fall ist, erfahren Sie über den SharePoint-Modernisierungsscanner, auf welchen Websites das Feature für moderne Seiten deaktiviert wurde. Zur Behebung dieses Problems verwenden Sie das folgende PnP-PowerShell-Beispielskript:

$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

Hinweis

PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Siehe auch