Guida di riferimento alla riga di comando e a PowerShell per l'emulatore di Windows (locale)

Articolo
09/12/2023

SI APPLICA A: Nosql Mongodb Cassandra Gremlin Tabella

L'emulatore di Azure Cosmos DB fornisce un ambiente locale che emula il servizio Azure Cosmos DB a scopo di sviluppo locale. Dopo aver installato l'emulatore, è possibile controllare l'emulatore con i comandi della riga di comando e di PowerShell. Questo articolo descrive come usare i comandi della riga di comando e di PowerShell per avviare e arrestare l'emulatore, configurare le opzioni ed eseguire altre operazioni. È necessario eseguire i comandi dal percorso di installazione.

Importante

Questo articolo include solo gli argomenti della riga di comando per l'emulatore locale di Windows.

Gestire l'emulatore con la sintassi della riga di comando

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

Per visualizzare l'elenco dei parametri, digitare Microsoft.Azure.Cosmos.Emulator.exe /? al prompt dei comandi.

Parametro	Descrizione	Comando di esempio
[Nessun argomento]	Avvia l'emulatore con le impostazioni predefinite.	Microsoft.Azure.Cosmos.Emulator.exe
[Help]	Visualizza l'elenco di argomenti della riga di comando supportati.	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	Ottiene lo stato dell'emulatore. Ogni codice di uscita indica uno stato: `1` = avvio, `2` = esecuzione e `3` = arresto. Un codice di uscita negativo indica che si è verificato un errore. Non viene prodotto altro output.	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	Arresta l'emulatore.	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	Specifica il percorso in cui archiviare i file di dati. Il valore predefinito è `%LocalAppdata%\CosmosDBEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	Specifica il numero di porta da usare per l'emulatore. Il valore predefinito è `8081`.	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	Specifica il numero di porta da usare per il servizio gateway di interoperabilità di calcolo. La porta probe dell'endpoint HTTP del gateway viene calcolata come `ComputePort + 79`. Pertanto, `ComputePort` e `ComputePort + 79` devono essere aperti e disponibili. Il valore predefinito è `8900`.	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	Abilita l'API per MongoDB versione 3.2.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	Abilita l'API per MongoDB versione 3.6.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	Abilita l'API per MongoDB versione 4.0.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	Specifica il numero di porta da usare per l'API per MongoDB. Il valore predefinito è `10255`.	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Abilita l'API per Apache Cassandra.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Specifica il numero di porta da usare per l'API per l'endpoint Cassandra. Il valore predefinito è `10350`.	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Abilita l'API per Apache Gremlin.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Numero di porta da usare per l'API per l'endpoint Apache Gremlin. Il valore predefinito è `8901`.	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Abilita l'API per la tabella.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	Numero di porta da usare per l'API per l'endpoint tabella. Il valore predefinito è `8902`.	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	Legge la chiave di autorizzazione dal file specificato. Usare l'opzione `/GenKeyFile` per generare un file di chiavi.	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	Rimuove in modo ricorsivo tutti i file nel percorso specificato. Se non si specifica un percorso, per impostazione predefinita è `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Iniziare a raccogliere i log di traccia di debug usando LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Interrompere la raccolta dei log di traccia di debug usando LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Iniziare a raccogliere i log di traccia di debug usando lo strumento Registrazione prestazioni di Windows .	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Interrompere la raccolta dei log di traccia di debug usando lo strumento Registrazione prestazioni di Windows .	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	Per impostazione predefinita, l'emulatore rigenera il certificato TLS/SSL autofirmato, se il nome di dominio dell'host dell'emulatore non include il nome di dominio dell'host dell'emulatore, l'indirizzo IP locale (v4), `localhost`e `127.0.0.1`. Con questa opzione, l'emulatore ha invece esito negativo all'avvio. È quindi consigliabile usare l'opzione `/GenCert` per creare e installare un nuovo certificato TLS/SSL autofirmato.	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	Genera e installa un nuovo certificato TLS/SSL autofirmato, facoltativamente, incluso un elenco delimitato da virgole di nomi DNS aggiuntivi per l'accesso all'emulatore in rete.	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	Specifica le porte da usare per la connettività diretta. Le impostazioni predefinite sono `10251`, `10252`, `10253`e `10254`.	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	Chiave di autorizzazione per l'emulatore. La chiave deve essere la codifica Base 64 di un vettore a 64 byte.	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	Specifica che il comportamento di limitazione della frequenza è abilitato.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	Specifica che il comportamento di limitazione della frequenza è disabilitato.	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	Non visualizzare l'interfaccia utente dell'emulatore.	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	Non mostra Esplora dati all'avvio.	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	Specifica il numero massimo di contenitori partizionati. Per altre informazioni, vedere Modificare il numero di contenitori. Il valore predefinito è `25`. Il valore massimo consentito è `250`.	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	Specifica il numero predefinito di partizioni per un contenitore partizionato. Il valore predefinito è `25`.	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	Consente l'accesso all'emulatore tramite una rete. È inoltre necessario passare `/Key=<key_string>` o /`KeyFile=<file_name>` per abilitare l'accesso alla rete.	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	Non modificare le regole del firewall quando `/AllowNetworkAccess` viene usata l'opzione .	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	Genera una nuova chiave di autorizzazione e la salva nel file specificato. La chiave generata può essere usata con le `/Key` opzioni o `/KeyFile` .	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	Imposta il livello di coerenza per l'account. Il valore predefinito è Session.	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	Mostra il messaggio della Guida.

Gestire l'emulatore con i cmdlet di PowerShell

L'emulatore include un modulo di PowerShell per avviare, arrestare, disinstallare e recuperare lo stato del servizio. Eseguire il cmdlet seguente per usare il modulo di PowerShell:

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

o collocare la directory PSModules in PSModulePath e importare il modulo come illustrato nel comando seguente:

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

Ecco un riepilogo dei comandi per il controllo dell'emulatore da PowerShell:

`Get-CosmosDbEmulatorStatus`

Ottiene lo stato dell'emulatore. Restituisce uno dei valori seguenti ServiceControllerStatus :

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

Se viene rilevato un errore, non viene restituito alcun valore.

Sintassi

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

Parametri

Nome	Tipo	Descrizione
`AlternativeInstallLocation`	`String`

Esempi

Ottenere lo stato di un emulatore installato nella D:\SomeFolder\AzureCosmosDBEmulator cartella .

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

`Start-CosmosDbEmulator`

Avvia l'emulatore nel computer locale. Per impostazione predefinita, il comando attende fino a quando l'emulatore è pronto per accettare richieste. Usare l'opzione -NoWait se si vuole che il cmdlet restituisca non appena avvia l'emulatore. Usare i parametri di Start-CosmosDbEmulator per specificare le opzioni, ad esempio la porta NoSQL, la porta diretta e i numeri di porta MongoDB.

Sintassi

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

Parametri

Nome	Tipo	Descrizione
`AllowNetworkAccess`	`SwitchParameter`	Consentire l'accesso da tutti gli indirizzi IP assegnati all'host dell'emulatore. È inoltre necessario specificare un valore per Key o KeyFile per consentire l'accesso alla rete.
`AlternativeInstallLocation`	`String`	Percorso alternativo dell'eseguibile dell'emulatore.
`CassandraPort`	`UInt16`	Numero di porta da usare per l'API per Cassandra. La porta predefinita è `10350`.
`ComputePort`	`UInt16`	Porta da usare per il servizio gateway di interoperabilità di calcolo. La porta probe dell'endpoint HTTP del gateway viene calcolata come `ComputePort + 79`. Pertanto, `ComputePort` e `ComputePort + 79` devono essere aperti e disponibili. Le porte predefinite sono `8900`, `8979`.
`Consistency`	`String`	Imposta il livello di coerenza predefinito per l'emulatore su Session, Strong, Eventual o BoundedStaleness. Il livello predefinito è Session.
`Credential`	`PSCredential`	Specifica un account utente che dispone delle autorizzazioni per eseguire questa azione. Usare un nome utente, ad esempio `User01` o `Domain01\User01`, o immettere un `PSCredential` oggetto, ad esempio uno del `Get-Credential` cmdlet . Per impostazione predefinita, il cmdlet usa le credenziali dell'utente corrente.
`DataPath`	`String`	Percorso per archiviare i file di dati. Il percorso predefinito per i file di dati è `$env:LocalAppData\CosmosDbEmulator`.
`DefaultPartitionCount`	`UInt16`	Numero di partizioni da riservare per raccolta partizionata. Il valore predefinito è 25, che corrisponde al valore predefinito del numero totale di partizioni.
`DirectPort`	`UInt16`	Elenco di quattro porte da usare per la connettività diretta al back-end dell'emulatore. L'elenco predefinito è `10251`, `10252`, `10253`e `10254`.
`EnableMongoDb`	`SwitchParameter`	Specifica che l'API per l'endpoint MongoDB è abilitata. Il valore predefinito è false.
`EnableCassandra`	`SwitchParameter`	Specifica che l'API per l'endpoint Apache Cassandra è abilitata. Il valore predefinito è false.
`EnableGremlin`	`SwitchParameter`	Specifica che l'API per l'endpoint Apache Gremlin è abilitata. Il valore predefinito è false.
`EnableTable`	`SwitchParameter`	Specifica che l'API per l'endpoint table è abilitata. Il valore predefinito è false.
`EnableSqlCompute`	`SwitchParameter`	Specifica che l'API per l'endpoint NoSQL è abilitata. Il valore predefinito è false.
`EnablePreview`	`SwitchParameter`	Abilita le funzionalità dell'emulatore in anteprima e non completamente maturate per impostazione predefinita.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	Per impostazione predefinita, l'emulatore rigenera il certificato TLS/SSL autofirmato, se il nome di dominio dell'host dell'emulatore non include il nome di dominio dell'host dell'emulatore, l'indirizzo IP locale (v4), `localhost`e `127.0.0.1`. Questa opzione causa l'esito negativo dell'emulatore all'avvio. È quindi consigliabile usare l'opzione `New-CosmosDbEmulatorCertificate` per creare e installare un nuovo certificato TLS/SSL autofirmato.
`GremlinPort`	`UInt16`	Numero di porta da usare per l'API per Apache Gremlin. Il numero di porta predefinito è `8901`.
`TablePort`	`UInt16`	Numero di porta da usare per l'API per La tabella. Il numero di porta predefinito è `8902`.
`SqlComputePort`	`UInt16`	Numero di porta da usare per l'API per NoSQL. Il numero di porta predefinito è `8903`.
`Key`	`String`	Chiave di autorizzazione per l'emulatore. Questo valore deve essere la codifica base 64 di un vettore a 64 byte.
`MongoPort`	`UInt16`	Numero di porta da usare per l'API per MongoDB. Il numero di porta predefinito è `10250`.
`MongoApiVersion`	`String`	Specifica la versione da usare per l'API per MongoDB. La versione predefinita è `4.0`.
`NoFirewall`	`SwitchParameter`	Specifica che non devono essere aggiunte regole di porta in ingresso al firewall dell'host dell'emulatore.
`NoTelemetry`	`SwitchParameter`	Specifica che il cmdlet non deve raccogliere dati per la sessione dell'emulatore corrente.
`NoUI`	`SwitchParameter`	Specifica che il cmdlet non deve presentare l'interfaccia utente o l'icona della barra delle applicazioni.
`NoWait`	`SwitchParameter`	Specifica che il cmdlet deve restituire non appena inizia l'avvio dell'emulatore. Per impostazione predefinita, il cmdlet attende il completamento dell'avvio e l'emulatore è pronto per ricevere le richieste prima della restituzione.
`PartitionCount`	`UInt16`	Numero totale di partizioni allocate dall'emulatore.
`Port`	`UInt16`	Numero di porta per il servizio gateway emulatore e l'interfaccia utente Web. Il numero di porta predefinito è `8081`.
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

Esempio

Avviare l'emulatore e attendere che venga avviato completamente e pronto per accettare le richieste.
```
Start-CosmosDbEmulator
```
Avviare l'emulatore con 5 partizioni riservate per ogni raccolta partizionata. Il numero totale di partizioni è impostato sul valore predefinito: 25. Di conseguenza, il numero totale di raccolte partizionate che è possibile creare è 5 = 25 partitions / 5 partitions/collection. Ogni raccolta partizionata è limitata a 50 GB = 5 partitions * 10 GB / partiton.
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

Avvia l'emulatore con numeri di porta alternativi.

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

`Stop-CosmosDbEmulator`

Attesta l'emulatore. Per impostazione predefinita, questo comando attende fino all'arresto completo dell'emulatore. Usare l'opzione -NoWait se si vuole che il cmdlet restituisca valori subito dopo l'inizio dell'arresto dell'emulatore.

Sintassi

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

Parametri

Nome	Tipo	Descrizione
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	Specifica che il cmdlet deve restituire non appena inizia l'arresto.
`Trace`	`SwitchParameter`

Esempio

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

`Uninstall-CosmosDbEmulator`

Disinstalla l'emulatore e, facoltativamente, rimuove il contenuto completo di $env:LOCALAPPDATA\CosmosDbEmulator. Il cmdlet verifica che l'emulatore sia arrestato prima di disinstallarlo.

Sintassi

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

Parametri

Nome	Tipo	Descrizione
`RemoveData`	`SwitchParameter`	Specifica che il cmdlet deve eliminare tutti i dati dopo la rimozione dell'emulatore.

Esempio

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

Modificare il numero di contenitori predefiniti

Per impostazione predefinita, è possibile creare fino a 25 contenitori a dimensione fissa (supportati solo usando gli SDK di Azure Cosmos DB) o 5 contenitori illimitati usando l'emulatore. Modificando il valore PartitionCount , è possibile creare fino a 250 contenitori a dimensione fissa o 50 contenitori illimitati o qualsiasi combinazione dei due contenitori che non superano 250 contenitori a dimensione fissa (dove un contenitore illimitato = 5 contenitori a dimensione fissa). Non è tuttavia consigliabile configurare l'emulatore per l'esecuzione con più di 200 contenitori di dimensione fissa. Ciò comporta infatti un sovraccarico delle operazioni di I/O su disco e può quindi causare timeout imprevedibili quando si usano le API per endpoint.

Se si tenta di creare un contenitore dopo il superamento del conteggio corrente delle partizioni, l'emulatore genera un'eccezione ServiceUnavailable con il messaggio seguente.

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

Per modificare il numero di contenitori disponibili nell'emulatore, eseguire la procedura seguente:

Eliminare tutti i dati dell'emulatore locale facendo clic con il pulsante destro del mouse sull'icona dell'emulatore nell'area di notifica e quindi scegliendo Reimposta dati....
Eliminare tutti i dati dell'emulatore in questa cartella: %LOCALAPPDATA%\CosmosDBEmulator.
Chiudere tutte le istanze aperte facendo clic con il pulsante destro del mouse sull'icona dell'emulatore nell'area di notifica e quindi scegliendo Esci. La chiusura di tutte le istanze può richiedere qualche minuto.
Installare la versione più recente dell'emulatore.
Avviare l'emulatore con il flag PartitionCount impostando un valore <= 250. Ad esempio: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Guida di riferimento alla riga di comando e a PowerShell per l'emulatore di Windows (locale)

Gestire l'emulatore con la sintassi della riga di comando

Gestire l'emulatore con i cmdlet di PowerShell

`Get-CosmosDbEmulatorStatus`

Sintassi

Parametri

Esempi

`Start-CosmosDbEmulator`

Sintassi

Parametri

Esempio

`Stop-CosmosDbEmulator`

Sintassi

Parametri

Esempio

`Uninstall-CosmosDbEmulator`

Sintassi

Parametri

Esempio

Modificare il numero di contenitori predefiniti

Passaggi successivi

Risorse aggiuntive