Azure DevOps自托管代理PowerShell无法运行SqlPackage工具求助

环境配置 #

• Azure DevOps Server 2019 Express
• 自托管代理（Self-Hosted Agent）
• 本地（localhost）运行
• 已安装.NET 6.x

问题描述 #

流水线里的PowerShell任务执行SqlPackage工具时，报错：
SqlPackage : 术语“SqlPackage”未被识别为 cmdlet、函数、脚本文件或可运行程序的名称。

为简化测试，编写了一段内联脚本：

Write-Host "Testing"
SqlPackage

脚本能正常输出“Testing”，但执行SqlPackage时触发上述错误。

已确认：在本地PowerShell命令行直接运行SqlPackage是正常的，会返回：
SqlPackage: 创建和部署SQL Server数据库及DACPAC包的命令行工具。(162.0.52.1) 版权所有 (c) 2023 Microsoft Corporation。保留所有权利。

解决方法 #

1. 检查并添加SqlPackage路径到系统环境变量 #

自托管代理运行时的环境变量和你本地登录用户的PATH可能不一致，SqlPackage的安装目录大概率没加到代理能读取的系统PATH里：

• 打开机器的系统属性 → 切换到高级标签 → 点击环境变量
• 在系统变量区域找到PATH，点击编辑，添加SqlPackage的安装路径（比如C:\Program Files\Microsoft SQL Server\160\DAC\bin，版本号根据你实际安装的SQL Server调整）
• 重启自托管代理服务，让新的PATH生效

2. 直接使用SqlPackage的绝对路径执行 #

如果不想修改系统环境变量，直接在脚本里写SqlPackage的完整路径即可：

Write-Host "Testing"
& "C:\Program Files\Microsoft SQL Server\160\DAC\bin\SqlPackage.exe"

注意：路径里的版本号要对应你实际安装的SqlPackage版本，比如150对应SQL Server 2019，160对应2022。

3. 调整自托管代理的运行账户 #

如果代理是用系统账户运行的，可能没有访问SqlPackage安装目录的权限：

• 打开Windows的服务，找到自托管代理对应的服务项
• 右键点击服务→属性→切换到登录标签，改成你本地能正常运行SqlPackage的用户账户
• 重启代理服务后再跑流水线测试

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