.NET を使用したモダンサイトページへの変換

[アーティクル]
04/08/2023

重要

SharePoint PnP モダン化は、PnP フレームワークの一部であり、継続的に進化しています。リリースノートで常に最新の変更内容を確認してください。問題が発生した場合は、「PnP フレームワークに関する GitHub の問題リスト」で問題を提出してください。

ページ変換エンジンは .NET を使用して構築され、 nuget パッケージとして配布されます。この nuget パッケージを追加すると、2 つのファイルがソリューションに追加されていることが表示されます。

ページ変換のソリューションファイル

注:

PnP Framework nuget パッケージには、.NET Standard 2.0 バージョンと .NET 5.0 バージョンが含まれており、任意の .NET プロジェクトにページ変換を埋め込むことができます。

webpartmapping.xml および webpartmapping_latestfrompackage.xml は、変換の実行方法を説明する変換モデルを表します。通常は、他のマッピングを独自の Web パーツに追加するなどの方法で、必要に応じて webpartmapping.xml ファイルを調整します。後から更新されたバージョンの nuget パッケージをインストールする場合、既定では webpartmapping.xml は上書きされませんが、webpartmapping_latestfrompackage.xml は上書きされます。後者のファイルを使用して、最新版の既定のマッピングと独自のマッピングを比較し、必要な変更を引き継ぐことができます。

適切なマッピングファイルで以下のスニペットを使用することにより (GitHub の Modernization.PageTransformation サンプル)、特定のサイトのすべてのページを変換できます。

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

よく寄せられる質問

マッピングプロパティを設定する

マッピングプロパティは、マッピング動作を促進するように設定されます (たとえば、コミュニティスクリプトエディターの使用を構成します)。次のサンプルコードに示すように、マッピングプロパティを構成できます。

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

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

pageTransformator.Transform(pti);

可能なマッピングプロパティの詳細については、 Web パーツ変換リストの記事を参照してください。

ページを別のサイトコレクションに変換する

既定の変換動作では、インプレース変換が実行されます。つまり、モダンページはクラシックページと同じ場所に作成されます。ただし、ターゲットサイトコレクションのクライアントコンテキストオブジェクトを指定することで、ページの最新バージョンを別のサイトコレクションに作成することもできます。

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

注:

すべての Web パーツがクロスサイト転送に適しているわけではありません。詳細については、Web パーツ変換の一覧のクロスサイトサポート列を確認してください。

発行ページを変換する

最新のページと発行ページを混在させるのはサポートされていないため、発行ページ変換は常にクロスサイト変換になります。次のサンプルは、"a" で始まるすべての発行ページがサイト内のモダンページに変換される方法を https://contoso.sharepoint.com/sites/mycommunicationsite 示しています。このサンプルでは、カスタムページレイアウトマッピングファイルを提供する方法も示します。

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

注:

オンプレミスの SharePoint 発行ページを読み取り、SharePoint Online のモダンページを作成します

従来のオンプレミスの公開ポータルを使用する場合には、まず、オンプレミスから SharePoint Online の従来のポータルにポータル一式を移動させてから、モダン化作業を行います。ただし、SharePoint オンプレミスポータルから従来の発行ページを直接読み取り、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();
    }
}

注:

この機能では、ソースとして SharePoint 2013、2016、2019 がサポートされています。ターゲットは常に SharePoint Online です
SharePoint Online 環境としてオンプレミスの SharePoint サーバーの両方に接続できるコンピューターでコードを実行することが重要です
このアプローチをテナント間でのページ変換に使用することもできます (必要な場合)。

ログ機能を使用する

既定では、3 つのログオブザーバー (コンソール、Markdown、MarkdownToSharePoint) があります。後者の 2 つは MD ベースのレポートを作成し、ディスクまたは SharePoint にモダンページとして配置しますが、最初のレポートはコンソールメッセージを出力するだけです。次のサンプルは、.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();
    }
}

モダンサイトページが、ページを変換するサイトで機能しません

ほとんどのサイトでは、モダンサイトページ機能は既定で有効ですが、後からオフにされている場合もあります。その場合、SharePoint モダン化スキャナーで、どのサイトがモダンページ機能をオフにしているかが分かります。これを修復するには、下記のサンプル PnP PowerShell スクリプトを使用してください。

$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

注:

PnP PowerShell はオープンソースソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープンソースツールのサポート SLA はありません。

次の方法で共有

.NET を使用したモダンサイトページへの変換

よく寄せられる質問

マッピングプロパティを設定する

ページを別のサイトコレクションに変換する

発行ページを変換する

オンプレミスの SharePoint 発行ページを読み取り、SharePoint Online のモダンページを作成します

ログ機能を使用する

モダンサイトページが、ページを変換するサイトで機能しません

関連項目

その他のリソース

次の方法で共有

.NET を使用したモダン サイト ページへの変換

よく寄せられる質問

マッピング プロパティを設定する

ページを別のサイト コレクションに変換する

発行ページを変換する

オンプレミスの SharePoint 発行ページを読み取り、SharePoint Online のモダン ページを作成します

ログ機能を使用する

モダン サイト ページが、ページを変換するサイトで機能しません

関連項目

その他のリソース

.NET を使用したモダンサイトページへの変換

マッピングプロパティを設定する

ページを別のサイトコレクションに変換する

オンプレミスの SharePoint 発行ページを読み取り、SharePoint Online のモダンページを作成します

モダンサイトページが、ページを変換するサイトで機能しません