Befehlszeilen- und PowerShell-Referenz für den Windows-Emulator (lokal)

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

Der Azure Cosmos DB-Emulator stellt eine lokale Umgebung bereit, die den Azure Cosmos DB-Dienst zu lokalen Entwicklungszwecken emuliert. Nach Installation des Emulators können Sie ihn mit Befehlszeilen- und PowerShell-Befehlen steuern. In diesem Artikel wird beschrieben, wie Sie mithilfe der Befehlszeilen- und PowerShell-Befehle den Emulator starten und anhalten, Optionen konfigurieren und andere Vorgänge ausführen. Sie müssen die Befehle vom Installationsort aus ausführen.

Wichtig

Dieser Artikel enthält nur Befehlszeilenargumente für den lokalen Windows-Emulator.

Verwalten des Emulators mit Befehlszeilensyntax

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

Geben Sie zum Anzeigen der Liste der Optionen in der Eingabeaufforderung Microsoft.Azure.Cosmos.Emulator.exe /? ein.

Parameter BESCHREIBUNG Beispielbefehl
[Keine Argumente] Startet den Emulator mit den Standardeinstellungen. Microsoft.Azure.Cosmos.Emulator.exe
[Hilfe] Zeigt die Liste mit unterstützten Befehlszeilenargumenten an. Microsoft.Azure.Cosmos.Emulator.exe /?
GetStatus Ruft den Status des Emulators ab. Jeder Exitcode gibt einen Status an: 1 = Wird gestartet, 2 = Wird ausgeführt und 3 = Beendet. Ein negativer Exitcode gibt an, dass ein Fehler aufgetreten ist. Es wird keine andere Ausgabe erzeugt. Microsoft.Azure.Cosmos.Emulator.exe /GetStatus
Shutdown Beendet den Emulator. Microsoft.Azure.Cosmos.Emulator.exe /Shutdown
DataPath Gibt den Pfad an, unter dem Datendateien gespeichert werden sollen. Standardwert: %LocalAppdata%\CosmosDBEmulator. Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder
Port Gibt die für den Emulator zu verwendende Portnummer an. Standardwert: 8081. Microsoft.Azure.Cosmos.Emulator.exe /Port=65000
ComputePort Gibt die Portnummer an, die für den Compute-Interop-Gatewaydienst verwendet werden soll. Der Testport für das Gateway des HTTP-Endpunkt wird als ComputePort + 79 berechnet. Daher müssen ComputePort und ComputePort + 79 offen und verfügbar sein. Standardwert: 8900. Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100
EnableMongoDbEndpoint=3.2 Aktiviert die API für die MongoDB-Version 3.2. Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2
EnableMongoDbEndpoint=3.6 Aktiviert die API für die MongoDB-Version 3.6. Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6
EnableMongoDbEndpoint=4.0 Aktiviert die API für die MongoDB-Version 4.0. Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0
MongoPort Gibt die für die API für MongoDB zu verwendende Portnummer an. Der Standardwert ist 10255. Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200
EnableCassandraEndpoint Aktiviert die API für Apache Cassandra. Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint
CassandraPort Gibt die für die API für den Cassandra-Endpunkt zu verwendende Portnummer an. Der Standardwert ist 10350. Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300
EnableGremlinEndpoint Aktiviert die API für Apache Gremlin. Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint
GremlinPort Die für die API für den Gremlin-Endpunkt zu verwendende Portnummer. Der Standardwert ist 8901. Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400
EnableTableEndpoint Aktiviert die API für Table. Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint
TablePort Die für die API für den Table-Endpunkt zu verwendende Portnummer. Der Standardwert ist 8902. Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500
KeyFile Liest den Autorisierungsschlüssel aus der angegebenen Datei. Verwenden Sie die Option /GenKeyFile, um eine Schlüsseldatei zu generieren. Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile
ResetDataPath Entfernt rekursiv alle Dateien im angegebenen Pfad. Wenn Sie keinen Pfad angeben, wird standardmäßig %LOCALAPPDATA%\CosmosDbEmulator verwendet. Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath
StartTraces Startet das Sammeln von Ablaufverfolgungsprotokollen für das Debuggen mithilfe von LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StartTraces
StopTraces Beendet das Sammeln von Ablaufverfolgungsprotokollen für das Debuggen mithilfe von LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StopTraces
StartWprTraces Startet das Sammeln von Ablaufverfolgungsprotokollen für das Debuggen mit dem Windows Performance Recorder. Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces
StopWprTraces Beendet das Sammeln von Ablaufverfolgungsprotokollen für das Debuggen mit dem Windows Performance Recorder. Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces
FailOnSslCertificateNameMismatch Das selbstsignierte TLS-/SSL-Zertifikat des Emulators wird standardmäßig neu generiert, wenn das SAN des Zertifikats den Domänennamen des Emulator-Hosts, die lokale IP-Adresse (v4), localhost und 127.0.0.1 nicht enthält. Mit dieser Option schlägt der Start des Emulators stattdessen fehl. Verwenden Sie dann die Option /GenCert, um ein neues, selbstsigniertes TLS-/SSL-Zertifikat zu erstellen und zu installieren. Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch
GenCert Generiert und installiert ein neues, selbstsigniertes TLS-/SSL-Zertifikat. optional mit einer durch Trennzeichen getrennten Liste zusätzlicher DNS-Namen für den Zugriff auf den Emulator über das Netzwerk. Microsoft.Azure.Cosmos.Emulator.exe /GenCert
DirectPorts Gibt die für die direkte Konnektivität zu verwendenden Ports an. Die Standardwerte sind 10251, 10252, 10253 und 10254. Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700
Key Autorisierungsschlüssel für den Emulator. Der Schlüssel muss die Base64-Codierung eines 64-Byte-Vektors sein. Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==
EnableRateLimiting Gibt an, dass das Verhalten für die Anforderungsratenbegrenzung aktiviert ist. Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting
DisableRateLimiting Gibt an, dass das Verhalten für die Anforderungsratenbegrenzung deaktiviert ist. Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting
NoUI Die Emulator-Benutzeroberfläche wird nicht angezeigt. Microsoft.Azure.Cosmos.Emulator.exe /NoUI
NoExplorer Der Daten-Explorer wird beim Start nicht angezeigt. Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer
PartitionCount Legt die maximale Anzahl von partitionierten Containern fest. Weitere Informationen finden Sie unter Ändern der Container-Anzahl. Standardwert: 25. Der zulässige Höchstwert ist 250. Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15
DefaultPartitionCount Gibt die Standardanzahl von Partitionen für einen partitionierten Container an. Standardwert: 25. Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50
AllowNetworkAccess Ermöglicht Zugriff auf den Emulator über ein Netzwerk. Sie müssen auch /Key=<key_string> oder KeyFile=<file_name> übergeben, um den Netzwerkzugriff zu ermöglichen. Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==
NoFirewall Passen Sie die Firewallregeln nicht an, wenn die Option /AllowNetworkAccess verwendet wird. Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall
GenKeyFile Generiert einen neuen Autorisierungsschlüssel und speichert ihn in der angegebenen Datei. Der generierte Schlüssel kann mit den Optionen /Key oder /KeyFile verwendet werden. Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile
Consistency Legt die Standardkonsistenzebene des Kontos fest. Der Standardwert lautet Sitzung. Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong
? Zeigt die Hilfemeldung an.

Verwalten des Emulators mit PowerShell Cmdlets

Der Emulator bietet ein PowerShell-Modul zum Starten, Beenden und Deinstallieren des Diensts und zum Abrufen des Dienststatus. Führen Sie das folgende Cmdlet aus, um das PowerShell-Modul zu verwenden:

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

oder platzieren Sie das PSModules-Verzeichnis auf Ihrem PSModulePath, und importieren Sie es wie in folgendem Befehl gezeigt:

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

Hier sehen Sie eine Zusammenfassung der Befehle zum Steuern des Emulators über PowerShell:

Get-CosmosDbEmulatorStatus

Ruft den Status des Emulators ab. Gibt einen dieser ServiceControllerStatus-Werte zurück:

  • ServiceControllerStatus.StartPending
  • ServiceControllerStatus.Running
  • ServiceControllerStatus.Stopped

Wenn ein Fehler auftritt, wird kein Wert zurückgegeben.

Syntax

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

Parameter

Name type BESCHREIBUNG
AlternativeInstallLocation String

Beispiele

  • Ruft den Status eines im Ordner D:\SomeFolder\AzureCosmosDBEmulator installierten Emulators ab.

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

Start-CosmosDbEmulator

Startet den Emulator auf dem lokalen Computer. Standardmäßig wartet der Befehl, bis der Emulator bereit ist, Anforderungen entgegenzunehmen. Verwenden Sie die Option -NoWait, wenn Sie möchten, dass das Cmdlet etwas zurückgeben wird, sobald der Emulator gestartet wurde. Verwenden Sie die Parameter von Start-CosmosDbEmulator, um Optionen wie den NoSQL-Port, den Direktanschluss und die MongoDB-Portnummern anzugeben.

Syntax

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

Parameter

Name type BESCHREIBUNG
AllowNetworkAccess SwitchParameter Lassen Sie den Zugriff von allen IP-Adressen zu, die dem Host des Emulators zugewiesen sind. Sie müssen auch einen Wert für Key oder KeyFile angeben, um den Netzwerkzugriff zuzulassen.
AlternativeInstallLocation String Alternativer Speicherortpfad zur ausführbaren Emulatordatei.
CassandraPort UInt16 Portnummer, die für die API für Cassandra verwendet werden soll. Der Standardport ist 10350.
ComputePort UInt16 Port, der für den Gatewaydienst für Compute-Interop verwendet werden soll. Der Testport für das Gateway des HTTP-Endpunkt wird als ComputePort + 79 berechnet. Daher müssen ComputePort und ComputePort + 79 offen und verfügbar sein. Die Standardports sind 8900 und 8979.
Consistency String Legt die Standardkonsistenzebene für den Emulator auf Sitzung, Stark, Letztlich oder Bounded staleness fest. Die Standardebene ist Sitzung.
Credential PSCredential Gibt ein Benutzerkonto an, das über die Berechtigung zum Ausführen dieser Aktion verfügt. Verwenden Sie einen Benutzernamen, wie User01 oder Domain01\User01, oder geben Sie ein PSCredential-Objekt ein, z. B. eines aus dem Cmdlet Get-Credential. Standardmäßig verwendet das Cmdlet die Anmeldeinformationen des aktuellen Benutzers.
DataPath String Pfad zum Speichern von Datendateien. Der Standardspeicherort für Datendateien ist $env:LocalAppData\CosmosDbEmulator.
DefaultPartitionCount UInt16 Die Anzahl der Partitionen, die pro partitionierter Sammlung reserviert werden sollen. Der Standardwert ist 25, was dem Standardwert für die Gesamtanzahl der Partitionen entspricht.
DirectPort UInt16 Eine Liste mit vier Ports, die für die direkte Konnektivität mit dem Back-End des Emulators verwendet werden sollen. Die Standardliste ist 10251, 10252, 10253 und 10254.
EnableMongoDb SwitchParameter Gibt an, dass die API für den MongoDB-Endpunkt aktiviert ist. Die Standardeinstellung ist false.
EnableCassandra SwitchParameter Gibt an, dass die API für den Apache Cassandra-Endpunkt aktiviert ist. Die Standardeinstellung ist false.
EnableGremlin SwitchParameter Gibt an, dass die API für den Apache Gremlin-Endpunkt aktiviert ist. Die Standardeinstellung ist false.
EnableTable SwitchParameter Gibt an, dass die API für den Table-Endpunkt aktiviert ist. Die Standardeinstellung ist false.
EnableSqlCompute SwitchParameter Gibt an, dass der API für NoSQL-Endpunkt aktiviert ist. Die Standardeinstellung ist false.
EnablePreview SwitchParameter Ermöglicht, dass Emulatorfunktionen, die sich in der Vorschau befinden und noch nicht vollständig ausgereift sind, standardmäßig aktiviert sind.
FailOnSslCertificateNameMismatch SwitchParameter Das selbstsignierte TLS-/SSL-Zertifikat des Emulators wird standardmäßig neu generiert, wenn das SAN des Zertifikats den Domänennamen des Emulator-Hosts, die lokale IP-Adresse (v4), localhost und 127.0.0.1 nicht enthält. Diese Option führt dazu, dass der Start des Emulators stattdessen fehlschlägt. Verwenden Sie dann die Option New-CosmosDbEmulatorCertificate, um ein neues, selbstsigniertes TLS-/SSL-Zertifikat zu erstellen und zu installieren.
GremlinPort UInt16 Portnummer, die für die API für Apache Gremlin verwendet werden soll. Die Standardportnummer ist 8901.
TablePort UInt16 Portnummer, die für die API für Table verwendet werden soll. Die Standardportnummer ist 8902.
SqlComputePort UInt16 Portnummer, die für die API für NoSQL verwendet werden soll. Die Standardportnummer ist 8903.
Key String Autorisierungsschlüssel für den Emulator. Dieser Wert muss die Base64-Codierung eines 64-Bytes-Vektors sein.
MongoPort UInt16 Portnummer, die für die API für MongoDB verwendet werden soll. Die Standardportnummer ist 10250.
MongoApiVersion String Gibt an, welche Version für die API für MongoDB verwendet werden soll. Die Standardversion ist 4.0.
NoFirewall SwitchParameter Gibt an, dass der Firewall des Emulatorhosts keine eingehenden Portregeln hinzugefügt werden sollen.
NoTelemetry SwitchParameter Gibt an, dass das Cmdlet keine Daten für die aktuelle Emulatorsitzung sammeln soll.
NoUI SwitchParameter Gibt an, dass das Cmdlet nicht das Symbol für die Benutzeroberfläche oder Taskleiste darstellen soll.
NoWait SwitchParameter Gibt an, dass das Cmdlet etwas zurückgeben soll, sobald der Emulator gestartet wird. Standardmäßig wartet das Cmdlet, bis der Start abgeschlossen ist und der Emulator bereit ist, Anforderungen zu empfangen, bevor es etwas zurückgibt.
PartitionCount UInt16 Die Gesamtanzahl der Partitionen, die vom Emulator zugeordnet werden.
Port UInt16 Portnummer für den Gatewaydienst des Emulators und die Web-Benutzeroberfläche. Die Standardportnummer ist 8081.
SimulateRateLimiting SwitchParameter
Timeout UInt32
Trace SwitchParameter

Beispiele

  • Starten Sie den Emulator, und warten Sie, bis er vollständig gestartet und bereit ist, Anforderungen zu akzeptieren.

    Start-CosmosDbEmulator
    
  • Starten Sie den Emulator mit 5 Partitionen, die für jede partitionierte Sammlung reserviert sind. Die Gesamtzahl der Partitionen ist auf den Standardwert 25 festgelegt. Daher ist die Gesamtzahl der partitionierten Sammlungen, die erstellt werden können, 5 = 25 partitions / 5 partitions/collection. Jede partitionierte Sammlung ist auf 50 GB = 5 partitions * 10 GB / partiton begrenzt.

    @parameters = {
        DefaultPartitionCount = 5
    }
    Start-CosmosDbEmulator @parameters
    
  • Startet den Emulator mit alternativen Portnummern.

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

Stop-CosmosDbEmulator

Beendet den Emulator. Standardmäßig wartet dieser Befehl, bis der Emulator vollständig heruntergefahren ist. Verwenden Sie die Option -NoWait, wenn Sie möchten, dass das Cmdlet zurückgegeben wird, sobald der Emulator heruntergefahren wird.

Syntax

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

Parameter

Name type BESCHREIBUNG
AlternativeInstallLocation String
Timeout UInt32
NoWait SwitchParameter Gibt an, dass das Cmdlet etwas zurückgeben soll, sobald das Herunterfahren beginnt.
Trace SwitchParameter

Beispiele

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

Uninstall-CosmosDbEmulator

Deinstalliert den Emulator und entfernt optional den gesamten Inhalt von $env:LOCALAPPDATA\CosmosDbEmulator. Das Cmdlet stellt sicher, dass der Emulator vor der Deinstallation beendet wird.

Syntax

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

Parameter

Name type BESCHREIBUNG
RemoveData SwitchParameter Gibt an, dass das Cmdlet alle Daten löschen soll, nachdem der Emulator entfernt wurde.

Beispiele

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

Ändern der Anzahl von Standardcontainern

Sie können standardmäßig bis zu 25 Container mit fester Größe (nur unterstützt durch Azure Cosmos DB SDKs) oder 5 unbegrenzte Container mit dem Emulator erstellen. Durch Ändern des Wertes PartitionCount können Sie bis zu 250 Container mit fester Größe oder 50 Container mit unbegrenzter Größe oder jede Kombination der beiden erstellen, die 250 Container mit fester Größe nicht überschreitet (wobei ein Container mit unbegrenzter Größe 5 Containern mit fester Größe entspricht). Es wird jedoch nicht empfohlen, den Emulator so einzurichten, dass er mit mehr als 200 Containern fester Größe ausgeführt wird. Wegen des Mehraufwands, der den E/A-Vorgängen des Datenträgers hinzugefügt wird, kann es zu unvorhersehbaren Timeouts bei der Verwendung der Endpunkt-APIs kommen.

Wenn Sie versuchen, einen Container zu erstellen, wenn die aktuelle Anzahl von Partitionen überschritten wurde, löst der Emulator eine ServiceUnavailable-Ausnahme mit der folgenden Meldung aus.

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

Gehen Sie wie folgt vor, um die Anzahl von Containern zu ändern, die für den Emulator verfügbar sind:

  1. Löschen Sie alle lokalen Emulatordaten, indem Sie mit der rechten Maustaste auf das Emulator-Symbol in der Taskleiste klicken und dann auf Daten zurücksetzen….

  2. Löschen Sie alle Emulatordaten in diesem Ordner %LOCALAPPDATA%\CosmosDBEmulator.

  3. Schließen Sie alle geöffneten Instanzen, indem Sie mit der rechten Maustaste auf das Emulator-Symbol in der Taskleiste klicken und dann auf Beenden. Bis alle Instanzen beendet wurden, kann unter Umständen eine Minute vergehen.

  4. Installieren der neuesten Version des Emulators.

  5. Starten Sie den Emulator mit dem PartitionCount-Flag, indem Sie einen Wert <= 250 festlegen. Beispiel: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Nächste Schritte