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

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 版本，下一步是启用 Az 模块的兼容性模式。 使用以下命令启用兼容性：

Enable-AzureRmAlias -Scope CurrentUser

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

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

更改模块和 cmdlet 名称

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

请注意此命名变更的例外情况。 某些模块会被重命名或并入现有模块，但不会影响其 cmdlet 的后缀，除非将 AzureRM 或 Azure 更改为 Az。 否则，请更改完整的 cmdlet 后缀以反映新的模块名称。

概要

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

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.*以下模块除外：

由于这些更改，需要更新使用 #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

若要使用新的模块和 cmdlet 名称，

Az.Compute\Get-AzVM

迁移模块清单依赖关系

更新模块清单 (.psd1) 文件中 RequiredModules 部分内的模块名称，适用于声明依赖 AzureRM 模块的模块：

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。

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

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

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

由于 .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 设置这些属性
• 删除了以下属性：
  • 从 PortalHostnameConfiguration中删除了类型 ProxyHostnameConfiguration 的属性 ManagementHostnameConfiguration、ScmHostnameConfiguration、PsApiManagementHostnameConfiguration 和 PsApiManagementContext。 请改用 PortalCustomHostnameConfiguration 类型的 ProxyCustomHostnameConfiguration、ManagementCustomHostnameConfiguration、ScmCustomHostnameConfiguration 和 PsApiManagementCustomHostNameConfiguration。
  • 从 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 对象，脚本不应再使用此字段的值来做出处理决策。
• InstanceView 对象的 PSVirtualMachineScaleSetVM 属性的类型从 VirtualMachineInstanceView 更改为 VirtualMachineScaleSetVMInstanceView
• 从 AutoOSUpgradePolicy 属性中删除了 AutomaticOSUpgrade 和 UpgradePolicy 属性
• Sku 对象中 PSSnapshotUpdate 属性的类型从 DiskSku 更改为 SnapshotSku
• VmScaleSetVMParameterSet 从 Add-AzVMDataDisk cmdlet 中删除，无法再单独向 ScaleSet VM 添加数据磁盘。

Az.KeyVault （以前为 AzureRM.KeyVault）

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

Az.Monitor （以前为 AzureRM.Insights）

• 从 Categories cmdlet 中删除了复数名称 Timegrains 和 Set-AzDiagnosticSetting 参数并将其替换为单数参数名称。使用以下内容的脚本

  Set-AzureRmDiagnosticSetting -Timegrains PT1M -Categories Category1, Category2
  

  应更改为

  Set-AzDiagnosticSetting -Timegrain PT1M -Category Category1, Category2
  

Az.Network （以前为 AzureRM.Network）

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

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

Az.Resources （以前为 AzureRM.Resources）

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

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

  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
• 在 Get-AzStorageUsage cmdlet 中，Location 参数现为必需参数。
• 存储 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 模块。