| title | description | services | documentationcenter | keywords | author | manager | editor | ms.assetid | ms.service | ms.devlang | ms.topic | ms.tgt_pltfrm | ms.workload | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Develop locally with the DocumentDB Emulator | Microsoft Docs |
Using the DocumentDB Emulator, you can develop and test your application locally for free, without creating an Azure subscription. |
documentdb |
DocumentDB Emulator |
arramac |
jhubbard |
90b379a6-426b-4915-9635-822f1a138656 |
documentdb |
multiple |
article |
na |
na |
01/30/2017 |
arramac |
The Azure DocumentDB Emulator provides a local environment that emulates the Azure DocumentDB service for development purposes. Using the DocumentDB 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 DocumentDB Emulator, you can switch to using an Azure DocumentDB account in the cloud.
We recommend getting started by watching the following video, where Kirill Gavrylyuk shows how to get started with the DocumentDB Emulator.
[!VIDEO https://channel9.msdn.com/Events/Connect/2016/192/player]
The DocumentDB 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 and install the DocumentDB Emulator from the Microsoft Download Center.
Note
To install, configure, and run the DocumentDB Emulator, you must have administrative privileges on the computer.
The DocumentDB Emulator includes a built-in Azure DocumentDB Data Explorer to browse data stored within DocumentDB, create new collections, and let you know when a new update is available for download.
Note
Data created in one version of the DocumentDB 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 DocumentDB account, rather than in the DocumentDB Emulator.
The DocumentDB Emulator provides a high-fidelity emulation of the DocumentDB service. It supports identical functionality as Azure DocumentDB, 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 DocumentDB Emulator, and deploy them to Azure at global scale by just making a single configuration change to the connection endpoint for DocumentDB.
While we created a high-fidelity local emulation of the actual DocumentDB service, the implementation of the DocumentDB Emulator is different than that of the service. For example, the DocumentDB 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 DocumentDB Emulator.
Just as with Azure Document in the cloud, every request that you make against the DocumentDB Emulator must be authenticated. The DocumentDB 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 DocumentDB Emulator. They are:
Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Note
The master key supported by the DocumentDB Emulator is intended for use only with the emulator. You cannot use your production DocumentDB account and key with the DocumentDB Emulator.
Additionally, just as the Azure DocumentDB service, the DocumentDB Emulator supports only secure communication via SSL.
To start the Azure DocumentDB Emulator, select the Start button or press the Windows key. Begin typing DocumentDB 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 DocumentDB Emulator by default runs on the local machine ("localhost") listening on port 8081.
The DocumentDB Emulator is installed by default to the C:\Program Files\DocumentDB Emulator directory. You can also start and stop the emulator from the command-line. See command-line tool reference for more information.
When the DocumentDB emulator launches it will automatically open the DocumentDB Data Explorer in your browser. The address will appear as https://localhost:8081/_explorer/index.html. If you close the explorer and would like to re-open it later, you can either open the URL in your browser or launch it from the DocumentDB Emulator in the Windows Tray Icon as shown below.
Once you have the DocumentDB Emulator running on your desktop, you can use any supported DocumentDB SDK or the DocumentDB REST API to interact with the Emulator. The DocumentDB Emulator also includes a built-in Data Explorer that lets you create collections, view and edit documents without writing any code.
// Connect to the DocumentDB Emulator running locally
DocumentClient client = new DocumentClient(
new Uri("https://localhost:8081"),
"C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");
If you're using DocumentDB protocol support for MongoDB, please use the following connection string:
mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10250/admin?ssl=true&3t.sslSelfSignedCerts=true
You can use existing tools like DocumentDB Studio to connect to the DocumentDB Emulator. You can also migrate data between the DocumentDB Emulator and the Azure DocumentDB service using the DocumentDB Data Migration Tool.
Using the DocumentDB emulator, by default, you can create up to 25 single partition collections or 1 partitioned collection. For more information about changing this value, see Setting the PartitionCount value.
.NET languages and runtime use the Windows Certificate Store to securely connect to the DocumentDB local emulator. Other languages have their own method of managing and using certificates. Java uses its own certificate store whereas Python uses socket wrappers.
In order to obtain a certificate to use with languages and runtimes that do not integrate with the Windows Certificate Store you will need to export it using the Windows Certificate Manager. You can start it by running certlm.msc or follow the step by step instructions in Export the DocumentDB Emulator Certificates. Once the certificate manager is running, open the Personal Certificates as shown below and export the certificate with the friendly name "DocumentDBEmulatorCertificate" as a BASE-64 encoded X.509 (.cer) file.
The X.509 certificate can be imported into the Java certificate store by following the instructions in Adding a Certificate to the Java CA Certificates Store. Once the certificate is imported into the cacerts store Java and MongoDB applications will be able to connect to the DocumentDB Emulator.
When connecting to the emulator from Python and Node.js SDKs, SSL verification is disabled.
From the installation location, you can use the command-line to start and stop the emulator, configure options, and perform other operations.
DocumentDB.Emulator.exe [/Shutdown] [/DataPath] [/Port] [/MongoPort] [/DirectPorts] [/Key] [/EnableRateLimiting] [/DisableRateLimiting] [/NoUI] [/NoExplorer] [/?]
To view the list of options, type DocumentDB.Emulator.exe /? at the command prompt.
| Option | Description | Command | Arguments |
| [No arguments] | Starts up the DocumentDB Emulator with default settings. | DocumentDB.Emulator.exe | |
| [Help] | Displays the list of supported command-line arguments. | DocumentDB.Emulator.exe /? | |
| Shutdown | Shuts down the DocumentDB Emulator. | DocumentDB.Emulator.exe /Shutdown | |
| DataPath | Specifies the path in which to store data files. Default is %LocalAppdata%\DocumentDBEmulator. | DocumentDB.Emulator.exe /DataPath=<datapath> | <datapath>: An accessible path |
| Port | Specifies the port number to use for the emulator. Default is 8081. | DocumentDB.Emulator.exe /Port=<port> | <port>: Single port number |
| MongoPort | Specifies the port number to use for MongoDB compatibility API. Default is 10250. | DocumentDB.Emulator.exe /MongoPort=<mongoport> | <mongoport>: Single port number |
| DirectPorts | Specifies the ports to use for direct connectivity. Defaults are 10251,10252,10253,10254. | DocumentDB.Emulator.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.Emulator.exe /Key:<key> | <key>: Key must be the base-64 encoding of a 64-byte vector |
| EnableRateLimiting | Specifies that request rate limiting behavior is enabled. | DocumentDB.Emulator.exe /EnableRateLimiting | |
| DisableRateLimiting | Specifies that request rate limiting behavior is disabled. | DocumentDB.Emulator.exe /DisableRateLimiting | |
| NoUI | Do not show the emulator user interface. | DocumentDB.Emulator.exe /NoUI | |
| NoExplorer | Don't show document explorer on startup. | DocumentDB.Emulator.exe /NoExplorer | |
| PartitionCount | Specifies the maximum number of partitioned collections. See [Change the number of collections](#set-partitioncount) for more information. | DocumentDB.Emulator.exe /PartitionCount=<partitioncount> | <partitioncount>: Maximum number of allowed single partition collections. Default is 25. Maximum allowed is 250. |
Because the DocumentDB Emulator provides an emulated environment running on a local developer workstation, there are some differences in functionality between the emulator and an Azure DocumentDB account in the cloud:
- The DocumentDB Emulator supports only a single fixed account and a well-known master key. Key regeneration is not possible in the DocumentDB Emulator.
- The DocumentDB Emulator is not a scalable service and will not support a large number of collections.
- The DocumentDB Emulator does not simulate different DocumentDB consistency levels.
- The DocumentDB Emulator does not simulate multi-region replication.
- The DocumentDB Emulator does not support the service quota overrides that are available in the Azure DocumentDB service (e.g. document size limits, increased partitioned collection storage).
- As your copy of the DocumentDB Emulator might not be up to date with the most recent changes with the Azure DocumentDB service, please DocumentDB capacity planner to accurately estimate production throughput (RUs) needs of your application.
By default, you can create up to 25 single partition collections, or 1 partitioned collection using the DocumentDB Emulator. By modifying the PartitionCount value, you can create up to 250 single partition collections or 10 partitioned collections, or any combination of the two that does not exceed 250 single partitions (where 1 partitioned collection = 25 single partition collection).
If you attempt to create a collection after the current partition count has been exceeded, the emulator throws a ServiceUnavailable exception, with the following message.
Sorry, we are currently experiencing high demand in this region,
and cannot fulfill your request at this time. We work continuously
to bring more and more capacity online, and encourage you to try again.
Please do not hesitate to email [email protected] at any time or
for any reason. ActivityId: 29da65cc-fba1-45f9-b82c-bf01d78a1f91
To change the number of collections available to the DocumentDB Emulator, do the following:
- Delete all local DocumentDB Emulator data by right-clicking the DocumentDB Emulator icon on the system tray, and then clicking Reset Data….
- Delete all emulator data in this folder C:\Users\user_name\AppData\Local\DocumentDBEmulator.
- Exit all open instances by right-clicking the DocumentDB Emulator icon on the system tray, and then clicking Exit. It may take a minute for all instances to exit.
- Install the latest version of the DocumentDB Emulator.
- Launch the emulator with the PartitionCount flag by setting a value <= 250. For example:
C:\Program Files\DocumentDB Emulator>DocumentDB.Emulator.exe /PartitionCount=100.
Use the following tips to help troubleshoot issues you encounter with the DocumentDB emulator:
-
If the DocumentDB emulator crashes, collect dump files from c:\Users\user_name\AppData\Local\CrashDumps folder, compress them, and attach them to an email to [email protected].
-
If you encounter a connectivity issue, collect trace files, compress them, and attach them to an email to [email protected].
To collect debugging traces, run the following commands from an administrative command prompt:
cd /d "%ProgramFiles%\DocumentDB Emulator"DocumentDB.Emulator.exe /shutdown. Watch the system tray to make sure the program has shut down, it may take a minute. You can also just click Exit in the DocumentDB emulator user interface.DocumentDB.Emulator.exe /starttracesDocumentDB.Emulator.exe- Reproduce the problem. If Data Explorer is not working, you only need to wait for the browser to open for a few seconds to catch the error.
DocumentDB.Emulator.exe /stoptraces- Navigate to
%ProgramFiles%\DocumentDB Emulatorand find the docdbemulator_000001.etl file. - Send the .etl file along with repro steps to [email protected] for debugging.
- To learn more about DocumentDB, see Introduction to Azure DocumentDB
- To start developing against the DocumentDB Emulator, download one of the supported DocumentDB SDKs.