Azure Data Lake Analytics USQL代码CI/CD构建报错咨询

这个错误本质是MSBuild找不到USQL编译任务对应的程序集，大概率是私有代理机器的环境配置问题，咱们一步步来搞定：

1. 确认私有代理已安装必要的Visual Studio组件 #

你的代理机器上必须安装Visual Studio，而且一定要勾选Azure Data Lake and Stream Analytics Tools这个工作负载/扩展：

• 打开Visual Studio安装器，找到已安装的VS实例，点击“修改”
• 在“工作负载”标签里找到“Azure开发”，确保它被勾选（这个工作负载包含ADL工具）
• 或者如果已经装了VS，直接在VS的“扩展和更新”里搜索安装“Azure Data Lake and Stream Analytics Tools”

2. 确保构建任务使用Visual Studio附带的MSBuild版本 #

很多时候私有代理会用系统默认的MSBuild，而不是VS自带的那个，这会导致找不到USQL相关的目标文件：

• 在VSTS的构建任务里，把MSBuild的路径指定为VS安装目录下的版本，比如VS2019 Enterprise的路径是：

  C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\MSBuild\Current\Bin\MSBuild.exe
  

• 如果你不确定路径，可以在代理机器上打开VS的开发者命令提示符，输入where msbuild，就能得到正确的路径

3. 检查Usql.targets的程序集路径和权限 #

错误提示里的Usql.targets在C:\Users\<代理账户>\AppData\Roaming\Microsoft\DataLake\MsBuild\1.0\下，你可以打开这个文件，检查里面引用的Microsoft.Cosmos.ScopeStudio.VsExtension.CompilerTask程序集路径是否正确：

• 确认这个DLL存在于VS的ADL工具目录下，比如：

  C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\Extensions\Microsoft\ADL Tools\Compiler\Microsoft.Cosmos.ScopeStudio.VsExtension.CompilerTask.dll
  

• 如果代理服务用的是系统账户，可能没有访问该用户AppData目录的权限，建议把代理服务切换为本地管理员账户运行，或者把Usql.targets复制到MSBuild的全局目标目录（比如C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\MSBuild\Microsoft\DataLake\）

4. 手动注册程序集到GAC（可选） #

如果上面的步骤都没用，可能是程序集没在全局程序集缓存里，导致MSBuild加载失败：

• 打开VS的开发者命令提示符（以管理员身份）
• 找到CompilerTask.dll的路径，然后运行以下命令：

  gacutil /i "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\Extensions\Microsoft\ADL Tools\Compiler\Microsoft.Cosmos.ScopeStudio.VsExtension.CompilerTask.dll"
  

• 注册完成后，重启代理服务，再重新触发构建

排查小技巧 #

可以在代理机器上手动运行构建命令，比如：

msbuild /t:Build YourUSQLProject.sln

这样能直接在本地看到错误详情，更容易定位问题所在。

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