Azure Cosmos DB 模拟器的命令行和 PowerShell 参考Command-line and PowerShell reference for Azure Cosmos DB Emulator

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

为方便本地开发,Azure Cosmos DB 模拟器提供了一个模拟 Azure Cosmos DB 服务的本地环境。The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for local development purposes. 安装模拟器后,可以通过命令行和 PowerShell 命令控制模拟器。After installing the emulator, you can control the emulator with command line and PowerShell commands. 本文介绍如何使用命令行和 PowerShell 命令启动和停止模拟器、配置选项和执行其他操作。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] [/?]

若要查看选项列表,请在命令提示符下键入 Microsoft.Azure.Cosmos.Emulator.exe /?To view the list of options, type Microsoft.Azure.Cosmos.Emulator.exe /? at the command prompt.

选项Option 说明Description 命令Command 参数Arguments
[无参数][No arguments] 使用默认设置启动 Azure Cosmos DB 模拟器。Starts up the Azure Cosmos DB Emulator with default settings. Microsoft.Azure.Cosmos.Emulator.exeMicrosoft.Azure.Cosmos.Emulator.exe
[帮助][Help] 显示支持的命令行参数列表。Displays the list of supported command-line arguments. Microsoft.Azure.Cosmos.Emulator.exe /?Microsoft.Azure.Cosmos.Emulator.exe /?
GetStatusGetStatus 获取 Azure Cosmos DB 模拟器的状态。Gets the status of the Azure Cosmos DB Emulator. 状态由退出代码指示:1 = 正在启动,2 = 正在运行,3 = 已停止。The status is indicated by the exit code: 1 = Starting, 2 = Running, 3 = Stopped. 退出代码为负表示发生了错误。A negative exit code indicates that an error occurred. 不生成其他输出。No other output is produced. Microsoft.Azure.Cosmos.Emulator.exe /GetStatusMicrosoft.Azure.Cosmos.Emulator.exe /GetStatus
关机Shutdown 关闭 Azure Cosmos DB 模拟器。Shuts down the Azure Cosmos DB Emulator. Microsoft.Azure.Cosmos.Emulator.exe /ShutdownMicrosoft.Azure.Cosmos.Emulator.exe /Shutdown
DataPathDataPath 指定要在其中存储数据文件的路径。Specifies the path in which to store data files. 默认值为 %LocalAppdata%\CosmosDBEmulator。Default value is %LocalAppdata%\CosmosDBEmulator. Microsoft.Azure.Cosmos.Emulator.exe /DataPath=<datapath>Microsoft.Azure.Cosmos.Emulator.exe /DataPath=<datapath> <datapath>:可访问路径<datapath>: An accessible path
端口Port 指定用于模拟器的端口号。Specifies the port number to use for the emulator. 默认值为 8081。Default value is 8081. Microsoft.Azure.Cosmos.Emulator.exe /Port=<port>Microsoft.Azure.Cosmos.Emulator.exe /Port=<port> <port>:单个端口号<port>: Single port number
ComputePortComputePort 指定用于计算互操作网关服务的端口号。Specified the port number to use for the Compute Interop Gateway service. 该网关的 HTTP 终结点探测端口计算得出 ComputePort + 79。The Gateway's HTTP endpoint probe port is calculated as ComputePort + 79. 因此,ComputePort 和 ComputePort + 79 必须打开且可使用。Hence, ComputePort and ComputePort + 79 must be open and available. 默认值为 8900。The default value is 8900. Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=<computeport>Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=<computeport> <computeport>:单个端口号<computeport>: Single port number
EnableMongoDbEndpoint=3.2EnableMongoDbEndpoint=3.2 启用 MongoDB API 3.2Enables MongoDB API 3.2 Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2
EnableMongoDbEndpoint=3.6EnableMongoDbEndpoint=3.6 启用 MongoDB API 3.6Enables MongoDB API 3.6 Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6
MongoPortMongoPort 指定用于 MongoDB 兼容性 API 的端口号。Specifies the port number to use for MongoDB compatibility API. 默认值为 10255。Default value is 10255. Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=<mongoport>Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=<mongoport> <mongoport>:单个端口号<mongoport>: Single port number
EnableCassandraEndpointEnableCassandraEndpoint 启用 Cassandra APIEnables Cassandra API Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint
CassandraPortCassandraPort 指定用于 Cassandra 终结点的端口号。Specifies the port number to use for the Cassandra endpoint. 默认值为 10350。Default value is 10350. Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=<cassandraport>Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=<cassandraport> <cassandraport>:单个端口号<cassandraport>: Single port number
EnableGremlinEndpointEnableGremlinEndpoint 启用 Gremlin APIEnables Gremlin API Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint
GremlinPortGremlinPort 用于 Gremlin 终结点的端口号。Port number to use for the Gremlin Endpoint. 默认值为 8901。Default value is 8901. Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=<port>Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=<port> <port>:单个端口号<port>: Single port number
EnableTableEndpointEnableTableEndpoint 启用 Azure 表 APIEnables Azure Table API Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint
TablePortTablePort 用于 Azure 表终结点的端口号。Port number to use for the Azure Table Endpoint. 默认值为 8902。Default value is 8902. Microsoft.Azure.Cosmos.Emulator.exe /TablePort=<port>Microsoft.Azure.Cosmos.Emulator.exe /TablePort=<port> <port>:单个端口号<port>: Single port number
KeyFileKeyFile 从指定文件中读取授权密钥。Read authorization key from the specified file. 使用 /GenKeyFile 选项来生成密钥文件Use the /GenKeyFile option to generate a keyfile Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=<file_name>Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=<file_name> <file_name>:文件的路径<file_name>: Path to the file
ResetDataPathResetDataPath 以递归方式删除指定路径中的所有文件。Recursively removes all the files in the specified path. 如果不指定路径,则默认为 %LOCALAPPDATA%\CosmosDbEmulatorIf you don't specify a path, it defaults to %LOCALAPPDATA%\CosmosDbEmulator Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath=<path>Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath=<path> <path>:文件路径<path>: File path
StartTracesStartTraces 开始使用 LOGMAN 收集调试跟踪日志。Start collecting debug trace logs using LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StartTracesMicrosoft.Azure.Cosmos.Emulator.exe /StartTraces
StopTracesStopTraces 停止使用 LOGMAN 收集调试跟踪日志。Stop collecting debug trace logs using LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StopTracesMicrosoft.Azure.Cosmos.Emulator.exe /StopTraces
StartWprTracesStartWprTraces 开始使用 Windows 性能记录工具收集调试跟踪日志。Start collecting debug trace logs using Windows Performance Recording tool. Microsoft.Azure.Cosmos.Emulator.exe /StartWprTracesMicrosoft.Azure.Cosmos.Emulator.exe /StartWprTraces
StopWprTracesStopWprTraces 停止使用 Windows 性能记录工具收集调试跟踪日志。Stop collecting debug trace logs using Windows Performance Recording tool. Microsoft.Azure.Cosmos.Emulator.exe /StopWprTracesMicrosoft.Azure.Cosmos.Emulator.exe /StopWprTraces
FailOnSslCertificateNameMismatchFailOnSslCertificateNameMismatch 默认情况下,模拟器会重新生成自签名的 TLS/SSL 证书(如果证书的 SAN 不包含模拟器主机的域名、本地 IPv4 地址、“localhost”和“127.0.0.1”)。By default the emulator regenerates its self-signed TLS/SSL certificate, if the certificate's SAN does not include the emulator host's domain name, local IPv4 address, 'localhost', and '127.0.0.1'. 启用此选项后,模拟器在启动时会失败。With this option, the emulator will fail at startup instead. 然后,你应使用 /GenCert 选项来创建并安装新的自签名 TLS/SSL 证书。You should then use the /GenCert option to create and install a new self-signed TLS/SSL certificate. Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatchMicrosoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch
GenCertGenCert 生成并安装新的自签名 TLS/SSL 证书。Generate and install a new self-signed TLS/SSL certificate. 选择性地包含用于通过网络访问模拟器的其他 DNS 名称的列表(以逗号分隔)。optionally including a comma-separated list of additional DNS names for accessing the emulator over the network. Microsoft.Azure.Cosmos.Emulator.exe /GenCert=<dns-names>Microsoft.Azure.Cosmos.Emulator.exe /GenCert=<dns-names> <dns-names>:其他 dns 名称的逗号分隔列表(可选)<dns-names>: Optional comma-separated list of additional dns names
DirectPortsDirectPorts 指定用于直接连接的端口。Specifies the ports to use for direct connectivity. 默认值为 10251、10252、10253、10254。Defaults are 10251,10252,10253,10254. Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:<directports>Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:<directports> <directports>:以逗号分隔的 4 个端口的列表<directports>: Comma-delimited list of 4 ports
密钥Key 模拟器的授权密钥。Authorization key for the emulator. 密钥必须是 64 字节向量的 base 64 编码。Key must be the base-64 encoding of a 64-byte vector. Microsoft.Azure.Cosmos.Emulator.exe /Key:<key>Microsoft.Azure.Cosmos.Emulator.exe /Key:<key> <key>:密钥必须是 64 字节向量的 base 64 编码<key>: Key must be the base-64 encoding of a 64-byte vector
EnableRateLimitingEnableRateLimiting 指定已启用请求速率限制行为。Specifies that request rate limiting behavior is enabled. Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimitingMicrosoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting
DisableRateLimitingDisableRateLimiting 指定已禁用请求速率限制行为。Specifies that request rate limiting behavior is disabled. Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimitingMicrosoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting
NoUINoUI 不显示模拟器用户界面。Do not show the emulator user interface. Microsoft.Azure.Cosmos.Emulator.exe /NoUIMicrosoft.Azure.Cosmos.Emulator.exe /NoUI
NoExplorerNoExplorer 在启动时不显示数据资源管理器。Don't show data explorer on startup. Microsoft.Azure.Cosmos.Emulator.exe /NoExplorerMicrosoft.Azure.Cosmos.Emulator.exe /NoExplorer
PartitionCountPartitionCount 指定已分区的容器的最大数。Specifies the maximum number of partitioned containers. 有关详细信息,请参阅更改容器数量See Change the number of containers for more information. Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=<partitioncount>Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=<partitioncount> <partitioncount>:允许的单分区容器的最大数量。<partitioncount>: Maximum number of allowed single partition containers. 默认值为 25。Default value is 25. 允许的最大值为 250。Maximum allowed is 250.
DefaultPartitionCountDefaultPartitionCount 指定分区容器的默认分区数。Specifies the default number of partitions for a partitioned container. Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount>Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount> <defaultpartitioncount> 默认值为 25。<defaultpartitioncount> Default value is 25.
AllowNetworkAccessAllowNetworkAccess 通过网络启用对仿真器的访问。Enables access to the emulator over a network. 要启用网络访问,还必须传递 /Key=<key_string> 或 /KeyFile=<file_name>。You must also pass /Key=<key_string> or /KeyFile=<file_name> to enable network access. Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=<key_string> 或 Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=<key_string> or Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>
NoFirewallNoFirewall 使用 /AllowNetworkAccess 选项时,不要调整防火墙规则。Don't adjust firewall rules when /AllowNetworkAccess option is used. Microsoft.Azure.Cosmos.Emulator.exe /NoFirewallMicrosoft.Azure.Cosmos.Emulator.exe /NoFirewall
GenKeyFileGenKeyFile 生成新的授权密钥并保存至指定文件。Generate a new authorization key and save to the specified file. 所生成的密钥可与 /Key 或 /KeyFile 选项配合使用。The generated key can be used with the /Key or /KeyFile options. Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=<path to key file>Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=<path to key file>
一致性Consistency 为帐户设置默认一致性级别。Set the default consistency level for the account. Microsoft.Azure.Cosmos.Emulator.exe /Consistency=<consistency>Microsoft.Azure.Cosmos.Emulator.exe /Consistency=<consistency> <consistency>:值必须是以下一致性级别之一:Session、Strong、Eventual 或 BoundedStaleness。<consistency>: Value must be one of the following consistency levels: Session, Strong, Eventual, or BoundedStaleness. 默认值为“Session”。The default value is Session.
?? 显示帮助消息。Show the help message.

通过 PowerShell 管理模拟器Manage the emulator with PowerShell

该模拟器附带一个 PowerShell 模块,它可用于启动、停止、卸载和检索服务的状态。The emulator comes with a PowerShell module to start, stop, uninstall, and retrieve the status of the service. 运行下列 cmdlet 以使用 PowerShell 模块:Run the following cmdlet to use the PowerShell module:

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

或者,将 PSModules 目录放置在 PSModulePath 上,并按如下命令中所示将其导入:or place the PSModules directory on your PSModulePath and import it as shown in the following command:

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

下面汇总的命令用于通过 PowerShell 来控制模拟器:Here is a summary of the commands for controlling the emulator from PowerShell:

Get-CosmosDbEmulatorStatus

语法Syntax

Get-CosmosDbEmulatorStatus

备注Remarks

返回以下 ServiceControllerStatus 值之一:ServiceControllerStatus.StartPending、ServiceControllerStatus.Running 或 ServiceControllerStatus.Stopped。Returns one of these ServiceControllerStatus values: ServiceControllerStatus.StartPending, ServiceControllerStatus.Running, or ServiceControllerStatus.Stopped.

Start-CosmosDbEmulator

语法Syntax

Start-CosmosDbEmulator [-DataPath <string>] [-DefaultPartitionCount <uint16>] [-DirectPort <uint16[]>] [-MongoPort <uint16>] [-NoUI] [-NoWait] [-PartitionCount <uint16>] [-Port <uint16>] [<CommonParameters>]

备注Remarks

启动模拟器。Starts the emulator. 默认情况下,此命令会一直等待,直至模拟器做好接受请求的准备。By default, the command waits until the emulator is ready to accept requests. 如果希望 cmdlet 在启动模拟器后立即返回,请使用 -NoWait 选项。Use the -NoWait option, if you wish the cmdlet to return as soon as it starts the emulator.

Stop-CosmosDbEmulator

语法Syntax

Stop-CosmosDbEmulator [-NoWait]

备注Remarks

停止模拟器。Stops the emulator. 默认情况下,此命令会一直等待,直至模拟器完全关闭。By default, this command waits until the emulator is fully shut down. 如果希望 cmdlet 在模拟器开始关闭后立即返回,请使用 -NoWait 选项。Use the -NoWait option, if you wish the cmdlet to return as soon as the emulator begins to shut down.

Uninstall-CosmosDbEmulator

语法Syntax

Uninstall-CosmosDbEmulator [-RemoveData]

备注Remarks

卸载模拟器,并可视需要删除 $env:LOCALAPPDATA\CosmosDbEmulator 的完整内容。Uninstalls the emulator and optionally removes the full contents of $env:LOCALAPPDATA\CosmosDbEmulator. 此 cmdlet 可确保在卸载模拟器之前,模拟器已停止。The cmdlet ensures the emulator is stopped before uninstalling it.

更改默认容器数量Change the number of default containers

默认情况下,可最多创建 25 个固定大小的容器(仅支持使用 Azure Cosmos DB SDK 进行创建),或使用 Azure Cosmos DB 模拟器创建 5 个不受限容器。By default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers using the Azure Cosmos DB Emulator. 通过修改 PartitionCount 值,可最多创建 250 个固定大小的容器或 50 个不受限容器,也可创建两者的任意组合(前提是总数不超过 250 个固定大小的容器,其中 1 个不受限容器 = 5 个固定大小的容器)。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 does not exceed 250 fixed size containers (where one unlimited container = 5 fixed size containers). 但是,建议不要设置用 200 个以上固定大小的容器进行运行的模拟器。However it's not recommended to set up the emulator to run with more than 200 fixed size containers. 因为这会造成磁盘 IO 操作的开销增加,导致在运行终结点 API 时出现不可预测的超时情况。Because of the overhead that it adds to the disk IO operations, which result in unpredictable timeouts when using the endpoint APIs.

如果在已超过当前分区计数后尝试创建容器,则模拟器将引发 ServiceUnavailable 异常,并收到以下消息。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-123456789abcActivityId: 12345678-1234-1234-1234-123456789abc

若要更改 Azure Cosmos DB 模拟器中可用容器的数量,请执行以下步骤:To change the number of containers available in the Azure Cosmos DB Emulator, run the following steps:

  1. 通过在系统任务栏上右键单击“Azure Cosmos DB 模拟器”图标,并单击“重置数据...”,删除所有本地 Azure Cosmos DB 模拟器数据。Delete all local Azure Cosmos DB Emulator data by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Reset Data….

  2. 删除文件夹 %LOCALAPPDATA%\CosmosDBEmulator 中的所有模拟器数据。Delete all emulator data in this folder %LOCALAPPDATA%\CosmosDBEmulator.

  3. 通过在系统任务栏上右键单击“Azure Cosmos DB 模拟器”图标,并单击“退出”,退出所有打开的实例。Exit all open instances by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Exit. 退出所有实例可能需要一分钟。It may take a minute for all instances to exit.

  4. 安装最新版的 Azure Cosmos DB 模拟器Install the latest version of the Azure Cosmos DB Emulator.

  5. 通过设置一个 <= 250 的值启动具有 PartitionCount 标志的模拟器。Launch the emulator with the PartitionCount flag by setting a value <= 250. 例如:C:\Program Files\Azure Cosmos DB Emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100For example: C:\Program Files\Azure Cosmos DB Emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

后续步骤Next steps