安装适用于 Azure Stack Hub 的 PowerShell Az 和 Azure Stack 模块

有关 AzureStack 模块的详细信息，请参阅 PSGallery。

本文介绍如何使用 PowerShellGet 安装 Azure PowerShell Az 和兼容的 Azure Stack Hub 管理员模块。 可以在 Windows、macOS 和 Linux 平台上安装 Az 模块。

还可以在 Docker 容器中运行 Azure Stack Hub 的 Az 模块。 有关说明，请参阅 使用 Docker 运行适用于 Azure Stack Hub 的 PowerShell。

可以使用 API 配置文件 为 Azure Stack Hub 资源提供程序指定兼容的终结点。 API 配置文件提供了一种管理 Azure 与 Azure Stack Hub 之间的版本差异的方法。 API 版本配置文件是一组具有特定 API 版本的 Azure 资源管理器 PowerShell 模块。 每个云平台都有一组受支持的 API 版本配置文件。 例如，Azure Stack Hub 支持特定的配置文件版本，例如 2020-09-01-hybrid。 安装配置文件时，将安装与指定配置文件对应的 Azure 资源管理器 PowerShell 模块。

可以在连接 Internet、部分连接或断开连接的方案中安装 Azure Stack Hub 兼容的 PowerShell Az 模块。 本文将引导你详细了解这些情境的具体说明。

验证先决条件

Azure Stack Hub 在安装更新 2002 或更高版本并安装所有当前修补程序后支持 Az 模块。 有关详细信息，请参阅 Azure Stack Hub 发行说明 。

Azure PowerShell Az 模块适用于所有平台上的 PowerShell 5.1 或更高版本，或者所有平台上的 PowerShell Core 6.x 及更高版本。 应该安装适用于操作系统的最新版本的 PowerShell Core。 在 PowerShell Core 上运行时，Azure PowerShell 没有其他要求。

若要检查 PowerShell 版本，请运行以下命令：

$PSVersionTable.PSVersion

Windows 的先决条件

在 Windows 上的 PowerShell 5.1 中使用 Azure PowerShell：

1. 如果需要，请更新到 Windows PowerShell 5.1 。 如果使用的是 Windows 10，则已安装 PowerShell 5.1。

2. 安装 .NET Framework 4.7.2 或更高版本。

3. 请确保具有最新版本的 PowerShellGet。 从具有管理员权限的命令提示符运行以下 cmdlet：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   
   powershell -noprofile
   $PSVersionTable
   Uninstall-Module PowershellGet -AllVersions -Force -Confirm:$false
   Get-module PowershellGet
   Find-module PowershellGet
   Install-Module PowershellGet -MinimumVersion 2.2.3 -Force
   

Linux 和 Mac 的先决条件

需要 PowerShell Core 6.x 或更高版本。 按照 链接 获取说明

卸载 Azure Stack Hub PowerShell 模块的现有版本

在安装所需版本之前，请确保卸载以前安装的任何 Azure Stack Hub Azure 资源管理器或 Az PowerShell 模块。 使用以下两种方法之一卸载模块：

• 若要卸载现有的 Azure 资源管理器和 Az PowerShell 模块，请关闭所有活动的 PowerShell 会话，并运行以下 cmdlet：

  Get-Module -Name Azure* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
  Get-Module -Name Azs.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
  Get-Module -Name Az.* -ListAvailable | Uninstall-Module -Force -Verbose -ErrorAction Continue
  

  如果遇到“模块已使用”等错误，请关闭使用模块并重新运行这些 cmdlet 的 PowerShell 会话。

• 如果Uninstall-Module未成功，请删除位置中所有以Azure、Az或$env:PSModulePath开头的文件夹。 对于 Windows PowerShell，位置可能 C:\Program Files\WindowsPowerShell\Modules 和 C:\Users\{yourusername}\Documents\WindowsPowerShell\Modules。 对于 PowerShell Core，位置可能 C:\Program Files\PowerShell\7\Modules 和 C:\Users\{yourusername}\Documents\PowerShell\Modules。 删除这些文件夹会删除任何现有的 Azure PowerShell 模块。

连接：使用 Internet 连接进行安装

Azure Stack Az 模块适用于 Windows 计算机上的 PowerShell 5.1 或更高版本，或者 Linux 或 macOS 平台上的 PowerShell 6.x 或更高版本。 使用 PowerShellGet cmdlet 是首选安装方法。 此方法在受支持的平台上的工作方式相同。

1. 从 PowerShell 会话运行以下命令，将 PowerShellGet 更新到最低版本 2.2.3：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module PowerShellGet -MinimumVersion 2.2.3 -Force
   

2. 关闭 PowerShell 会话，然后打开新的 PowerShell 会话，使更新生效。

3. 运行以下命令以安装 Az 模块：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-Module -Name Az.BootStrapper -Force
   Install-AzProfile -Profile 2020-09-01-hybrid -Force
   

4. 安装 AzureStack PowerShell 模块：

   Install-Module -Name AzureStack -RequiredVersion 2.4.0
   

   Install-Module -Name AzureStack -RequiredVersion 2.3.0
   

   Install-Module -Name AzureStack -RequiredVersion 2.2.0
   

   Install-Module -Name AzureStack -RequiredVersion 2.1.1
   

已断开连接：在没有 Internet 连接的情况下安装

在断开连接的情况下，首先将 PowerShell 模块下载到具有 Internet 连接的计算机。 然后，将它们传输到 Azure Stack 开发工具包（ASDK）进行安装。

使用 Internet 连接登录到计算机，并使用以下脚本下载 Azure 资源管理器和 Azure Stack Hub 包，具体取决于 Azure Stack Hub 的版本。

安装有五个步骤：

1. 在连接的计算机上安装 Azure Stack Hub PowerShell。
2. 启用其他存储功能。
3. 将 PowerShell 包传输到断开连接的工作站。
4. 在断开连接的工作站上手动启动 NuGet 提供程序。
5. 确认 PowerShell 的安装。

安装 Azure Stack Hub PowerShell

1. 以下代码从 可信联机存储库安装 Az 模块：

   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   Install-module -Name PowerShellGet -MinimumVersion 2.2.3 -Force
   Import-Module -Name PackageManagement -ErrorAction Stop
   $savedModulesPath = "<Path that is used to save the packages>"
   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name Az -Path $savedModulesPath -Force -RequiredVersion 2.0.1
   

2. 安装 Az 模块后，继续安装 AzureStack 模块：

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.4.0
   

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.3.0
   

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.2.0
   

   Save-Package -ProviderName NuGet -Source https://www.powershellgallery.com/api/v2 -Name AzureStack -Path $savedModulesPath -Force -RequiredVersion 2.1.1
   

将包添加到工作站

1. 将下载的包复制到 USB 设备。

2. 登录到断开连接的工作站，并将包从 USB 设备复制到工作站上的某个位置。

3. 在断开连接的工作站上手动启动 NuGet 提供程序。 有关说明，请参阅 在未连接到 Internet 的计算机上手动启动 NuGet 提供程序。

4. 将此位置注册为默认存储库，并安装此存储库中的 AzureRM 和 AzureStack 模块：

    # requires -Version 5
    # requires -RunAsAdministrator
    # requires -Module PowerShellGet
    # requires -Module PackageManagement
   
    $SourceLocation = "<Location on the development kit that contains the PowerShell packages>"
    $RepoName = "MyNuGetSource"
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    Register-PSRepository -Name $RepoName -SourceLocation $SourceLocation -InstallationPolicy Trusted
   

5. 安装 Az 模块。

    Install-Module -Name Az -Repository $RepoName -RequiredVersion 2.0.1 -Scope AllUsers
   

6. 安装 AzureStack modulesL

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.4.0 -Scope AllUsers
   

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.3.0 -Scope AllUsers
   

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.2.0 -Scope AllUsers
   

   Install-Module -Name AzureStack -Repository $RepoName -RequiredVersion 2.1.1 -Scope AllUsers
   

确认 PowerShell 的安装

运行以下命令确认安装：

Get-Module -Name "Az*" -ListAvailable
Get-Module -Name "Azs*" -ListAvailable

将 PowerShell 配置为使用代理服务器

在需要代理服务器访问 Internet 的情况下，首先将 PowerShell 配置为使用现有代理服务器：

1. 打开提升的 PowerShell 提示符。

2. 运行以下命令：

   #To use Windows credentials for proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = [System.Net.CredentialCache]::DefaultCredentials
   
   #Alternatively, to prompt for separate credentials that can be used for #proxy authentication
   [System.Net.WebRequest]::DefaultWebProxy.Credentials = Get-Credential
   

使用 Az 模块

仍可以使用基于 AzureRM 模块的 cmdlet 和代码示例。 但是，必须更改模块和 cmdlet 的名称。 模块名称已更改，因此 AzureRM Azure 变为 Az，cmdlet 也是如此。 例如，模块 AzureRM.Compute 已重命名为 Az.Compute。 New-AzureRMVM是 New-AzVM，现在是Get-AzureStorageBlobGet-AzStorageBlob。

有关将 AzureRM 脚本迁移到 Az 的更深入的讨论和指南，以及有关 Azure Stack Hub Az 模块中重大更改的信息，请参阅 从 AzureRM 迁移到 Azure PowerShell Az。

已知问题

安装 Az 模块时引发错误

• 适用于：此问题适用于 2002 及更高版本
• 原因：安装模块时引发错误。 错误消息的开头为：Register-PacakgeSource : A parameter cannot be found that matches parameter name. 'PackageManagementProvider'.，错误消息也可能包含以下文本：PackageManagement\Install-Package : Cannot convert value "2.0.1-preview" to type "System.Version". Error: "Input string was not in a correct format."
• 补救措施：在同一会话中运行以下 cmdlet：
  Install-Module PowershellGet -MinimumVersion 2.3.0 -Force
  关闭会话并启动权限提升的新 PowerShell 会话。
• 发生次数：通用

安装 Az 模块时，错误地引发“需要管理员权限”错误

• 适用于：此问题适用于 2002 及更高版本
• 原因：在提升的提示符下安装模块时，会引发错误。 错误说，“Administrator rights required”。
• 补救措施：关闭会话并启动权限提升的新 PowerShell 会话。 请确保会话中没有加载现有的 Az. 账户模块已加载到会话中。
• 发生次数：通用

使用 2020-09-01-hybrid 配置文件时，cmdlet New-AzVmss 失败

• 适用：此问题适用于 2020-09-01-hybrid 配置文件。
• 原因：cmdlet New-AzVmss 不适用于 2020-09-01-hybrid 配置文件。
• 补救措施：使用模板创建虚拟机规模设置。 可以在 GitHub 存储库 AzureStack-QuickStart-Templates/101-vmss-windows-vm 中找到 Azure Stack Hub 资源管理器模板示例，还可以找到有关将 Azure Stack Hub 资源管理器与 Visual Studio Code 配合使用的说明。
• 发生次数：通用

运行 PowerShell 脚本时引发的错误

• 适用于：此问题适用于 2002 及更高版本。

• 原因：使用 Azure Stack Hub 特定模块运行脚本或 PowerShell 命令时，需要在模块中提供脚本或命令。 你可能会看到以下错误：

  Method 'get_SerializationSettings' in type 'Microsoft.Azure.Management.Internal.Resources.ResourceManagementClient' from assembly 'Microsoft.Azure.Commands.ResourceManager.Common, Version=4.0.0.0, 
  Culture=neutral, PublicKeyToken=31bf3856ad364e35' does not have an implementation.
  

  当前模块是 PowerShell Az 模块，它已取代 PowerShell AzureRM 模块。 如果在安装 Az 模块时尝试运行调用 AzureRM 命令的脚本，脚本将引发错误。 或者，如果在安装 AzureRM 模块时尝试运行调用 Az 命令的脚本，脚本将引发错误。

• 修正：卸载 AzureRM 模块并安装 Az 模块。 有关说明，请参阅 安装适用于 Azure Stack Hub 的 PowerShell Az 模块。 如果使用 Azure Stack Hub 工具，请使用 Az 工具。 从 az 分支克隆工具存储库，或从 az 分支下载 AzureStack-Tools。 有关说明，请参阅 从 GitHub 下载 Azure Stack Hub 工具

• 发生次数：通用

使用 New-AzADServicePrincipal 和 New-AzADApplication 引发的错误

• 适用：使用 Microsoft Entra ID 的 Azure Stack 环境。

• 原因：Azure Active Directory Graph 引入了重大变更，限制 Active Directory 应用程序必须是目录中已验证域的子域。 在更改之前，仅对多租户应用强制实施此限制。 现在，此限制也适用于单租户应用。 更改将导致以下错误： Values of identifierUris property must use a verified domain of the organization or its subdomain' is displayed when running

• 修正：可以通过两种方式解决此限制。

  • 需要使用服务主体名称，该名称是目录租户的子域。 例如，如果目录是 contoso.partner.onmschina.cn，则服务主体名称必须采用以下 <foo>.contoso.partner.onmschina.cn形式。 使用以下 cmdlet：

    New-AzADServicePrincipal -Role Owner -DisplayName <foo>.contoso.partner.onmschina.cn
    

    有关标识和使用 Azure Stack Hub 的服务主体的详细信息，请参阅 Azure Stack Hub 的标识提供者概述。

  • 创建 Microsoft Entra 应用程序，提供有效的 IdentifierUri，然后使用以下 cmdlet 创建服务主体，并将其与应用程序关联：

    $app=New-AzADApplication -DisplayName 'newapp' -IdentifierUris http://anything.contoso.partner.onmschina.cn
    New-AzADServicePrincipal -Role Owner -ApplicationId $app.ApplicationId
    

• 发生次数：通用

错误：“SharedTokenCacheCredential 身份验证失败”

• 适用于：此问题适用于所有支持的版本。
• 原因：在使用 Azure Stack Hub PowerShell 模块版本 2.1.1 安装多个版本的 AzAccounts 时，将引发 SharedTokenCacheCredential 身份验证失败错误。
• 修正：删除所有版本的 AzAccounts，并仅安装受支持的 AzAccounts 版本 2.2.8。
• 发生次数：通用

后续步骤

• 从 GitHub 下载 Azure Stack Hub 工具
• 配置 Azure Stack Hub 用户的 PowerShell 环境
• 配置 Azure Stack Hub作员的 PowerShell 环境
• 管理 Azure Stack Hub 中的 API 版本配置文件