Azure Pipeline报错：Get-AzVirtualNetworkPeering cmdlet未被识别

核心原因 #

这个错误的本质是当前PowerShell环境中未加载Az.Network模块——Get-AzVirtualNetworkPeering是该模块专属的cmdlet。上周正常运行、今日报错，大概率是Azure Pipeline的执行环境发生了变更，比如模块版本自动更新、代理池环境重置，或者任务配置被修改。

排查步骤 #

• 检查Azure Pipeline的Azure PowerShell任务配置：确认是否指定了Az模块的固定版本，如果用的是latest，可能自动更新到了不兼容的版本，导致模块未正确加载。
• 验证代理池的Az模块状态：如果是微软托管代理，可能某次平台更新清理了旧模块；如果是自托管代理，可能代理上的Az.Network模块被卸载或损坏。
• 核对代码的模块导入逻辑：之前的代码可能依赖环境自动加载模块，但现在环境变化后需要显式导入。

解决方法 #

1. 显式导入Az.Network模块 #

在执行目标cmdlet前添加模块导入命令，可指定和上周运行时一致的版本，避免版本兼容问题：

# 显式导入指定版本的Az.Network模块，版本号替换为上周正常运行的版本
Import-Module Az.Network -RequiredVersion 6.5.0 -Force
$peering = Get-AzVirtualNetworkPeering -Name $peering_name -VirtualNetworkName $peering_record.vNetRemotePeer -ResourceGroupName $peering_record.vNetRemotePeerRG -ErrorAction SilentlyContinue

如果不确定具体版本，可先尝试不指定版本，用Import-Module Az.Network -Force强制加载。

2. 锁定Pipeline中Az模块版本 #

修改Azure Pipeline的AzurePowerShell任务，固定Az模块版本，防止自动更新引发问题：

- task: AzurePowerShell@5
  inputs:
    azureSubscription: '你的服务连接名称'
    ScriptType: 'FilePath'
    ScriptPath: '你的脚本路径.ps1'
    azurePowerShellVersion: 'Specify'
    preferredAzurePowerShellVersion: '9.6.0' # 替换为上周正常运行的版本或兼容版本

可通过Find-Module Az.Network -AllVersions命令查看所有可用的Az.Network版本，选择包含目标cmdlet的版本。

3. 修复代理池环境 #

• 微软托管代理：在Pipeline任务中添加模块安装命令，确保环境中存在Az.Network模块：

  Install-Module Az.Network -Force -AllowClobber -Scope CurrentUser
  

• 自托管代理：登录代理服务器，手动执行上述安装命令，修复模块缺失问题。

4. 提前验证cmdlet存在性 #

在代码开头添加检查逻辑，提前发现模块缺失问题并抛出明确提示：

if (-not (Get-Command Get-AzVirtualNetworkPeering -ErrorAction SilentlyContinue)) {
    throw "未找到Get-AzVirtualNetworkPeering cmdlet，请先安装Az.Network模块。"
}

内容的提问来源于stack exchange，提问作者learner