通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

自动将 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 cmdlet 生成升级计划，以将脚本和模块迁移到 Az PowerShell 模块。 此 cmdlet 不会对现有脚本进行任何更改。 使用 FilePath 参数，以特定脚本为目标；或使用 DirectoryPath 参数，以特定文件夹中的所有脚本为目标。

注意

New-AzUpgradeModulePlan cmdlet 不会执行该计划，它只会生成升级步骤。

下面的示例为 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 来执行升级。 指定 SaveChangesToNewFiles 作为 FileEditMode 参数值，以防止对原始脚本进行更改。 使用此模式时，将通过创建每个目标脚本的副本的来执行升级，并向文件名追加 _az_upgraded。

警告

如果指定了 -FileEditMode ModifyExistingFiles 选项，则 Invoke-AzUpgradeModulePlan cmdlet 具有破坏性！ 它会根据 New-AzUpgradeModulePlan cmdlet 生成的模块升级计划就地修改脚本和函数。 若要获取非破坏性选项，请改为指定 -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。

如何报告问题

在 azure-powershell-migration 存储库通过 a GitHub 问题报告有关 Az.Tools.Migration PowerShell 模块的反馈和问题。

后续步骤

要详细了解 Az PowerShell 模块，请参阅 Azure PowerShell 文档