通过

EF Core Azure Cosmos DB Provider

  • 项目

警告

在 9.0 版本中，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");

警告

为了简单起见，此处对终结点和密钥进行了硬编码，但在生产应用中，应安全地存储这些终结点和密钥。 有关连接到 Azure Cosmos DB 的不同方式，请参阅连接和验证。

在本例中，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 方法的每个重载的安全含义和最佳做法。

连接机制 UseCosmos 重载 详细信息
帐户终结点和密钥 UseCosmos<DbContext>(accountEndpoint, accountKey, databaseName) 主/辅助密钥
帐户终结点和令牌 UseCosmos<DbContext>(accountEndpoint, tokenCredential, databaseName) 资源令牌
连接字符串 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 选项文档。