Get started with Azure Cosmos DB for MongoDB using .NET
APPLIES TO: MongoDB
This article shows you how to connect to Azure Cosmos DB for MongoDB using .NET Core and the relevant NuGet packages. Once connected, you can perform operations on databases, collections, and documents.
Note
The example code snippets are available on GitHub as a .NET Core project.
API for MongoDB reference documentation | MongoDB Package (NuGet)
Prerequisites
- An Azure account with an active subscription. Create an account for free.
- .NET 6.0
- Azure Command-Line Interface (CLI) or Azure PowerShell
- Azure Cosmos DB for MongoDB resource
Create a new .NET Core app
Create a new .NET Core application in an empty folder using your preferred terminal. For this scenario, you'll use a console application. Use the
dotnet new
command to create and name the console app.dotnet new console -o app
Add the MongoDB NuGet package to the console project. Use the
dotnet add package
command specifying the name of the NuGet package.dotnet add package MongoDB.Driver
To run the app, use a terminal to navigate to the application directory and run the application.
dotnet run
Connect to Azure Cosmos DB for MongoDB with the MongoDB native driver
To connect to Azure Cosmos DB with the MongoDB native driver, create an instance of the MongoClient
class. This class is the starting point to perform all operations against MongoDb databases. The most common constructor for MongoClient accepts a connection string, which you can retrieve using the following steps:
Get resource name
Create a shell variable for resourceGroupName.
# Variable for resource group name resourceGroupName="msdocs-cosmos"
Use the
az cosmosdb list
command to retrieve the name of the first Azure Cosmos DB account in your resource group and store it in the accountName shell variable.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Retrieve your connection string
Find the API for MongoDB connection string from the list of connection strings for the account with the
az cosmosdb keys list
command.az cosmosdb keys list --type connection-strings \ --resource-group $resourceGroupName \ --name $accountName
Record the PRIMARY KEY values. You'll use these credentials later.
Configure environment variables
To use the CONNECTION STRING values within your code, set this value in the local environment running the application. To set the environment variable, use your preferred terminal to run the following commands:
$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"
Create MongoClient with connection string
Define a new instance of the MongoClient
class using the constructor and the connection string variable you set previously.
// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));
var settings = client.Settings;
Console.WriteLine(settings.Server.Host);
Use the MongoDB client classes with Azure Cosmos DB for API for MongoDB
Before you start building the application, let's look into the hierarchy of resources in Azure Cosmos DB. Azure Cosmos DB has a specific object model used to create and access resources. The Azure Cosmos DB creates resources in a hierarchy that consists of accounts, databases, collections, and docs.
Hierarchical diagram showing an Azure Cosmos DB DB account at the top. The account has two child database nodes. One of the database nodes includes two child collection nodes. The other database node includes a single child collection node. That single collection node has three child doc nodes.
Each type of resource is represented by one or more associated C# classes. Here's a list of the most common classes:
Class | Description |
---|---|
MongoClient |
This class provides a client-side logical representation for the API for MongoDB layer on Azure Cosmos DB. The client object is used to configure and execute requests against the service. |
MongoDatabase |
This class is a reference to a database that may, or may not, exist in the service yet. The database is validated or created server-side when you attempt to perform an operation against it. |
Collection |
This class is a reference to a collection that also may not exist in the service yet. The collection is validated server-side when you attempt to work with it. |
The following guides show you how to use each of these classes to build your application and manage data.
Guide:
See also
Next steps
Now that you've connected to an API for MongoDB account, use the next guide to create and manage databases.