Referencia de la línea de comandos y PowerShell para el emulador de Windows (local)

Artículo
09/14/2023

SE APLICA A: NoSQL MongoDB Cassandra Gremlin Table

El emulador de Azure Cosmos DB proporciona un entorno local que emula el servicio Azure Cosmos DB con fines de desarrollo local. Después de instalar el emulador, puede controlarlo con la línea de comandos y los comandos de PowerShell. En este artículo se describe cómo usar los comandos de la línea de comandos y PowerShell para iniciar y detener el emulador, configurar sus opciones y realizar otras operaciones. Tiene que ejecutar los comandos desde la ubicación de instalación.

Importante

En este artículo solo se incluyen argumentos de la línea de comandos para el emulador local de Windows.

Administración del emulador con la sintaxis de línea de comandos

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

Para ver la lista de parámetros, escriba Microsoft.Azure.Cosmos.Emulator.exe /? en el símbolo del sistema.

Parámetro	Descripción	Comando de ejemplo
[Sin argumentos]	Inicia el Emulador con la configuración predeterminada.	Microsoft.Azure.Cosmos.Emulator.exe
[Ayuda]	Muestra la lista de argumentos de la línea de comandos admitidos.	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	Obtiene el estado del emulador. Cada código de salida indica un estado: `1` = Inicio, `2` = Ejecución y `3` = Detenido. Un código de salida negativo indica que se ha producido un error. Se produce ninguna otra salida.	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	Apaga el emulador.	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	Especifica la ruta de acceso en la que se almacenarán los archivos de datos. El valor predeterminado es `%LocalAppdata%\CosmosDBEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	Especifica el número de puerto que se utilizará para el emulador. El valor predeterminado es `8081`.	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	Especifica el número de puerto que se utilizará para el servicio de puerta de enlace de interoperabilidad informática. El puerto de sondeo del punto de conexión HTTP de la puerta de enlace se calcula como `ComputePort + 79`. Por lo tanto, `ComputePort` y `ComputePort + 79` debe estar abiertos y disponibles. El valor predeterminado es `8900`.	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	Habilita la API para MongoDB versión 3.2.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	Habilita la API para MongoDB versión 3.6.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	Habilita la API para MongoDB versión 4.0.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	Especifica el número de puerto que se va a usar para la API para MongoDB. El valor predeterminado es `10255`.	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Habilita la API para Apache Cassandra.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Especifica el número de puerto que se utilizará para la API del punto de conexión de Cassandra. El valor predeterminado es `10350`.	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Habilita la API para Apache Gremlin.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Número de puerto que se usará para la API del punto de conexión de Apache Gremlin. El valor predeterminado es `8901`.	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Habilita la API para Table.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	Número de puerto que se utilizará para la API del punto de conexión de Azure Table. El valor predeterminado es `8902`.	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	Lee la clave de autorización del archivo especificado. Usa la opción `/GenKeyFile` para generar un archivo de claves.	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	Quita todos los archivos repetidamente de la ruta de acceso especificada. Si no especifica una ruta de acceso, el valor predeterminado es `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Comienza a recopilar los registros de seguimiento de la depuración mediante LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Deja de recopilar los registros de seguimiento de la depuración mediante LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Inicia la recopilación de registros de seguimiento de depuración con la herramienta Windows Performance Recording.	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Detiene la recopilación de registros de seguimiento de depuración con la herramienta Windows Performance Recording.	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	De forma predeterminada, el emulador vuelve a generar su certificado TLS/SSL autofirmado, si los SAN de certificado no incluyen el nombre de dominio del host del emulador, la dirección IP local, (v4), `localhost` y `127.0.0.1`. Con esta opción, en su lugar, se produce un error en el emulador al iniciarse. A continuación, debe usar la opción `/GenCert` para crear e instalar un nuevo certificado TLS/SSL autofirmado.	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	Genera e instala un nuevo certificado TLS/SSL autofirmado. puede incluir una lista de nombres DNS adicionales separada por comas para acceder al emulador a través de la red.	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	Especifica los puertos que se usarán para la conectividad directa. Los valores predeterminados son `10251`, `10252`, `10253` y `10254`.	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	Clave de autorización para el emulador. La clave debe ser la codificación en base 64 de un vector de 64 bytes.	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	Especifica que el comportamiento de limitación de velocidad de solicitudes está habilitado.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	Especifica que el comportamiento de limitación de velocidad de solicitudes está deshabilitado.	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	No muestra la interfaz de usuario del emulador.	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	No muestra el Explorador de datos en el inicio.	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	Especifica el número máximo de los contenedores particionados. Para más información, consulte cambio del número de contenedores. El valor predeterminado es `25`. El máximo permitido es `250`.	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	Especifica el número predeterminado de particiones para un contenedor. El valor predeterminado es `25`.	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	Permite acceder al emulador a través de una red. También debe pasar `/Key=<key_string>` o /`KeyFile=<file_name>` para habilitar el acceso de red.	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	No ajuste las reglas de firewall cuando se utilice la opción `/AllowNetworkAccess`.	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	Genere una nueva clave de autorización y guárdela en el archivo especificado. La clave generada se puede utilizar con las opciones `/Key` o `/KeyFile`.	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	Defina el nivel de coherencia predeterminado de la cuenta. El valor predeterminado es Session.	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	Se muestra el mensaje de ayuda.

Administración del emulador con cmdlets de PowerShell

El emulador incluye un módulo de PowerShell para iniciar, detener, desinstalar y recuperar el estado del servicio. Ejecute el siguiente cmdlet para utilizar el módulo de PowerShell:

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

o bien coloque el directorio PSModules en su PSModulePath e impórtelo como se muestra en el siguiente comando:

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

Este es un resumen de los comandos de control del emulador desde PowerShell:

`Get-CosmosDbEmulatorStatus`

Obtiene el estado del emulador. Devuelve uno de estos ServiceControllerStatus valores:

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

Si se produce un error, no se devuelve ningún valor.

Sintaxis

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

Parámetros

Nombre	Tipo	Descripción
`AlternativeInstallLocation`	`String`

Ejemplos

Obtenga el estado de un emulador instalado en la carpeta D:\SomeFolder\AzureCosmosDBEmulator.

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

`Start-CosmosDbEmulator`

Inicia el emulador en el equipo local. De forma predeterminada, el comando espera hasta que el emulador está listo para aceptar solicitudes. Utilice la opción -NoWait, si desea que el cmdlet realice la devolución en cuanto inicie el emulador. Use los parámetros de Start-CosmosDbEmulator para especificar opciones, como el puerto NoSQL, el puerto directo y los números de puerto de MongoDB.

Sintaxis

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

Parámetros

Nombre	Tipo	Descripción
`AllowNetworkAccess`	`SwitchParameter`	Permitir el acceso desde todas las direcciones IP asignadas al host del emulador. También debe especificar un valor para Key o KeyFile para permitir el acceso a la red.
`AlternativeInstallLocation`	`String`	Ruta de acceso de ubicación alternativa al ejecutable del emulador.
`CassandraPort`	`UInt16`	Número de puerto que se va a usar para la API de Cassandra. El puerto predeterminado es `10350`.
`ComputePort`	`UInt16`	Puerto que se va a usar para el servicio de puerta de enlace de interoperabilidad de proceso. El puerto de sondeo del punto de conexión HTTP de la puerta de enlace se calcula como `ComputePort + 79`. Por lo tanto, `ComputePort` y `ComputePort + 79` debe estar abiertos y disponibles. Los puertos predeterminados son `8900`, `8979`.
`Consistency`	`String`	Establece el nivel de coherencia predeterminado del emulador en Session, Strong, Eventual o BoundedStaleness. El nivel predeterminado es Session.
`Credential`	`PSCredential`	Especifica una cuenta de usuario con permiso para realizar esta acción. Use un nombre de usuario, como `User01` o `Domain01\User01`, o escriba tanto un objeto `PSCredential`, como uno del cmdlet `Get-Credential`. De forma predeterminada, el cmdlet usa las credenciales del usuario actual.
`DataPath`	`String`	Ruta de acceso para almacenar archivos de datos. La ubicación predeterminada de los archivos de datos es `$env:LocalAppData\CosmosDbEmulator`.
`DefaultPartitionCount`	`UInt16`	Número de particiones que se reservan por colección con particiones. El valor predeterminado es 25, que es el mismo que el valor predeterminado del recuento total de particiones.
`DirectPort`	`UInt16`	Lista de cuatro puertos que se van a usar para la conexión directa con el back-end del emulador. La lista predeterminada es `10251`, `10252`, `10253`, y `10254`.
`EnableMongoDb`	`SwitchParameter`	Especifica que la API para el punto de conexión de MongoDB está habilitada. El valor predeterminado es false.
`EnableCassandra`	`SwitchParameter`	Especifica que la API para el punto de conexión de Apache Cassandra está habilitada. El valor predeterminado es false.
`EnableGremlin`	`SwitchParameter`	Especifica que la API para el punto de conexión de Apache Gremlin está habilitada. El valor predeterminado es false.
`EnableTable`	`SwitchParameter`	Especifica que la API para el punto de conexión de Table está habilitada. El valor predeterminado es false.
`EnableSqlCompute`	`SwitchParameter`	Especifica que la API para el punto de conexión de NoSQL está habilitada. El valor predeterminado es false.
`EnablePreview`	`SwitchParameter`	Habilita las características del emulador que están en versión preliminar y que no están totalmente maduras para estar activadas de forma predeterminada.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	De forma predeterminada, el emulador vuelve a generar su certificado TLS/SSL autofirmado, si los SAN de certificado no incluyen el nombre de dominio del host del emulador, la dirección IP local, (v4), `localhost` y `127.0.0.1`. En su lugar, esta opción hace que el emulador produzca un error en el inicio. A continuación, debe usar la opción `New-CosmosDbEmulatorCertificate` para crear e instalar un nuevo certificado TLS/SSL autofirmado.
`GremlinPort`	`UInt16`	Número de puerto que se va a usar para la API de Apache Gremlin. El número de puerto predeterminado es `8901`.
`TablePort`	`UInt16`	Número de puerto que se va a usar para la API de Table. El número de puerto predeterminado es `8902`.
`SqlComputePort`	`UInt16`	Número de puerto que se va a usar para la API de NoSQL. El número de puerto predeterminado es `8903`.
`Key`	`String`	Clave de autorización para el emulador. Este valor debe ser la codificación base 64 de un vector de 64 bytes.
`MongoPort`	`UInt16`	Número de puerto que se va a usar para la API de MongoDB. El número de puerto predeterminado es `10250`.
`MongoApiVersion`	`String`	Especifica la versión que se va a usar para la API de MongoDB. La versión predeterminada es `4.0`.
`NoFirewall`	`SwitchParameter`	Especifica que no se deben agregar reglas de puerto de entrada al firewall del host del emulador.
`NoTelemetry`	`SwitchParameter`	Especifica que el cmdlet no debe recopilar datos para la sesión del emulador actual.
`NoUI`	`SwitchParameter`	Especifica que el cmdlet no debe presentar la interfaz de usuario ni el icono de la barra de tareas.
`NoWait`	`SwitchParameter`	Especifica que el cmdlet debe devolver en cuanto el emulador empiece a iniciarse. De forma predeterminada, el cmdlet espera hasta que se complete el inicio y el emulador está listo para recibir solicitudes antes de devolverlas.
`PartitionCount`	`UInt16`	Número total de particiones asignadas por el emulador.
`Port`	`UInt16`	Número de puerto para el servicio de puerta de enlace del emulador y la interfaz de usuario web. El número de puerto predeterminado es `8081`.
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

Ejemplos

Inicie el emulador y espere hasta que esté completamente iniciado y listo para aceptar solicitudes.
```
Start-CosmosDbEmulator
```
Inicie el emulador con 5 particiones reservadas para cada colección con particiones. El número total de particiones se establece en el valor predeterminado: 25. Por lo tanto, el número total de colecciones con particiones que se pueden crear es 5 = 25 partitions / 5 partitions/collection. Cada colección con particiones está limitada a 50 GB = 5 partitions * 10 GB / partiton.
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

Inicia el emulador con números de puerto alternativos.

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

`Stop-CosmosDbEmulator`

Detiene el emulador. De forma predeterminada, este comando espera hasta que el emulador esté completamente apagado. Utilice la opción -NoWait, si desea que el cmdlet realice la devolución en cuanto el emulador comience el apagado.

Sintaxis

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

Parámetros

Nombre	Tipo	Descripción
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	Especifica que el cmdlet debe devolverse en cuanto se inicie el apagado.
`Trace`	`SwitchParameter`

Ejemplos

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

`Uninstall-CosmosDbEmulator`

Desinstala el emulador y, opcionalmente, quita todo el contenido de $env:LOCALAPPDATA\CosmosDbEmulator. El cmdlet garantiza que el emulador se detiene antes de desinstalarlo.

Sintaxis

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

Parámetros

Nombre	Tipo	Descripción
`RemoveData`	`SwitchParameter`	Especifica que el cmdlet debe eliminar todos los datos después de quitar el emulador.

Ejemplos

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

Cambio del número de contenedores predeterminados

De forma predeterminada se pueden crear hasta 25 contenedores de tamaño fijo (solo compatibles con los SDK de Azure Cosmos DB) o 5 contenedores ilimitados con el emulador. Al modificar el valor de PartitionCount, se pueden crear hasta 250 contenedores de tamaño fijo o 50 contenedores ilimitados, o cualquier combinación de los dos que no supere los 250 contenedores de tamaño fijo (un contenedor ilimitado = 5 contenedores de tamaño fijo). Sin embargo, no se recomienda configurar el emulador para que se ejecute con más de 200 contenedores de tamaño fijo. Esto se debe a la sobrecarga añadida a las operaciones de E/S del disco, que producen tiempos de expiración impredecibles al usar las API de punto de conexión.

Si intenta crear un contenedor después de que se haya excedido el recuento de particiones actual, el emulador generará una excepción ServiceUnavailable con el siguiente mensaje.

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

Para cambiar el número de contenedores disponibles en el emulador, ejecute los siguientes pasos:

Elimine todos los datos del emulador local haciendo clic con el botón derecho en el icono del emulador de la bandeja del sistema y, luego, haciendo clic en Restablecer datos….
Elimine todos los datos del emulador de la carpeta %LOCALAPPDATA%\CosmosDBEmulator.
Salga de todas las instancias abiertas haciendo clic con el botón derecho en el icono del emulador de la bandeja del sistema y, luego, haciendo clic en Salir. Todas las instancias pueden tardar un minuto en salir.
Instalación de la versión más reciente del emulador.
Para iniciar el emulador con la marca PartitionCount, establezca un valor <= 250. Por ejemplo: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Referencia de la línea de comandos y PowerShell para el emulador de Windows (local)

Administración del emulador con la sintaxis de línea de comandos

Administración del emulador con cmdlets de PowerShell

`Get-CosmosDbEmulatorStatus`

Sintaxis

Parámetros

Ejemplos

`Start-CosmosDbEmulator`

Sintaxis

Parámetros

Ejemplos

`Stop-CosmosDbEmulator`

Sintaxis

Parámetros

Ejemplos

`Uninstall-CosmosDbEmulator`

Sintaxis

Parámetros

Ejemplos

Cambio del número de contenedores predeterminados

Pasos siguientes

Recursos adicionales