Aspire.Microsoft.Azure.Cosmos
9.0.0
Prefix Reserved
dotnet add package Aspire.Microsoft.Azure.Cosmos --version 9.0.0
NuGet\Install-Package Aspire.Microsoft.Azure.Cosmos -Version 9.0.0
<PackageReference Include="Aspire.Microsoft.Azure.Cosmos" Version="9.0.0" />
paket add Aspire.Microsoft.Azure.Cosmos --version 9.0.0
#r "nuget: Aspire.Microsoft.Azure.Cosmos, 9.0.0"
// Install Aspire.Microsoft.Azure.Cosmos as a Cake Addin #addin nuget:?package=Aspire.Microsoft.Azure.Cosmos&version=9.0.0 // Install Aspire.Microsoft.Azure.Cosmos as a Cake Tool #tool nuget:?package=Aspire.Microsoft.Azure.Cosmos&version=9.0.0
Aspire.Microsoft.Azure.Cosmos library
Registers CosmosClient as a singleton in the DI container for connecting to Azure Cosmos DB. Enables corresponding logging and telemetry.
Getting started
Prerequisites
- Azure subscription - create one for free
- Azure Cosmos DB account - create a Cosmos DB account
Install the package
Install the .NET Aspire Microsoft Azure Cosmos DB library with NuGet:
dotnet add package Aspire.Microsoft.Azure.Cosmos
Usage example
In the Program.cs file of your project, call the AddAzureCosmosClient
extension method to register a CosmosClient
for use via the dependency injection container. The method takes a connection name parameter.
builder.AddAzureCosmosClient("cosmosConnectionName");
You can then retrieve the CosmosClient
instance using dependency injection. For example, to retrieve the client from a Web API controller:
private readonly CosmosClient _client;
public ProductsController(CosmosClient client)
{
_client = client;
}
See the Azure Cosmos DB documentation for examples on using the CosmosClient
.
Configuration
The .NET Aspire Azure Cosmos DB library provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project. Note that either an AccountEndpoint
or a ConnectionString
is a required to be supplied.
Use a connection string
When using a connection string from the ConnectionStrings
configuration section, you can provide the name of the connection string when calling builder.AddAzureCosmosClient()
:
builder.AddAzureCosmosClient("cosmosConnectionName");
And then the connection string will be retrieved from the ConnectionStrings
configuration section. Two connection formats are supported:
Account Endpoint
The recommended approach is to use an AccountEndpoint, which works with the MicrosoftAzureCosmosSettings.Credential
property to establish a connection. If no credential is configured, the DefaultAzureCredential is used.
{
"ConnectionStrings": {
"cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
}
}
Connection string
Alternatively, an Azure Cosmos DB connection string can be used.
{
"ConnectionStrings": {
"cosmosConnectionName": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
}
}
Use configuration providers
The .NET Aspire Microsoft Azure Cosmos DB library supports Microsoft.Extensions.Configuration. It loads the MicrosoftAzureCosmosSettings
and QueueClientOptions
from configuration by using the Aspire:Microsoft:Azure:Cosmos
key. Example appsettings.json
that configures some of the options:
{
"Aspire": {
"Microsoft": {
"Azure": {
"Cosmos": {
"DisableTracing": false,
}
}
}
}
}
Use inline delegates
You can also pass the Action<MicrosoftAzureCosmosSettings> configureSettings
delegate to set up some or all the options inline, for example to disable tracing from code:
builder.AddAzureCosmosClient("cosmosConnectionName", settings => settings.DisableTracing = true);
You can also setup the CosmosClientOptions using the optional Action<CosmosClientOptions> configureClientOptions
parameter of the AddAzureCosmosClient
method. For example, to set the ApplicationName
"User-Agent" header suffix for all requests issues by this client:
builder.AddAzureCosmosClient("cosmosConnectionName", configureClientOptions: clientOptions => clientOptions.ApplicationName = "myapp");
AppHost extensions
In your AppHost project, install the Aspire Azure CosmosDB Hosting library with NuGet:
dotnet add package Aspire.Hosting.Azure.CosmosDB
Then, in the Program.cs file of AppHost
, add a Cosmos DB connection and consume the connection using the following methods:
var cosmosdb = builder.ExecutionContext.IsPublishMode
? builder.AddAzureCosmosDB("cdb").AddDatabase("cosmosdb")
: builder.AddConnectionString("cosmosdb");
var myService = builder.AddProject<Projects.MyService>()
.WithReference(cosmosdb);
The AddAzureCosmosDB
method will add an Azure Cosmos DB resource to the builder. Or AddConnectionString
can be used to read connection information from the AppHost's configuration (for example, from "user secrets") under the ConnectionStrings:cosmosdb
config key. The WithReference
method passes that connection information into a connection string named cosmosdb
in the MyService
project. In the Program.cs file of MyService
, the connection can be consumed using:
builder.AddAzureCosmosClient("cosmosdb");
Emulator usage
Aspire supports the usage of the Azure Cosmos DB emulator to use the emulator, add the following to your AppHost project:
// AppHost
var cosmosdb = builder.AddAzureCosmosDB("cosmos").RunAsEmulator();
When the AppHost starts up a local container running the Azure CosmosDB will also be started:
// Service code
builder.AddAzureCosmosClient("cosmos");
Additional documentation
- https://learn.microsoft.com/azure/cosmos-db/nosql/sdk-dotnet-v3
- https://github.com/dotnet/aspire/tree/main/src/Components/README.md
Feedback & contributing
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Azure.Core (>= 1.44.1)
- Azure.Identity (>= 1.13.1)
- Microsoft.Azure.Cosmos (>= 3.45.0)
- Microsoft.Extensions.Configuration.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 8.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Hosting.Abstractions (>= 8.0.1)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Options (>= 8.0.2)
- Microsoft.Extensions.Primitives (>= 8.0.0)
- Newtonsoft.Json (>= 13.0.3)
- OpenTelemetry.Extensions.Hosting (>= 1.9.0)
- System.Text.Json (>= 8.0.5)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Aspire.Microsoft.Azure.Cosmos:
Package | Downloads |
---|---|
Hexalith.Infrastructure.AspireService.Hosting
Hexalith is a set of libraries to build a micro-service architecture. |
|
Sekiban.Aspire.Infrastructure.Cosmos
Sekiban - Event Sourcing Framework Cosmos Aspire Connector |
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on Aspire.Microsoft.Azure.Cosmos:
Repository | Stars |
---|---|
J-Tech-Japan/Sekiban
Sekiban - an Opinionated Event Sourcing and CQRS Framework using C#. It can store data into Azure Cosmos DB, AWS Dynamo DB or Postgres
|
Version | Downloads | Last updated |
---|---|---|
9.0.0 | 6,263 | 11/12/2024 |
9.0.0-rc.1.24511.1 | 1,362 | 10/15/2024 |
8.2.2 | 8,552 | 10/24/2024 |
8.2.1 | 13,850 | 9/26/2024 |
8.2.0 | 12,539 | 8/29/2024 |
8.1.0 | 6,063 | 7/23/2024 |
8.0.2 | 4,315 | 6/28/2024 |
8.0.1 | 11,442 | 5/21/2024 |
8.0.0 | 410 | 5/21/2024 |
8.0.0-preview.7.24251.11 | 925 | 5/7/2024 |
8.0.0-preview.6.24214.1 | 711 | 4/23/2024 |
8.0.0-preview.5.24201.12 | 840 | 4/9/2024 |
8.0.0-preview.4.24156.9 | 881 | 3/12/2024 |
8.0.0-preview.3.24105.21 | 2,168 | 2/13/2024 |
8.0.0-preview.2.23619.3 | 1,334 | 12/20/2023 |
8.0.0-preview.1.23557.2 | 906 | 11/14/2023 |