Skip to content

Latest commit

 

History

History
85 lines (55 loc) · 5.35 KB

index.md

File metadata and controls

85 lines (55 loc) · 5.35 KB
Raw
title description author ms.date uid
Azure Cosmos DB Provider - EF Core
Documentation for the database provider that allows Entity Framework Core to be used with Azure Cosmos DB.
AndriySvyryd
02/12/2023
core/providers/cosmos/index

EF Core Azure Cosmos DB Provider

Warning

Extensive work has gone into the Azure Cosmos DB provider in 9.0. In order to improve the provider, a number of high-impact breaking changes had to be made; if you are upgrading an existing application, please read the breaking changes section carefully.

This database provider allows Entity Framework Core to be used with Azure Cosmos DB. The provider is maintained as part of the Entity Framework Core Project.

It is strongly recommended to familiarize yourself with the Azure Cosmos DB documentation before reading this section.

Note

This provider only works with Azure Cosmos DB for NoSQL.

Install

Install the Microsoft.EntityFrameworkCore.Cosmos NuGet package.

.NET Core CLI

dotnet add package Microsoft.EntityFrameworkCore.Cosmos

Visual Studio

Install-Package Microsoft.EntityFrameworkCore.Cosmos

Get started

Tip

You can view this article's sample on GitHub.

As for other providers the first step is to call UseCosmos:

[!code-csharpConfiguration]

Warning

The endpoint and key are hardcoded here for simplicity, but in a production app these should be stored securely. See Connecting and authenticating for different ways to connect to Azure Cosmos DB.

In this example Order is a simple entity with a reference to the owned type StreetAddress.

[!code-csharpOrder]

[!code-csharpStreetAddress]

Saving and querying data follows the normal EF pattern:

[!code-csharpHelloCosmos]

Important

Calling EnsureCreatedAsync is necessary to create the required containers and insert the seed data if present in the model. However EnsureCreatedAsync should only be called during deployment, not normal operation, as it may cause performance issues.

Azure Cosmos DB SDK does not support RBAC for management plane operations in Azure Cosmos DB. Use Azure Management API instead of EnsureCreatedAsync with RBAC.

Connecting and authenticating

The Azure Cosmos DB provider for EF Core has multiple overloads of the UseCosmos method. These overloads support the different ways that a connection can be made to the database, and the different ways of ensuring that the connection is secure.

Important

Make sure to understand Secure access to data in Azure Cosmos DB to understand the security implications and best practices for using each overload of the UseCosmos method. Generally, RBAC with token credentials is the recommended access-control mechanism.

Connection Mechanism UseCosmos Overload More information
Account endpoint and key UseCosmos<DbContext>(accountEndpoint, accountKey, databaseName) Primary/secondary keys
Account endpoint and token UseCosmos<DbContext>(accountEndpoint, tokenCredential, databaseName) RBAC and Resource tokens
Connection string UseCosmos<DbContext>(connectionString, databaseName) Work with account keys and connection strings

Azure Cosmos DB options

It is also possible to configure the Azure Cosmos DB provider with a single connection string and to specify other options to customize the connection:

[!code-csharpConfiguration]

The code above shows some possible options - these are not intended to be used at the same time. See the Azure Cosmos DB Options documentation for a detailed description of the effect of each option mentioned above.