AzureRM から Az PowerShell モジュールに PowerShell スクリプトを自動的に移行する

  • [アーティクル]

この記事では、Az.Migration PowerShell モジュールを使用して、PowerShell スクリプトとスクリプト モジュールを AzureRM から Az PowerShell モジュールに自動的にアップグレードする方法について説明します。 その他の移行オプションについては、「AzureRM から Az への Azure PowerShell の移行」をご覧ください。

警告

AzureRM PowerShell モジュールは、2024 年 2 月 29 日に正式に非推奨になりました。 引き続きサポートを受け、更新を受け取れるようにするために、AzureRM から Az PowerShell モジュールに移行することをお勧めします。

AzureRM モジュールの機能は今後も使用できますが、メンテナンスやサポートは行われないため、引き続きの使用はユーザーの判断に委ねられ、リスクが発生することがあります。 Az モジュールへの移行に関するガイダンスについては、移行リソースを参照してください。

要件

  • 既存の PowerShell スクリプトを最新バージョンの AzureRM PowerShell モジュール (6.13.1) に更新します。

  • Az.Tools.Migration PowerShell モジュールをインストールします。

    Install-Module -Name Az.Tools.Migration

手順 1:アップグレード プランの生成

New-AzUpgradeModulePlan コマンドレットを使用して、Az PowerShell モジュールにスクリプトとモジュールを移行するためのアップグレード プランを生成します。 このコマンドレットによって、既存のスクリプトに変更が加えられることはありません。 特定のスクリプトを対象にする場合は FilePath パラメーターを使用し、特定のフォルダー内にあるすべてのスクリプトを対象にする場合は DirectoryPath パラメーターを使用します。

Note

New-AzUpgradeModulePlan コマンドレットでは、プランは実行されません。アップグレード手順のみが生成されます。

次の例では、 C:\Scripts フォルダー内のすべてのスクリプトに対するプランを生成します。 OutVariable パラメーターが指定されているので、結果が返され、それと同時に Plan という名前の変数に格納されます。

# Generate an upgrade plan for all the scripts and module files in the specified folder and save it to a variable.
New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts' -OutVariable Plan

次の出力に示されているとおり、アップグレード プランには、AzureRM から Az PowerShell コマンドレットに移行するときに変更が必要となる特定のファイルとオフセット ポイントの詳細が記載されています。

Order Location                                                   UpgradeType     PlanResult             Original
----- --------                                                   -----------     ----------             --------
1     compute-create-dockerhost.ps1:59:24                        CmdletParameter ReadyToUpgrade         ExtensionName
2     compute-create-dockerhost.ps1:59:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
3     compute-create-dockerhost.ps1:54:1                         Cmdlet          ReadyToUpgrade         New-AzureRmVM
4     compute-create-dockerhost.ps1:51:1                         Cmdlet          ReadyToUpgrade         Add-AzureRmVM...
5     compute-create-dockerhost.ps1:47:1                         Cmdlet          ReadyToUpgrade         Add-AzureRmVM...
6     compute-create-dockerhost.ps1:46:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
7     compute-create-dockerhost.ps1:45:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
8     compute-create-dockerhost.ps1:44:13                        Cmdlet          ReadyToUpgrade         New-AzureRmVM...
9     compute-create-dockerhost.ps1:40:8                         Cmdlet          ReadyToUpgrade         New-AzureRmNe...
10    compute-create-dockerhost.ps1:36:8                         Cmdlet          ReadyToUpgrade         New-AzureRmNe...
11    compute-create-dockerhost.ps1:31:16                        Cmdlet          ReadyToUpgrade         New-AzureRmNe...
12    compute-create-dockerhost.ps1:26:15                        Cmdlet          ReadyToUpgrade         New-AzureRmNe...
13    compute-create-dockerhost.ps1:22:8                         Cmdlet          ReadyToUpgrade         New-AzureRmPu...
14    compute-create-dockerhost.ps1:18:9                         Cmdlet          ReadyToUpgrade         New-AzureRmVi...
15    compute-create-dockerhost.ps1:15:17                        Cmdlet          ReadyToUpgrade         New-AzureRmVi...
16    compute-create-dockerhost.ps1:12:1                         Cmdlet          ReadyToUpgrade         New-AzureRmRe...
17    compute-create-windowsvm-quick.ps1:18:3                    CmdletParameter ReadyToUpgrade         ImageName
18    compute-create-windowsvm-quick.ps1:14:1                    Cmdlet          ReadyToUpgrade         New-AzureRmVM
19    compute-create-windowsvm-quick.ps1:11:1                    Cmdlet          ReadyToUpgrade         New-AzureRmRe...
20    compute-create-wordpress-mysql.ps1:59:24                   CmdletParameter ReadyToUpgrade         ExtensionName
...

アップグレードを実行する前に、プランの結果を表示して問題を確認する必要があります。 次の例では、スクリプトの一覧と、その中に含まれていてスクリプトを自動的にアップグレードできない原因となっている項目が返されます。

# Filter plan results to only warnings and errors
$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List

次の出力に示された項目は、まず問題を手動で修正しなければ、自動的にはアップグレードされません。

Order                  : 42
UpgradeType            : CmdletParameter
PlanResult             : ErrorParameterNotFound
PlanSeverity           : Error
PlanResultReason       : Parameter was not found in Get-AzResource or it's aliases.
SourceCommand          : CommandReference
SourceCommandParameter : CommandReferenceParameter
Location               : devtestlab-add-marketplace-image-to-lab.ps1:14:74
FullPath               : C:\Scripts\devtestlab-add-marketplace-image-to-lab.ps1
StartOffset            : 556
Original               : ResourceNameEquals
Replacement            :

手順 2:アップグレードを実行する

注意事項

元に戻す操作はありません。 アップグレードしようとしている PowerShell スクリプトとモジュールのバックアップ コピーがあることを必ず確認してください。

プランに問題がなければ、 Invoke-AzUpgradeModulePlan コマンドレットを使用してアップグレードを実行します。 元のスクリプトに変更を加えないようにするには、 FileEditMode パラメーター値に対して SaveChangesToNewFiles を指定します。 このモードを使用すると、対象となる各スクリプトのファイル名に _az_upgraded を付加したコピーを作成して、アップグレードが実行されます。

警告

-FileEditMode ModifyExistingFiles オプションが指定されている場合、Invoke-AzUpgradeModulePlan コマンドレットは破壊的です。 スクリプトと関数は、New-AzUpgradeModulePlan コマンドレットによって生成されたモジュール アップグレード プランに従ってインプレースで変更されます。 非破壊的オプションの場合は、代わりに -FileEditMode SaveChangesToNewFiles を指定します。

# Execute the automatic upgrade plan and save the results to a variable.
Invoke-AzUpgradeModulePlan -Plan $Plan -FileEditMode SaveChangesToNewFiles -OutVariable Results

Order Location                                                   UpgradeType     UpgradeResult    Original
----- --------                                                   -----------     -------------    --------
1     compute-create-dockerhost.ps1:59:24                        CmdletParameter UpgradeCompleted ExtensionName
2     compute-create-dockerhost.ps1:59:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMExtens...
3     compute-create-dockerhost.ps1:54:1                         Cmdlet          UpgradeCompleted New-AzureRmVM
4     compute-create-dockerhost.ps1:51:1                         Cmdlet          UpgradeCompleted Add-AzureRmVMSshPub...
5     compute-create-dockerhost.ps1:47:1                         Cmdlet          UpgradeCompleted Add-AzureRmVMNetwor...
6     compute-create-dockerhost.ps1:46:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMSource...
7     compute-create-dockerhost.ps1:45:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMOperat...
8     compute-create-dockerhost.ps1:44:13                        Cmdlet          UpgradeCompleted New-AzureRmVMConfig
9     compute-create-dockerhost.ps1:40:8                         Cmdlet          UpgradeCompleted New-AzureRmNetworkI...
10    compute-create-dockerhost.ps1:36:8                         Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
11    compute-create-dockerhost.ps1:31:16                        Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
12    compute-create-dockerhost.ps1:26:15                        Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
13    compute-create-dockerhost.ps1:22:8                         Cmdlet          UpgradeCompleted New-AzureRmPublicIp...
14    compute-create-dockerhost.ps1:18:9                         Cmdlet          UpgradeCompleted New-AzureRmVirtualN...
15    compute-create-dockerhost.ps1:15:17                        Cmdlet          UpgradeCompleted New-AzureRmVirtualN...
16    compute-create-dockerhost.ps1:12:1                         Cmdlet          UpgradeCompleted New-AzureRmResource...
17    compute-create-windowsvm-quick.ps1:18:3                    CmdletParameter UpgradeCompleted ImageName
18    compute-create-windowsvm-quick.ps1:14:1                    Cmdlet          UpgradeCompleted New-AzureRmVM
19    compute-create-windowsvm-quick.ps1:11:1                    Cmdlet          UpgradeCompleted New-AzureRmResource...
20    compute-create-wordpress-mysql.ps1:59:24                   CmdletParameter UpgradeCompleted ExtensionName
...

エラーが返された場合は、次のコマンドを使用して、エラーの結果を詳しく調べることができます。

# Filter results to show only errors
$Results | Where-Object UpgradeResult -ne UpgradeCompleted | Format-List

Order                  : 42
UpgradeType            : CmdletParameter
UpgradeResult          : UnableToUpgrade
UpgradeSeverity        : Error
UpgradeResultReason    : Parameter was not found in Get-AzResource or it's aliases.
SourceCommand          : CommandReference
SourceCommandParameter : CommandReferenceParameter
Location               : devtestlab-add-marketplace-image-to-lab.ps1:14:74
FullPath               : C:\Scripts\devtestlab-add-marketplace-image-to-lab.ps1
StartOffset            : 556
Original               : ResourceNameEquals
Replacement            :

制限事項

  • ファイル I/O 操作では、既定のエンコードが使用されます。 通常とは異なるファイル エンコードの場合は、問題が発生する可能性があります。
  • Pester 単体テストのモック ステートメントに引数として渡される AzureRM コマンドレットは、検出されません。

問題を報告する方法

Az.Migration PowerShell モジュールに関するフィードバックと問題については、azure-powershell-migration リポジトリで GitHub の問題を通じて報告してください。

次のステップ

Az PowerShell モジュールの詳細については、Azure PowerShell のドキュメントをご覧ください。