Getting Started with DocumentDB Emulator Development

To start developing with the DocumentDB Emulator, you'll first need to download and install the emulator. The DocumentDB Emulator can be downloaded from the Azure website.

The emulator supports the same data model as DocumentDB, which means you can use the same code to interact with your local emulator as you would with a live DocumentDB database. This makes it easy to get started and test your applications.

You can run the emulator on your local machine and interact with it using the Azure Cosmos DB .NET SDK. The emulator provides a local endpoint for your application to connect to, allowing you to test and develop your application without incurring costs or affecting your production database.

To get started with the Azure DocumentDB Local Quick Start, you can download and install the local emulator, which is currently only available for Windows, but the team is looking for cross-platform solutions.

The local emulator is a great tool, and it's even more impressive that it comes with a nice web page that pops up in your web browser after installation, guiding you through the quick start process.

The current release is 0.1.0, which is still an alpha level release, so you might encounter some issues, like the sample package name not lining up, requiring a simple package name change to get it working.

The local Emulator also includes a web-based local Data Explorer, which is a useful feature for exploring and managing your data.

The repository itself is not overly complex, with only around 120 lines of code, which can be condensed to about 60 lines when removing whitespace and curly braces.

The DocumentDB Emulator is free and doesn't require a sign-in. It's essentially the same core engine code as the one running in Azure, with changes like using the local file system for persistence.

To get started, you'll need to download and install the emulator. The good news is that it's available for various platforms, including Windows, macOS, and Linux.

The emulator is designed to mimic the behavior of the Azure DocumentDB service, allowing you to test and develop your applications locally. This means you can use the same code and APIs as you would in a production environment.

Here are the key benefits of using the DocumentDB Emulator:

Azure Cosmos DB supports multiple APIs, including SQL API, Table, MongoDB, Cassandra, and Gremlin, which makes it a versatile choice for various scenarios, such as migrating an existing database or creating a new one.

The Azure Cosmos DB Emulator also supports these APIs, allowing you to focus on adding value to your team or organisation without worrying about underlying implementation details.

However, keep in mind that the data explorer provided with the service only supports SQL API at the moment, so you may need to use a different tool for other APIs.

The DocumentDB Emulator has its own set of limitations, including only supporting a single fixed account and a well-known master key, and not simulating different DocumentDB consistency levels or multi-region replication.

You can install the emulator on a different system via the installer or Chocolatey to avoid these problems.

To connect to the emulator from a different system, you'll need to export the emulator's public SSL certificate and add it to the trusted certificates on your machine.

This process involves exporting the certificate as a base64 X509, adding it to the trusted certificates, and noting the change in file extension from .cer to .crt.

The certificate is regenerated on emulator startup, so you'll either need to do this every time or pass the emulator a predefined certificate to use.

If you want to validate the certificate has been installed, you can check the list of available SSL CA certificates on your system.

Here are the key limitations of the DocumentDB Emulator:

• Only supports a single fixed account and a well-known master key

• Does not simulate different DocumentDB consistency levels

• Does not simulate multi-region replication

• Does not support service quota overrides

• May not be up to date with the most recent changes in the Azure DocumentDB service

Azure Cosmos DB supports multiple APIs, including SQL API, Table, MongoDB, Cassandra, and Gremlin.

These APIs cover a wide range of scenarios, from migrating an existing database to modernizing a legacy application or creating a brand new one.

The Azure Cosmos DB Emulator also supports these APIs, but the underlying implementation details are different from the real service on Azure.

The emulator hides all abstractions from you, allowing you to focus on adding value to your team or organization.

However, the data explorer provided with the service only supports SQL API at the moment.

To access Cosmos DB, you can use the Cosmos DB API, which is a low-level access way to the database. Most features supported by the SDK are available through this API.

The Cosmos DB API can be customized to fit your needs, allowing you to pass required authorization information using HTTP headers. This is necessary to customize calls and ensure they are processed correctly.

One of the required header fields is x-ms-version, which specifies the version of the REST API being used. You can find the available versions here, and it's recommended to use the latest one.

The x-ms-session-token header field is also required if you want to use session consistency. This token is assigned by Cosmos DB for each new write request in Session consistency and must be tracked and used in subsequent requests.

The latest version of the Cosmos DB API is 2019-06-30, which can be found here. Using the latest version is recommended to ensure you have access to the most up-to-date features and functionality.

When working with the emulator, it's essential to keep in mind the differences that set it apart from other tools.

The data explorer only supports the SQL API, but you can still use other APIs from within your application using the SDK.

One thing to note is that the emulator only supports a single account with a well known key. You can change this key from the command line, but not within the explorer itself.

Provisioning throughput mode is the only supported mode, meaning serverless mode is not an option.

Another limitation is that core features like different consistency levels, scaling, replication, and performance guarantees are not supported.

To accurately estimate your required throughput, be sure to check the Azure Cosmos DB capacity planner, as the client might not be up to date with the latest service.

Lastly, keep in mind that the minimum ID property size is 256 characters.