Windows(本地)模拟器的命令行和 PowerShell 参考

适用对象: 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。 因此,ComputePortComputePort + 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])、localhost127.0.0.1)。 使用此选项时,模拟器在启动时会失败。 然后,应使用 /GenCert 选项以新建并安装自签名 TLS/SSL 证书。 Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch
GenCert 生成并安装新的自签名 TLS/SSL 证书。 选择性地包含用于通过网络访问模拟器的其他域名系统 (DNS) 名称的列表(以逗号分隔)。 Microsoft.Azure.Cosmos.Emulator.exe /GenCert
DirectPorts 指定用于直接连接的端口。 默认值为 10251102521025310254 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>]

参数设置

客户 Type 说明
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>]

参数设置

客户 Type 描述
AllowNetworkAccess SwitchParameter 允许从分配给模拟器主机的所有 IP 地址进行访问。 还必须指定 Key 或 KeyFile 的值以允许网络访问。
AlternativeInstallLocation String 模拟器可执行文件的备用位置路径。
CassandraPort UInt16 用于 API for Cassandra 的端口号。 默认端口为 10350
ComputePort UInt16 用于计算互操作网关服务的端口。 该网关的 HTTP 终结点探测端口计算得出 ComputePort + 79。 因此,ComputePortComputePort + 79 必须开启且可用。 默认端口为 89008979
Consistency String 将模拟器的默认一致性级别设置为 SessionStrongEventualBoundedStaleness。 默认级别为 Session
Credential PSCredential 指定有权执行此操作的用户帐户。 使用用户名(例如 User01Domain01\User01),或者输入 PSCredential 对象(例如 Get-Credential cmdlet 中的对象)。 默认情况下,该 cmdlet 使用当前用户的凭据。
DataPath String 存储数据文件的路径。 数据文件的默认位置为 $env:LocalAppData\CosmosDbEmulator
DefaultPartitionCount UInt16 每个已分区集合要保留的分区数。 默认值为 25,这与总分区计数的默认值相同。
DirectPort UInt16 用于直接连接到模拟器后端的四个端口的列表。 默认列表为 10251102521025310254
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])、localhost127.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>]

参数设置

客户 Type 描述
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>]

参数设置

客户 Type 描述
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

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

  1. 在系统托盘上右击“模拟器”图标,然后点击“重置数据...”,从而删除所有本地模拟器数据。

  2. 删除文件夹 %LOCALAPPDATA%\CosmosDBEmulator 中的所有模拟器数据。

  3. 在系统托盘上右击“模拟器”图标,然后点击“退出”,从而退出所有打开的实例。 退出所有实例可能需要一分钟。

  4. 安装最新版本的 模拟器

  5. 通过设置一个 <= 250 的值启动具有 PartitionCount 标志的模拟器。 例如:C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100

后续步骤