次の方法で共有

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

  • [アーティクル]

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

警告

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 コマンドレットを使用してアップグレードが実行されます。 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 のドキュメントを参照してください