网关模式下初始化CosmosClient时触发空引用异常

问题重现 #

使用Azure Cosmos DB SDK 3.50版本，以网关模式初始化CosmosClient时触发NullReferenceException，堆栈指向GlobalEndpointManager.GetOnlyGlobalEndpointAsync()。尽管目标域名通过nslookup解析正常，且测试多个Cosmos DB实例均出现相同问题。

代码示例：

var options = new CosmosClientOptions() { 
       ConnectionMode = ConnectionMode.Gateway 
};
 
var cosmosClient = new CosmosClient(endpoint, tokenCredential: tokenCredential, options);

异常信息 #

System.NullReferenceException: 
Object reference not set to an instance of an object.
   at Microsoft.Azure.Cosmos.Routing.GlobalEndpointManager.GetAccountPropertiesHelper.GetOnlyGlobalEndpointAsync()
   at Microsoft.Azure.Cosmos.Routing.GlobalEndpointManager.GetAccountPropertiesHelper.GetAccountPropertiesAsync()

完整堆栈跟踪：

System.NullReferenceException: Object reference not set to an instance of an object.
   at Microsoft.Azure.Cosmos.Routing.GlobalEndpointManager.GetAccountPropertiesHelper.GetOnlyGlobalEndpointAsync()
   at Microsoft.Azure.Cosmos.Routing.GlobalEndpointManager.GetAccountPropertiesHelper.GetAccountPropertiesAsync()
   at Microsoft.Azure.Cosmos.Routing.GlobalEndpointManager.GetDatabaseAccountFromAnyLocationsAsync(Uri defaultEndpoint, IList`1 locations, IList`1 accountInitializationCustomEndpoints, Func`2 getDatabaseAccountFn, CancellationToken cancellationToken)
   at Microsoft.Azure.Cosmos.GatewayAccountReader.InitializeReaderAsync()
   at Microsoft.Azure.Cosmos.CosmosAccountServiceConfiguration.InitializeAsync()
   at Microsoft.Azure.Cosmos.DocumentClient.InitializeGatewayConfigurationReaderAsync()
   at Microsoft.Azure.Cosmos.DocumentClient.GetInitializationTaskAsync(IStoreClientFactory storeClientFactory)
   at Microsoft.Azure.Documents.BackoffRetryUtility`1.ExecuteRetryAsync[TParam,TPolicy](Func`1 callbackMethod, Func`3 callbackMethodWithParam, Func`2 callbackMethodWithPolicy, TParam param, IRetryPolicy retryPolicy, IRetryPolicy`1 retryPolicyWithArg, Func`1 inBackoffAlternateCallbackMethod, Func`2 inBackoffAlternateCallbackMethodWithPolicy, TimeSpan minBackoffForInBackoffCallback, CancellationToken cancellationToken, Action`1 preRetryCallback)
   at Microsoft.Azure.Documents.ShouldRetryResult.ThrowIfDoneTrying(ExceptionDispatchInfo capturedException)
   at Microsoft.Azure.Documents.BackoffRetryUtility`1.ExecuteRetryAsync[TParam,TPolicy](Func`1 callbackMethod, Func`3 callbackMethodWithParam, Func`2 callbackMethodWithPolicy, TParam param, IRetryPolicy retryPolicy, IRetryPolicy`1 retryPolicyWithArg, Func`1 inBackoffAlternateCallbackMethod, Func`2 inBackoffAlternateCallbackMethodWithPolicy, TimeSpan minBackoffForInBackoffCallback, CancellationToken cancellationToken, Action`1 preRetryCallback)
   at Microsoft.Azure.Documents.BackoffRetryUtility`1.ExecuteRetryAsync[TParam,TPolicy](Func`1 callbackMethod, Func`3 callbackMethodWithParam, Func`2 callbackMethodWithPolicy, TParam param, IRetryPolicy retryPolicy, IRetryPolicy`1 retryPolicyWithArg, Func`1 inBackoffAlternateCallbackMethod, Func`2 inBackoffAlternateCallbackMethodWithPolicy, TimeSpan minBackoffForInBackoffCallback, CancellationToken cancellationToken, Action`1 preRetryCallback)
   at Microsoft.Azure.Cosmos.AsyncCacheNonBlocking`2.GetAsync(TKey key, Func`2 singleValueInitFunc, Func`2 forceRefresh)
   at Microsoft.Azure.Cosmos.DocumentClient.EnsureValidClientAsync(ITrace trace)
   at Microsoft.Azure.Cosmos.Handlers.RequestInvokerHandler.EnsureValidClientAsync(RequestMessage request, ITrace trace)
   at Microsoft.Azure.Cosmos.Handlers.RequestInvokerHandler.SendAsync(RequestMessage request, CancellationToken cancellationToken)
   at Microsoft.Azure.Cosmos.Handlers.RequestInvokerHandler.SendAsync(String resourceUriString, ResourceType resourceType, OperationType operationType, RequestOptions requestOptions, ContainerInternal cosmosContainerCore, FeedRange feedRange, Stream streamPayload, Action`1 requestEnricher, ITrace trace, CancellationToken cancellationToken)
   at Microsoft.Azure.Cosmos.ContainerCore.ProcessItemStreamAsync(Nullable`1 partitionKey, String itemId, Stream streamPayload, OperationType operationType, ItemRequestOptions requestOptions, ITrace trace, Nullable`1 targetResponseSerializationFormat, CancellationToken cancellationToken)
   at Microsoft.Azure.Cosmos.ContainerCore.ReadItemAsync[T](String id, PartitionKey partitionKey, ITrace trace, ItemRequestOptions requestOptions, CancellationToken cancellationToken)
   at Microsoft.Azure.Cosmos.ClientContextCore.RunWithDiagnosticsHelperAsync[TResult](String containerName, String databaseName, OperationType operationType, ITrace trace, Func`2 task, Nullable`1 openTelemetry, RequestOptions requestOptions, Nullable`1 resourceType)

环境信息 #

• SDK版本：3.50
• 操作系统：Windows Server

解决方法 #

1. 检查Endpoint格式
   确保传入的endpoint是完整的Uri格式，包含https://前缀，例如https://your-account.documents.azure.com:443/。缺失协议前缀会导致SDK内部解析失败，触发空引用异常。

2. 显式配置网关模式连接端点
   在CosmosClientOptions中手动指定网关端点，绕过SDK自动发现逻辑：

var options = new CosmosClientOptions()
{
    ConnectionMode = ConnectionMode.Gateway,
    AccountEndpoint = new Uri(endpoint)
};

3. 调整SDK版本
   3.50版本的SDK存在已知的网关模式初始化bug，建议升级到3.51及以上版本，或者降级到3.49版本，该问题在后续版本中已被修复。

4. 验证TokenCredential有效性
   确保tokenCredential已正确初始化并拥有Cosmos DB访问权限。可以尝试使用主键初始化CosmosClient进行测试，排除凭证问题：

var cosmosClient = new CosmosClient(endpoint, primaryKey, options);

5. 检查网络代理配置
   如果服务器处于代理环境中，需为SDK配置正确的代理信息，网关模式依赖HTTP请求，代理配置错误会导致无法获取账户端点信息：

var options = new CosmosClientOptions()
{
    ConnectionMode = ConnectionMode.Gateway,
    WebProxy = new WebProxy("http://your-proxy:port")
};

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