使用 Azure Cosmos 模拟器进行本地开发和测试Use the Azure Cosmos Emulator for local development and testing

为方便开发,Azure Cosmos 模拟器提供了一个模拟 Azure Cosmos DB 服务的本地环境。The Azure Cosmos Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. 使用 Azure Cosmos 模拟器可在本地开发和测试应用程序,无需创建 Azure 订阅且不会产生任何费用。Using the Azure Cosmos Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. 如果对应用程序在 Azure Cosmos 拟器中的工作情况感到满意,可以转为在云中使用 Azure Cosmos 帐户。When you're satisfied with how your application is working in the Azure Cosmos Emulator, you can switch to using an Azure Cosmos account in the cloud.

可使用 Azure Cosmos 模拟器结合 SQLCassandraMongoDBGremlin API 帐户进行开发。You can develop using Azure Cosmos Emulator with SQL, Cassandra, MongoDB, Gremlin, and Table API accounts. 但是,该模拟器中的数据资源管理器视图目前仅完全支持 SQL API 的客户端。However at this time the Data Explorer view in the emulator fully supports clients for SQL API only.

模拟器的工作原理How the emulator works

Azure Cosmos 模拟器提供对 Azure Cosmos DB 服务的高保真模拟。The Azure Cosmos Emulator provides a high-fidelity emulation of the Azure Cosmos DB service. 它支持与 Azure Cosmos DB 相同的功能,包括创建和查询数据、支持预配和缩放容器,以及执行存储过程和触发器。It supports identical functionality as Azure Cosmos DB, including support for creating and querying data, provisioning and scaling containers, and executing stored procedures and triggers. 可以使用 Azure Cosmos 模拟器开发和测试应用程序,并通过直接对 Azure Cosmos DB 的连接终结点进行单一配置更改将其部署到多区域范围的 Azure。You can develop and test applications using the Azure Cosmos Emulator, and deploy them to Azure at multiple-region scale by just making a single configuration change to the connection endpoint for Azure Cosmos DB.

虽然模拟 Azure Cosmos DB 服务很逼真,但模拟器的实现不同于服务。While emulation of the Azure Cosmos DB service is faithful, the emulator's implementation is different than the service. 例如,模拟器使用标准 OS 组件,例如用于暂留的本地文件系统和用于连接的 HTTPS 协议堆栈。For example, the emulator uses standard OS components such as the local file system for persistence, and the HTTPS protocol stack for connectivity. 依赖于 Azure 基础结构的功能(如多区域复制、读/写的单位数毫秒延迟,以及可调整的一致性级别)不适用。Functionality that relies on Azure infrastructure like multiple-region replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not applicable.

可通过 Azure Cosmos DB 数据迁移工具在 Azure Cosmos 模拟器与 Azure Cosmos DB 服务之间迁移数据。You can migrate data between the Azure Cosmos Emulator and the Azure Cosmos DB service by using the Azure Cosmos DB Data Migration Tool.

可在 Windows Docker 容器上运行 Azure Cosmos 模拟器;详见 Docker Hub 获取 Docker 拉取命令,详见 GitHub 获取Dockerfile 以及更多信息。You can run Azure Cosmos Emulator on the Windows Docker container, see the Docker Hub for the docker pull command and GitHub for the Dockerfile and more information.

模拟器和服务之间的差异Differences between the emulator and the service

由于 Azure Cosmos 模拟器提供一个在本地开发人员工作站上运行的模拟环境,因此该模拟器在功能上与 Azure Cosmos 云端帐户之间存在一些差异:Because the Azure Cosmos Emulator provides an emulated environment running on the local developer workstation, there are some differences in functionality between the emulator and an Azure Cosmos account in the cloud:

  • 目前,模拟器中的数据资源管理器支持 SQL API 的客户端。Currently Data Explorer in the emulator supports clients for SQL API. 不完全支持在数据资源管理器查看和操作 Azure Cosmos DB API,例如 MongoDB API、表 API、Graph API 和 Cassandra API。The Data Explorer view and operations for Azure Cosmos DB APIs such as MongoDB, Table, Graph, and Cassandra APIs are not fully supported.
  • Azure Cosmos 模拟器只支持单一固定帐户和公开的主密钥。The Azure Cosmos Emulator supports only a single fixed account and a well-known master key. 不可在 Azure Cosmos 模拟器中重新生成密钥,但可使用命令行选项更改默认密钥。Key regeneration is not possible in the Azure Cosmos Emulator, however the default key can be changed using the command-line option.
  • Azure Cosmos 模拟器是一项不可伸缩的服务,不支持大量容器。The Azure Cosmos Emulator is not a scalable service and will not support a large number of containers.
  • Azure Cosmos 模拟器只提供一种 Azure Cosmos DB 一致性级别The Azure Cosmos Emulator does not offer different Azure Cosmos DB consistency levels.
  • Azure Cosmos 模拟器不提供多区域复制The Azure Cosmos Emulator does not offer multi-region replication.
  • 由于 Azure Cosmos 模拟器副本并不总是能反映出 Azure Cosmos DB 服务中的最新更改,因此应使用 Azure Cosmos DB 容量规划器来准确估计应用程序的生产吞吐量 (RU) 需求。As your copy of the Azure Cosmos Emulator might not always be up-to-date with the most recent changes in the Azure Cosmos DB service, you should refer to the Azure Cosmos DB capacity planner to accurately estimate the production throughput (RUs) needs of your application.
  • 默认使用 Azure Cosmos 模拟器时,可最多创建 25 个固定大小的容器(仅支持使用 Azure Cosmos DB SDK 创建),或使用 Azure Cosmos 模拟器创建 5 个不受限容器。When using the Azure Cosmos Emulator, by default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers using the Azure Cosmos Emulator. 有关如何更改此值的详细信息,请参阅设置 PartitionCount 值For more information about changing this value, see Setting the PartitionCount value.
  • 模拟器支持的最大 ID 属性大小为 254 个字符。Emulator supports max id property size of 254 characters.

系统要求System requirements

Azure Cosmos 模拟器具有以下硬件和软件要求:The Azure Cosmos Emulator has the following hardware and software requirements:

  • 软件要求Software requirements
    • Windows Server 2012 R2、Windows Server 2016 或 Windows 10Windows Server 2012 R2, Windows Server 2016, or Windows 10
    • 64 位操作系统64-bit operating system
  • 最低硬件要求Minimum Hardware requirements
    • 2-GB RAM2-GB RAM
    • 10-GB 可用硬盘空间10-GB available hard disk space


可以从下载中心下载并安装 Azure Cosmos 模拟器,也可以在用于 Windows 的 Docker 上运行模拟器。You can download and install the Azure Cosmos Emulator from the Download Center or you can run the emulator on Docker for Windows. 有关在用于 Windows 的 Docker 上使用模拟器的说明,请参阅在 Docker 上运行For instructions on using the emulator on Docker for Windows, see Running on Docker.


若要安装、配置和运行 Azure Cosmos 模拟器,必须在计算机上具有管理特权。To install, configure, and run the Azure Cosmos Emulator, you must have administrative privileges on the computer. 该模拟器将创建/添加证书并设置防火墙规则,从而运行其服务;因此,模拟器必须能够执行此类操作。The emulator will create/add a certificate and also set the firewall rules in order to run its services; therefore it's necessary for the emulator to be able to execute such operations.

在 Windows 上运行Running on Windows

要启动 Azure Cosmos 模拟器,请选择“开始”按钮或按 Windows 键。To start the Azure Cosmos Emulator, select the Start button or press the Windows key. 开始键入“Azure Cosmos 模拟器”,再从应用程序列表中选择该模拟器。Begin typing Azure Cosmos Emulator, and select the emulator from the list of applications.

选择“开始”按钮或按 Windows 键,开始键入“Azure Cosmos 模拟器”,再从应用程序列表中选择该模拟器

运行模拟器时,在 Windows 任务栏通知区域中会显示一个图标。When the emulator is running, you'll see an icon in the Windows taskbar notification area.

Azure Cosmos DB 本地模拟器任务栏通知

默认情况下,Azure Cosmos 模拟器在本地计算机(“localhost”)上运行,侦听端口 8081。The Azure Cosmos Emulator by default runs on the local machine ("localhost") listening on port 8081.

Azure Cosmos 模拟器默认安装到 C:\Program Files\Azure Cosmos DB EmulatorThe Azure Cosmos Emulator is installed to C:\Program Files\Azure Cosmos DB Emulator by default. 还可以从命令行启动和停止该模拟器。You can also start and stop the emulator from the command-line. 有关详细信息,请参阅命令行工具参考For more information, see the command-line tool reference.

启动数据资源管理器Start Data Explorer

Azure Cosmos 模拟器启动时,会在浏览器中自动打开 Azure Cosmos 数据资源管理器。When the Azure Cosmos Emulator launches, it automatically opens the Azure Cosmos Data Explorer in your browser. 地址显示为 https://localhost:8081/_explorer/index.htmlThe address appears as https://localhost:8081/_explorer/index.html. 如果关闭了资源管理器且稍后想要重新打开它,可在浏览器中打开 URL,或者通过 Windows 托盘图标中的 Azure Cosmos 模拟器进行启动,如下所示。If you close the explorer and would like to reopen it later, you can either open the URL in your browser or launch it from the Azure Cosmos Emulator in the Windows Tray Icon as shown below.

Azure Cosmos 本地模拟器数据资源管理器启动器

检查更新Checking for updates

数据资源管理器指示是否有新的更新可供下载。Data Explorer indicates if there is a new update available for download.


在某版本的 Azure Cosmos 模拟器中创建数据后(参见 %LOCALAPPDATA%\CosmosDBEmula 或数据路径可选设置),不保证在使用其他版本时可访问。Data created in one version of the Azure Cosmos Emulator (see %LOCALAPPDATA%\CosmosDBEmulator or data path optional settings) is not guaranteed to be accessible when using a different version. 如果需要长期保存数据,建议将该数据存储在 Azure Cosmos 帐户中,而不是存储在 Azure Cosmos 模拟器中。If you need to persist your data for the long term, it is recommended that you store that data in an Azure Cosmos account, rather than in the Azure Cosmos Emulator.

对请求进行身份验证Authenticating requests

与云中的 Azure Cosmos DB 一样,针对 Azure Cosmos 模拟器发出的每个请求都必须进行身份验证。As with Azure Cosmos DB in the cloud, every request that you make against the Azure Cosmos Emulator must be authenticated. Azure Cosmos 模拟器支持单一固定帐户和用于主密钥身份验证的公开的身份验证密钥。The Azure Cosmos Emulator supports a single fixed account and a well-known authentication key for master key authentication. 此帐户和密钥是允许用于 Azure Cosmos 模拟器的唯一凭据。This account and key are the only credentials permitted for use with the Azure Cosmos Emulator. 它们分别是:They are:

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


Azure Cosmos 模拟器支持的主密钥仅可用于该模拟器。The master key supported by the Azure Cosmos Emulator is intended for use only with the emulator. 不能在 Azure Cosmos DB 模拟器中使用生产 Azure Cosmos DB 帐户和密钥。You cannot use your production Azure Cosmos DB account and key with the Azure Cosmos Emulator.


如果是使用 /Key 选项启动的模拟器,请使用所生成的密钥而不是 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==. 有关 /Key 选项的详细信息,请参阅命令行工具参考For more information about /Key option, see Command-line tool reference.

与 Azure Cosmos DB 一样,Azure Cosmos 模拟器仅支持采用 TLS 的安全通信。As with the Azure Cosmos DB, the Azure Cosmos Emulator supports only secure communication via TLS.

在本地网络上运行Running on a local network

可在本地网络中运行仿真器。You can run the emulator on a local network. 要启用网络访问,请在命令行中指定 /AllowNetworkAccess 选项,同时还需指定 /Key=key_string/KeyFile=file_nameTo enable network access, specify the /AllowNetworkAccess option at the command-line, which also requires that you specify /Key=key_string or /KeyFile=file_name. 可使用 /GenKeyFile=file_name 提前生成具有随机密钥的文件。You can use /GenKeyFile=file_name to generate a file with a random key upfront. 然后,可将其传递到 /KeyFile=file_name/Key=contents_of_fileThen you can pass that to /KeyFile=file_name or /Key=contents_of_file.

首次启用网络访问时,用户应关闭模拟器,并删除模拟器的数据目录 (%LOCALAPPDATA%\CosmosDBEmulator)。To enable network access for the first time the user should shut down the emulator and delete the emulator's data directory (%LOCALAPPDATA%\CosmosDBEmulator).

通过模拟器进行开发Developing with the emulator


在桌面上运行 Azure Cosmos 模拟器后,可使用任意受支持的 Azure Cosmos DB SDKAzure Cosmos DB REST API 与模拟器进行交互。Once you have the Azure Cosmos 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. Azure Cosmos 模拟器还包括内置数据资源管理器,它让你无需编写任何代码即可为 SQL API 创建容器(或为 Mongo DB API 创建 Cosmos DB)并查看和编辑项目。The Azure Cosmos Emulator also includes a built-in Data Explorer that lets you create containers for SQL API or Cosmos DB for Mongo DB API, and view and edit items without writing any code.

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

Azure Cosmos DB 的用于 MongoDB 的 APIAzure Cosmos DB's API for MongoDB

在桌面上运行 Azure Cosmos 模拟器后,可以使用 Azure Cosmos DB 的用于 MongoDB 的 API 与该模拟器进行交互。Once you have the Azure Cosmos Emulator running on your desktop, you can use the Azure Cosmos DB's API for MongoDB to interact with the emulator. 在命令提示符下,以管理员的身份使用“/EnableMongoDbEndpoint”启动模拟器。Start emulator from command prompt as an administrator with "/EnableMongoDbEndpoint". 然后,使用以下连接字符串来连接到 MongoDB API 帐户:Then use the following connection string to connect to the MongoDB API account:


表 APITable API

在桌面上运行 Azure Cosmos 模拟器后,可使用任意受支持的 Azure Cosmos DB 表 API SDK 与模拟器进行交互。Once you have the Azure Cosmos Emulator running on your desktop, you can use the Azure Cosmos DB Table API SDK to interact with the emulator. 在命令提示符处,以管理员的身份使用“/EnableTableEndpoint”启动模拟器。Start emulator from command prompt as an administrator with "/EnableTableEndpoint". 接下来,运行下列代码以连接到表 API 帐户:Next run the following code to connect to the table API account:

using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Table;
using CloudTable = Microsoft.WindowsAzure.Storage.Table.CloudTable;
using CloudTableClient = Microsoft.WindowsAzure.Storage.Table.CloudTableClient;

string connectionString = "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;";

CloudStorageAccount account = CloudStorageAccount.Parse(connectionString);
CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("testtable");
table.Execute(TableOperation.Insert(new DynamicTableEntity("partitionKey", "rowKey")));

Cassandra APICassandra API

在管理员命令提示符处使用“/EnableCassandraEndpoint”启动模拟器。Start emulator from an administrator command prompt with "/EnableCassandraEndpoint". 或者,也可设置环境变量 AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=trueAlternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

  • 安装 Python 2.7Install Python 2.7

  • 安装 Cassandra CLI/CQLSHInstall Cassandra CLI/CQLSH

  • 在常规命令提示符窗口中运行以下命令:Run the following commands in a regular command prompt window:

    set Path=c:\Python27;%Path%
    cd /d C:\sdk\apache-cassandra-3.11.3\bin
    set SSL_VERSION=TLSv1_2
    set SSL_VALIDATE=false
    cqlsh localhost 10350 -u localhost -p C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== --ssl
  • 在 CQLSH shell 中,运行下列命令以连接到 Cassandra 终结点:In the CQLSH shell, run the following commands to connect to the Cassandra endpoint:

    CREATE KEYSPACE MyKeySpace WITH replication = {'class':'MyClass', 'replication_factor': 1};
    DESCRIBE keyspaces;
    USE mykeyspace;
    CREATE table table1(my_id int PRIMARY KEY, my_name text, my_desc text);
    INSERT into table1 (my_id, my_name, my_desc) values( 1, 'name1', 'description 1');
    SELECT * from table1;

Gremlin APIGremlin API

在管理员命令提示符处使用“/EnableGremlinEndpoint”启动模拟器。Start emulator from an administrator command prompt with "/EnableGremlinEndpoint". 或者,也可设置环境变量 AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=trueAlternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

  • 安装 apache-tinkerpop-gremlin-console-3.3.4Install apache-tinkerpop-gremlin-console-3.3.4.

  • 在模拟器的数据资源管理器中创建数据库“db1”和集合“coll1”,并选择“/name”作为分区键In the emulator's Data Explorer create a database "db1" and a collection "coll1"; for the partition key, choose "/name"

  • 在常规命令提示符窗口中运行以下命令:Run the following commands in a regular command prompt window:

    cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.3.4-bin\apache-tinkerpop-gremlin-console-3.3.4
    copy /y conf\remote.yaml conf\remote-localcompute.yaml
    notepad.exe conf\remote-localcompute.yaml
    hosts: [localhost]
    port: 8901
    username: /dbs/db1/colls/coll1
    password: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    connectionPool: {
    enableSsl: false}
    serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0,
    config: { serializeResultToString: true  }}
  • 在 Gremlin shell 中,运行下列命令以连接到 Gremlin 终结点:In the Gremlin shell run the following commands to connect to the Gremlin endpoint:

    :remote connect tinkerpop.server conf/remote-localcompute.yaml
    :remote console
    :> g.V()
    :> g.addV('person1').property(id, '1').property('name', 'somename1')
    :> g.addV('person2').property(id, '2').property('name', 'somename2')
    :> g.V()

导出 TLS/SSL 证书Export the TLS/SSL certificate

.NET 语言和运行时使用 Windows 证书存储来安全地连接到 Azure Cosmos DB 本地模拟器。.NET languages and runtime use the Windows Certificate Store to securely connect to the Azure Cosmos DB local emulator. 其他语言有自己管理和使用证书方法。Other languages have their own method of managing and using certificates. Java 使用自己的证书存储,而 Python 使用套接字包装器Java uses its own certificate store whereas Python uses socket wrappers.

为了获得用于语言和运行时(未与 Windows 证书存储集成)的证书,需要通过 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. 可通过运行 certlm.msc 进行启动,也可按照导出 Azure Cosmos 模拟器证书中的分步说明进行操作。You can start it by running certlm.msc or follow the step by step instructions in Export the Azure Cosmos Emulator Certificates. 证书管理器开始运行后,打开个人证书(如下所示),并将友好名称为“DocumentDBEmulatorCertificate”的证书导出为 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.

Azure Cosmos DB 本地模拟器 TLS/SSL 证书

可按照将证书添加到 Java CA 证书存储中的说明,将 X.509 证书导入 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. 证书导入证书存储后,SQL 和 MongoDB 的 Azure Cosmos DB API 的客户端就能连接到 Azure Cosmos 模拟器。Once the certificate is imported into the certificate store, clients for SQL and Azure Cosmos DB's API for MongoDB will be able to connect to the Azure Cosmos Emulator.

从 Python 和 Node.js SDK 连接到模拟器时,会禁用 TLS 验证。When connecting to the emulator from Python and Node.js SDKs, TLS verification is disabled.

命令行工具参考Command-line tool reference

从安装位置中,可以使用命令行启动和停止模拟器、配置选项和执行其他操作。From the installation location, you can use the command-line to start and stop the emulator, configure options, and perform other operations.

命令行语法Command-line syntax

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

若要查看选项列表,请在命令提示符下键入 Microsoft.Azure.Cosmos.Emulator.exe /?To view the list of options, type Microsoft.Azure.Cosmos.Emulator.exe /? at the command prompt.

选项Option 说明Description 命令Command 参数Arguments
[无参数][No arguments] 使用默认设置启动 Azure Cosmos 模拟器。Starts up the Azure Cosmos Emulator with default settings. Microsoft.Azure.Cosmos.Emulator.exeMicrosoft.Azure.Cosmos.Emulator.exe
[帮助][Help] 显示支持的命令行参数列表。Displays the list of supported command-line arguments. Microsoft.Azure.Cosmos.Emulator.exe /?Microsoft.Azure.Cosmos.Emulator.exe /?
GetStatusGetStatus 获取 Azure Cosmos 模拟器的状态。Gets the status of the Azure Cosmos Emulator. 状态由退出代码指示:1 = 正在启动,2 = 正在运行,3 = 已停止。The status is indicated by the exit code: 1 = Starting, 2 = Running, 3 = Stopped. 退出代码为负表示发生了错误。A negative exit code indicates that an error occurred. 不生成其他输出。No other output is produced. Microsoft.Azure.Cosmos.Emulator.exe /GetStatusMicrosoft.Azure.Cosmos.Emulator.exe /GetStatus
关机Shutdown 关闭 Azure Cosmos 模拟器。Shuts down the Azure Cosmos Emulator. Microsoft.Azure.Cosmos.Emulator.exe /ShutdownMicrosoft.Azure.Cosmos.Emulator.exe /Shutdown
DataPathDataPath 指定要在其中存储数据文件的路径。Specifies the path in which to store data files. 默认值为 %LocalAppdata%\CosmosDBEmulator。Default value is %LocalAppdata%\CosmosDBEmulator. Microsoft.Azure.Cosmos.Emulator.exe /DataPath=<datapath>Microsoft.Azure.Cosmos.Emulator.exe /DataPath=<datapath> <datapath>:可访问路径<datapath>: An accessible path
端口Port 指定用于模拟器的端口号。Specifies the port number to use for the emulator. 默认值为 8081。Default value is 8081. Microsoft.Azure.Cosmos.Emulator.exe /Port=<port>Microsoft.Azure.Cosmos.Emulator.exe /Port=<port> <port>:单个端口号<port>: Single port number
ComputePortComputePort 指定用于计算互操作网关服务的端口号。Specified the port number to use for the Compute Interop Gateway service. 该网关的 HTTP 终结点探测端口计算得出 ComputePort + 79。The Gateway's HTTP endpoint probe port is calculated as ComputePort + 79. 因此,ComputePort 和 ComputePort + 79 必须打开且可使用。Hence, ComputePort and ComputePort + 79 must be open and available. 默认值为 8900。The default value is 8900. Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=<computeport>Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=<computeport> <computeport>:单个端口号<computeport>: Single port number
EnableMongoDbEndpoint=3.2EnableMongoDbEndpoint=3.2 启用 MongoDB API 3.2Enables MongoDB API 3.2 Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2
EnableMongoDbEndpoint=3.6EnableMongoDbEndpoint=3.6 启用 MongoDB API 3.6Enables MongoDB API 3.6 Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6
MongoPortMongoPort 指定用于 MongoDB 兼容性 API 的端口号。Specifies the port number to use for MongoDB compatibility API. 默认值为 10255。Default value is 10255. Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=<mongoport>Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=<mongoport> <mongoport>:单个端口号<mongoport>: Single port number
EnableCassandraEndpointEnableCassandraEndpoint 启用 Cassandra APIEnables Cassandra API Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint
CassandraPortCassandraPort 指定用于 Cassandra 终结点的端口号。Specifies the port number to use for the Cassandra endpoint. 默认值为 10350。Default value is 10350. Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=<cassandraport>Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=<cassandraport> <cassandraport>:单个端口号<cassandraport>: Single port number
EnableGremlinEndpointEnableGremlinEndpoint 启用 Gremlin APIEnables Gremlin API Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint
GremlinPortGremlinPort 用于 Gremlin 终结点的端口号。Port number to use for the Gremlin Endpoint. 默认值为 8901。Default value is 8901. Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=<port>Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=<port> <port>:单个端口号<port>: Single port number
EnableTableEndpointEnableTableEndpoint 启用 Azure 表 APIEnables Azure Table API Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpointMicrosoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint
TablePortTablePort 用于 Azure 表终结点的端口号。Port number to use for the Azure Table Endpoint. 默认值为 8902。Default value is 8902. Microsoft.Azure.Cosmos.Emulator.exe /TablePort=<port>Microsoft.Azure.Cosmos.Emulator.exe /TablePort=<port> <port>:单个端口号<port>: Single port number
KeyFileKeyFile 从指定文件中读取授权密钥。Read authorization key from the specified file. 使用 /GenKeyFile 选项来生成密钥文件Use the /GenKeyFile option to generate a keyfile Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=<file_name>Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=<file_name> <file_name>:文件的路径<file_name>: Path to the file
ResetDataPathResetDataPath 以递归方式删除指定路径中的所有文件。Recursively removes all the files in the specified path. 如果不指定路径,则默认为 %LOCALAPPDATA%\CosmosDbEmulatorIf you don't specify a path, it defaults to %LOCALAPPDATA%\CosmosDbEmulator Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath=<path>Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath=<path> <path>:文件路径<path>: File path
StartTracesStartTraces 开始使用 LOGMAN 收集调试跟踪日志。Start collecting debug trace logs using LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StartTracesMicrosoft.Azure.Cosmos.Emulator.exe /StartTraces
StopTracesStopTraces 停止使用 LOGMAN 收集调试跟踪日志。Stop collecting debug trace logs using LOGMAN. Microsoft.Azure.Cosmos.Emulator.exe /StopTracesMicrosoft.Azure.Cosmos.Emulator.exe /StopTraces
StartWprTracesStartWprTraces 开始使用 Windows 性能记录工具收集调试跟踪日志。Start collecting debug trace logs using Windows Performance Recording tool. Microsoft.Azure.Cosmos.Emulator.exe /StartWprTracesMicrosoft.Azure.Cosmos.Emulator.exe /StartWprTraces
StopWprTracesStopWprTraces 停止使用 Windows 性能记录工具收集调试跟踪日志。Stop collecting debug trace logs using Windows Performance Recording tool. Microsoft.Azure.Cosmos.Emulator.exe /StopWprTracesMicrosoft.Azure.Cosmos.Emulator.exe /StopWprTraces
FailOnSslCertificateNameMismatchFailOnSslCertificateNameMismatch 默认情况下,模拟器会重新生成自签名的 TLS/SSL 证书(如果证书的 SAN 不包含模拟器主机的域名、本地 IPv4 地址、“localhost”和“”)。By default the Emulator regenerates its self-signed TLS/SSL certificate, if the certificate's SAN does not include the Emulator host's domain name, local IPv4 address, 'localhost', and ''. 启用此选项后,模拟器在启动时会失败。With this option, the emulator will fail at startup instead. 然后,你应使用 /GenCert 选项来创建并安装新的自签名 TLS/SSL 证书。You should then use the /GenCert option to create and install a new self-signed TLS/SSL certificate. Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatchMicrosoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch
GenCertGenCert 生成并安装新的自签名 TLS/SSL 证书。Generate and install a new self-signed TLS/SSL certificate. 选择性地包含用于通过网络访问模拟器的其他 DNS 名称的列表(以逗号分隔)。optionally including a comma-separated list of additional DNS names for accessing the Emulator over the network. Microsoft.Azure.Cosmos.Emulator.exe /GenCert=<dns-names>Microsoft.Azure.Cosmos.Emulator.exe /GenCert=<dns-names> <dns-names>:其他 dns 名称的逗号分隔列表(可选)<dns-names>: Optional comma-separated list of additional dns names
DirectPortsDirectPorts 指定用于直接连接的端口。Specifies the ports to use for direct connectivity. 默认值为 10251、10252、10253、10254。Defaults are 10251,10252,10253,10254. Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:<directports>Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:<directports> <directports>:以逗号分隔的 4 个端口的列表<directports>: Comma-delimited list of 4 ports
密钥Key 模拟器的授权密钥。Authorization key for the emulator. 密钥必须是 64 字节向量的 base 64 编码。Key must be the base-64 encoding of a 64-byte vector. Microsoft.Azure.Cosmos.Emulator.exe /Key:<key>Microsoft.Azure.Cosmos.Emulator.exe /Key:<key> <key>:密钥必须是 64 字节向量的 base 64 编码<key>: Key must be the base-64 encoding of a 64-byte vector
EnableRateLimitingEnableRateLimiting 指定已启用请求速率限制行为。Specifies that request rate limiting behavior is enabled. Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimitingMicrosoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting
DisableRateLimitingDisableRateLimiting 指定已禁用请求速率限制行为。Specifies that request rate limiting behavior is disabled. Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimitingMicrosoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting
NoUINoUI 不显示模拟器用户界面。Do not show the emulator user interface. Microsoft.Azure.Cosmos.Emulator.exe /NoUIMicrosoft.Azure.Cosmos.Emulator.exe /NoUI
NoExplorerNoExplorer 在启动时不显示数据资源管理器。Don't show data explorer on startup. Microsoft.Azure.Cosmos.Emulator.exe /NoExplorerMicrosoft.Azure.Cosmos.Emulator.exe /NoExplorer
PartitionCountPartitionCount 指定已分区的容器的最大数。Specifies the maximum number of partitioned containers. 有关详细信息,请参阅更改容器数量See Change the number of containers for more information. Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=<partitioncount>Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=<partitioncount> <partitioncount>:允许的单分区容器的最大数量。<partitioncount>: Maximum number of allowed single partition containers. 默认值为 25。Default value is 25. 允许的最大值为 250。Maximum allowed is 250.
DefaultPartitionCountDefaultPartitionCount 指定分区容器的默认分区数。Specifies the default number of partitions for a partitioned container. Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount>Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=<defaultpartitioncount> <defaultpartitioncount> 默认值为 25。<defaultpartitioncount> Default value is 25.
AllowNetworkAccessAllowNetworkAccess 通过网络启用对仿真器的访问。Enables access to the emulator over a network. 要启用网络访问,还必须传递 /Key=<key_string> 或 /KeyFile=<file_name>。You must also pass /Key=<key_string> or /KeyFile=<file_name> to enable network access. Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=<key_string> 或 Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=<key_string> or Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /KeyFile=<file_name>
NoFirewallNoFirewall 使用 /AllowNetworkAccess 选项时,不要调整防火墙规则。Don't adjust firewall rules when /AllowNetworkAccess option is used. Microsoft.Azure.Cosmos.Emulator.exe /NoFirewallMicrosoft.Azure.Cosmos.Emulator.exe /NoFirewall
GenKeyFileGenKeyFile 生成新的授权密钥并保存至指定文件。Generate a new authorization key and save to the specified file. 所生成的密钥可与 /Key 或 /KeyFile 选项配合使用。The generated key can be used with the /Key or /KeyFile options. Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=<path to key file>Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=<path to key file>
一致性Consistency 为帐户设置默认一致性级别。Set the default consistency level for the account. Microsoft.Azure.Cosmos.Emulator.exe /Consistency=<consistency>Microsoft.Azure.Cosmos.Emulator.exe /Consistency=<consistency> <consistency>:值必须是以下一致性级别之一:Session、Strong、Eventual 或 BoundedStaleness。<consistency>: Value must be one of the following consistency levels: Session, Strong, Eventual, or BoundedStaleness. 默认值为“Session”。The default value is Session.
?? 显示帮助消息。Show the help message.

更改容器数量Change the number of containers

默认情况下,可最多创建 25 个固定大小的容器(仅支持使用 Azure Cosmos DB SDK 创建),或使用 Azure Cosmos 模拟器创建 5 个不受限容器。By default, you can create up to 25 fixed size containers (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers using the Azure Cosmos Emulator. 通过修改 PartitionCount 值,可最多创建 250 个固定大小的容器或 50 个不受限容器,也可创建两者的任意组合(前提是总数不超过 250 个固定大小的容器,其中 1 个不受限容器 = 5 个固定大小的容器)。By modifying the PartitionCount value, you can create up to 250 fixed size containers or 50 unlimited containers, or any combination of the two that does not exceed 250 fixed size containers (where one unlimited container = 5 fixed size containers). 但是,建议不要设置用 200 个以上固定大小的容器进行运行的模拟器。However it's not recommended to set up the emulator to run with more than 200 fixed size containers. 因为这会造成磁盘 IO 操作的开销增加,导致在运行终结点 API 时出现不可预测的超时情况。Because of the overhead that it adds to the disk IO operations, which result in unpredictable timeouts when using the endpoint APIs.

如果在已超过当前分区计数后尝试创建容器,则模拟器将引发 ServiceUnavailable 异常,并收到以下消息。If you attempt to create a container 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. ActivityId:12345678-1234-1234-1234-123456789abc”ActivityId: 12345678-1234-1234-1234-123456789abc"

要更改 Azure Cosmos 模拟器中可用容器的数量,请执行以下步骤:To change the number of containers available in the Azure Cosmos Emulator, run the following steps:

  1. 在系统任务栏上右键单击“Azure Cosmos 模拟器”图标,并单击“重置数据...”,删除所有本地 Azure Cosmos 模拟器数据 。Delete all local Azure Cosmos Emulator data by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Reset Data….
  2. 删除文件夹 %LOCALAPPDATA%\CosmosDBEmulator 中的所有模拟器数据。Delete all emulator data in this folder %LOCALAPPDATA%\CosmosDBEmulator.
  3. 通过在系统任务栏上右键单击“Azure Cosmos DB 模拟器”图标,并单击“退出”,退出所有打开的实例。Exit all open instances by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Exit. 退出所有实例可能需要一分钟。It may take a minute for all instances to exit.
  4. 安装最新版的 Azure Cosmos 模拟器Install the latest version of the Azure Cosmos Emulator.
  5. 通过设置一个 <= 250 的值启动具有 PartitionCount 标志的模拟器。Launch the emulator with the PartitionCount flag by setting a value <= 250. 例如:C:\Program Files\Azure Cosmos DB Emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100For example: C:\Program Files\Azure Cosmos DB Emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

控制模拟器Controlling the emulator

该模拟器附带一个 PowerShell 模块,它可用于启动、停止、卸载和检索服务的状态。The emulator comes with a PowerShell module to start, stop, uninstall, and retrieve the status of the service. 运行下列 cmdlet 以使用 PowerShell 模块:Run the following cmdlet to use the PowerShell module:

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

或者,将 PSModules 目录放置在 PSModulesPath 上,并按如下命令中所示将其导入:or place the PSModules directory on your PSModulesPath and import it as shown in the following command:

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

下面汇总的命令用于通过 PowerShell 来控制模拟器:Here is a summary of the commands for controlling the emulator from PowerShell:





返回以下 ServiceControllerStatus 值之一:ServiceControllerStatus.StartPending、ServiceControllerStatus.Running 或 ServiceControllerStatus.Stopped。Returns one of these ServiceControllerStatus values: ServiceControllerStatus.StartPending, ServiceControllerStatus.Running, or ServiceControllerStatus.Stopped.



Start-CosmosDbEmulator [-DataPath <string>] [-DefaultPartitionCount <uint16>] [-DirectPort <uint16[]>] [-MongoPort <uint16>] [-NoUI] [-NoWait] [-PartitionCount <uint16>] [-Port <uint16>] [<CommonParameters>]


启动模拟器。Starts the emulator. 默认情况下,此命令会一直等待,直至模拟器做好接受请求的准备。By default, the command waits until the emulator is ready to accept requests. 如果希望 cmdlet 在启动模拟器后立即返回,请使用 -NoWait 选项。Use the -NoWait option, if you wish the cmdlet to return as soon as it starts the emulator.



Stop-CosmosDbEmulator [-NoWait]


停止模拟器。Stops the emulator. 默认情况下,此命令会一直等待,直至模拟器完全关闭。By default, this command waits until the emulator is fully shut down. 如果希望 cmdlet 在模拟器开始关闭后立即返回,请使用 -NoWait 选项。Use the -NoWait option, if you wish the cmdlet to return as soon as the emulator begins to shut down.



Uninstall-CosmosDbEmulator [-RemoveData]


卸载模拟器,并可视需要删除 $env:LOCALAPPDATA\CosmosDbEmulator 的完整内容。Uninstalls the emulator and optionally removes the full contents of $env:LOCALAPPDATA\CosmosDbEmulator. 此 cmdlet 可确保在卸载模拟器之前,模拟器已停止。The cmdlet ensures the emulator is stopped before uninstalling it.

在 Docker 上运行Running on Docker

可在用于 Windows 的 Docker 上运行 Azure Cosmos 模拟器。The Azure Cosmos Emulator can be run on Docker for Windows. 该模拟器不适合于用于 Oracle Linux 的 Docker。The emulator does not work on Docker for Oracle Linux.

安装用于 Windows 的 Docker 后,通过右键单击工具栏上的 Docker 图标并选择“切换到 Windows 容器”切换到 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.

接下来,通过从你喜欢使用的 shell 运行以下命令,从 Docker 中心拉取模拟器映像。Next, pull the emulator image from Docker Hub by running the following command from your favorite shell.

docker pull mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

若要启动映像,请运行以下命令。To start the image, run the following commands.

通过命令行:From the command-line:

md %LOCALAPPDATA%\CosmosDBEmulator\bind-mount

docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%LOCALAPPDATA%\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator


如果在运行 docker run 命令时发现端口冲突错误(指定的端口已在使用中),则可以通过更改端口号来传递自定义端口。If you see a port conflict error (specified port is already in use) when you run the docker run command, you can pass a custom port by altering the port numbers. 例如,可以将“-p 8081:8081”更改为“-p 443:8081”For example, you can change the "-p 8081:8081" to "-p 443:8081"

通过 PowerShell:From PowerShell:

md $env:LOCALAPPDATA\CosmosDBEmulator\bind-mount 2>null

docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=$env:LOCALAPPDATA\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

响应类似于以下内容:The response looks similar to the following:

Starting emulator
Emulator Endpoint:
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

现在,在客户端中使用来自响应的终结点和主密钥,并将 TLS/SSL 证书导入到主机中。Now use the endpoint and master key-in from the response in your client and import the TLS/SSL certificate into your host. 若要导入 TLS/SSL 证书,请从管理员命令提示符处执行以下操作:To import the TLS/SSL certificate, do the following from an admin command prompt:

通过命令行:From the command-line:

cd  %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
powershell .\importcert.ps1

通过 PowerShell:From PowerShell:

cd $env:LOCALAPPDATA\CosmosDBEmulator\bind-mount

在模拟器启动之后便关闭交互式 shell 会关闭模拟器的容器。Closing the interactive shell once the emulator has been started will shut down the emulator's container.

若要打开数据资源管理器,请在浏览器中导航到以下 URL。To open the Data Explorer, navigate to the following URL in your browser. 上面所示的响应消息中提供了模拟器终结点。The emulator endpoint is provided in the response message shown above.

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

如果你有在 Linux docker 容器上运行的 .NET 客户端应用程序,并且你在主机上运行 Azure Cosmos 模拟器,请根据适用于 Linux 的以下部分将证书导入到 Linux docker 容器中。If you have a .NET client application running on a Linux docker container and if you are running Azure Cosmos emulator on a host machine, please follow the below section for Linux to import the certificate into the Linux docker container.

在 Mac 或 Linux 上运行Running on Mac or Linux

目前 Cosmos 模拟器只能在 Windows 上运行。Currently the Cosmos emulator can only be run on Windows. 运行 Mac 或 Linux 的用户可以在托管虚拟机监控程序(如 Parallels 或 VirtualBox)的 Windows 虚拟机中运行模拟器。Users running Mac or Linux can run the emulator in a Windows virtual machine hosted a hypervisor such as Parallels or VirtualBox. 以下是启用此功能的步骤。Below are the steps to enable this.

在 Windows VM 中运行以下命令并记下 IPv4 地址。Within the Windows VM run the command below and make note of the IPv4 address.


在你的应用程序中,你需要更改用作终结点的 URI,以使用由 ipconfig.exe 返回的 IPv4 地址而不是使用 localhostWithin your application you need to change the URI used as Endpoint to use the IPv4 address returned by ipconfig.exe instead of localhost.

接下来,在 Windows VM 中,使用以下选项从命令行启动 Cosmos 模拟器。The next step, from the within the Windows VM, launch the Cosmos emulator from the command line using the following options.

Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

最后,我们需要将模拟器 CA 证书导入到 Linux 或 Mac 环境中。Finally, we need to import the Emulator CA certificate into the Linux or Mac environment.


如果在 Linux 中工作,则 .NET 依赖于 OpenSSL 来执行验证:If you are working on Linux, .NET relays on OpenSSL to do the validation:

  1. 使用 PFX 格式导出证书(当选择导出私钥时,PFX 可用)。Export the certificate in PFX format (PFX is available when choosing to export the private key).

  2. 将该 PFX 文件复制到 Linux 环境。Copy that PFX file into your Linux environment.

  3. 将 PFX 文件转换为 CRT 文件Convert the PFX file into a CRT file

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
  4. 将 CRT 文件复制到你的 Linux 分发版中包含自定义证书的文件夹。Copy the CRT file to the folder that contains custom certificates in your Linux distribution. 在 Debian 分发版中,它通常位于 /usr/local/share/ca-certificates/Commonly on Debian distributions, it is located on /usr/local/share/ca-certificates/.

    cp YourCTR.crt /usr/local/share/ca-certificates/
  5. 更新 CA 证书,这将更新 /etc/ssl/certs/ 文件夹。Update the CA certificates, which will update the /etc/ssl/certs/ folder.



如果在 Mac 中工作,请使用以下步骤:Use the following steps if you are working on Mac:

  1. 使用 PFX 格式导出证书(当选择导出私钥时,PFX 可用)。Export the certificate in PFX format (PFX is available when choosing to export the private key).

  2. 将该 PFX 文件复制到 Mac 环境。Copy that PFX file into your Mac environment.

  3. 打开 Keychain Access 应用程序并导入 PFX 文件。Open the Keychain Access application and import the PFX file.

  4. 打开证书列表,并找到名为 localhost 的证书。Open the list of Certificates and identify the one with the name localhost.

  5. 打开该特定项的上下文菜单,选择“获取项”,然后在“信任” > “使用此证书时”选项下选择“始终信任”。 Open the context menu for that particular item, select Get Item and under Trust > When using this certificate option, select Always Trust.

    打开该特定项的上下文菜单,选择“获取项”,然后在“信任 - 使用此证书时”选项下选择“始终信任”

完成这些步骤后,当连接到通过 /AllowNetworkAccess 公开的 IP 地址时,你的环境将信任模拟器使用的证书。After following these steps, your environment will trust the certificate used by the Emulator when connecting to the IP address exposes by /AllowNetworkAccess.


使用以下提示来帮助解决使用 Azure Cosmos 模拟器时遇到的问题:Use the following tips to help troubleshoot issues you encounter with the Azure Cosmos Emulator:

  • 如果安装了新版本的模拟器并遇到错误,请务必重置数据。If you installed a new version of the emulator and are experiencing errors, ensure you reset your data. 可在系统任务栏上右键单击“Azure Cosmos 模拟器”图标,然后单击“重置数据...”来重置数据。You can reset your data by right-clicking the Azure Cosmos Emulator icon on the system tray, and then clicking Reset Data…. 如果仍无法消除错误,可卸载该模拟器和所有旧版模拟器(如有),删除“C:\Program files\Azure Cosmos DB Emulator”目录,并卸载模拟器。If that does not fix the errors, you can uninstall the emulator and any older versions of the emulator if found, remove "C:\Program files\Azure Cosmos DB Emulator" directory and reinstall the emulator. 有关说明,请参阅卸载本地模拟器See Uninstall the local emulator for instructions.

  • 如果 Azure Cosmos 模拟器崩溃,请从“%LOCALAPPDATA%\CrashDumps”文件夹收集转储文件,对其进行压缩,然后从 Azure 门户开具支持票证。If the Azure Cosmos Emulator crashes, collect dump files from '%LOCALAPPDATA%\CrashDumps' folder, compress them, and open a support ticket from the Azure portal.

  • 如果 Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe 中出现崩溃,这可能表示性能计数器处于损坏状态。If you experience crashes in Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe, this might be a symptom where the Performance Counters are in a corrupted state. 通常,从管理员命令提示符处运行以下命令即可解决此问题:Usually running the following command from an admin command prompt fixes the issue:

    lodctr /R
  • 如果遇到连接问题,请收集跟踪文件,对其进行压缩,然后在 Azure 门户中开具支持票证。If you encounter a connectivity issue, collect trace files, compress them, and open a support ticket in the Azure portal.

  • 如果收到“服务不可用”消息,模拟器可能无法初始化网络堆栈。If you receive a Service Unavailable message, the emulator might be failing to initialize the network stack. 请查看是否安装了 Pulse 安全客户端或 Juniper 网络客户端,因为其网络筛选器驱动程序可能会导致该问题。Check to see if you have the Pulse secure client or Juniper networks client installed, as their network filter drivers may cause the problem. 卸载第三方网络筛选器驱动程序通常可修复此问题。Uninstalling third-party network filter drivers typically fixes the issue. 或者,使用 /DisableRIO 启动模拟器,这会将模拟器网络通信切换到常规 Winsock。Alternatively, start the emulator with /DisableRIO, which will switch the emulator network communication to regular Winsock.

  • 在模拟器运行时,如果计算机进入了睡眠模式或运行了任何 OS 更新,则你可能会看到“服务当前不可用”消息。While the emulator is running, if your computer goes to sleep mode or runs any OS updates, you might see a Service is currently unavailable message. 请右键单击 Windows 通知托盘中显示的图标,再选择“重置数据”来重置模拟器的数据。Reset the emulator's data, by right-clicking on the icon that appears on the windows notification tray and select Reset Data.

收集跟踪文件Collect trace files

若要收集调试跟踪,请从管理命令提示符运行以下命令:To collect debugging traces, run the following commands from an administrative command prompt:

  1. cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
  2. Microsoft.Azure.Cosmos.Emulator.exe /shutdown 列中的一个值匹配。Microsoft.Azure.Cosmos.Emulator.exe /shutdown. 监视系统托盘,确保该程序已关闭,这可能需要几分钟时间。Watch the system tray to make sure the program has shut down, it may take a minute. 还可仅单击 Azure Cosmos 模拟器用户界面中的“退出”。You can also just click Exit in the Azure Cosmos Emulator user interface.
  3. Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
  4. Microsoft.Azure.Cosmos.Emulator.exe
  5. 再现问题。Reproduce the problem. 如果数据资源管理器无法运行,只需等待几秒钟,待浏览器打开以捕获错误。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. Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces
  7. 导航到 %ProgramFiles%\Azure Cosmos DB Emulator,查找 docdbemulator_000001.etl 文件。Navigate to %ProgramFiles%\Azure Cosmos DB Emulator and find the docdbemulator_000001.etl file.
  8. Azure 门户中开具支持票证,并提供 .etl 文件以及再现步骤。Open a support ticket in the Azure portal and include the .etl file along with repro steps.

卸载本地模拟器Uninstall the local emulator

  1. 通过在系统任务栏上右键单击“Azure Cosmos 模拟器”图标,然后单击“退出”,退出所有打开的本地模拟器实例。Exit all open instances of the local emulator by right-clicking the Azure Cosmos Emulator icon on the system tray, and then clicking Exit. 退出所有实例可能需要一分钟。It may take a minute for all instances to exit.
  2. 在 Windows 搜索框中,键入“应用和功能”,然后单击“应用和功能(系统设置)”结果 。In the Windows search box, type Apps & features and click on the Apps & features (System settings) result.
  3. 在应用列表中,滚动到“Azure Cosmos DB 模拟器”并将其选中,单击“卸载”,然后确认并再次单击“卸载” 。In the list of apps, scroll to Azure Cosmos DB Emulator, select it, click Uninstall, then confirm and click Uninstall again.
  4. 卸载应用后,导航到 %LOCALAPPDATA%\CosmosDBEmulator 并删除该文件夹。When the app is uninstalled, navigate to %LOCALAPPDATA%\CosmosDBEmulator and delete the folder.

后续步骤Next steps

在本教程中,你已了解了如何使用本地模拟器进行免费的本地开发。In this tutorial, you've learned how to use the local emulator for free local development. 现在可以继续学习下一教程,了解如何导出模拟器 TLS/SSL 证书。You can now proceed to the next tutorial and learn how to export emulator TLS/SSL certificates.