共用方式為

EF Core Azure Cosmos DB 提供者

  • 發行項

警告

廣泛的工作已進入 9.0 中的 Azure Cosmos DB 提供者。 為了改善提供者，必須進行一些高度影響的變更：如果要升級現有的應用程式，請仔細閱讀重大變更一節 。

此資料庫提供者可讓 Entity Framework Core 與 Azure Cosmos DB 搭配使用。 Entity Framework Core 專案的維護包含此提供者。

強烈建議您在閱讀本節之前先熟悉 Azure Cosmos DB 文件。

注意

此提供者只適用於適用 NoSQL 的 Azure Cosmos DB。

安裝

安裝 Microsoft.EntityFrameworkCore.Cosmos NuGet 套件。

dotnet add package Microsoft.EntityFrameworkCore.Cosmos

開始使用

提示

您可以檢視本文中的 GitHut 範例。

至於其他提供者，第一步是呼叫 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，而不是具有 RBAC 的 EnsureCreatedAsync。

連線和驗證

EF Core 的 Azure Cosmos DB 提供者有多個 UseCosmos 方法的多載。 這些多載支援多種連接資料庫的方式，以及確保連接安全的不同方法。

重要

請務必了解安全存取 Azure Cosmos DB 中的資料，以了解使用 UseCosmos 方法每個多載的安全性影響和最佳做法。 一般而言，具有令牌認證的 RBAC 是建議的訪問控制機制。

連接機制 UseCosmos 多載 其他相關資訊
帳戶端點和金鑰 UseCosmos<DbContext>(accountEndpoint, accountKey, databaseName) 主要/次要金鑰
帳戶端點和權杖 UseCosmos<DbContext>(accountEndpoint, tokenCredential, databaseName) RBAC 和資源令牌
Connection string 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 選項文件。