EF Core Azure Cosmos DB Provider
警告
在 9.0 版本中，Azure Cosmos DB 提供程序已经进行了大量的工作。 为了改进提供程序，必须做出一些具有重大影响的重大更改；如果要升级现有的应用程序，请仔细阅读重大更改部分。
此数据库提供程序允许将 Entity Framework Core 与 Azure Cosmos DB 一起使用。 该提供程序作为 Entity Framework Core 项目的组成部分进行维护。
在阅读本部分之前，强烈建议先熟悉 Azure Cosmos DB 文档。
注意
此提供程序仅适用于 Azure Cosmos DB for NoSQL。
安装
安装 Microsoft.EntityFrameworkCore.Cosmos NuGet 包。
dotnet add package Microsoft.EntityFrameworkCore.Cosmos
入门
提示
可在 GitHub 示例中查看此文章的示例。
与其他提供程序一样，第一步是调用 UseCosmos：
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
=> optionsBuilder.UseCosmos(
"https://localhost:8081",
"C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
databaseName: "OrdersDB");
在本例中，Order 是一个简单实体，其中包含对从属类型 StreetAddress 的引用。
public class Order
{
public int Id { get; set; }
public int? TrackingNumber { get; set; }
public string PartitionKey { get; set; }
public StreetAddress ShippingAddress { get; set; }
}
public class StreetAddress
{
public string Street { get; set; }
public string City { get; set; }
}
保存和查询数据遵循常规 EF 模式：
using (var context = new OrderContext())
{
await context.Database.EnsureDeletedAsync();
await context.Database.EnsureCreatedAsync();
context.Add(
new Order
{
Id = 1, ShippingAddress = new StreetAddress { City = "London", Street = "221 B Baker St" }, PartitionKey = "1"
});
await context.SaveChangesAsync();
}
using (var context = new OrderContext())
{
var order = await context.Orders.FirstAsync();
Console.WriteLine($"First order will ship to: {order.ShippingAddress.Street}, {order.ShippingAddress.City}");
Console.WriteLine();
}
重要
要创建所需的容器并插入种子数据（如果存在于模型中），则需要调用 EnsureCreatedAsync。 但是只应在部署期间调用 EnsureCreatedAsync，而不应在正常操作中调用，否则可能会导致性能问题。
Azure Cosmos DB SDK 不支持在 Azure Cosmos DB 中执行管理平面操作的 RBAC。 使用 Azure 管理 API，而不是使用 EnsureCreatedAsync 与 RBAC。
连接和身份验证
EF Core 的 Azure Cosmos DB 提供程序具有 UseCosmos 方法的多个重载。 这些重载支持用不同的方式与数据库建立连接，用不同的方式来确保连接安全。
重要
请务必查看安全访问 Azure Cosmos DB 中的数据，了解使用 UseCosmos 方法的每个重载的安全含义和最佳做法。
通常，使用令牌凭据的 RBAC 是推荐的访问控制机制。
| 连接机制 | UseCosmos 重载 | 详细信息 |
|---|---|---|
| 帐户终结点和密钥 | UseCosmos<DbContext>(accountEndpoint, accountKey, databaseName) |
主/辅助密钥 |
| 帐户终结点和令牌 | UseCosmos<DbContext>(accountEndpoint, tokenCredential, databaseName) |
RBAC 和资源令牌 |
| 连接字符串 | UseCosmos<DbContext>(connectionString, databaseName) |
使用帐户密钥和连接字符串 |
Azure Cosmos DB 选项
还可以使用单个连接字符串配置 Azure Cosmos DB 提供程序，并指定其他选项来自定义连接：
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
=> optionsBuilder.UseCosmos(
"AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
databaseName: "OptionsDB",
options =>
{
options.ConnectionMode(ConnectionMode.Gateway);
options.WebProxy(new WebProxy());
options.LimitToEndpoint();
options.Region(Regions.AustraliaCentral);
options.GatewayModeMaxConnectionLimit(32);
options.MaxRequestsPerTcpConnection(8);
options.MaxTcpConnectionsPerEndpoint(16);
options.IdleTcpConnectionTimeout(TimeSpan.FromMinutes(1));
options.OpenTcpConnectionTimeout(TimeSpan.FromMinutes(1));
options.RequestTimeout(TimeSpan.FromMinutes(1));
});
上面的代码显示了一些可能的选项，这些选项不应同时使用。 有关上述每种选项的效果的详细说明，请参阅 Azure Cosmos DB 选项文档。
