Emulator command-line and PowerShell reference - Azure Cosmos DB (2023)

APPLIES TO:NoSQLMongoDBCassandraGremlinTable

The Azure Cosmos DB emulator provides a local environment that emulates the Azure Cosmos DB service for local development purposes. After installing the emulator, you can control the emulator with command line and PowerShell commands. This article describes how to use the command-line and PowerShell commands to start and stop the emulator, configure options, and perform other operations. You have to run the commands from the installation location.

Manage the emulator with command-line syntax

Microsoft.Azure.Cosmos.Emulator.exe [/Shutdown] [/DataPath] [/Port] [/MongoPort] [/DirectPorts] [/Key] [/EnableRateLimiting] [/DisableRateLimiting] [/NoUI] [/NoExplorer] [/EnableMongoDbEndpoint] [/?]

To view the list of parameters, type Microsoft.Azure.Cosmos.Emulator.exe /? at the command prompt.

Manage the emulator with PowerShell cmdlets

The emulator comes with a PowerShell module to start, stop, uninstall, and retrieve the status of the service. Run the following cmdlet to use the PowerShell module:

Import-Module "$env:ProgramFiles\emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"

or place the PSModules directory on your PSModulePath and import it as shown in the following command:

$env:PSModulePath += ";$env:ProgramFiles\emulator\PSModules"Import-Module Microsoft.Azure.CosmosDB.Emulator

Here's a summary of the commands for controlling the emulator from PowerShell:

Get-CosmosDbEmulatorStatus

Gets the status of the emulator. Returns one of these ServiceControllerStatus values:

• ServiceControllerStatus.StartPending
• ServiceControllerStatus.Running
• ServiceControllerStatus.Stopped

If an error is encountered, no value is returned.

Syntax

Get-CosmosDbEmulatorStatus [[-AlternativeInstallLocation] <String>] [<CommonParameters>]

Parameters

Examples

• Get the status of an emulator installed in the D:\SomeFolder\AzureCosmosDBEmulator folder.

  @parameters = { AlternativeInstallLocation = "D:\SomeFolder\AzureCosmosDBEmulator"}Get-CosmosDbEmulatorStatus @parameters

Start-CosmosDbEmulator

Starts the emulator on the local computer. By default, the command waits until the emulator is ready to accept requests. Use the -NoWait option, if you wish the cmdlet to return as soon as it starts the emulator. Use the parameters of Start-CosmosDbEmulator to specify options, such as the NoSQL port, direct port, and MongoDB port numbers.

Syntax

Start-CosmosDbEmulator [-AllowNetworkAccess] [-AlternativeInstallLocation <String>] [-CassandraPort <UInt16>] [-ComputePort <UInt16>] [-Consistency <String>] [-Credential <PSCredential>] [-DataPath <String>] [-DefaultPartitionCount <UInt16>] [-DirectPort <UInt16[]>] [-EnableMongoDb] [-EnableCassandra] [-EnableGremlin] [-EnableTable] [-EnableSqlCompute] [-EnablePreview] [-FailOnSslCertificateNameMismatch] [-GremlinPort <UInt16>] [-TablePort <UInt16>] [-SqlComputePort <UInt16>] [-Key <String>] [-MongoPort <UInt16>] [-MongoApiVersion <String>] [-NoFirewall] [-NoTelemetry] [-NoUI] [-NoWait] [-PartitionCount <UInt16>] [-Port <UInt16>] [-SimulateRateLimiting] [-Timeout <UInt32>] [-Trace] [<CommonParameters>]

Parameters

Examples

• Start the emulator and wait until it's fully started and ready to accept requests.

  Start-CosmosDbEmulator

• Start the emulator with 5 partitions reserved for each partitioned collection. The total number of partitions is set to the default: 25. Hence, the total number of partitioned collections that can be created is 5 = 25 partitions / 5 partitions/collection. Each partitioned collection is capped at 50 GB = 5 partitions * 10 GB / partiton.

  @parameters = { DefaultPartitionCount = 5}Start-CosmosDbEmulator @parameters

• Starts the emulator with alternative port numbers.

  @parameters = { Port = 443 MongoPort = 27017 DirectPort = 20001,20002,20003,20004}Start-CosmosDbEmulator @parameters

Stop-CosmosDbEmulator

Stops the emulator. By default, this command waits until the emulator is fully shut down. Use the -NoWait option, if you wish the cmdlet to return as soon as the emulator begins to shut down.

Syntax

Stop-CosmosDbEmulator [[-AlternativeInstallLocation] <String>] [-NoWait] [[-Timeout] <UInt32>] [-Trace] [<CommonParameters>]

Parameters

Examples

@parameters = { NoWait = $true}Stop-CosmosDbEmulator @parameters

Uninstall-CosmosDbEmulator

Uninstalls the emulator and optionally removes the full contents of $env:LOCALAPPDATA\CosmosDbEmulator. The cmdlet ensures the emulator is stopped before uninstalling it.

Syntax

Uninstall-CosmosDbEmulator [-RemoveData] [<CommonParameters>]

Parameters

Examples

@parameters = { RemoveData = $false}Uninstall-CosmosDbEmulator @parameters

Change the number of default containers

By default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers using the emulator. By modifying the PartitionCount value, you can create up to 250 fixed size containers or 50 unlimited containers, or any combination of the two that doesn't exceed 250 fixed size containers (where one unlimited container = 5 fixed size containers). However it's not recommended to set up the emulator to run with more than 200 fixed size containers. Because of the overhead that it adds to the disk IO operations, which result in unpredictable timeouts when using the endpoint APIs.

If you attempt to create a container 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.ActivityId: 12345678-1234-1234-1234-123456789abc

To change the number of containers available in the emulator, run the following steps:

1. Delete all local emulator data by right-clicking the emulator icon on the system tray, and then clicking Reset Data….

2. Delete all emulator data in this folder %LOCALAPPDATA%\CosmosDBEmulator.

3. Exit all open instances by right-clicking the emulator icon on the system tray, and then clicking Exit. It may take a minute for all instances to exit.

4. Install the latest version of the emulator.

5. Launch the emulator with the PartitionCount flag by setting a value <= 250. For example: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Next steps

• Export the emulator certificates for use with Java, Python, and Node.js apps
• Debug issues with the emulator