entity-framework/core/providers/cosmos/index.md
[!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 the Microsoft.EntityFrameworkCore.Cosmos NuGet package.
dotnet add package Microsoft.EntityFrameworkCore.Cosmos
Install-Package Microsoft.EntityFrameworkCore.Cosmos
[!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
EnsureCreatedAsyncshould 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.
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
UseCosmosmethod. 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 |
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.