您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

将 Azure PowerShell 从 AzureRM 迁移到 AzMigrate Azure PowerShell from AzureRM to Az

Az 模块与 AzureRM 具有功能奇偶一致性,但 Az 模块使用更短且更一致的 cmdlet 名称。The Az module has feature parity with AzureRM, but uses shorter and more consistent cmdlet names. 为 AzureRM cmdlet 编写的脚本不会自动与新模块配合工作。Scripts written for the AzureRM cmdlets won't automatically work with the new module. 为了简化转换,Az 提供了工具,以便你可以使用 AzureRM 运行现有的脚本。To make the transition easier, Az offers tools to allow you to run your existing scripts using AzureRM. 不迁移到新的命令集十分省事,但本文将帮助你开始转换到新的模块。No migration to a new command set is ever convenient, but this article will help you get started on transitioning to the new module.

若要查看从 AzureRM 到 Az 的中断性变更的完整列表,请参阅从 AzureRM 到 Az 的全部变更To see the full list of breaking changes between AzureRM and Az, see the full changes from AzureRM to Az.

确保现有脚本兼容最新的 AzureRM 版本Ensure existing scripts work with the latest AzureRM release

在执行任何迁移步骤之前,请检查系统上安装了 AzureRM 的哪些版本。Before taking any migration steps, check which versions of AzureRM are installed on your system. 这样做可以确保脚本已在最新版本上运行,并了解哪些 AzureRM 版本必须卸载。Doing so allows you to make sure scripts are already running on the latest release, and let you know which versions of AzureRM must be uninstalled.

若要检查已安装了 AzureRM 的哪个(些)版本,请运行以下命令:To check which version(s) of AzureRM you have installed, run the command:

Get-InstalledModule -Name AzureRM -AllVersions

AzureRM 的__最新__发布版本为 6.13.1The latest available release of AzureRM is 6.13.1. 如果尚未安装此版本,则除了本文以及中断性变更列表中描述的内容,现有脚本可能还需要进行其他的修改,否则无法使用 Az 模块。If you don't have this version installed, your existing scripts may need additional modification to work with the Az module beyond what's described here and in the breaking changes list.

如果脚本不兼容 AzureRM 6.13.1,请按照 AzureRM 5.x 到 6.x 迁移指南中的说明对其进行更新。If your scripts don't work with AzureRM 6.13.1, update them according to the AzureRM 5.x to 6.x migration guide. 如果使用更低版本的 AzureRM 模块,请参阅每个主要版本的迁移指南。If you use an earlier version of the AzureRM module, there are migration guides available for each major version.

卸载 AzureRMUninstall AzureRM

不能保证 Az 模块兼容 Windows 版 PowerShell 5.1 中任何现有的 AzureRM 安装。The Az module is not guaranteed to be compatible with any existing AzureRM installs in PowerShell 5.1 for Windows. 在安装 Az 模块之前,请卸载 AzureRMBefore you install the Az module, uninstall AzureRM.

重要

如果尚未做好从系统中删除 AzureRM 模块的准备,可以改为安装适用于 PowerShell Core 6.x 或更高版本的 Az 模块。If you're not ready to remove the AzureRM module from your system, you can install the Az module for PowerShell Core 6.x or later instead. PowerShell Core 和 Windows 版 PowerShell 5.1 使用不同的模块库,因此不会有冲突。PowerShell Core and PowerShell 5.1 for Windows use different module libraries, so there will be no conflicts. 仍然可以在 PowerShell Core 中启用别名You can still enable aliases in PowerShell Core.

安装 Azure Powershell Az 模块Install the Azure PowerShell Az module

第一步是在平台上安装 Az 模块。The first step is to install the Az module on your platform. 安装 Az 时,建议卸载 AzureRM。When you install Az, it's recommended that you uninstall AzureRM. 以下步骤将介绍如何继续运行现有脚本并为旧 cmdlet 名称启用兼容性。In the following steps, you'll learn how to keep running your existing scripts and enable compatibility for old cmdlet names.

若要安装 Azure PowerShell Az 模块,请按安装 Az 模块中的说明操作。To install the Azure PowerShell Az module, follow the instructions in Install the Az module.

备注

此时可能需要运行 Az 模块中提供的 Uninstall-AzureRM cmdlet,只是为了确保所有版本的 AzureRM 都已卸载,不会造成冲突。At this point, you might want to run the Uninstall-AzureRM cmdlet provided in the Az module, just to make sure that all versions of AzureRM have been uninstalled and won't cause conflicts.

启用 AzureRM 兼容性别名Enable AzureRM compatibility aliases

卸载 AzureRM 并且脚本可以与最新的 AzureRM 版本配合工作后,下一步骤是为 Az 模块启用兼容模式。With AzureRM uninstalled and your scripts working with the latest AzureRM version, the next step is to enable the compatibility mode for the Az module. 使用以下命令启用兼容性:Compatibility is enabled with the command:

Enable-AzureRmAlias -Scope CurrentUser

在安装了 Az 模块的情况下,通过别名可以使用旧 cmdlet 名称。Aliases enable the ability to use old cmdlet names with the Az module installed. 这些别名会写入到所选范围的配置文件。These aliases are written to the profile for the selected scope. 如果不存在配置文件,则会创建一个。If no profile exists, one is created. 当使用的 -Scope 超出 CurrentUser 时,必须拥有适当的权限才能创建或更新相应的配置文件。When using a -Scope broader than CurrentUser, the appropriate permissions are required to create or update the corresponding profile file.

重要

cmdlet 名称需要使用别名,模块名称不需要!Only cmdlet names are aliased - module names aren't! 如果使用 #RequiresImport-Module,或者使用 .psd1 中的依赖项列表,或者使用完全限定的 cmdlet 名称,此时务必按照有关模块名称的中断性变更列表中概述的过程对其进行迁移。If you're using #Requires, Import-Module, dependency lists in a .psd1, or fully-qualified cmdlet names, make sure that you migrate them at this point by following the process outlined in the breaking changes list regarding module names.

警告

可以为此命令使用其他 -Scope,但不建议这样做。You can use a different -Scope for this command, but it's not recommended. 别名会写入到所选范围的用户配置文件,因此请保持将其启用到尽可能有限的范围。Aliases are written to the user profile for the selected scope, so keep enabling them to as limited a scope as possible. 在系统范围启用别名可能会导致在本地范围安装 AzureRM 的其他用户出现问题。Enabling aliases system-wide can cause issues for other users who have AzureRM installed in their local scope.

启用别名模式后,请再次运行脚本以确认它们仍然正常运行。Once the alias mode is enabled, run your scripts again to confirm that they still function as expected. Az 模块已更改或添加了某些参数名称,或者已将其设置为必需。Some parameter names have been changed, added, or made required by the Az module. cmdlet 的输出类型可能也已更改。Output types of cmdlets may have changed as well. 这些更改详见中断性变更列表These changes are detailed in the breaking changes list.

更新 cmdlet、模块和参数Update cmdlets, modules, and parameters

等脚本完成更新并在别名下运行以后,即可抽时间更新这些项,以便使用新 cmdlet 并充分利用其他变更,例如新功能。With scripts updated and running under aliases, you can take your time to update them to use the new cmdlets and take advantage of other changes like new features. 对于大多数脚本,只需遵循 Az 中的新 cmdlet 命名方案更新 cmdlet 名称即可。For most scripts, you will only need to update cmdlet names, following the new cmdlet naming scheme in Az. 可能还需要进行一些其他的更改才能使用脚本,具体取决于脚本的功能以及脚本所使用的 Azure PowerShell 功能。There may also be some other changes that you need to make in order to have your scripts work, depending on what they do and which Azure PowerShell features they take advantage of.

例如,Blob 存储 cmdlet 在进行彻底修改后需要使用新的异步模型,因此使用它们的脚本在进行更新时,所耗费的工作就要多于那些仅对 cmdlet 名称进行了相关更改的脚本。For example, the Blob Storage cmdlets have been completely reworked to use a new asynchronous model, so scripts using them will take more work to update than those where the only relevant changes were cmdlet names.

即使你到现在为止只需对脚本进行小的、简单的更改,或者在启用别名的情况下不需对脚本进行其他修改,也请阅读 Az 1.0.0 中的中断性变更的完整列表,确保不会依赖别名的“透明”行为,该行为在你更改 cmdlet 名称并禁用别名后可能会消失。Even if you've only had to make small, simple changes to your scripts up to this point - or they even work without additional modification when aliases are enabled - read the full list of breaking changes in Az 1.0.0 to make sure that you're not relying on 'transparent' behavior of aliases which could disappear after you change cmdlet names and disable aliases.

禁用别名Disable aliases

完成迁移且不再依赖别名行为以后,建议禁用别名。Once you've completed your migration and are no longer relying on aliasing behavior, it's recommended that you disable aliases. 请通过 Disable-AzureRmAlias cmdlet 完成该操作。This is done with the Disable-AzureRmAlias cmdlet.

重要

运行此 cmdlet 时,请__确保__针对每个 -Scope(已为其调用 Enable-AzureRmAlias)调用它,否则,系统中仍然会有脚本依赖此别名行为。When running this cmdlet, make sure that you invoke it for each -Scope that Enable-AzureRmAlias was invoked for, otherwise there may still be scripts on your system relying on the aliasing behavior.