自動將PowerShell腳本從 AzureRM 遷移至 Az PowerShell 模組

  • 發行項

在本文中，您將瞭解如何使用 Az.Tools.Migration PowerShell 模組，將 PowerShell 腳本和腳本模組從 AzureRM 自動升級至 Az PowerShell 模組。 如需其他移轉選項，請參閱 將 Azure PowerShell 從 AzureRM 遷移至 Az。

警告

自 2024 年 2 月 29 日起，AzureRM PowerShell 模組已正式淘汰。 建議使用者從 AzureRM 遷移至 Az PowerShell 模組，以確保持續支援和更新。

雖然 AzureRM 模組可能仍可運作，但不再維護或支援它，但會根據用戶的判斷權和風險放置任何繼續使用。 如需轉換至 Az 模組的指引，請參閱我們的 移轉資源 。

需求

步驟 1：產生升級計劃

您可以使用 New-AzUpgradeModulePlan Cmdlet 來產生將腳本和模組移轉至 Az PowerShell 模組的升級計劃。 此 Cmdlet 不會對現有的腳本進行任何變更。 FilePath使用 參數以特定文本為目標，或DirectoryPath將特定資料夾中的所有腳本設為目標的參數。

注意

Cmdlet 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 Cmdlet 時需要變更的特定檔案和位移點。

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 Cmdlet 執行升級。 指定 SaveChangesToNewFilesFileEditMode 參數值，以防止對原始腳本進行變更。 使用此模式時，會藉由建立每個以附加至檔名為目標 _az_upgraded 的腳本複本來執行升級。

警告

指定 選項時-FileEditMode ModifyExistingFiles，Cmdlet Invoke-AzUpgradeModulePlan 會具有破壞性！ 它會根據 Cmdlet 所產生的 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 Cmdlet。

如何回報問題

透過存放庫中的 GitHub 問題，回報 Az.Tools.Migration PowerShell 模組的相關意見反應和問題azure-powershell-migration。

下一步

若要深入瞭解 Az PowerShell 模組，請參閱 Azure PowerShell 檔