PowerShell を使用してモダンサイトページに変換する

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

重要

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

ページ変換エンジンは PowerShell からも使用できます。このようにすると、ページ変換エンジンをサイトモダン化スクリプトに統合できます。このスクリプトは、ページ変換の他に、ソリューションのインストール、サイトの Microsoft 365 グループへの接続、テナントのブランド化の適用なども実行できます。モダン化スクリプト全体の優れた例は、Microsoft 365 Group 接続に関する記事でご確認ください。

注:

以下のスクリプトは、ページを変換する方法を示します。これには、PnP PowerShell バージョン 1.3.* (2021 年 2 月リリース) 以上が必要です。追加のサンプルスクリプト (例: 発行ページの変換およびオンプレミスの SharePoint からの変換) は GitHub スクリプトの場所で利用できます。

<# 

.Synopsis

    Converts all classic wiki and web part pages in a site. 
    You need to install PnP PowerShell: https://pnp.github.io/powershell/

    Sample includes:
        - Conversion of wiki and web part pages
        - Connecting to MFA or supplying credentials
        - Includes Logging to File, log flushing into single log file        

.Example

    Convert-WikiAndWebPartPages.ps1 -SourceUrl "https://contoso.sharepoint.com/sites/classicteamsite" -TakeSourcePageName:$true

.Notes
    
    Useful references:
        - https://aka.ms/sppnp-pagetransformation
        - https://aka.ms/sppnp-powershell
#>

[CmdletBinding()]
param (

    [Parameter(Mandatory = $true, HelpMessage = "Url of the site containing the pages to modernize")]
    [string]$SourceUrl,

    [Parameter(Mandatory = $false, HelpMessage = "Modern page takes source page name")]
    [bool]$TakeSourcePageName = $false,    

    [Parameter(Mandatory = $false, HelpMessage = "Supply credentials for multiple runs/sites")]
    [PSCredential]$Credentials,

    [Parameter(Mandatory = $false, HelpMessage = "Specify log file location, defaults to the same folder as the script is in")]
    [string]$LogOutputFolder = $(Get-Location)
)
begin
{
    Write-Host "Connecting to " $SourceUrl
    
    if($Credentials)
    {
        Connect-PnPOnline -Url $SourceUrl -Credentials $Credentials
        Start-Sleep -s 3
    }
    else
    {
        Connect-PnPOnline -Url $sourceUrl -Interactive
        Start-Sleep -s 3
    }
}
process 
{    
    Write-Host "Ensure the modern page feature is enabled..." -ForegroundColor Green
    Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web -Force

    Write-Host "Modernizing wiki and web part pages..." -ForegroundColor Green
    # Get all the pages in the site pages library. 
    # Use paging (-PageSize parameter) to ensure the query works when there are more than 5000 items in the list
    $pages = Get-PnPListItem -List sitepages -PageSize 500

    Write-Host "Pages are fetched, let's start the modernization..." -ForegroundColor Green
    Foreach($page in $pages)
    { 
        $pageName = $page.FieldValues["FileLeafRef"]
        
        if ($page.FieldValues["ClientSideApplicationId"] -eq "b6917cb1-93a0-4b97-a84d-7cf49975d4ec" ) 
        { 
            Write-Host "Page " $page.FieldValues["FileLeafRef"] " is modern, no need to modernize it again" -ForegroundColor Yellow
        } 
        else 
        {
            Write-Host "Processing page $($pageName)" -ForegroundColor Cyan
            
            # -TakeSourcePageName:
            # The old pages will be renamed to Previous_<pagename>.aspx. If you want to 
            # keep the old page names as is then set the TakeSourcePageName to $false. 
            # You then will see the new modern page be named Migrated_<pagename>.aspx

            # -Overwrite:
            # Overwrites the target page (needed if you run the modernization multiple times)
            
            # -LogVerbose:
            # Add this switch to enable verbose logging if you want more details logged

            # KeepPageCreationModificationInformation:
            # Give the newly created page the same page author/editor/created/modified information 
            # as the original page. Remove this switch if you don't like that

            # -CopyPageMetadata:
            # Copies metadata of the original page to the created modern page. Remove this
            # switch if you don't want to copy the page metadata

            ConvertTo-PnPPage -Identity $page.FieldValues["ID"] `
                                -Overwrite `
                                -TakeSourcePageName:$TakeSourcePageName `
                                -LogType File `
                                -LogFolder $LogOutputFolder `
                                -LogSkipFlush `
                                -KeepPageCreationModificationInformation `
                                -CopyPageMetadata
        }
    }

    # Write the logs to the folder
    Write-Host "Writing the conversion log file..." -ForegroundColor Green
    Save-PnPPageConversionLog

    Write-Host "Wiki and web part page modernization complete! :)" -ForegroundColor Green
}
end
{
    Disconnect-PnPOnline
}

ConvertTo-PnPPage コマンドレットのオプション

ConvertTo-PnPPage コマンドレットは、特定のページを最新化するためのキーコマンドレットです。以下の表は、このコマンドレットでページ変換を制御するために使用できるコマンドラインパラメーターを示しています。

パラメーター	既定値	サポート対象	説明
ID (`*`)		すべてのページの種類	Wiki ページ、Web パーツページおよび発行ページ、またはクラシックブログページのブログタイトルのページ名 (例: pageA.aspx)。最初のブログページのタイトルが `Identity` で始まるクラシックブログページの場合、別の方法としてページの ID (整数値) を指定することもできます。
ライブラリ		Wiki/Web パーツのページ	ページを保持するライブラリ。 Wiki またWeb パーツページが既定の SitePages ライブラリの外にある場合は、この `-Library` パラメーターを使用します。
Folder		Wiki ページ/Web パーツページ/発行ページ	変換するページがフォルダー内にある場合、そのフォルダーを指定できます (例: `-Folder "Folder1/SubFolder"`)。
WebPartMappingFile		すべてのページの種類	ページ変換はマッピングファイルによって行われます。このコマンドレットには、既定のマッピングファイルが埋め込まれていますが、ページ変換のニーズに合わせて、カスタム Web パーツのマッピングファイル (`webpartmapping.xml`) を指定することもできます (たとえば、サードパーティのカスタム Web パーツに変換します)。この処理を実行するには、`-WebPartMappingFile` パラメーターを使用してファイルのパスを指定します。
Overwrite	$false	すべてのページの種類	`-Overwrite` を追加すると、ページ変換フレームワークは必要に応じてターゲットページを上書きします。既定では新しいページ名のプレフィックスが Migrated_ となります。つまり、Migrated_YourPage.aspx が既に存在する場合 (通常は以前のページ変換処理によって生じたもの) には上書きされます。
ReplaceHomePageWithDefault	$false	Wiki/Web パーツのページ	既定の動作は、サイトのホームページを、他の通常ページと同様にモダンページに変換することです。 `-ReplaceHomeWithDefault` を使用すると、サイトのホームページは '既定の' すぐに使用できるモダンホームページ、つまりモダンチームサイトを新たに作成した場合に得られるような状態になります。
TakeSourcePageName	$false	Wiki/Web パーツのページ	既定の動作の場合、作成されたモダンページの名前は Migrated_ というプレフィックスで始まり、元のページは既存名を保持します。 `-TakeSourcePageName` を指定すると、新しく作成されたページが元のページの名前に置き換わり、元のページの名前にはプレフィックス Previous_ が付きます。元のページを指すすべてのリンクが新しいモダンページを読み込むようになるため、このオプションは、モダンページに移行することが確実な場合に設定します。
ClearCache	$false	すべてのページの種類	パフォーマンスを最適化するため、特定のデータ (使用可能な最新の Web パーツのリスト、メタデータをコピーするためのフィールドの計算リストなど) が最初の実行後にキャッシュされます。 `-ClearCache` スイッチを使用しない限り、このキャッシュは完全な PowerShell セッション中に有効なままです。 PowerShell セッションを再起動すると、キャッシュもクリアされます。
SkipItemLevelPermissionCopyToClientSidePage	$false	すべてのページの種類	既定の項目レベルのアクセス権では、モダンページにコピーされますので、これを防ぐには、`-SkipItemLevelPermissionCopyToClientSidePage`を使用します。
CopyPageMetadata	$false	Wiki ページ/Web パーツページ/ブログページ	既定の動作では、ページのメタデータはコピーされません (したがって、サイトページライブラリに列が追加されます)。 `-CopyPageMetadata` を指定すると、変換するページのカスタムメタデータフィールドの値が、新しく作成したページにコピーされます。また、2019 年 10 月リリース時点では、クロスサイト変換でページのメタデータのコピーが機能します。
TargetWebUrl (`**`)		クロスサイト変換	変換された最新のページを別のサイトコレクションに作成する場合は、その別のサイトコレクションの URL を指定します。クロスサイトコレクション変換で変換される Web パーツについて理解するには、Web パーツの変換リストの記事を参照してください。
TargetConnection (`**`)		クロスサイト変換	Connection オブジェクトを使用して、より柔軟にターゲットを定義できます。これにより、たとえば、オンプレミスからオンラインへ変換する、テナント間変換を実行できます。
UseCommunityScriptEditor	$false	すべてのページの種類	コミュニティスクリプトエディターのインストールが完了していて変換中に使用する場合、`-UseCommunityScriptEditor` を使用してください。詳細については、Web パーツの変換リストの記事を参照してください。
SummaryLinksToHtml	$false	すべてのページの種類	QuickLinks Web パーツを使用した既定の変換の代わりに、SummaryLinks Web パーツをテキスト Web パーツでホストされる HTML に変換する場合は、`-SummaryLinksToHtml` を使用してください。詳細については、Web パーツの変換リストの記事を参照してください。
LogType	なし	すべてのページの種類	ログ記録を有効にするには `-LogType` を使用します。`File` はディスクにログを記録し、`SharePoint` は SharePoint SitePages ライブラリにログページを作成します。`Console` はコンソールにデータを出力します。
LogFolder		すべてのページの種類	`LogType` が `File` に設定されている場合は、`-LogFolder` を使用してログを作成するフォルダーを指定できます。
LogVerbose	$false	すべてのページの種類	詳細ログを生成するには、`-LogVerbose` を使用します。
LogSkipFlush	$false	すべてのページの種類	既定では、各コマンドレットの呼び出しで一意のログファイルが生成されます。ログエントリを蓄積するには、`-LogSkipFlush` パラメーターを使用します。構築されたログファイルのエントリを保持するには、LogSkipFlush を使用せずに呼び出しで終了する必要があることに注意してください。
DontPublish	$false	すべてのページの種類	作成されたモダンページを発行しないようにするには、`-DontPublish` オプションを使用します。
KeepPageCreationModificationInformation	$false	すべてのページの種類	作成者/編集者/作成済み/更新済みのページのプロパティを継承する場合は、`-KeepPageCreationModificationInformation` パラメーターを使用します。このオプションは、ソースページがモダンページの対象となる宛先と同じ SPO テナントにある場合に機能します。
PostAsNews	$false	すべてのページの種類	サイトのニュースとして作成済みのモダンページを投稿する場合は、`-PostAsNews` パラメーターを使用します。また、これは発行をスキップするよう構成されていても、ページが発行されることを意味します。
SetAuthorInPageHeader	$false	Wiki/webpart/blog ページ	作成されたページのヘッダーに作成者を追加する場合は、`-SetAuthorInPageHeader` パラメーターを使用します。作成者は (ユーザーにマップされた) ソースページの作成者に設定されます。
DisablePageComments	$false	すべてのページの種類	作成されたページでコメントオプションを無効にする場合は、`-DisablePageComments` を使用します。
PublishingPage	$false	発行ページ	発行ページを変換している場合は、`-PublishingPage` パラメーターを設定します。 Wiki ページ、Web パーツページおよびクラシックブログページの場合、このパラメーターは省略するか false に設定する必要があります。
PageLayoutMapping		発行ページ	発行ページで既定以外のページレイアウトを使用している場合は、`-PageLayoutMapping` を介して、発行ページ変換に使用するページレイアウトマッピングファイルのパスを指定できます
TargetPageName		Wiki ページ/Web パーツページ/ブログページ	`-TargetPageName` パラメーターを使用して、最新のページの既定の名前を上書きします。これは、たとえば、従来のチームサイトのホームページを最新のコミュニケーションサイトにクロスサイト変換する場合に、既存の home.aspx ページの上書きを防ぐために必要です。
PublishingTargetPageName		発行ページ	`-PublishingTargetPageName`パラメーターを使用して、最新のページの名前を上書きする
TargetPageFolder		すべてのページの種類	`-TargetPageFolder` パラメーターを使用して、モダンページのターゲットフォルダーを指定します。フォルダーが自動的に作成された場合は (たとえば、追加の wiki ページライブラリからの変換中)、このパラメーターで指定したフォルダーが自動生成されたフォルダーと結合されます(`-TargetPageFolderOverridesDefaultFolder`を指定した場合を除く)。フォルダーの入れ子構造を作成する場合は、`MyFolder` または `MyFolder/SubFolder` のようなフォルダーを指定できます。値として `<root>` を指定すると、ターゲットサイトページライブラリのルートを対象にすることができます
TargetPageFolderOverridesDefaultFolder	$false	すべてのページの種類	`-TargetPageFolderOverridesDefaultFolder` パラメーターを使用して、自動的に作成されたフォルダーがあるかどうかに関係なく、ページの変換を強制的に`-TargetPageFolder`経由で指定したフォルダーを使用することができます。
UrlMappingFile		クロスサイト変換	カスタム URL マッピング定義を含むファイルを使用すると、既定の URL マッピング以外の操作を行うことができます。詳細については、「URL マッピング」の記事を参照してください。
SkipUrlRewriting	$false	クロスサイト変換	ページ変換の発行中に、URL はターゲットサイトコレクションで有効になるように書き換えられますが、`-SkipUrlRewriting` を使用すると URL の書き換えを無効にできます。詳細については、「URL マッピング」の記事を参照してください。
SkipDefaultUrlRewriting		クロスサイト変換	カスタム URL マッピングを使用し、既定の URL 書き換えロジックを無効にしてから `-SkipDefaultUrlRewriting` パラメーターを設定する場合。
AddTableListImageAsImageWebPart	$true	すべてのページの種類	テーブル/リスト内にある画像も、そのテーブル/リストの下に個別の画像 Web パーツとして作成されます。 `-AddTableListImageAsImageWebPart` パラメーターを使用して、それらの個別の画像 Web パーツの作成を停止します。
BlogPage	$false	ブログページ	従来のブログページを変換している場合は、`-BlogPage` パラメーターを設定します。 Wiki ページ、Web パーツページおよび発行ページの場合、このパラメーターは省略するか false に設定する必要があります。
UserMappingFile		すべてのページの種類	ユーザーマッピング情報が含まれているファイル。詳細については、「ユーザーマッピング」の記事を参照してください。
LDAPConnectionString		すべてのページの種類	Active Directory にクエリを実行する LDAP 接続文字列。詳細については、「ユーザーマッピング」の記事を参照してください。
SkipUserMapping	$false	すべてのページの種類	ユーザーマッピングをスキップします。 SPO 変換では、マッピングファイルを指定しない限り、ユーザーマッピングはオフになります。このフラグが設定されている場合を除いで、オンプレミスの SharePoint ユーザーマッピングは常にオンになります。詳細については、「ユーザーマッピング」の記事を参照してください。
TermMappingFile		クロスサイト変換	カスタム用語マッピング定義を含むファイルを使用すると、既定の用語マッピング以外の操作を行うことができます。詳細については、「用語マッピング」の記事を参照してください。
SkipTermStoreMapping	$false	クロスサイト変換	ページ変換中に、ターゲットサイトコレクションで用語が有効になるようにマッピングされますが、`-SkipTermStoreMapping` パラメーターを使用すると用語マッピングを無効にできます。詳細については、「用語マッピング」の記事を参照してください。

(*) 必須のコマンドラインパラメーター/ (**) -PublishingPage または -BlogPage パラメーターが設定されている場合は必須 (-TargetWebUrl または -TargetConnection のいずれか)

FAQ

発行ページの変換方法

上に表示されているサンプルは、若干異なる構文を必要とする発行ページを変換するインプレースのページ変換を示しています。下に表示されているサンプルは、mypage.aspx ページをモダン化する方法とそのモダンバージョンをコミュニケーションサイトで作成する方法を示しています。この変換中、ページ変換は、ページが既定のページレイアウトを使用している場合に組み込みページレイアウトのマッピングを使用するか、カスタムページレイアウトにオンザフライでページレイアウトのマッピングを生成します。

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite

カスタムページレイアウトを使用している場合、使用済みページレイアウトマッピングファイルを使用する前に、そのファイルを調整することを強くお勧めします。これを行うには、次の手順を実行します。

カスタムページレイアウトのマッピングファイルを生成する

PnP PowerShell を使用して、既存のページレイアウトを分析し、マッピングファイルを生成します。

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

Export-PnPPageMapping -CustomPageLayoutMapping -Folder c:\temp

注:

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

OOB ページレイアウトのマッピングファイルを生成する場合は、AnalyzeOOBPageLayouts スイッチを指定します。

生成されたマッピングファイルをチューニングする

作成されたマッピングファイルを開き、各マッピングを確認します。

Web パーツ、Web パーツ領域および固定 Web パーツの行と列の値を正しく設定して、コンテンツがモダンページの正しい位置に表示されるようにします。必要な数の行を含めることができ、各行はモダンページ上のセクションになります。列の値は 1、2、3 に制限され、モダンページで使用可能な列のオプションに変換されます
変換する必要があるフィールドをメタデータとして定義する
Web パーツに生成されたフィールドのマッピングを確認する
ヘッダーに生成されたフィールドのマッピングを確認する

カスタムマッピングファイルを使用する

PageLayoutMapping パラメーターを介すると、クリーンアップされたカスタムマッピングファイルの使用が簡単になります。

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -PageLayoutMapping c:\temp\mypagelayouts.xml

(オンプレミス) 発行ページを SharePoint Online の最新ページに変換するためのサンプルスクリプト

始めるために https://github.com/SharePoint/sp-dev-modernization/tree/dev/Scripts/PageTransformation のスクリプトを確認してください。

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

従来のオンプレミスの公開ポータルを使用する場合には、まず、オンプレミスから SharePoint Online の従来のポータルにポータル一式を移動させてから、モダン化作業を行います。ただし、SharePoint オンプレミスポータルから従来の発行ページを直接読み取り、SharePoint Online のモダンバージョンを作成する方がしばしば簡単です。これを実行するには、以下のスクリプトで示されているように、オンプレミスポータルに接続するために SharePoint Online の PnP PowerShell を使用する必要があります:

# Setup connection the target site - must be SPO and must be a modern site
$target = Connect-PnPOnline https://contoso.sharepoint.com/sites/moderncommunicationsite -ReturnConnection

# Connect to your on-premises portal
$source = Connect-PnPOnline https://portal2013.pnp.com/sites/classicportal -TransformationOnPrem -CurrentCredentials -ReturnConnection

# Convert a classic page living in the on-premises portal to a modern page in SharePoint Online. Dependent images and videos are copied as well from on-premises to online during this process.
ConvertTo-PnPPage -Identity "page1.aspx" -PublishingPage -TargetConnection $target -LogVerbose -LogType File -LogFolder c:\temp -Connection $source

注:

この機能は、ソース環境として SharePoint 2013、2016、2019 をサポートしています。ターゲット環境は常に SharePoint Online です。 SharePoint 2010 から変換することが可能ですが、これには以前の PnP PowerShell バージョンが必要です
オンプレミスの SharePoint server と SharePoint Online 環境の両方に接続する必要があるので、SharePoint Online の PnP PowerShell バージョンを使用することが重要です。
このアプローチをテナント間でのページ変換に使用することもできます (必要な場合)。

ログ記録機能を使用する

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/portaltomodernize -Interactive

# Convert a series of pages, logs are not yet written
ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -LogSkipFlush -LogType SharePoint -LogVerbose
ConvertTo-PnPPage -PublishingPage -Identity mypage.aspx -Overwrite -TargetWebUrl https://contoso.sharepoint.com/sites/moderncommunicationsite -LogSkipFlush -LogType SharePoint -LogVerbose

# persist the log data from all previous page transformations to the defined log
Save-PnPPageConversionLog

サイトのルート (つまり、ライブラリの外) にあるページを変換する

一部の古いサイトでは、Web パーツがライブラリの外にある場合があります。モダン化する場合は、下に示すように、ページがサイトのルートにあることを -Folder "<root>" を使用して示す必要があります。

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/sitetomodernize -Interactive

ConvertTo-PnPPage -Identity pageinroot.aspx -Overwrite -Folder "<root>"

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

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

Connect-PnPOnline -Url "<your web url>" -Interactive

# Enable modern page feature
Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web

次の方法で共有

PowerShell を使用してモダンサイトページに変換する

ConvertTo-PnPPage コマンドレットのオプション

FAQ

発行ページの変換方法

カスタムページレイアウトのマッピングファイルを生成する

生成されたマッピングファイルをチューニングする

カスタムマッピングファイルを使用する

(オンプレミス) 発行ページを SharePoint Online の最新ページに変換するためのサンプルスクリプト

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

ログ記録機能を使用する

サイトのルート (つまり、ライブラリの外) にあるページを変換する

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

関連項目

その他のリソース

次の方法で共有

PowerShell を使用してモダン サイト ページに変換する

ConvertTo-PnPPage コマンドレットのオプション

FAQ

発行ページの変換方法

カスタム ページ レイアウトのマッピング ファイルを生成する

生成されたマッピング ファイルをチューニングする

カスタム マッピング ファイルを使用する

(オンプレミス) 発行ページを SharePoint Online の最新ページに変換するためのサンプル スクリプト

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

ログ記録機能を使用する

サイトのルート (つまり、ライブラリの外) にあるページを変換する

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

関連項目

その他のリソース

PowerShell を使用してモダンサイトページに変換する

カスタムページレイアウトのマッピングファイルを生成する

生成されたマッピングファイルをチューニングする

カスタムマッピングファイルを使用する

(オンプレミス) 発行ページを SharePoint Online の最新ページに変換するためのサンプルスクリプト

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

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