从 AzureRM 迁移到 Azure Stack Hub 中的 Azure PowerShell Az

项目
03/12/2025

Az 模块在功能上与 AzureRM 对等，但使用的 cmdlet 名称更短且更统一。为 AzureRM cmdlet 编写的脚本不会自动处理新模块。为了简化转换，Az 提供了工具，使你能够使用 AzureRM 运行现有脚本。迁移到新的命令集从来都不方便，但本文将帮助你开始过渡到新模块。

若要查看 AzureRM 和 Az 之间的重大更改的完整列表，请参阅 Az 1.0.0 迁移指南

检查已安装的 AzureRM 版本

在执行任何迁移步骤之前，请检查系统上安装了哪些版本的 AzureRM。这样做可以确保脚本已在最新版本上运行，并告知是否可以在不卸载 AzureRM 的情况下启用命令别名。

若要检查已安装的 AzureRM 版本，请运行以下命令：

Get-InstalledModule -Name AzureRM -AllVersions

检查当前脚本是否适用于 AzureRM

这是最重要的步骤！运行现有脚本，并确保这些脚本适用于最新版本的 AzureRM (2.5.0)。如果脚本不起作用，请确保阅读 AzureRM 迁移指南。

安装 Azure PowerShell Az 模块

第一步是在平台上安装 Az 模块。安装 Az 时，建议卸载 AzureRM。在以下步骤中，你将了解如何继续运行现有脚本，并为旧的 cmdlet 名称启用兼容性。

若要安装 Azure PowerShell Az 模块，请执行以下步骤：

推荐：卸载 AzureRM 模块。请确保删除所有已安装的 AzureRM 版本，不只是最新版本。
安装 Az 模块

启用 AzureRM 兼容性别名

重要

只有已卸载了 AzureRM 的所有版本时，才应启用兼容模式。在 AzureRM cmdlet 仍然可用时启用兼容模式可能会导致不可预知的行为。如果决定保留 AzureRM 安装，请跳过此步骤，但请注意，任何 AzureRM cmdlet 都将使用旧模块，而不调用任何 Az cmdlet。

卸载 AzureRM 后，脚本使用最新的 AzureRM 版本，下一步是启用 Az 模块的兼容性模式。使用以下命令启用兼容性：

Enable-AzureRmAlias -Scope CurrentUser

在安装了 Az 模块的情况下，通过别名可以使用旧 cmdlet 名称。这些别名将被记录到所选择的范围的用户配置文件中。如果不存在用户配置文件，则会创建一个。

警告

可以对此命令使用不同的 -Scope，但不建议这样做。别名会写入到所选范围的用户配置文件，因此请保持将其启用到尽可能有限的范围。启用全局别名也可能导致对本地范围内安装了 AzureRM 的其他用户出现问题。

启用别名模式后，再次运行脚本以确认它们仍然按预期工作。

更改模块和 cmdlet 名称

通常，模块名称已更改，以便 AzureRM 和 Azure 变为 Az，并且 cmdlet 也是如此。例如，AzureRM.Compute 模块已重命名为 Az.Compute。 New-AzureRMVM 已成为 New-AzVM，Get-AzureStorageBlob 现在 Get-AzStorageBlob。

应注意的此命名更改存在例外情况。某些模块已重命名或合并到现有模块中，除了将 AzureRM 或 Azure 更改为 Az外，这不会影响其 cmdlet 的后缀。其他情况下，完整的 cmdlet 后缀已更改，以反映新的模块名称。

AzureRM 模块	Az 模块	Cmdlet 后缀已更改？
AzureRM.Profile	Az.Accounts	是的
AzureRM.Insights	Az.Monitor	是的
AzureRM.Tags	Az.Resources	不
AzureRM.UsageAggregates	Az.Billing	不
AzureRM.Consumption	Az.Billing	不

总结

按照以下步骤操作，可以更新所有现有脚本以使用新模块。如果您在这些步骤中遇到任何使您的迁移变得困难的疑问或问题，请对本文发表评论，以便我们可以改进说明。

Az 1.0.0 的重大更改

本文档提供有关 AzureRM 6.x 与新 Az 模块版本 1.x 及更高版本之间的更改的详细信息。可以通过目录了解完整的迁移路径，包括特定于模块的可能会影响脚本的变更。

常规重大更改

此部分详述在重新设计 Az 模块过程中所做的常规中断性变更。

Cmdlet 名词前缀更改

在 AzureRM 模块中，cmdlet 使用 AzureRM 或 Azure 作为名词前缀。 Az 简化了 cmdlet 名称并规范化，以便所有 cmdlet 都使用“Az”作为其 cmdlet 名词前缀。例如：

Get-AzureRMVM
Get-AzureKeyVaultSecret

已更改为：

Get-AzVM
Get-AzKeyVaultSecret

为了简化对这些新 cmdlet 名称的转换，Az 引入了两个新的 cmdlet，Enable-AzureRmAlias，Disable-AzureRmAlias。 Enable-AzureRmAlias 为 AzureRM 中较旧的 cmdlet 名称创建别名，这些名称映射到较新的 Az cmdlet 名称。将 -Scope 参数与 Enable-AzureRmAlias 结合使用，可以选择启用别名的位置。

例如，AzureRM 中的以下脚本：

#Requires -Modules AzureRM.Storage
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

可以通过使用 Enable-AzureRmAlias 进行最少的更改来运行：

#Requires -Modules Az.Storage
Enable-AzureRmAlias -Scope Process
Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

运行 Enable-AzureRmAlias -Scope CurrentUser 将启用打开的所有 PowerShell 会话的别名，以便在执行此 cmdlet 之后，无需更改如下所示的脚本：

Get-AzureRmStorageAccount | Get-AzureStorageContainer | Get-AzureStorageBlob

若要获得有关别名 cmdlet 用法的完整详细信息，请查看 Enable-AzureRmAlias 参考。

准备好禁用别名时，Disable-AzureRmAlias 删除创建的别名。有关完整详细信息，请参阅 Disable-AzureRmAlias 参考。

重要

禁用别名时，请确保在启用了别名的所有范围内禁用别名。

模块名称更改

模块名称已从 AzureRM.* 更改为 Az.*，但以下模块除外：

AzureRM 模块	Az 模块
Azure.Storage	Az.Storage
Azure.AnalysisServices	Az.AnalysisServices
AzureRM.Profile	Az.Accounts
AzureRM.Insights	Az.Monitor
AzureRM.RecoveryServices.Backup	Az.RecoveryServices
AzureRM.RecoveryServices.SiteRecovery	Az.RecoveryServices
AzureRM.Tags	Az.Resources
AzureRM.MachineLearningCompute	Az.MachineLearning
AzureRM.UsageAggregates	Az.Billing
AzureRM.Consumption	Az.Billing

模块名称中的更改意味着需要更改使用 #Requires 或 Import-Module 加载特定模块的任何脚本，才能改用新模块。对于其中的 cmdlet 后缀尚未更改的模块，这意味着，虽然模块名称已更改，但指示操作空间的后缀尚未更改。

迁移 requires 和 import module 语句

必须更新那些使用 #Requires 或 Import-Module 声明对 AzureRM 模块依赖的脚本，以便使用新的模块名称。例如：

#Requires -Module AzureRM.Compute

应更改为：

#Requires -Module Az.Compute

对于 Import-Module：

Import-Module -Name AzureRM.Compute

应更改为：

Import-Module -Name Az.Compute

迁移完全限定的 cmdlet 调用

使用模块限定的 cmdlet 调用的脚本，例如：

AzureRM.Compute\Get-AzureRmVM

必须更改以使用新的模块和命令行小程序名称：

Az.Compute\Get-AzVM

迁移模块清单依赖关系

通过模块清单（.psd1）文件表达对 AzureRM 模块的依赖项的模块将需要在其 RequiredModules 部分中更新模块名称：

RequiredModules = @(@{ModuleName="AzureRM.Profile"; ModuleVersion="5.8.2"})

必须更改为：

RequiredModules = @(@{ModuleName="Az.Accounts"; ModuleVersion="1.0.0"})

已删除的模块

已删除以下模块：

AzureRM.Backup
AzureRM.Compute.ManagedService
AzureRM.Scheduler

这些服务所用的工具不再受到主动支持。建议客户在方便后立即迁移到替代服务。

Windows PowerShell 5.1 和 .NET 4.7.2

将 Az 与 PowerShell 5.1 for Windows 配合使用需要安装 .NET Framework 4.7.2。使用 PowerShell Core 6.x 或更高版本不需要 .NET Framework。

由于 .NET Standard 的身份验证流发生更改，我们暂时通过 PSCredential 删除用户登录名。此功能将在 2019 年 1 月 15 日版本的 PowerShell 5.1 for Windows 中重新引入。此 GitHub 问题中详细讨论了这方面的内容。

由于 .NET Standard 的身份验证流发生更改，我们在交互式登录期间使用设备登录作为默认登录流。对于 Windows 的 PowerShell 5.1，基于网络浏览器的登录将在 2019 年 1 月 15 日发布的版本中重新引入，并作为默认方式。届时，用户将能够使用切换参数选择设备登录。

模块中断性变更

此部分详述单个模块和 cmdlet 的具体中断性变更。

Az.ApiManagement （以前为 AzureRM.ApiManagement）

删除了以下 cmdlet：
- New-AzureRmApiManagementHostnameConfiguration
- Set-AzureRmApiManagementHostnames
- Update-AzureRmApiManagementDeployment
- Import-AzureRmApiManagementHostnameCertificate
- 改用 Set-AzApiManagement cmdlet 设置这些属性
删除了以下属性：
- 从 PsApiManagementContext中删除了类型 PsApiManagementHostnameConfiguration 的属性 PortalHostnameConfiguration、ProxyHostnameConfiguration、ManagementHostnameConfiguration 和 ScmHostnameConfiguration。请改用 PsApiManagementCustomHostNameConfiguration 类型的 PortalCustomHostnameConfiguration、ProxyCustomHostnameConfiguration、ManagementCustomHostnameConfiguration 和 ScmCustomHostnameConfiguration。
- 从 PsApiManagementContext 中删除了属性 StaticIPs。该属性已拆分为 PublicIPAddresses 和 PrivateIPAddresses。
- 从 New-AzureApiManagementVirtualNetwork cmdlet 中删除了所需的属性 Location。

Az.Billing（以前是 AzureRM.Billing、AzureRM.Consumption 和 AzureRM.UsageAggregates）

InvoiceName 参数已从 Get-AzConsumptionUsageDetail cmdlet 中删除。脚本需要使用发票的其他标识参数。

Az.Compute （以前为 AzureRM.Compute）

IdentityIds 从 Identity 属性中删除，该属性属于 PSVirtualMachine 和 PSVirtualMachineScaleSet 对象，脚本不应再使用此字段的值来做出处理决策。
PSVirtualMachineScaleSetVM 对象的 InstanceView 属性的类型从 VirtualMachineInstanceView 更改为 VirtualMachineScaleSetVMInstanceView
从 UpgradePolicy 属性中删除了 AutoOSUpgradePolicy 和 AutomaticOSUpgrade 属性
PSSnapshotUpdate 对象中 Sku 属性的类型从 DiskSku 更改为 SnapshotSku
VmScaleSetVMParameterSet 从 Add-AzVMDataDisk cmdlet 中删除，无法再单独向 ScaleSet VM 添加数据磁盘。

Az.KeyVault （以前为 AzureRM.KeyVault）

PurgeDisabled 属性已从 PSKeyVaultKeyAttributes、PSKeyVaultKeyIdentityItem和 PSKeyVaultSecretAttributes 对象中删除，脚本不应再引用 PurgeDisabled 属性来做出处理决策。

Az.Monitor （以前为 AzureRM.Insights）

从 Set-AzDiagnosticSetting cmdlet 中删除了复数名称 Categories 和 Timegrains 参数并将其替换为单数参数名称。使用以下内容的脚本
```
Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2
```
应更改为
```
Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2
```

Az.Network （以前为 AzureRM.Network）

从 Get-AzServiceEndpointPolicyDefinition cmdlet 中删除了弃用的 ResourceId 参数
从 PSVirtualNetwork 对象中删除了弃用的 EnableVmProtection 属性
删除了弃用的 Set-AzVirtualNetworkGatewayVpnClientConfig cmdlet

脚本不应再根据这些字段的值做出处理决策。

Az.Resources （以前为 AzureRM.Resources）

从 New/Set-AzPolicyAssignment cmdlet 中删除了 Sku 参数

从 New-AzADServicePrincipal 和 New-AzADSpCredential cmdlet 中删除了 Password 参数。密码将自动生成，提供了密码的脚本：

New-AzAdSpCredential -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb -Password $secPassword

应更改以从输出中检索密码：

$credential = New-AzAdSpCredential -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
$secPassword = $credential.Secret

Az.Storage（以前是 Azure.Storage 和 AzureRM.Storage）

为了支持创建仅包含存储帐户名称的 Oauth 存储上下文，默认参数集已更改为 OAuthParameterSet
- 示例：$ctx = New-AzureStorageContext -StorageAccountName $accountName
Location 参数在 Get-AzStorageUsage cmdlet 中变为必需参数
存储 API 方法现在使用基于任务的异步模式（TAP），而不是同步 API 调用。以下示例演示了新的异步命令：

Blob 快照

AzureRM：

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$b.ICloudBlob.Snapshot()

Az：

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -Context $ctx
$task = $b.ICloudBlob.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

AzureRM：

$Share = Get-AzureStorageShare -Name $containerName -Context $ctx
$snapshot = $Share.Snapshot()

Az：

$Share = Get-AzStorageShare -Name $containerName -Context $ctx
$task = $Share.SnapshotAsync()
$task.Wait()
$snapshot = $task.Result

撤消删除软删除的 Blob

AzureRM：

$b = Get-AzureStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$b.ICloudBlob.Undelete()

Az：

$b = Get-AzStorageBlob -Container $containerName -Blob $blobName -IncludeDeleted -Context $ctx
$task = $b.ICloudBlob.UndeleteAsync()
$task.Wait()

设置 blob 层

AzureRM：

$blockBlob = Get-AzureStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$blockBlob.ICloudBlob.SetStandardBlobTier("hot")

$pageBlob = Get-AzureStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$pageBlob.ICloudBlob.SetPremiumBlobTier("P4")

Az：

$blockBlob = Get-AzStorageBlob -Container $containerName -Blob $blockBlobName -Context $ctx
$task = $blockBlob.ICloudBlob.SetStandardBlobTierAsync("hot")
$task.Wait()

$pageBlob = Get-AzStorageBlob -Container $containerName -Blob $pageBlobName -Context $ctx
$task = $pageBlob.ICloudBlob.SetPremiumBlobTierAsync("P4")
$task.Wait()

Az.Websites （以前为 AzureRM.Websites）

从 PSAppServicePlan、PSCertificate、PSCloningInfo和 PSSite 对象中删除了弃用的属性

后续步骤

详细了解 Azure Stack Hub 上的 PowerShell，请参阅 Azure Stack Hub 中的 PowerShell 入门
安装 PowerShell Az 模块，请参阅安装适用于 Azure Stack Hub 的 PowerShell Az 模块

通过

从 AzureRM 迁移到 Azure Stack Hub 中的 Azure PowerShell Az

检查已安装的 AzureRM 版本

检查当前脚本是否适用于 AzureRM

安装 Azure PowerShell Az 模块

启用 AzureRM 兼容性别名

更改模块和 cmdlet 名称

总结

Az 1.0.0 的重大更改

常规重大更改

Cmdlet 名词前缀更改

模块名称更改

迁移 requires 和 import module 语句

迁移完全限定的 cmdlet 调用

迁移模块清单依赖关系

已删除的模块

Windows PowerShell 5.1 和 .NET 4.7.2

模块中断性变更

Az.ApiManagement （以前为 AzureRM.ApiManagement）

Az.Billing（以前是 AzureRM.Billing、AzureRM.Consumption 和 AzureRM.UsageAggregates）

Az.Compute （以前为 AzureRM.Compute）

Az.KeyVault （以前为 AzureRM.KeyVault）

Az.Monitor （以前为 AzureRM.Insights）

Az.Network （以前为 AzureRM.Network）

Az.Resources （以前为 AzureRM.Resources）

Az.Storage（以前是 Azure.Storage 和 AzureRM.Storage）

Blob 快照

撤消删除软删除的 Blob

设置 blob 层

Az.Websites （以前为 AzureRM.Websites）

后续步骤

反馈

其他资源

通过

从 AzureRM 迁移到 Azure Stack Hub 中的 Azure PowerShell Az

检查已安装的 AzureRM 版本

检查当前脚本是否适用于 AzureRM

安装 Azure PowerShell Az 模块

启用 AzureRM 兼容性别名

更改模块和 cmdlet 名称

总结

Az 1.0.0 的重大更改

常规重大更改

Cmdlet 名词前缀更改

模块名称更改

迁移 requires 和 import module 语句

迁移完全限定的 cmdlet 调用

迁移模块清单依赖关系

已删除的模块

Windows PowerShell 5.1 和 .NET 4.7.2

使用 PSCredential 临时禁用用户登录功能

改为使用默认设备代码登录，而不使用 Web 浏览器提示。

模块中断性变更

Az.ApiManagement （以前为 AzureRM.ApiManagement）

Az.Billing（以前是 AzureRM.Billing、AzureRM.Consumption 和 AzureRM.UsageAggregates）

Az.Compute （以前为 AzureRM.Compute）

Az.KeyVault （以前为 AzureRM.KeyVault）

Az.Monitor （以前为 AzureRM.Insights）

Az.Network （以前为 AzureRM.Network）

Az.Resources （以前为 AzureRM.Resources）

Az.Storage（以前是 Azure.Storage 和 AzureRM.Storage）

Blob 快照

共享快照

撤消删除软删除的 Blob

设置 blob 层

Az.Websites （以前为 AzureRM.Websites）

后续步骤

反馈

其他资源