Freigeben über

EF Core Azure Cosmos DB-Anbieter

  • Artikel

Warnung

Der Cosmos DB- Anbieter in Version 9.0 wurde umfangreich überarbeitet. Um den Anbieter zu verbessern, mussten einige wichtige Änderungen vorgenommen werden; wenn Sie eine bestehende Anwendung aktualisieren, lesen Sie bitte den Abschnitt über die Änderungen sorgfältig durch.

Dieser Datenbankanbieter ermöglicht die Verwendung von Entity Framework Core mit Azure Cosmos DB. Dieser Anbieter wird nicht im Rahmen des Entity Framework Core-Projekts verwaltet.

Es wird dringend empfohlen, sich vor dem Lesen dieses Abschnitts mit der Azure Cosmos DB-Dokumentation vertraut zu machen.

Hinweis

Dieser Anbieter funktioniert nur mit Azure Cosmos DB for NoSQL.

Installieren

Installieren Sie das NuGet-Paket „Microsoft.EntityFrameworkCore.Cosmos“.

dotnet add package Microsoft.EntityFrameworkCore.Cosmos

Erste Schritte

Tipp

Das in diesem Artikel verwendete Beispiel finden Sie auf GitHub.

Wie bei anderen Anbietern besteht der erste Schritt darin, UseCosmos aufzurufen:

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    => optionsBuilder.UseCosmos(
        "https://localhost:8081",
        "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
        databaseName: "OrdersDB");

Warnung

Der Endpunkt und der Schlüssel sind aus Gründen der Einfachheit hier hartcodiert, aber in einer Produktions-App sollten sie sicher gespeichert werden. Unter Verbinden und Authentifizieren finden Sie verschiedene Möglichkeiten zum Herstellen einer Verbindung mit Azure Cosmos DB.

In diesem Beispiel ist Order eine einfache Entität mit einem Verweis auf den nicht eigenständigen Typ 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; }
}

Das Speichern und Abfragen von Daten folgt dem normalen EF-Muster:

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();
}

Wichtig

Der Aufruf von EnsureCreatedAsync ist erforderlich, um die erforderlichen Container zu erstellen und die Seeddaten einzufügen, wenn Sie im Modell vorhanden sind. EnsureCreatedAsync sollte jedoch nur während der Bereitstellung und nicht im normalen Betrieb aufgerufen werden, da dies zu Leistungsproblemen führen kann.

Das Azure Cosmos DB SDK unterstützt RBAC für die Vorgänge der Verwaltungsebene in Azure Cosmos DB nicht. Verwenden Sie die Azure Management API anstelle von EnsureCreatedAsync mit RBAC.

Verbinden und Authentifizieren

Der Azure Cosmos DB-Anbieter für EF Core verfügt über mehrere Überladungen der UseCosmos-Methode. Diese Überladungen unterstützen die verschiedenen Möglichkeiten, eine Verbindung mit der Datenbank herzustellen, und eine sichere Verbindung zu gewährleisten.

Wichtig

Stellen Sie sicher, dass Sie sich mit sicherem Zugriff auf Daten in Azure Cosmos DB auskennen, um die Sicherheitsauswirkungen und bewährten Methoden für das Verwenden aller Überladung der UseCosmos-Methode zu verstehen.

Verbindungsmechanismus UseCosmos-Überladung Weitere Informationen
Kontoendpunkt und -schlüssel UseCosmos<DbContext>(accountEndpoint, accountKey, databaseName) Primäre/sekundäre Schlüssel
Kontoendpunkt und -token UseCosmos<DbContext>(accountEndpoint, tokenCredential, databaseName) Ressourcentoken
Verbindungszeichenfolge UseCosmos<DbContext>(connectionString, databaseName) Arbeiten mit Kontoschlüsseln und Verbindungszeichenfolgen

Azure Cosmos DB-Optionen

Es ist auch möglich, den Azure Cosmos DB-Anbieter mit einer einzelnen Verbindungszeichenfolge zu konfigurieren und andere Optionen zum Anpassen der Verbindung anzugeben:

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));
        });

Der obige Code zeigt einige mögliche Optionen – diese sind nicht für die gleichzeitige Verwendung vorgesehen. In der Dokumentation zu Azure Cosmos DB-Optionen finden Sie eine ausführliche Beschreibung der Auswirkungen der einzelnen oben genannten Optionen.