通过

你当前正在访问 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。

警告

截至 2024 年 2 月 29 日，AzureRM PowerShell 模块已正式弃用。 建议用户从 AzureRM 迁移到 Az PowerShell 模块，以确保持续支持和更新。

尽管 AzureRM 模块仍然可能正常运行，但它已不再维护或提供支持，继续使用将由用户自行决定并承担风险。 有关过渡到 Az 模块的指导，请参阅我们的迁移资源。

要求

步骤 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。

警告

如果指定了 Invoke-AzUpgradeModulePlan 选项，则 -FileEditMode ModifyExistingFiles 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 未被检测到。

如何报告问题

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

后续步骤

若要了解有关 Az PowerShell 模块的详细信息，请参阅 Azure PowerShell 文档