Introduction
When developing applications that use Azure Cosmos DB, having a local development environment is essential. Developers often need a way to test queries, validate data models, and build features without connecting to a live Azure subscription. This is where the Azure Cosmos DB Emulator becomes valuable.
For years, the Cosmos DB Emulator was primarily available for Windows, making local development more challenging for developers working on Linux, macOS, containers, and cloud-native environments. The Azure Cosmos DB Linux Emulator addresses this gap by providing a container-based solution that enables developers to run Cosmos DB locally across platforms.
In this article, you'll learn what the Azure Cosmos DB Linux Emulator is, its benefits, how to get started, key limitations, and best practices for using it effectively in .NET applications.
What Is the Azure Cosmos DB Linux Emulator?
The Azure Cosmos DB Linux Emulator is a containerized version of the Cosmos DB Emulator that runs on Linux environments using Docker.
It provides a local instance of Azure Cosmos DB that developers can use for:
Local application development
Testing data access code
Learning Cosmos DB concepts
Continuous Integration (CI) workflows
Containerized development environments
The emulator allows developers to interact with Cosmos DB APIs without incurring Azure costs or requiring an internet connection.
From the application's perspective, the emulator behaves similarly to a real Cosmos DB account, making it easier to develop and test locally before deployment.
Why the Linux Emulator Matters
Modern development teams increasingly use:
The traditional Windows-only emulator created challenges for teams working in these environments.
The Linux Emulator offers several advantages:
Cross-Platform Development
Developers using Linux, macOS, or Windows can now work with a consistent local database experience.
Better Container Support
Since the emulator runs as a container, it integrates naturally into modern containerized workflows.
Simplified Team Collaboration
Teams no longer need different development approaches based on operating systems.
Improved CI/CD Testing
Automated pipelines can run integration tests against a local Cosmos DB instance without requiring cloud resources.
Running the Linux Emulator
The Linux Emulator is distributed as a Docker container.
A typical command looks like this:
docker run \
-p 8081:8081 \
-p 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator
Once the container starts, the emulator exposes local endpoints that applications can connect to.
Because it runs inside Docker, setup is generally faster and more portable than traditional installation-based approaches.
Developers can include the emulator directly in development environments and automated testing workflows.
Connecting a .NET Application
Connecting to the Linux Emulator is similar to connecting to a production Cosmos DB account.
Install the Azure Cosmos DB SDK:
dotnet add package Microsoft.Azure.Cosmos
Create a Cosmos client:
using Microsoft.Azure.Cosmos;
string endpoint =
"https://localhost:8081";
string key =
"YOUR_EMULATOR_KEY";
var client = new CosmosClient(
endpoint,
key);
The SDK interacts with the emulator in the same way it would interact with an Azure-hosted Cosmos DB account.
This allows developers to validate application behavior locally before deployment.
Creating a Database and Container
One of the first tasks when working with Cosmos DB is creating databases and containers.
Example:
var database =
await client.CreateDatabaseIfNotExistsAsync(
"ProductCatalog");
var container =
await database.Database
.CreateContainerIfNotExistsAsync(
"Products",
"/category");
This creates:
A database named ProductCatalog
A container named Products
A partition key based on category
Running these operations locally helps developers verify schema and partitioning decisions early in the development process.
Working with Data
Let's create a simple product model.
public class Product
{
public string Id { get; set; } = Guid.NewGuid().ToString();
public string Name { get; set; } = string.Empty;
public string Category { get; set; } = string.Empty;
public decimal Price { get; set; }
}
Insert data into the container:
var product = new Product
{
Name = "Laptop",
Category = "Electronics",
Price = 50000
};
await container.CreateItemAsync(
product,
new PartitionKey(product.Category));
The emulator stores data locally, allowing developers to test CRUD operations without affecting production resources.
Querying Data
Query testing is one of the most common development tasks.
Example query:
var query =
new QueryDefinition(
"SELECT * FROM c WHERE c.category = @category")
.WithParameter("@category", "Electronics");
var iterator =
container.GetItemQueryIterator<Product>(query);
while (iterator.HasMoreResults)
{
var response =
await iterator.ReadNextAsync();
foreach (var item in response)
{
Console.WriteLine(item.Name);
}
}
Using the emulator, developers can validate query behavior and optimize data access patterns before deployment.
Key Limitations to Understand
Although the Linux Emulator is extremely useful, it is not a complete replacement for Azure Cosmos DB.
Developers should be aware of several limitations.
| Feature | Production Cosmos DB | Linux Emulator |
|---|
| Local Development | No | Yes |
| Multi-Region Replication | Yes | No |
| Global Distribution | Yes | No |
| High Availability Testing | Yes | Limited |
| Production Scale Testing | Yes | No |
| Offline Development | No | Yes |
The emulator is intended for development and testing rather than production-scale validation.
Performance characteristics may differ from those in Azure.
Best Practices
Use the Emulator Early
Start development with the emulator rather than waiting until cloud resources are available.
This accelerates development and reduces costs.
Match Production Configurations
Where possible, use:
This helps reduce surprises when deploying to Azure.
Include Emulator Testing in CI Pipelines
Container-based execution makes the Linux Emulator ideal for automated integration testing.
Testing data access logic during builds improves application reliability.
Avoid Performance Assumptions
The emulator is not designed for performance benchmarking.
Always validate large-scale workloads against actual Azure Cosmos DB environments.
Manage Test Data Carefully
Use realistic sample datasets when validating queries and partitioning strategies.
Small datasets may hide scalability issues that become visible in production.
Common Use Cases
The Linux Emulator is particularly useful for:
ASP.NET Core applications
Microservices development
Local API testing
Containerized development environments
Automated integration testing
Learning Azure Cosmos DB
Proof-of-concept projects
Developers can iterate quickly without provisioning cloud resources for every experiment.
Conclusion
The Azure Cosmos DB Linux Emulator is a significant improvement for developers building modern cloud-native applications. By providing a cross-platform, container-based development experience, it removes many of the barriers that previously existed for Linux and container-focused workflows.
For .NET developers, the emulator enables local testing of databases, containers, queries, and CRUD operations using the same SDKs and programming patterns used in production. While it does not replace real-world testing against Azure Cosmos DB, it serves as an excellent tool for development, learning, and integration testing.
If your applications depend on Azure Cosmos DB, incorporating the Linux Emulator into your development workflow can improve productivity, reduce costs, and help catch issues earlier in the development lifecycle.