The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Using the Cosmos DB Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. When you're satisfied with how your application is working in the Cosmos DB Emulator, you can switch to using an Azure Cosmos DB account in the cloud.
The Cosmos DB Emulator has the following hardware and software requirements:
- Software requirements
- Windows Server 2012 R2, Windows Server 2016, or Windows 10
- Minimum Hardware requirements
- 2 GB RAM
- 10 GB available hard disk space
You can download the Cosmos DB Emulator from the Microsoft Download Center. To install, configure, and run the Cosmos DB Emulator, you must have administrative privileges on the computer.
Note
To install, configure, and run the Cosmos DB Emulator, you must have administrative privileges on the computer.
The Cosmos DB Emulator includes a built-in Azure Cosmos DB Data Explorer to browse data stored within Cosmos DB, create new collections, and let you know when a new update is available for download.
Note
Data created in one version of the Cosmos DB Emulator is not guaranteed to be accessible when using a different version. If you need to persist your data for the long term, it is recommended that you store that data in an Azure Cosmos DB account, rather than in the Cosmos DB Emulator.
The Cosmos DB Emulator provides a high-fidelity emulation of the Cosmos DB service. It supports identical functionality as Azure Cosmos DB, including support for creating and querying JSON documents, provisioning and scaling collections, and executing stored procedures and triggers. You can develop and test applications using the Cosmos DB Emulator, and deploy them to Azure at global scale by just making a single configuration change to the connection endpoint for Cosmos DB.
While we created a high-fidelity local emulation of the actual Cosmos DB service, the implementation of the Cosmos DB Emulator is different than that of the service. For example, the Cosmos DB Emulator uses standard OS components such as the local file system for persistence, and HTTPS protocol stack for connectivity. This means that some functionality that relies on Azure infrastructure like global replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not available via the Cosmos DB Emulator.
Just as with Azure Document in the cloud, every request that you make against the Cosmos DB Emulator must be authenticated. The Cosmos DB Emulator supports a single fixed account and a well-known authentication key for master key authentication. This account and key are the only credentials permitted for use with the Cosmos DB Emulator. They are:
Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Note
The master key supported by the Cosmos DB Emulator is intended for use only with the emulator. You cannot use your production Cosmos DB account and key with the Cosmos DB Emulator.
Additionally, just as the Azure Cosmos DB service, the Cosmos DB Emulator supports only secure communication via SSL.
To start the Azure Cosmos DB Emulator, select the Start button or press the Windows key. Begin typing Cosmos DB Emulator, and select the emulator from the list of applications. When the emulator is running, you'll see an icon in the Windows taskbar notification area.
The Cosmos DB Emulator is installed by default to the C:\Program Files\Azure DocumentDB Emulator directory. You can also start and stop the emulator from the command line. Please see below for options for running the emulator from the command line.
Once you have the Cosmos DB Emulator running on your desktop, you can use any supported Cosmos DB SDK or the Cosmos DB REST API to interact with the Emulator. The Cosmos DB Emulator also includes a built-in Data Explorer that lets you create collections, view and edit documents without writing any code.
// Connect to the Cosmos DB Emulator running locally
DocumentClient client = new DocumentClient(
new Uri("https://localhost:8081"),
"C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");
You can use existing tools like DocumentDB Studio to connect to the Cosmos DB Emulator. You can also migrate data between the Cosmos DB Emulator and the Azure Cosmos DB service using the DocumentDB Data Migration Tool.
From the installation location, you can use the command line to start and stop the emulator, configure options, and perform other operations.
DocumentDB.LocalEmulator.exe [/shutdown] [/datapath] [/port] [/mongoport] [/directports] [/key] [/?]
To view the list of options, type DocumentDB.LocalEmulator.exe /? at the command prompt.
| Option | Description | Command | Arguments |
| [No arguments] | Starts up the Cosmos DB Emulator with default settings | DocumentDB.LocalEmulator.exe | |
| Shutdown | Shuts down the Cosmos DB Emulator | DocumentDB.LocalEmulator.exe /Shutdown | |
| Help | Displays the list of command line arguments | DocumentDB.LocalEmulator.exe /? | |
| Datapath | Specifies the path in which to store data files | DocumentDB.LocalEmulator.exe /datapath=<datapath> | <datapath>: An accessible path |
| Port | Specifies the port number to use for the emulator. Default is 8081 | DocumentDB.LocalEmulator.exe /port=<port> | <port>: Single port number |
| MongoPort | Specifies the port number to use for MongoDB compatibility API. Default is 10250 | DocumentDB.LocalEmulator.exe /mongoport=<mongoport> | <mongoport>: Single port number |
| DirectPorts | Specifies the ports to use for direct connectivity. Defaults are 10251,10252,10253,10254 | DocumentDB.LocalEmulator.exe /directports:<directports> | <directports>: Comma delimited list of 4 ports |
| Key | Authorization key for the emulator. Key must be the base-64 encoding of a 64-byte vector | DocumentDB.LocalEmulator.exe /key:<key> | <key>: Key must be the base-64 encoding of a 64-byte vector |
| EnableThrottling | Specifies that request throttling behavior is enabled | DocumentDB.LocalEmulator.exe /enablethrottling | |
| DisableThrottling | Specifies that request throttling behavior is disabled | DocumentDB.LocalEmulator.exe /disablethrottling |
Because the Cosmos DB Emulator provides an emulated environment running on a local developer workstation, there are some differences in functionality between the emulator and an Azure Cosmos DB account in the cloud:
- The Cosmos DB Emulator supports only a single fixed account and a well-known master key. Key regeneration is not possible in the Cosmos DB Emulator.
- The Cosmos DB Emulator is not a scalable service and will not support a large number of collections.
- The Cosmos DB Emulator does not simulate different DocumentDB consistency levels.
- The Cosmos DB Emulator does not simulate multi-region replication.
- The Cosmos DB Emulator does not support service quota overrides which may be available in the Azure Cosmos DB service (e.g. document size limits, increased partitioned collection storage).
- While the Cosmos DB Emulator will return request charges similar to the Azure Cosmos DB service, the emulator cannot be used to estimate provisioned throughput requirements for applications leveraging the Azure Cosmos DB service. To accurately estimate production throughput needs, use the Cosmos DB capacity planner.
- While the Cosmos DB Emulator persists data, the emulator cannot be used to estimate data and index storage requirements for applications leveraging the Azure Cosmos DB service. To accurately estimate production storage needs, use the Cosmos DB capacity planner.
- To learn more about Cosmos DB, see Introduction to Azure Cosmos DB
- To start developing against the Cosmos DB Emulator, download one of the supported Cosmos DB SDKs