Docker Desktop中SqlClient连接SQL Server Express失败的解决方法

核心问题分析 #

Linux容器中的System.Data.SqlClient不支持命名管道协议，而SQL Server Express默认的实例连接格式（如host.docker.internal\SQLEXPRESS）会优先尝试命名管道，这正是触发TCP Provider error:25的关键原因。此外，SQL Express默认使用动态TCP端口，容器无法稳定访问，需配置固定端口。

具体解决步骤 #

1. 为SQL Server Express配置固定TCP端口 #

• 打开SQL Server配置管理器，展开SQL Server网络配置 -> SQLEXPRESS的协议，确保TCP/IP已启用。
• 双击TCP/IP切换到IP地址标签：
  • 找到IPAll区域，清空TCP动态端口，在TCP端口处填写固定端口（例如1433，若被占用可选择1434等其他端口）。
• 重启SQL Server Express服务，使端口配置生效。

2. 修改连接字符串，强制使用TCP协议 #

放弃实例名格式，改用IP:端口的方式指定数据源，避免触发命名管道连接尝试：

var cs = new System.Data.SqlClient.SqlConnectionStringBuilder();
cs.InitialCatalog = "dev_db";
// 可使用宿主机IP+固定端口，或host.docker.internal+端口
cs.DataSource = @"host.docker.internal,1433"; 
cs.IntegratedSecurity = false;
cs.ConnectTimeout = 5;
cs.Encrypt = false;
cs.UserID = "user";
cs.Password = "password";

var xpto = new System.Data.SqlClient.SqlConnection(cs.ConnectionString);
xpto.Open();

注意：若使用开发机IP，需确保宿主机防火墙允许该端口的TCP入站流量。

3. 验证TCP连接可用性 #

• 在宿主机上测试端口是否开放：

  Test-NetConnection localhost -Port 1433
  

• 进入容器内部测试连通性：

  # 先进入容器bash
  docker exec -it [容器ID] bash
  # 测试ping和端口连通
  ping host.docker.internal
  telnet host.docker.internal 1433
  

4. 检查SQL账户权限 #

确保使用的SQL账户user具备dev_db的访问权限，且SQL Server已启用SQL Server身份验证模式（而非仅Windows身份验证）。

额外优化建议 #

• 若使用.NET 7+版本，建议切换到Microsoft.Data.SqlClient（官方推荐的新客户端库），对Linux环境兼容性更好，用法与System.Data.SqlClient基本一致。
• 确认Docker Desktop的Settings -> Resources -> Network中，host.docker.internal功能已启用（默认开启）。

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