.NET Framework v4.8 Web API如何接入Cosmos DB实现CRUD

旧版Microsoft.Azure.DocumentDB（v2 .NET SDK）已经停止维护弃用，针对.NET Framework 4.8项目，正确接入方式如下：

包版本选择 #

直接选用官方持续维护的 v3系列Microsoft.Azure.Cosmos SDK，不要使用4.x版本——4.x版本最低仅支持.NET 6，不兼容.NET Framework 4.8；3.x系列完整支持.NET Framework 4.7.2及以上版本，完全覆盖旧v2 SDK的所有功能，同时有持续的bug修复、性能优化和安全更新，是当前.NET Framework场景下的官方推荐选项。

接入步骤 #

• 安装依赖
  在NuGet包管理器中搜索Microsoft.Azure.Cosmos，选择3.x分支的最新稳定版安装即可，也可以通过包管理器控制台执行安装命令：

  Install-Package Microsoft.Azure.Cosmos
  

• 单例初始化客户端
  CosmosClient是线程安全的，必须在应用启动时注册为单例复用，禁止每次请求新建实例，否则会出现连接泄漏、请求延迟飙升、连接池耗尽等问题。Web API项目可以在Global.asax中初始化全局实例，也可以通过项目自带的依赖注入容器注册单例，初始化示例：

  // 全局单例客户端
  private static readonly CosmosClient _cosmosClient = new CosmosClient(
      connectionString: "你的Cosmos DB账户连接字符串", // 也可以分别传终结点+密钥
      clientOptions: new CosmosClientOptions
      {
          ApplicationName = "你的WebAPI服务名称",
          ConnectionMode = ConnectionMode.Direct, // 服务环境允许直连端口时选Direct模式性能最优，有网络限制时可以用Gateway网关模式
          // 如需兼容项目现有Newtonsoft.Json序列化规则，可在此处配置自定义序列化器
      }
  );
  

• 初始化数据库和容器
  可以提前在Azure门户手动创建数据库、容器并配置分区键，也可以通过SDK在启动时自动创建不存在的资源：

  // 自动建库
  Database targetDb = await _cosmosClient.CreateDatabaseIfNotExistsAsync("你的业务数据库名");
  // 自动建容器，必须配置正确的分区键路径，这是Cosmos DB性能和成本控制的核心配置
  Container targetContainer = await targetDb.CreateContainerIfNotExistsAsync(
      new ContainerProperties
      {
          Id = "你的业务容器名",
          PartitionKeyPath = "/partitionKey" // 替换为业务实际的分区键路径，比如/userId、/orderId等
      },
      throughput: 400 // 按需配置初始吞吐量，生产环境根据实际负载调整
  );
  

• 基础CRUD实现
  拿到Container实例后，直接调用内置方法即可完成所有数据操作，常用操作示例：

  // 1. 新增数据
  var newItem = new YourBusinessModel { Id = Guid.NewGuid().ToString(), PartitionKey = "分区键值", /* 其他业务字段 */ };
  var createResponse = await targetContainer.CreateItemAsync(newItem, new PartitionKey(newItem.PartitionKey));
  
  // 2. 按ID查询单条数据
  var queryResponse = await targetContainer.ReadItemAsync<YourBusinessModel>(
      id: "要查询的记录ID",
      partitionKey: new PartitionKey("记录对应的分区键值")
  );
  var queriedItem = queryResponse.Resource;
  
  // 3. 更新/插入数据（Upsert：存在则更新，不存在则插入）
  var updateResponse = await targetContainer.UpsertItemAsync(updatedItem, new PartitionKey(updatedItem.PartitionKey));
  
  // 4. 删除数据
  await targetContainer.DeleteItemAsync<YourBusinessModel>(
      id: "要删除的记录ID",
      partitionKey: new PartitionKey("记录对应的分区键值")
  );
  
  // 5. 自定义条件查询
  using var feedIterator = targetContainer.GetItemQueryIterator<YourBusinessModel>(
      queryText: "SELECT * FROM c WHERE c.createTime > @startTime",
      requestOptions: new QueryRequestOptions { PartitionKey = new PartitionKey("指定查询的分区键值") },
      parameters: new List<SqlParameter> { new("@startTime", DateTimeOffset.Now.AddDays(-7)) }
  );
  List<YourBusinessModel> resultSet = new List<YourBusinessModel>();
  while (feedIterator.HasMoreResults)
  {
      var currentPage = await feedIterator.ReadNextAsync();
      resultSet.AddRange(currentPage.ToList());
  }
  

注意事项 #

• 所有点读、写入、删除操作必须传入正确的分区键值，否则会触发跨分区查询，带来数倍的性能损耗和额外RU（请求单位）消耗。
• 不要在生产代码中硬编码Cosmos DB的密钥、连接字符串，建议存放到Web.config的配置节点，通过配置管理读取。
• 高并发场景下可以根据实际压测结果调整CosmosClientOptions里的连接数、重试策略等参数，适配业务负载。

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