DocumentDB连接与数据存储报错求助：服务当前不可用

这个问题我之前帮不少开发者排查过，结合你说的「Studio能正常连接但SDK报错」的情况，可以从这几个方向入手解决：

1. 优先升级SDK版本 #

你当前使用的documentdb-dotnet-sdk/1.19.1是非常老旧的版本，现在Azure Cosmos DB（原DocumentDB）的官方SDK已经迭代到3.x+版本，旧版SDK早已停止维护，和当前服务端的兼容性问题是这类报错的常见原因。

建议你卸载旧的Microsoft.Azure.DocumentDB NuGet包，安装最新的Microsoft.Azure.Cosmos包——新版SDK不仅修复了大量兼容性问题，重试策略、网络适配逻辑也更完善，能更好应对临时的服务不可用场景。

2. 切换连接模式为网关模式 #

DocumentDB Studio默认使用网关模式连接，但旧SDK可能默认启用直接连接模式。如果你的网络环境防火墙限制了直接连接所需的10250-10255端口，就会出现「Studio能连、SDK连不上」的矛盾情况。

你可以在连接字符串里强制指定网关模式：

AccountEndpoint=https://your-account.documents.azure.com:443/;AccountKey=your-key;ConnectionMode=Gateway;

或者在代码中配置：

var client = new DocumentClient(new Uri(endpoint), key, new ConnectionPolicy { ConnectionMode = ConnectionMode.Gateway });

3. 排查网络与代理配置 #

即使Studio能正常连接，也可能存在SDK未正确适配网络环境的情况：

• 如果你的环境需要通过代理访问外部服务，旧SDK不会自动读取系统代理，需要手动在ConnectionPolicy中配置：

var policy = new ConnectionPolicy();
policy.Proxy = new WebProxy("http://your-proxy-address:port");
var client = new DocumentClient(new Uri(endpoint), key, policy);

• 确认防火墙允许SDK的出站请求，网关模式下443端口必须是开放状态。

4. 检查账户区域与故障转移状态 #

登录Azure门户查看你的Cosmos DB账户：

• 确认所属区域是否有服务故障（Azure状态页可以查看区域健康）；
• 检查是否触发了故障转移，旧SDK无法自动感知故障转移后的新主区域，升级SDK后会自动处理区域切换，也可以手动指定账户的主区域地址。

5. 调整重试策略 #

旧SDK的默认重试策略可能不足以应对临时的服务节流或不可用情况，你可以自定义重试参数来提升容错性：

var policy = new ConnectionPolicy();
policy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 10;
policy.RetryOptions.MaxRetryWaitTimeInSeconds = 30;
var client = new DocumentClient(new Uri(endpoint), key, policy);

按照上面的步骤逐一排查，大概率能解决你的问题。如果升级SDK后仍有报错，可以再检查代码中数据库、容器名称的大小写（Cosmos DB资源名称是大小写敏感的），或者捕获更详细的异常日志来进一步定位。

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