你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Windows（本地）模拟器的命令行和 PowerShell 参考

项目
09/13/2023

适用于： NoSQL MongoDB Cassandra Gremlin 表

为便于本地开发，Azure Cosmos DB 模拟器提供了模拟 Azure Cosmos DB 服务的本地环境。安装模拟器后，可以通过命令行和 PowerShell 命令控制模拟器。本文介绍如何使用命令行和 PowerShell 命令启动和停止模拟器、配置选项和执行其他操作。必须从安装位置运行命令。

重要

本文仅包含 Windows 本地模拟器的命令行参数。

用命令行语法管理模拟器

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

要查看参数列表，请在命令提示符下键入 Microsoft.Azure.Cosmos.Emulator.exe /?。

参数	说明	示例命令
[无参数]	使用默认设置启动模拟器。	Microsoft.Azure.Cosmos.Emulator.exe
[帮助]	显示支持的命令行参数列表。	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	获取模拟器状态。每个退出代码都指示一种状态：“`1` = 正在启动”、“`2` = 正在运行” 和“`3` = 已停止”。退出代码为负表示发生了错误。不生成其他输出。	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	关闭模拟器。	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	指定要在其中存储数据文件的路径。默认值为 `%LocalAppdata%\CosmosDBEmulator`。	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	指定用于模拟器的端口号。默认值是 `8081`。	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	指定用于计算互操作网关服务的端口号。该网关的 HTTP 终结点探测端口计算得出 `ComputePort + 79`。因此，`ComputePort` 和 `ComputePort + 79` 必须开启且可用。默认值为 `8900`。	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	为 MongoDB 版本 3.2 启用 API。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	为 MongoDB 版本 3.6 启用 API。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	为 MongoDB 版本 4.0 启用 API。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	指定用于 API for MongoDB 的端口号。默认值为 `10255`。	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	启用 API for Apache Cassandra。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	指定用于 API for Cassandra 终结点的端口号。默认值为 `10350`。	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	启用 API for Apache Gremlin。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	用于 API for Apache Gremlin 终结点的端口号。默认值为 `8901`。	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	启用 API for Table。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	用于 API for Table 终结点的端口号。默认值为 `8902`。	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	从指定文件中读取授权密钥。使用 `/GenKeyFile` 选项生成密钥文件。	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	以递归方式删除指定路径中的所有文件。如果未指定路径，则默认为 `%LOCALAPPDATA%\CosmosDbEmulator`。	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	开始使用 LOGMAN 收集调试跟踪日志。	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	停止使用 LOGMAN 收集调试跟踪日志。	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	开始使用 Windows 性能记录工具收集调试跟踪日志。	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	停止使用 Windows 性能记录工具收集调试跟踪日志。	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	默认情况下，模拟器会重新生成其自签名的 TLS/SSL 证书（如果证书的 SAN 不包含模拟器主机的域名、本地 IP 地址 (v4)、`localhost` 和 `127.0.0.1`）。使用此选项时，模拟器在启动时会失败。然后，应使用 `/GenCert` 选项以新建并安装自签名 TLS/SSL 证书。	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	生成并安装新的自签名 TLS/SSL 证书。选择性地包含用于通过网络访问模拟器的其他 DNS 名称的列表（以逗号分隔）。	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	指定用于直接连接的端口。默认值为 `10251`、`10252`、`10253` 和 `10254`。	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	模拟器的授权密钥。密钥必须是 64 字节向量的 base 64 编码。	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	指定已启用请求速率限制行为。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	指定已禁用请求速率限制行为。	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	不显示模拟器用户界面。	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	在启动时不显示数据资源管理器。	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	指定已分区的容器的最大数。有关详细信息，请参阅更改容器数。默认值为 `25`。允许的最大值为 `250`。	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	指定分区容器的默认分区数。默认值为 `25`。	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	通过网络启用对仿真器的访问。要启用网络访问，还必须传递 `/Key=<key_string>` 或 /`KeyFile=<file_name>`。	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	使用 `/AllowNetworkAccess` 选项时，不要调整防火墙规则。	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	生成新的授权密钥并保存至指定文件。生成的密钥可与 `/Key` 或 `/KeyFile` 选项结合使用。	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	为帐户设置默认一致性级别。默认值为 Session。	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	显示帮助消息。

使用 PowerShell cmdlet 管理模拟器

该模拟器附带一个 PowerShell 模块，它可用于启动、停止、卸载和检索服务的状态。运行下列 cmdlet 以使用 PowerShell 模块：

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

或者，将 PSModules 目录放置在 PSModulePath 上，并按如下命令中所示将其导入：

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

下面汇总了用于通过 PowerShell 控制模拟器的命令：

`Get-CosmosDbEmulatorStatus`

获取模拟器状态。返回以下 ServiceControllerStatus 值之一：

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

如果遇到错误，不返回任何值。

语法

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

参数

名称	类型	说明
`AlternativeInstallLocation`	`String`

示例

获取 D:\SomeFolder\AzureCosmosDBEmulator 文件夹中安装的模拟器的状态。

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

`Start-CosmosDbEmulator`

在本地计算机上启动模拟器。默认情况下，此命令会一直等待，直至模拟器做好接受请求的准备。如果希望 cmdlet 在启动模拟器后立即返回，请使用 -NoWait选项。使用 Start-CosmosDbEmulator 的参数指定 NoSQL 端口、直接端口和 MongoDB 端口号等选项。

语法

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>]

参数

名称	类型	说明
`AllowNetworkAccess`	`SwitchParameter`	允许从分配给模拟器主机的所有 IP 地址进行访问。还必须指定 Key 或 KeyFile 的值以允许网络访问。
`AlternativeInstallLocation`	`String`	模拟器可执行文件的备用位置路径。
`CassandraPort`	`UInt16`	用于 API for Cassandra 的端口号。默认端口为 `10350`。
`ComputePort`	`UInt16`	用于计算互操作网关服务的端口。该网关的 HTTP 终结点探测端口计算得出 `ComputePort + 79`。因此，`ComputePort` 和 `ComputePort + 79` 必须开启且可用。默认端口为 `8900`、`8979`。
`Consistency`	`String`	将模拟器的默认一致性级别设置为 Session、Strong、 Eventual 或 BoundedStaleness。默认级别为 Session。
`Credential`	`PSCredential`	指定有权执行此操作的用户帐户。使用用户名（例如 `User01` 或 `Domain01\User01`），或者输入 `PSCredential` 对象（例如 `Get-Credential` cmdlet 中的对象）。默认情况下，该 cmdlet 使用当前用户的凭据。
`DataPath`	`String`	存储数据文件的路径。数据文件的默认位置为 `$env:LocalAppData\CosmosDbEmulator`。
`DefaultPartitionCount`	`UInt16`	每个已分区集合要保留的分区数。默认值为 25，这与总分区计数的默认值相同。
`DirectPort`	`UInt16`	用于直接连接到模拟器后端的四个端口的列表。默认列表为 `10251`、`10252`、`10253` 和 `10254`。
`EnableMongoDb`	`SwitchParameter`	指定启用 API for MongoDB 终结点。默认值为 false。
`EnableCassandra`	`SwitchParameter`	指定启用 API for Apache Cassandra 终结点。默认值为 false。
`EnableGremlin`	`SwitchParameter`	指定启用 API for Apache Gremlin 终结点。默认值为 false。
`EnableTable`	`SwitchParameter`	指定启用 API for Table 终结点。默认值为 false。
`EnableSqlCompute`	`SwitchParameter`	指定启用 API for NoSQL 终结点。默认值为 false。
`EnablePreview`	`SwitchParameter`	默认情况下，启用处于预览状态且未完全成熟的模拟器功能。
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	默认情况下，模拟器会重新生成其自签名的 TLS/SSL 证书（如果证书的 SAN 不包含模拟器主机的域名、本地 IP 地址 (v4)、`localhost` 和 `127.0.0.1`）。此选项会导致模拟器在启动时失败。然后，应使用 `New-CosmosDbEmulatorCertificate` 选项以新建并安装自签名 TLS/SSL 证书。
`GremlinPort`	`UInt16`	用于 API for Apache Gremlin 的端口号。默认端口号为 `8901`。
`TablePort`	`UInt16`	用于 API for Table 的端口号。默认端口号为 `8902`。
`SqlComputePort`	`UInt16`	用于 API for NoSQL 的端口号。默认端口号为 `8903`。
`Key`	`String`	模拟器的授权密钥。此值必须是 64 字节向量的 base 64 编码。
`MongoPort`	`UInt16`	用于 API for MongoDB 的端口号。默认端口号为 `10250`。
`MongoApiVersion`	`String`	指定用于 API for MongoDB 的版本。默认版本为 `4.0`。
`NoFirewall`	`SwitchParameter`	指定不应将入站端口规则添加到模拟器主机的防火墙。
`NoTelemetry`	`SwitchParameter`	指定 cmdlet 不应收集当前模拟器会话的数据。
`NoUI`	`SwitchParameter`	指定 cmdlet 不应显示用户界面或任务栏图标。
`NoWait`	`SwitchParameter`	指定 cmdlet 应在模拟器开始启动后立即返回。默认情况下，cmdlet 会等待，直到启动完成，模拟器已准备好接收请求，然后再返回。
`PartitionCount`	`UInt16`	模拟器分配的分区总数。
`Port`	`UInt16`	模拟器网关服务和 Web UI 的端口号。默认端口号为 `8081`。
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

示例

启动模拟器并等待，直到它完全启动并准备好接受请求。
```
Start-CosmosDbEmulator
```
使用为每个已分区集合保留的 5 个分区启动模拟器。分区总数设置为默认值：25。因此，可以创建的分区集合总数为 5 = 25 partitions / 5 partitions/collection。每个已分区集合的上限为 50 GB = 5 partitions * 10 GB / partiton。
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

使用备用端口号启动模拟器。

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

`Stop-CosmosDbEmulator`

停止模拟器。默认情况下，此命令会一直等待，直至模拟器完全关闭。如果希望 cmdlet 在模拟器开始关闭后立即返回，请使用 -NoWait 选项。

语法

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

参数

名称	类型	说明
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	指定 cmdlet 应在关闭开始后立即返回。
`Trace`	`SwitchParameter`

示例

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

`Uninstall-CosmosDbEmulator`

卸载模拟器，并选择性地删除 $env:LOCALAPPDATA\CosmosDbEmulator 的完整内容。此 cmdlet 可确保在卸载模拟器之前，模拟器已停止。

语法

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

参数

名称	类型	说明
`RemoveData`	`SwitchParameter`	指定 cmdlet 应在删除模拟器后删除所有数据。

示例

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

更改默认容器数量

默认情况下，可以创建最多 25 个固定大小的容器（仅支持使用 Azure Cosmos DB SDK 创建），或使用模拟器创建 5 个不受限容器。通过修改 PartitionCount 值，可以创建最多 250 个固定大小的容器或 50 个不受限容器，也可以创建两者的任意组合（前提是不超过 250 个固定大小的容器，其中 1 个不受限容器 = 5 个固定大小的容器）。但是，建议不要设置用 200 个以上固定大小的容器进行运行的模拟器。因为这会造成磁盘 IO 操作的开销增加，导致在运行终结点 API 时出现不可预测的超时情况。

如果在已超过当前分区计数后尝试创建容器，则模拟器将引发 ServiceUnavailable 异常，并收到以下消息。

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

要更改模拟器中的可用容器数，请执行以下步骤：

在系统托盘上右击“模拟器”图标，然后点击“重置数据...”，从而删除所有本地模拟器数据。
删除文件夹 %LOCALAPPDATA%\CosmosDBEmulator 中的所有模拟器数据。
在系统托盘上右击“模拟器”图标，然后点击“退出”，从而退出所有打开的实例。退出所有实例可能需要一分钟。
安装最新版本的模拟器。
通过设置一个 <= 250 的值启动具有 PartitionCount 标志的模拟器。例如：C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100。