Provedor do Azure Cosmos DB no EF Core

  • Artigo

Aviso

Um trabalho extensivo foi feito para o provedor do Azure Cosmos DB na versão 9.0. Para melhorar o provedor, uma série de alterações significativas de alto impacto tiveram que ser feitas; Se você estiver atualizando um aplicativo existente, leia a seção Alterações interruptivas com atenção.

Este provedor de banco de dados permite que o Entity Framework Core seja usado com o Azure Cosmos DB. O provedor é mantido como parte do Projeto do Entity Framework Core.

É extremamente recomendado familiarizar-se com a documentação do Azure Cosmos DB antes de ler esta seção.

Observação

Esse provedor só funciona com o Azure Cosmos DB for NoSQL.

Instalar

Instale o pacote NuGet Microsoft.EntityFrameworkCore.Cosmos.

dotnet add package Microsoft.EntityFrameworkCore.Cosmos

Introdução

Dica

Veja o exemplo deste artigo no GitHub.

Assim como para outros provedores, a primeira etapa é chamar UseCosmos:

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

Aviso

Aqui, o ponto de extremidade e a chave são embutidos no código para simplificar, mas em um aplicativo de produção, eles devem ser armazenados com segurança. Consulte Conectar e autenticar para obter diferentes maneiras de se conectar ao Azure Cosmos DB.

Neste exemplo, Order é uma entidade simples com uma referência ao tipo próprio 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; }
}

O processo de salvar e consultar dados segue o padrão de EF normal:

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

Importante

Será necessário chamar EnsureCreatedAsync para criar os contêineres obrigatórios e inserir os dados de semente (se presentes no modelo). No entanto, EnsureCreatedAsync só deve ser chamado durante a implantação, não durante a operação normal, pois isso pode causar problemas de desempenho.

O SDK do Azure Cosmos DB não dá suporte ao RBAC para operações do plano de gerenciamento no Azure Cosmos DB. Use a API de Gerenciamento do Azure em vez de EnsureCreatedAsync com RBAC.

Conectando e autenticando

O provedor do Azure Cosmos DB para EF Core tem várias sobrecargas do método UseCosmos. Essas sobrecargas dão suporte às diferentes maneiras pelas quais uma conexão pode ser feita com o banco de dados e as diferentes maneiras de garantir que a conexão seja segura.

Importante

Certifique-se de entender o acesso seguro aos dados no Azure Cosmos DB para entender as implicações de segurança e as práticas recomendadas para usar cada sobrecarga do método UseCosmos. Geralmente, o RBAC com credenciais de token é o mecanismo de controle de acesso recomendado.

Mecanismo de conexão Sobrecarga do UseCosmos Mais informações
Ponto de extremidade e chave da conta UseCosmos<DbContext>(accountEndpoint, accountKey, databaseName) Chaves primária e secundária
Ponto de extremidade e token da conta UseCosmos<DbContext>(accountEndpoint, tokenCredential, databaseName) RBAC e tokens de recurso
Cadeia de conexão UseCosmos<DbContext>(connectionString, databaseName) Trabalhar com chaves de conta e cadeias de conexão

Opções do Azure Cosmos DB

Também é possível configurar o provedor Azure Cosmos DB com uma única cadeia de conexão e especificar outras opções para personalizar a conexão:

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

O código acima mostra algumas opções possíveis - elas não devem ser usadas ao mesmo tempo. Confira a documentação de Opções do Azure Cosmos DB para obter uma descrição detalhada do efeito de cada opção mencionada acima.