適用於 Windows 的命令行和 PowerShell 參考（本機）模擬器

發行項
08/15/2024

適用於：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`	指定要用於計算 Interop 閘道服務的埠號碼。閘道的 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`	指定要用於 MongoDB API 的埠號碼。預設值為 `10255`。	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	啟用適用於 Apache Cassandra 的 API。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	指定要用於 Cassandra 端點之 API 的埠號碼。預設值為 `10350`。	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	啟用適用於 Apache Gremlin 的 API。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	要用於 Apache Gremlin 連接點 API 的埠號碼。預設值為 `8901`。	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	啟用資料表的 API。	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	要用於數據表端點 API 的埠號碼。預設值為 `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`	根據預設，如果憑證的SAN不包含模擬器主機的功能變數名稱、本機IP位址（v4） `localhost`和 `127.0.0.1`，則模擬器會重新產生其自我簽署的TLS/SSL 憑證。使用此選項時，模擬器會在啟動時失敗。然後，您應該使用 `/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`

在本機電腦上啟動模擬器。根據預設，命令會等候模擬器準備好接受要求。 -NoWait如果您想要 Cmdlet 在啟動模擬器時立即傳回，請使用選項。使用的參數 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`	用於 Cassandra API 的埠號碼。預設連接埠為 `10350`。
`ComputePort`	`UInt16`	要用於計算 Interop 閘道服務的埠。閘道的 HTTP 連接點探查埠會計算為 `ComputePort + 79`。因此， `ComputePort` 和 `ComputePort + 79` 必須開啟且可供使用。預設連接埠為 `8900`、 `8979`。
`Consistency`	`String`	將模擬器的預設一致性層級設定為 Session、Strong、Eventual 或 BoundedStaleness。默認層級為 Session。
`Credential`	`PSCredential`	指定具有執行此動作許可權的用戶帳戶。使用使用者名稱，例如 `User01` 或 `Domain01\User01`，或輸入 `PSCredential` 物件，例如 Cmdlet 中的 `Get-Credential` 用戶名稱。根據預設，Cmdlet 會使用目前用戶的認證。
`DataPath`	`String`	儲存資料文件的路徑。資料檔案的預設位置為 `$env:LocalAppData\CosmosDbEmulator`。
`DefaultPartitionCount`	`UInt16`	要保留每個數據分割集合的數據分割數目。預設值為 25，與資料分割計數總計的預設值相同。
`DirectPort`	`UInt16`	四個埠的清單，用於直接連線到模擬器的後端。預設清單為 `10251`、 `10252`、 `10253`和 `10254`。
`EnableMongoDb`	`SwitchParameter`	指定已啟用 MongoDB 端點的 API。預設值為 false。
`EnableCassandra`	`SwitchParameter`	指定已啟用 Apache Cassandra 端點的 API。預設值為 false。
`EnableGremlin`	`SwitchParameter`	指定已啟用 Apache Gremlin 端點的 API。預設值為 false。
`EnableTable`	`SwitchParameter`	指定已啟用資料表端點的 API。預設值為 false。
`EnableSqlCompute`	`SwitchParameter`	指定已啟用 NoSQL 端點的 API。預設值為 false。
`EnablePreview`	`SwitchParameter`	啟用處於預覽狀態且未完全成熟且預設為開啟的模擬器功能。
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	根據預設，如果憑證的SAN不包含模擬器主機的功能變數名稱、本機IP位址（v4） `localhost`和 `127.0.0.1`，則模擬器會重新產生其自我簽署的TLS/SSL 憑證。此選項會導致模擬器在啟動時失敗。然後，您應該使用 `New-CosmosDbEmulatorCertificate` 選項來建立並安裝新的自我簽署 TLS/SSL 憑證。
`GremlinPort`	`UInt16`	要用於 Apache Gremlin 之 API 的埠號碼。預設連接埠號碼為 `8901`。
`TablePort`	`UInt16`	要用於數據表 API 的埠號碼。預設連接埠號碼為 `8902`。
`SqlComputePort`	`UInt16`	要用於 NoSQL 之 API 的埠號碼。預設連接埠號碼為 `8903`。
`Key`	`String`	模擬器的授權金鑰。此值必須是64位元組向量的基底64編碼。
`MongoPort`	`UInt16`	要用於 MongoDB API 的埠號碼。預設連接埠號碼為 `10250`。
`MongoApiVersion`	`String`	指定要用於 MongoDB API 的版本。預設版本為 `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 個固定大小容器（其中一個無限制的容器 = 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 。

共用方式為

適用於 Windows 的命令行和 PowerShell 參考（本機）模擬器

使用命令行語法管理模擬器

使用 PowerShell Cmdlet 管理模擬器

`Get-CosmosDbEmulatorStatus`

語法

參數

範例

`Start-CosmosDbEmulator`

語法

參數

範例

`Stop-CosmosDbEmulator`

語法

參數

範例

`Uninstall-CosmosDbEmulator`

語法

參數

範例

變更預設容器的數目

下一步

意見反應

其他資源

共用方式為

適用於 Windows 的命令行和 PowerShell 參考 （本機） 模擬器

使用命令行語法管理模擬器

使用 PowerShell Cmdlet 管理模擬器

Get-CosmosDbEmulatorStatus

語法

參數

範例

Start-CosmosDbEmulator

語法

參數

範例

Stop-CosmosDbEmulator

語法

參數

範例

Uninstall-CosmosDbEmulator

語法

參數

範例

變更預設容器的數目

下一步

意見反應

其他資源

適用於 Windows 的命令行和 PowerShell 參考（本機）模擬器

`Get-CosmosDbEmulatorStatus`

`Start-CosmosDbEmulator`

`Stop-CosmosDbEmulator`

`Uninstall-CosmosDbEmulator`