Windows (本機) 模擬器的命令列和 PowerShell 參考

發行項
09/12/2023

適用於： NoSQL MongoDB Cassandra Gremlin Table

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`使用選項來產生 keyfile。	`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) 和 `localhost127.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`	產生新的授權金鑰並儲存到指定的檔案。產生的金鑰可以搭配或 `/KeyFile` 選項使用 `/Key` 。	`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`	將模擬器的預設一致性層級設定為會話、強式、最終或 BoundedStaleness。預設層級為會話。
`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`	根據預設，模擬器會重新產生其自我簽署 TLS/SSL 憑證，如果憑證的 SAN 不包含模擬器主機的功能變數名稱、本機 IP 位址 (v4) 、 `localhost` 和 `127.0.0.1` 。此選項會導致模擬器在啟動時失敗。然後，您應該使用 `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 中的所有模擬器資料。
以滑鼠右鍵按一下系統匣上的 模擬器 圖示，然後按一下 [ 結束]，以結束所有開啟的實例。結束所有執行個體可能需要數分鐘的時間。
安裝最新版的模擬器。
啟動具有 PartitionCount 旗標的模擬器，方法是設定值 <= 250。例如：C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100。