Azure Pipelines Tasks中Azure PowerShell任务故障排查指南

问题现象

在使用Azure DevOps的Azure PowerShell任务时，用户遇到了一个典型的依赖冲突错误。错误信息显示："Exception calling ".ctor" with "3" argument(s): "Method not found: 'Newtonsoft.Json.JsonSerializerSettings System.Net.Http.Formatting.BaseJsonMediaTypeFormatter.get_SerializerSettings()'"。

这个错误通常发生在将Azure服务连接从服务主体(手动)切换到工作负载身份联合(手动)后。错误发生在任务初始化阶段，甚至在执行用户脚本之前。

错误分析

从日志中可以清楚地看到，错误发生在Azure PowerShell任务尝试获取VSS HTTP客户端时。具体来说，是Newtonsoft.Json序列化器设置方法在BaseJsonMediaTypeFormatter类中找不到。

这种类型的错误通常表明存在以下问题之一：

1. 程序集版本冲突 - 不同组件引用了不同版本的Newtonsoft.Json
2. 依赖项不匹配 - 某些组件期望的API在运行时不可用
3. 模块加载顺序问题 - 错误的模块版本被优先加载

根本原因

经过分析，这个问题的主要原因是：

1. Azure PowerShell任务内部使用的VSTS SDK与Az模块之间存在版本不兼容
2. 当使用工作负载身份联合认证时，任务需要加载额外的组件来处理联合令牌
3. 这些组件对Newtonsoft.Json的版本有特定要求，与环境中加载的版本不匹配

解决方案

针对这个问题，有以下几种可行的解决方案：

方案一：切换到PowerShell Core

这是最直接的解决方案。Azure PowerShell任务支持在PowerShell Core环境下运行，这通常能避免传统PowerShell中的一些依赖冲突问题。

在YAML配置中，可以这样指定：

steps:
- task: AzurePowerShell@5
  inputs:
    azurePowerShellVersion: 'LatestVersion'
    pwsh: true

方案二：更新代理版本

确保使用最新版本的Microsoft托管代理。旧版本的代理可能包含不兼容的依赖项。

方案三：明确指定Az模块版本

虽然错误发生在任务初始化阶段，但确保使用较新版本的Az模块也能帮助避免兼容性问题。

steps:
- task: AzurePowerShell@5
  inputs:
    azurePowerShellVersion: 'OtherVersion'
    preferredAzurePowerShellVersion: '8.0.0'

方案四：回退到服务主体认证

如果短期内无法解决兼容性问题，可以考虑暂时回退到服务主体认证方式，但这只是临时解决方案。

最佳实践建议

1. 优先使用PowerShell Core：新项目应该从一开始就使用PowerShell Core，它更现代且依赖管理更好。

2. 保持环境更新：定期更新构建代理和任务版本，确保使用最新的兼容组件。

3. 模块版本管理：在可能的情况下，明确指定关键模块的版本，避免自动更新带来的意外问题。

4. 测试环境先行：在将认证方式变更应用到生产流水线前，先在测试环境中验证。

技术背景

这个问题涉及到几个关键技术点：

1. 工作负载身份联合：这是Azure AD提供的一种无密码认证机制，相比传统服务主体更安全。

2. Newtonsoft.Json依赖：.NET生态系统中广泛使用的JSON序列化库，不同版本间有时存在兼容性问题。

3. 模块加载机制：PowerShell的模块加载顺序和版本解析策略可能导致意外的依赖冲突。

通过理解这些底层技术，可以更好地预防和解决类似问题。