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

Articolo
08/15/2024

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 la riga di comando e i comandi 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 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
[Guida]	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`. Di conseguenza, `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 chiave.	`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 viene impostato su `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Iniziare a raccogliere i log di traccia di debug con LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Interrompere la raccolta dei log di traccia di debug con 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 certificato SAN 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 (Domain Name System) 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`, `1025210253`, 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. È anche 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"

In alternativa, posizionare la directory nell'oggetto PSModules PSModulePath e importarla 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 controllare l'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 desidera che il cmdlet restituisca non appena avvia l'emulatore. Usare i parametri di Start-CosmosDbEmulator per specificare 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`. Di conseguenza, `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 ogni 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`, `1025310252`, e `10254`.
`EnableMongoDb`	`SwitchParameter`	Specifica che l'API per l'endpoint MongoDB è abilitata. L'impostazione predefinita è false.
`EnableCassandra`	`SwitchParameter`	Specifica che l'API per l'endpoint Apache Cassandra è abilitata. L'impostazione predefinita è false.
`EnableGremlin`	`SwitchParameter`	Specifica che l'API per l'endpoint Apache Gremlin è abilitata. L'impostazione predefinita è false.
`EnableTable`	`SwitchParameter`	Specifica che l'API per l'endpoint tabella è abilitata. L'impostazione predefinita è false.
`EnableSqlCompute`	`SwitchParameter`	Specifica che l'API per l'endpoint NoSQL è abilitata. L'impostazione predefinita è false.
`EnablePreview`	`SwitchParameter`	Abilita le funzionalità dell'emulatore in anteprima e non completamente mature per essere attivate per impostazione predefinita.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	Per impostazione predefinita, l'emulatore rigenera il certificato TLS/SSL autofirmato, se il certificato SAN non include il nome di dominio dell'host dell'emulatore, l'indirizzo IP locale (v4), `localhost`e `127.0.0.1`. Questa opzione fa sì che l'emulatore non riesca 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 Table. 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 essere restituito 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`

Esempi

Avviare l'emulatore e attendere che sia 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 essere restituito non appena inizia l'arresto.
`Trace`	`SwitchParameter`

Esempi

@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.

Esempi

@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 con Azure Cosmos DB Software Development Kit (SDK) o 5 contenitori illimitati usando l'emulatore. Modificando il valore PartitionCount , è possibile creare fino a 250 contenitori a dimensione fissa o 50 contenitori illimitati oppure qualsiasi combinazione dei due contenitori che non supera i 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 a 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 numero di partizioni corrente, 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 nella barra delle applicazioni 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. L'uscita di tutte le istanze potrebbe richiedere un 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.

Condividi tramite

Guida di riferimento alla riga di comando e a PowerShell per l'emulatore 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

Esempi

`Stop-CosmosDbEmulator`

Sintassi

Parametri

Esempi

`Uninstall-CosmosDbEmulator`

Sintassi

Parametri

Esempi

Modificare il numero di contenitori predefiniti

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive