Usare l'emulatore di Azure Cosmos DB per sviluppo e test localiUse the Azure Cosmos DB Emulator for local development and testing

File binariBinaries Scarica MSIDownload MSI
DockerDocker Hub dockerDocker Hub
Origine dockerDocker source GithubGithub

L'emulatore di Azure Cosmos DB fornisce un ambiente locale che emula il servizio Azure Cosmos DB a fini di sviluppo.The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Usando l'emulatore di Azure Cosmos DB, è possibile sviluppare e testare l'applicazione in locale, senza creare una sottoscrizione di Azure né sostenere costi.Using the Azure Cosmos DB Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. Quando si è soddisfatti del funzionamento dell'applicazione nell'emulatore di Azure Cosmos DB, è possibile iniziare a usare l'account Azure Cosmos DB nel cloud.When you're satisfied with how your application is working in the Azure Cosmos DB Emulator, you can switch to using an Azure Cosmos DB account in the cloud.

Questo articolo illustra le attività seguenti:This article covers the following tasks:

  • Installazione dell'emulatoreInstalling the Emulator
  • Autenticazione delle richiesteAuthenticating requests
  • Uso di Esplora dati nell'emulatoreUsing the Data Explorer in the Emulator
  • Esportazione di certificati SSLExporting SSL certificates
  • Chiamata dell'emulatore dalla riga di comandoCalling the Emulator from the command line
  • Esecuzione dell'emulatore in Docker per WindowsRunning the Emulator on Docker for Windows
  • Raccolta dei file di tracciaCollecting trace files
  • Risoluzione dei problemiTroubleshooting

È consigliabile guardare prima di tutto il video seguente, in cui Kirill Gavrylyuk illustra come iniziare a usare l'emulatore di Azure Cosmos DB.We recommend getting started by watching the following video, where Kirill Gavrylyuk shows how to get started with the Azure Cosmos DB Emulator. Si noti che il video fa riferimento all'emulatore come emulatore di DocumentDB, ma lo strumento stesso è stato rinominato Emulatore Azure Cosmos DB dopo la registrazione del video.Note that the video refers to the emulator as the DocumentDB Emulator, but the tool itself has been renamed the Azure Cosmos DB Emulator since taping the video. Tutte le informazioni del video sono ancora corrette per l'emulatore Azure Cosmos DB.All information in the video is still accurate for the Azure Cosmos DB Emulator.

Come funziona l'emulatoreHow the Emulator works

L'emulatore Azure Cosmos DB offre un'emulazione ultra fedele del servizio Azure Cosmos DB.The Azure Cosmos DB Emulator provides a high-fidelity emulation of the Azure Cosmos DB service. Supporta le stesse funzionalità di Azure Cosmos DB, incluso il supporto per la creazione e l'esecuzione di query su documenti JSON, il provisioning e la scalabilità delle raccolte e l'esecuzione di stored procedure e trigger.It supports identical functionality as Azure Cosmos DB, including support for creating and querying JSON documents, provisioning and scaling collections, and executing stored procedures and triggers. È possibile sviluppare e testare le applicazioni usando l'emulatore di Azure Cosmos DB e distribuirle in Azure su scala globale semplicemente apportando una singola modifica di configurazione all'endpoint di connessione per Azure Cosmos DB.You can develop and test applications using the Azure Cosmos DB Emulator, and deploy them to Azure at global scale by just making a single configuration change to the connection endpoint for Azure Cosmos DB.

Anche se è stata creata un'emulazione locale estremamente fedele del servizio Azure Cosmos DB effettivo, l'implementazione dell'emulatore di Azure Cosmos DB è diversa da quella del servizio.While we created a high-fidelity local emulation of the actual Azure Cosmos DB service, the implementation of the Azure Cosmos DB Emulator is different than that of the service. L'emulatore di Azure Cosmos DB, ad esempio, usa i componenti del sistema operativo standard, ad esempio il file system locale per la persistenza e lo stack di protocolli HTTPS per la connettività.For example, the Azure Cosmos DB Emulator uses standard OS components such as the local file system for persistence, and HTTPS protocol stack for connectivity. Di conseguenza alcune funzionalità basate sull'infrastruttura di Azure, ad esempio la replica globale, la latenza in millisecondi a cifra singola per le operazioni di lettura/scrittura e i livelli di coerenza regolabili, non sono disponibili nell'emulatore di Azure Cosmos DB.This means that some functionality that relies on Azure infrastructure like global replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not available via the Azure Cosmos DB Emulator.

Nota

Esplora dati nell'emulatore supporta attualmente solo la creazione di raccolte di API DocumentDB e raccolte di MongoDB.At this time the Data Explorer in the emulator only supports the creation of DocumentDB API collections and MongoDB collections. Esplora dati nell'emulatore non supporta attualmente la creazione di tabelle e grafici.The Data Explorer in the emulator does not currently support the creation of tables and graphs.

Differenze tra l'emulatore e il servizioDifferences between the Emulator and the service

Poiché l'emulatore di Azure Cosmos DB fornisce un ambiente emulato eseguito in una workstation di sviluppo locale, esistono alcune differenze a livello di funzionalità tra l'emulatore e un account Azure Cosmos DB nel cloud:Because the Azure Cosmos DB Emulator provides an emulated environment running on a local developer workstation, there are some differences in functionality between the emulator and an Azure Cosmos DB account in the cloud:

  • L'emulatore di Azure Cosmos DB supporta solo un singolo account fisso e una chiave master nota.The Azure Cosmos DB Emulator supports only a single fixed account and a well-known master key. La rigenerazione della chiave non è possibile nell'emulatore di Azure Cosmos DB.Key regeneration is not possible in the Azure Cosmos DB Emulator.
  • L'emulatore di Azure Cosmos DB non è un servizio scalabile e non supporta un numero elevato di raccolte.The Azure Cosmos DB Emulator is not a scalable service and will not support a large number of collections.
  • L'emulatore di Azure Cosmos DB non simula livelli di coerenza di Azure Cosmos DB diversi.The Azure Cosmos DB Emulator does not simulate different Azure Cosmos DB consistency levels.
  • L'emulatore di Azure Cosmos DB non simula la replica tra più aree.The Azure Cosmos DB Emulator does not simulate multi-region replication.
  • L'emulatore di Azure Cosmos DB non supporta gli override della quota del servizio disponibili nel servizio Azure Cosmos DB, ad esempio i limiti di dimensioni dei documenti e lo spazio di archiviazione per le raccolte aumentato.The Azure Cosmos DB Emulator does not support the service quota overrides that are available in the Azure Cosmos DB service (e.g. document size limits, increased partitioned collection storage).
  • Poiché la copia dell'emulatore di Azure Cosmos DB potrebbe non essere aggiornata con le modifiche più recenti del servizio Azure Cosmos DB, vedere Capacity Planner di Azure Cosmos DB per stimare con precisione le esigenze di produttività (UR) dell'applicazione.As your copy of the Azure Cosmos DB Emulator might not be up to date with the most recent changes with the Azure Cosmos DB service, please Azure Cosmos DB capacity planner to accurately estimate production throughput (RUs) needs of your application.

Requisiti di sistemaSystem requirements

L'emulatore di Azure Cosmos DB presenta i requisiti hardware e software seguenti:The Azure Cosmos DB Emulator has the following hardware and software requirements:

  • Requisiti softwareSoftware requirements
    • Windows Server 2012 R2, Windows Server 2016 o Windows Server 10Windows Server 2012 R2, Windows Server 2016, or Windows 10
  • Requisiti hardware minimiMinimum Hardware requirements
    • 2 GB di RAM2 GB RAM
    • 10 GB di spazio su disco disponibile10 GB available hard disk space

InstallazioneInstallation

È possibile scaricare e installare l'emulatore di Azure Cosmos DB dall'Area download Microsoft o eseguirlo in Docker per Windows.You can download and install the Azure Cosmos DB Emulator from the Microsoft Download Center or you can run the emulator on Docker for Windows. Per istruzioni sull'uso dell'emulatore in Docker per Windows, vedere Esecuzione in Docker.For instructions on using the Emulator on Docker for Windows, see Running on Docker.

Nota

Per installare, configurare ed eseguire l'emulatore di Azure Cosmos DB, è necessario avere i privilegi di amministratore nel computer.To install, configure, and run the Azure Cosmos DB Emulator, you must have administrative privileges on the computer.

Esecuzione in WindowsRunning on Windows

Per avviare l'emulatore di Azure Cosmos DB, selezionare il pulsante Start o premere WINDOWS sulla tastiera.To start the Azure Cosmos DB Emulator, select the Start button or press the Windows key. Iniziare a digitare emulatore di Azure Cosmos DBe selezionare l'emulatore nell'elenco di applicazioni.Begin typing Azure Cosmos DB Emulator, and select the emulator from the list of applications.

Selezionare il pulsante Start o premere il tasto WINDOWS, iniziare a digitare **emulatore di Azure Cosmos DB** e selezionare l'emulatore nell'elenco di applicazioni

Quando l'emulatore è in esecuzione, verrà visualizzata un'icona nell'area di notifica della barra delle applicazioni di Windows.When the emulator is running, you'll see an icon in the Windows taskbar notification area. Notifica della barra delle applicazioni dell'emulatore locale di Azure Cosmos DB

Per impostazione predefinita, l'emulatore di Azure Cosmos DB viene eseguito nel computer locale ("localhost") in ascolto sulla porta 8081.The Azure Cosmos DB Emulator by default runs on the local machine ("localhost") listening on port 8081.

Per impostazione predefinita, l'emulatore di Azure Cosmos DB viene installato nella directory C:\Program Files\Azure Cosmos DB Emulator.The Azure Cosmos DB Emulator is installed by default to the C:\Program Files\Azure Cosmos DB Emulator directory. È anche possibile avviare e arrestare l'emulatore dalla riga di comando.You can also start and stop the emulator from the command-line. Per altre informazioni, vedere le informazioni di riferimento sullo strumento da riga di comando.See command-line tool reference for more information.

Avviare Esplora datiStart Data Explorer

Quando l'emulatore di Azure Cosmos DB viene avviato, apre automaticamente Esplora dati di Azure Cosmos DB nel browser.When the Azure Cosmos DB emulator launches it automatically opens the Azure Cosmos DB Data Explorer in your browser. L'indirizzo visualizzato è https://localhost:8081/_explorer/index.html.The address appears as https://localhost:8081/_explorer/index.html. Se si chiude lo strumento di esplorazione e lo si vuole riaprire in seguito, è possibile aprire l'URL nel browser o avviarlo dall'emulatore di Azure Cosmos DB usando l'icona dell'area di notifica di Windows, come illustrato sotto.If you close the explorer and would like to re-open it later, you can either open the URL in your browser or launch it from the Azure Cosmos DB Emulator in the Windows Tray Icon as shown below.

Utilità di avvio di Esplora dati dell'emulatore locale di Azure Cosmos DB

Preparazione per gli aggiornamentiChecking for updates

Esplora dati indica se è disponibile un nuovo aggiornamento per il download.Data Explorer indicates if there is a new update available for download.

Nota

I dati creati in una versione dell'emulatore di Azure Cosmos DB non sono necessariamente accessibili quando si usa una versione diversa.Data created in one version of the Azure Cosmos DB Emulator is not guaranteed to be accessible when using a different version. Se è necessario rendere persistenti i dati a lungo termine, si consiglia di archiviare i dati in un account di Azure Cosmos DB invece che nell'emulatore di Azure Cosmos DB.If you need to persist your data for the long term, it is recommended that you store that data in an Azure Cosmos DB account, rather than in the Azure Cosmos DB Emulator.

Autenticazione delle richiesteAuthenticating requests

Come per Azure Cosmos DB nel cloud, tutte le richieste effettuate nell'emulatore di Azure Cosmos DB devono essere autenticate.Just as with Azure Cosmos DB in the cloud, every request that you make against the Azure Cosmos DB Emulator must be authenticated. L'emulatore di Azure Cosmos DB supporta un singolo account fisso e una chiave di autenticazione nota per l'autenticazione della chiave master.The Azure Cosmos DB Emulator supports a single fixed account and a well-known authentication key for master key authentication. Questo account e questa chiave sono le uniche credenziali consentite per l'uso con l'emulatore di Azure Cosmos DB.This account and key are the only credentials permitted for use with the Azure Cosmos DB Emulator. Sono:They are:

Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Nota

La chiave master supportata dall'emulatore di Azure Cosmos DB deve essere usata solo con l'emulatore.The master key supported by the Azure Cosmos DB Emulator is intended for use only with the emulator. È possibile utilizzare l'account Azure Cosmos DB di produzione e la chiave con l'emulatore di Azure Cosmos DB.You cannot use your production Azure Cosmos DB account and key with the Azure Cosmos DB Emulator.

Nota

Se l'emulatore è stato avviato con l'opzione /Key, usare la chiave generata anziché "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="If you have started the emulator with the /Key option, then use the generated key instead of "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="

Proprio come il servizio Azure Cosmos DB, anche l'emulatore di Azure Cosmos DB supporta solo la comunicazione sicura tramite SSL.Additionally, just as the Azure Cosmos DB service, the Azure Cosmos DB Emulator supports only secure communication via SSL.

Esecuzione in una rete localeRunning on a local network

È possibile eseguire l'emulatore in una rete locale.You can run the emulator on a local network. Per abilitare l'accesso alla rete, specificare l'opzione /AllowNetworkAccess nella riga di comando, che richiede di specificare anche /Key=stringa_chiave o /KeyFile=nome_file.To enable network access, specify the /AllowNetworkAccess option at the command line, which also requires that you specify /Key=key_string or /KeyFile=file_name. È possibile usare /GenKeyFile=nome_file per generare un file con una chiave casuale sin dall'inizio,You can use /GenKeyFile=file_name to generate a file with a random key upfront. per poi passarlo a /KeyFile=nome_file o /Key=contenuto_del_file.Then you can pass that to /KeyFile=file_name or /Key=contents_of_file.

Per abilitare l'accesso alla rete per la prima volta, l'utente deve arrestare l'emulatore ed eliminare la directory dei dati dell'emulatore (C:\Users\nome_utente\AppData\Local\CosmosDBEmulator).To enable network access for the first time the user should shutdown the emulator and delete the emulator’s data directory (C:\Users\user_name\AppData\Local\CosmosDBEmulator).

Sviluppo con l'emulatoreDeveloping with the Emulator

Quando l'emulatore di Azure Cosmos DB è in esecuzione sul desktop, è possibile usare qualsiasi Azure Cosmos DB SDK supportato o l'API REST di Azure Cosmos DB per interagire con l'emulatore.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use any supported Azure Cosmos DB SDK or the Azure Cosmos DB REST API to interact with the Emulator. L'emulatore Azure Cosmos DB include anche l'utilità Esplora dati predefinita che consente di creare raccolte per API DocumentDB e MongoDB e di visualizzare e modificare documenti senza scrivere codice.The Azure Cosmos DB Emulator also includes a built-in Data Explorer that lets you create collections for the DocumentDB and MongoDB APIs, and view and edit documents without writing any code.

// Connect to the Azure Cosmos DB Emulator running locally
DocumentClient client = new DocumentClient(
    new Uri("https://localhost:8081"), 
    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

Se si usa il supporto del protocollo Azure Cosmos DB per MongoDB, usare la stringa di connessione seguente:If you're using Azure Cosmos DB protocol support for MongoDB, please use the following connection string:

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

È possibile usare gli strumenti esistenti, ad esempio Azure DocumentDB Studio, per connettersi all'emulatore di Azure Cosmos DB.You can use existing tools like Azure DocumentDB Studio to connect to the Azure Cosmos DB Emulator. È anche possibile eseguire la migrazione dei dati tra l'emulatore di Azure Cosmos DB e il servizio Azure Cosmos DB usando lo strumento per la migrazione dei dati di Azure Cosmos DB.You can also migrate data between the Azure Cosmos DB Emulator and the Azure Cosmos DB service using the Azure Cosmos DB Data Migration Tool.

Nota

Se l'emulatore è stato avviato con l'opzione /Key, usare la chiave generata anziché "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="If you have started the emulator with the /Key option, then use the generated key instead of "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="

Usando l'emulatore di Azure Cosmos DB, per impostazione predefinita è possibile creare fino a 25 raccolte con partizione singola o una raccolta partizionata.Using the Azure Cosmos DB emulator, by default, you can create up to 25 single partition collections or 1 partitioned collection. Per altre informazioni sulla modifica di questo valore, vedere la sezione su come impostare il valore PartitionCount.For more information about changing this value, see Setting the PartitionCount value.

Esportare il certificato SSLExport the SSL certificate

I linguaggi e il runtime .NET usano l'archivio certificati Windows per connettersi in modo sicuro all'emulatore locale di Azure Cosmos DB..NET languages and runtime use the Windows Certificate Store to securely connect to the Azure Cosmos DB local emulator. Gli altri linguaggi hanno il proprio metodo di gestione e uso dei certificati.Other languages have their own method of managing and using certificates. Java usa il proprio archivio certificati, mentre Python usa i wrapper per i socket.Java uses its own certificate store whereas Python uses socket wrappers.

Per ottenere un certificato da usare con i linguaggi e i runtime che non si integrano con l'archivio certificati Windows, sarà necessario esportarlo usando Gestione certificati di Windows.In order to obtain a certificate to use with languages and runtimes that do not integrate with the Windows Certificate Store you will need to export it using the Windows Certificate Manager. Per avviarlo, eseguire certlm.msc o seguire le istruzioni dettagliate nel post Export the Azure Cosmos DB Emulator Certificates (Esportare i certificati dell'emulatore di Azure Cosmos DB).You can start it by running certlm.msc or follow the step by step instructions in Export the Azure Cosmos DB Emulator Certificates. Quando Gestione certificati è in esecuzione, aprire i certificati personali, come illustrato sotto, ed esportare il certificato con il nome descrittivo "DocumentDBEmulatorCertificate" come file Codificato Base 64 X.509 (.CER).Once the certificate manager is running, open the Personal Certificates as shown below and export the certificate with the friendly name "DocumentDBEmulatorCertificate" as a BASE-64 encoded X.509 (.cer) file.

Certificato SSL dell'emulatore locale di Azure Cosmos DB

Per importare il certificato X.509 nell'archivio certificati Java, seguire le istruzioni disponibili in Aggiunta di un certificato all'archivio certificati CA Java.The X.509 certificate can be imported into the Java certificate store by following the instructions in Adding a Certificate to the Java CA Certificates Store. Dopo l'importazione del certificato nell'archivio certificati, le applicazioni Java e MongoDB, potranno connettersi all'emulatore di Azure Cosmos DB.Once the certificate is imported into the certificate store, Java and MongoDB applications will be able to connect to the Azure Cosmos DB Emulator.

Quando ci si connette all'emulatore da Python e Node.js SDK, la verifica SSL è disabilitata.When connecting to the emulator from Python and Node.js SDKs, SSL verification is disabled.

Riferimenti allo strumento da riga di comandoCommand-line tool reference

Dal percorso di installazione è possibile usare la riga di comando per avviare e arrestare l'emulatore, configurare le opzioni ed eseguire altre operazioni.From the installation location, you can use the command-line to start and stop the emulator, configure options, and perform other operations.

Sintassi della riga di comandoCommand-line syntax

CosmosDB.Emulator.exe [/Shutdown] [/DataPath] [/Port] [/MongoPort] [/DirectPorts] [/Key] [/EnableRateLimiting] [/DisableRateLimiting] [/NoUI] [/NoExplorer] [/?]

Per visualizzare l'elenco di opzioni, digitare CosmosDB.Emulator.exe /? al prompt dei comandi.To view the list of options, type CosmosDB.Emulator.exe /? at the command prompt.

OpzioneOption DescrizioneDescription ComandoCommand ArgomentiArguments
[Nessun argomento][No arguments] Avvia l'emulatore di Azure Cosmos DB con le impostazioni predefinite.Starts up the Azure Cosmos DB Emulator with default settings. CosmosDB.Emulator.exeCosmosDB.Emulator.exe
[Help][Help] Visualizza l'elenco di argomenti della riga di comando supportati.Displays the list of supported command-line arguments. CosmosDB.Emulator.exe /?CosmosDB.Emulator.exe /?
ShutdownShutdown Arresta l'emulatore di Azure Cosmos DB.Shuts down the Azure Cosmos DB Emulator. CosmosDB.Emulator.exe /ShutdownCosmosDB.Emulator.exe /Shutdown
DataPathDataPath Specifica il percorso in cui archiviare i file di dati.Specifies the path in which to store data files. Il valore predefinito è %LocalAppdata%\CosmosDBEmulator.Default is %LocalAppdata%\CosmosDBEmulator. CosmosDB.Emulator.exe /DataPath=<percorsodati>CosmosDB.Emulator.exe /DataPath=<datapath> <percorsodati>: percorso accessibile<datapath>: An accessible path
PortaPort Specifica il numero di porta da usare per l'emulatore.Specifies the port number to use for the emulator. Il valore predefinito è 8081.Default is 8081. CosmosDB.Emulator.exe /Port=<porta>CosmosDB.Emulator.exe /Port=<port> <porta>: numero di porta singolo<port>: Single port number
MongoPortMongoPort Specifica il numero di porta da usare per l'API di compatibilità MongoDB.Specifies the port number to use for MongoDB compatibility API. Il valore predefinito è 10255.Default is 10255. CosmosDB.Emulator.exe /MongoPort=<portaMongo>CosmosDB.Emulator.exe /MongoPort=<mongoport> <portaMongo>: numero di porta singolo<mongoport>: Single port number
DirectPortsDirectPorts Specifica le porte da usare per la connettività diretta.Specifies the ports to use for direct connectivity. I valori predefiniti sono 10251, 10252, 10253 e 10254.Defaults are 10251,10252,10253,10254. CosmosDB.Emulator.exe /DirectPorts:<portedirette>CosmosDB.Emulator.exe /DirectPorts:<directports> <portedirette>: elenco delimitato da virgole di 4 porte.<directports>: Comma-delimited list of 4 ports
ChiaveKey Chiave di autorizzazione per l'emulatore.Authorization key for the emulator. La chiave deve essere la codifica Base 64 di un vettore a 64 byte.Key must be the base-64 encoding of a 64-byte vector. CosmosDB.Emulator.exe /Key:<chiave>CosmosDB.Emulator.exe /Key:<key> <chiave>: la chiave deve essere la codifica Base 64 di un vettore a 64 byte.<key>: Key must be the base-64 encoding of a 64-byte vector
EnableRateLimitingEnableRateLimiting Specifica che il comportamento di limitazione della frequenza è abilitato.Specifies that request rate limiting behavior is enabled. CosmosDB.Emulator.exe /EnableRateLimitingCosmosDB.Emulator.exe /EnableRateLimiting
DisableRateLimitingDisableRateLimiting Specifica che il comportamento di limitazione della frequenza è disabilitato.Specifies that request rate limiting behavior is disabled. CosmosDB.Emulator.exe /DisableRateLimitingCosmosDB.Emulator.exe /DisableRateLimiting
NoUINoUI Non mostra l'interfaccia utente dell'emulatore.Do not show the emulator user interface. CosmosDB.Emulator.exe /NoUICosmosDB.Emulator.exe /NoUI
NoExplorerNoExplorer Non mostra Esplora documenti all'avvio.Don't show document explorer on startup. CosmosDB.Emulator.exe /NoExplorerCosmosDB.Emulator.exe /NoExplorer
PartitionCountPartitionCount Specifica il numero massimo di raccolte partizionate.Specifies the maximum number of partitioned collections. Per altre informazioni vedere Modificare il numero di raccolte.See Change the number of collections for more information. CosmosDB.Emulator.exe /PartitionCount=<conteggiopartizioni>CosmosDB.Emulator.exe /PartitionCount=<partitioncount> <partitioncount>: numero massimo di raccolte con partizione singola consentite.<partitioncount>: Maximum number of allowed single partition collections. Il valore predefinito è 25.Default is 25. Il valore massimo consentito è 250.Maximum allowed is 250.
DefaultPartitionCountDefaultPartitionCount Specifica il numero predefinito di partizioni per una raccolta partizionata.Specifies the default number of partitions for a partitioned collection. CosmosDB.Emulator.exe /DefaultPartitionCount=<numeropredefinitopartizioni>CosmosDB.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount> <numeropredefinitopartizioni> Il valore predefinito è 25.<defaultpartitioncount> Default is 25.
AllowNetworkAccessAllowNetworkAccess Consente l'accesso all'emulatore tramite una rete.Enables access to the emulator over a network. È necessario passare anche /Key=<stringa_chiave> o /KeyFile=<nome_file> per abilitare l'accesso alla rete.You must also pass /Key=<key_string> or /KeyFile=<file_name> to enable network access. CosmosDB.Emulator.exe /AllowNetworkAccess /Key=<stringa_chiave>CosmosDB.Emulator.exe /AllowNetworkAccess /Key=<key_string>

oppureor

CosmosDB.Emulator.exe /AllowNetworkAccess /KeyFile=<nome_file>CosmosDB.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>
NoFirewallNoFirewall Non modificare le regole del firewall quando si usa /AllowNetworkAccess.Don't adjust firewall rules when /AllowNetworkAccess is used. CosmosDB.Emulator.exe /NoFirewallCosmosDB.Emulator.exe /NoFirewall
GenKeyFileGenKeyFile Genera una nuova chiave di autorizzazione e la salva nel file specificato.Generate a new authorization key and save to the specified file. La chiave generata può essere usata con le opzioni /Key o /KeyFile.The generated key can be used with the /Key or /KeyFile options. CosmosDB.Emulator.exe /GenKeyFile=<percorso del file della chiave>CosmosDB.Emulator.exe /GenKeyFile=<path to key file>
ConsistencyConsistency Imposta il livello di coerenza per l'account.Set the default consistency level for the account. CosmosDB.Emulator.exe /Consistency=<coerenza>CosmosDB.Emulator.exe /Consistency=<consistency> <coerenza>: il valore deve essere uno dei seguenti livelli di coerenza: Session, Strong, Eventual o BoundedStaleness.<consistency>: Value must be one of the following consistency levels: Session, Strong, Eventual, or BoundedStaleness. Il valore predefinito è Session.The default value is Session.
?? Mostra il messaggio della Guida.Show the help message.

Modificare il numero di raccolteChange the number of collections

Per impostazione predefinita, è possibile creare fino a 25 raccolte con partizione singola o una raccolta partizionata usando l'emulatore di Azure Cosmos DB.By default, you can create up to 25 single partition collections, or 1 partitioned collection using the Azure Cosmos DB Emulator. Modificando il valore PartitionCount, è possibile creare fino a 250 raccolte a partizione singola o 10 raccolte partizionate o qualsiasi combinazione delle due che non contenga più di 250 raccolte a partizione singola (dove una raccolta partizionata = 25 raccolte a partizione singola).By modifying the PartitionCount value, you can create up to 250 single partition collections or 10 partitioned collections, or any combination of the two that does not exceed 250 single partitions (where 1 partitioned collection = 25 single partition collection).

Se si tenta di creare una raccolta dopo il superamento di questi limiti, l'emulatore genera un'eccezione ServiceUnavailable con il messaggio seguente.If you attempt to create a collection after the current partition count has been exceeded, the emulator throws a ServiceUnavailable exception, with the following message.

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. 
Please do not hesitate to email docdbswat@microsoft.com at any time or 
for any reason. ActivityId: 29da65cc-fba1-45f9-b82c-bf01d78a1f91

Per modificare il numero di raccolte disponibili nell'emulatore di Azure Cosmos DB, procedere come segue:To change the number of collections available to the Azure Cosmos DB Emulator, do the following:

  1. Eliminare tutti i dati locali dell'emulatore di Azure Cosmos DB facendo clic sull'icona dell'emulatore di Azure Cosmos DB sull'area di notifica e quindi su Reset data (Reimposta dati).Delete all local Azure Cosmos DB Emulator data by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Reset Data….
  2. Eliminare tutti i dati dell'emulatore dalla cartella C:\Users\user_name\AppData\Local\CosmosDBEmulator.Delete all emulator data in this folder C:\Users\user_name\AppData\Local\CosmosDBEmulator.
  3. Chiudere tutte le istanze aperte facendo clic con il pulsante destro del mouse sull'icona dell'emulatore di Azure Cosmos DB sull'area di notifica, quindi fare clic su Esci.Exit all open instances by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Exit. La chiusura di tutte le istanze può richiedere qualche minuto.It may take a minute for all instances to exit.
  4. Installare la versione più recente dell'emulatore di Azure Cosmos DB.Install the latest version of the Azure Cosmos DB Emulator.
  5. Avviare l'emulatore con il flag PartitionCount impostando un valore <= 250.Launch the emulator with the PartitionCount flag by setting a value <= 250. Ad esempio: C:\Program Files\Azure CosmosDB Emulator>CosmosDB.Emulator.exe /PartitionCount=100.For example: C:\Program Files\Azure CosmosDB Emulator>CosmosDB.Emulator.exe /PartitionCount=100.

Esecuzione in DockerRunning on Docker

L'emulatore di Azure Cosmos DB può essere eseguito in Docker per Windows.The Azure Cosmos DB Emulator can be run on Docker for Windows. L'emulatore non funziona su Docker per Oracle Linux.The Emulator does not work on Docker for Oracle Linux.

Dopo aver installato Docker per Windows, passare ai contenitori Windows facendo clic con il pulsante destro del mouse sull'icona di Docker sulla barra degli strumenti e selezionando Switch to Windows containers (Passa a contenitori Windows).Once you have Docker for Windows installed, switch to Windows containers by right-clicking the Docker icon on the toolbar and selecting Switch to Windows containers.

Eseguire quindi il pull dell'immagine dell'emulatore dall'hub Docker eseguendo il comando seguente dalla shell preferita.Next, pull the Emulator image from Docker Hub by running the following command from your favorite shell.

docker pull microsoft/azure-cosmosdb-emulator 

Per avviare l'immagine, eseguire i comandi seguenti.To start the image, run the following commands.

Dalla riga di comando:From the command line:

md %LOCALAPPDATA%\CosmosDBEmulatorCert 2>null
docker run -v %LOCALAPPDATA%\CosmosDBEmulatorCert:c:\CosmosDBEmulator\CosmosDBEmulatorCert -P -t -i -m 2GB microsoft/azure-cosmosdb-emulator 

Da PowerShell:From PowerShell:

md $env:LOCALAPPDATA\CosmosDBEmulatorCert 2>null
docker run -v $env:LOCALAPPDATA\CosmosDBEmulatorCert:c:\CosmosDBEmulator\CosmosDBEmulatorCert -P -t -i -m 2GB microsoft/azure-cosmosdb-emulator 

La risposta sarà simile a quanto riportato di seguito:The response looks similar to the following:

Starting Emulator
Emulator Endpoint: https://172.20.229.193:8081/
Master Key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Exporting SSL Certificate
You can import the SSL certificate from an administrator command prompt on the host by running:
cd /d %LOCALAPPDATA%\CosmosDBEmulatorCert
powershell .\importcert.ps1
--------------------------------------------------------------------------------------------------
Starting interactive shell

Usare ora nel client l'endpoint e la chiave master presenti nella risposta e importare il certificato SSL nell'host.Now use the endpoint and master key in from the response in your client and import the SSL certificate into your host. Per importare il certificato SSL, eseguire le operazioni seguenti da un prompt dei comandi di amministratore:To import the SSL certificate, do the following from an admin command prompt:

cd %LOCALAPPDATA%\CosmosDBEmulatorCert
powershell .\importcert.ps1

Se si chiude la shell interattiva una volta avviato l'emulatore, il contenitore dell'emulatore verrà arrestato.Closing the interactive shell once the Emulator has been started will shutdown the Emulator’s container.

Per aprire Esplora dati, passare all'URL seguente nel browser.To open the Data Explorer navigate to the following URL in your browser. L'endpoint dell'emulatore è specificato nel messaggio di risposta illustrato in precedenza.The emulator endpoint is provided in the response message shown above.

https://<emulator endpoint provided in response>/_explorer/index.html

Risoluzione dei problemiTroubleshooting

Usa i suggerimenti seguenti per aiutare a risolvere i problemi dell'emulatore di Azure Cosmos DB:Use the following tips to help troubleshoot issues you encounter with the Azure Cosmos DB emulator:

  • Se è stata installata una nuova versione dell'emulatore e si verificano errori, provare a ripristinare i dati.If you installed a new version of the Emulator and are experiencing errors, ensure you reset your data. Per ripristinare i dati, fare clic con il pulsante destro del mouse sull'icona dell'emulatore di Azure Cosmos DB nell'area di notifica e quindi fare clic su Reset Data (Ripristina dati).You can reset your data by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Reset Data…. Se gli errori persistono, è possibile provare a disinstallare e reinstallare l'app.If that does not fix the errors, you can uninstall and reinstall the app. Per istruzioni, vedere Disinstallare l'emulatore locale.See Uninstall the local emulator for instructions.

  • In caso di arresto anomalo dell'emulatore di Azure Cosmos DB, raccogliere file di dump dalla cartella c:\Users\nome_utente\AppData\Local\CrashDumps, comprimerli e allegarli a un messaggio di posta elettronica da inviare all'indirizzo askcosmosdb@microsoft.com.If the Azure Cosmos DB emulator crashes, collect dump files from c:\Users\user_name\AppData\Local\CrashDumps folder, compress them, and attach them to an email to askcosmosdb@microsoft.com.

  • In caso di arresti anomali del sistema in CosmosDB.StartupEntryPoint.exe, eseguire il comando seguente da un prompt dei comandi di amministratore: lodctr /RIf you experience crashes in CosmosDB.StartupEntryPoint.exe, run the following command from an admin command prompt: lodctr /R

  • In caso di problemi di connettività, raccogliere i file di traccia, comprimerli e allegarli a un messaggio di posta elettronica da inviare all'indirizzo askcosmosdb@microsoft.com.If you encounter a connectivity issue, collect trace files, compress them, and attach them to an email to askcosmosdb@microsoft.com.

  • Se si riceve un messaggio di tipo Servizio non disponibile, è possibile che l'emulatore non riesca a inizializzare lo stack di rete.If you receive a Service Unavailable message, the emulator might be failing to initialize the network stack. Controllare per verificare se è stato installato il client sicuro Pulse o il client di rete Juniper, perché è possibile che i rispettivi driver del filtro di rete provochino il problema.Check to see if you have the Pulse secure client or Juniper networks client installed, as their network filter drivers may cause the problem. La disinstallazione dei driver filtro di rete di terze parti consente in genere di risolvere il problema.Uninstalling third party network filter drivers typically fixes the issue.

Raccogliere i file di tracciaCollect trace files

Per raccogliere le tracce di debug, eseguire i comandi seguenti da un prompt dei comandi amministrativi:To collect debugging traces, run the following commands from an administrative command prompt:

  1. cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
  2. CosmosDB.Emulator.exe /shutdown.CosmosDB.Emulator.exe /shutdown. Verificare l'area di notifica per assicurarsi che il programma sia stato arrestato. Potrebbe essere necessario qualche minuto.Watch the system tray to make sure the program has shut down, it may take a minute. È anche possibile fare semplicemente clic su Esci nell'interfaccia utente dell'emulatore Azure Cosmos DB.You can also just click Exit in the Azure Cosmos DB emulator user interface.
  3. CosmosDB.Emulator.exe /starttraces
  4. CosmosDB.Emulator.exe
  5. Riprodurre il problema.Reproduce the problem. Se Esplora dati non funziona, è sufficiente attendere qualche secondo per l'apertura del browser e il rilevamento dell'errore.If Data Explorer is not working, you only need to wait for the browser to open for a few seconds to catch the error.
  6. CosmosDB.Emulator.exe /stoptraces
  7. Passare a %ProgramFiles%\Azure Cosmos DB Emulator e individuare il file docdbemulator_000001.etl.Navigate to %ProgramFiles%\Azure Cosmos DB Emulator and find the docdbemulator_000001.etl file.
  8. Inviare il file con estensione etl insieme alla procedura per la riproduzione all'indirizzo askcosmosdb@microsoft.com per il debug.Send the .etl file along with repro steps to askcosmosdb@microsoft.com for debugging.

Disinstallare l'emulatore localeUninstall the local Emulator

  1. Chiudere tutte le istanze aperte dell'emulatore locale facendo clic con il pulsante destro del mouse sull'icona dell'emulatore di Azure Cosmos DB nell'area di notifica e quindi fare clic su Esci.Exit all open instances of the local Emulator by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Exit. La chiusura di tutte le istanze può richiedere qualche minuto.It may take a minute for all instances to exit.
  2. Nella casella di ricerca di Windows digitare Apps & features (App e funzionalità) e fare clic sul risultato Apps & features (System settings) (App e funzionalità - Impostazioni di sistema).In the Windows search box, type Apps & features and click on the Apps & features (System settings) result.
  3. Nell'elenco di app scorrere fino a Azure Cosmos DB Emulator (Emulatore di Azure Cosmos DB), selezionarla, fare clic su Disinstalla, confermare e quindi fare clic nuovamente su Disinstalla.In the list of apps, scroll to Azure Cosmos DB Emulator, select it, click Uninstall, then confirm and click Uninstall again.
  4. Quando l'app è disinstallata, passare a C:\Users<user>\AppData\Local\CosmosDBEmulator ed eliminare la cartella.When the app is uninstalled, navigate to C:\Users<user>\AppData\Local\CosmosDBEmulator and delete the folder.

Passaggi successiviNext steps

In questa esercitazione sono state eseguite le operazioni seguenti:In this tutorial, you've done the following:

  • Installazione dell'emulatore localeInstalled the local Emulator
  • Esecuzione dell'emulatore in Docker per WindowsRand the Emulator on Docker for Windows
  • Autenticazione delle richiesteAuthenticated requests
  • Uso di Esplora dati nell'emulatoreUsed the Data Explorer in the Emulator
  • Esportazione dei certificati SSLExported SSL certificates
  • Chiamata dell'emulatore dalla riga di comandoCalled the Emulator from the command line
  • Raccolta dei file di tracciaCollected trace files

In questa esercitazione, si è appresso come usare l'emulatore locale per sviluppo locale libero.In this tutorial, you've learned how to use the local Emulator for free local development. È ora possibile passare all'esercitazione successiva e apprendere come esportare i certificati SSL dell'emulatore.You can now proceed to the next tutorial and learn how to export Emulator SSL certificates.