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

2025-06-05

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

Warnung

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 パラメーターを使用します。

注

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 コマンドレットを使用してアップグレードが実行されます。 SaveChangesToNewFiles パラメーター値のFileEditModeを指定して、元のスクリプトに変更が加えられるのを防ぎます。このモードを使用する場合、アップグレードは、ファイル名に追加された _az_upgraded を対象とする各スクリプトのコピーを作成することによって実行されます。

Warnung

Invoke-AzUpgradeModulePlan オプションが指定されている場合、-FileEditMode ModifyExistingFiles コマンドレットは破壊的です。 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 コマンドレットは検出されません。

問題を報告する方法

リポジトリの azure-powershell-migrationを使用して、Az.Tools.Migration PowerShell モジュールに関するフィードバックと問題を報告します。

次のステップ

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