安装并使用 Azure Cosmos DB 模拟器进行本地开发和测试Install and use the Azure Cosmos DB Emulator for local development and testing

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

为方便进行开发,Azure Cosmos DB 模拟器提供了一个模拟 Azure Cosmos DB 服务的本地环境。The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. 使用 Azure Cosmos DB 模拟器可在本地开发和测试应用程序,无需创建 Azure 订阅且不会产生任何费用。Using the Azure Cosmos DB Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. 如果对应用程序在 Azure Cosmos DB 模拟器中的运行情况感到满意,则可以通过切换在云中使用 Azure Cosmos 帐户。When you're satisfied with how your application is working in the Azure Cosmos DB Emulator, you can switch to using an Azure Cosmos account in the cloud. 本文介绍了如何在 Windows、Linux、macOS 和 Windows Docker 环境中安装并使用模拟器。This article describes how to install and use the emulator on Windows, Linux, macOS, and Windows docker environments.

下载模拟器Download the emulator

若要开始,请在本地计算机上下载并安装最新版本的 Azure Cosmos DB 模拟器。To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer. 模拟器发行说明一文列出了所有可用版本以及每个版本中所做的功能更新。The emulator release notes article lists all the available versions and the feature updates that were made in each release.

下载 Azure Cosmos DB 模拟器

你可以使用 Azure Cosmos DB 模拟器结合 SQLCassandraMongoDBGremlin API 帐户来开发应用程序。You can develop applications using Azure Cosmos DB Emulator with the SQL, Cassandra, MongoDB, Gremlin, and Table API accounts. 目前,模拟器中的数据资源管理器仅完全支持查看 SQL 数据;目前无法查看使用 MongoDB、Gremlin/Graph 和 Cassandra 客户端应用程序创建的数据。Currently the data explorer in the emulator fully supports viewing SQL data only; the data created using MongoDB, Gremlin/Graph and Cassandra client applications it is not viewable at this time. 若要了解详细信息,请参阅如何从不同的 API 连接到模拟器终结点To learn more, see how to connect to the emulator endpoint from different APIs.

模拟器如何工作?How does the emulator work?

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

虽然模拟 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 the Azure infrastructure like multiple-region replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not applicable when you use the emulator.

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

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

由于 Azure Cosmos DB 模拟器提供一个在本地开发人员工作站上运行的模拟环境,因此该模拟器在功能上与 Azure Cosmos 云端帐户之间存在一些差异:Because the Azure Cosmos DB Emulator provides an emulated environment that runs 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 the Data Explorer pane in the emulator fully supports SQL API clients only. 不完全支持在“数据资源管理器”中查看和操作 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.

  • 模拟器仅支持一个固定的帐户和一个公开的主密钥。The emulator supports only a single fixed account and a well-known primary key. 使用 Azure Cosmos DB 模拟器时,无法重新生成密钥,但是可以使用命令行选项更改默认密钥。You can't regenerate key when using the Azure Cosmos DB Emulator, however you can change the default key by using the command-line option.

  • 使用模拟器时,只能在预配吞吐量模式下创建 Azure Cosmos 帐户;目前它不支持无服务器模式。With the emulator, you can create an Azure Cosmos account in provisioned throughput mode only; currently it doesn't support serverless mode.

  • 此模拟器不是一项可缩放的服务,它不支持大量容器。The emulator is not a scalable service and it doesn't support a large number of containers. 使用 Azure Cosmos DB 模拟器时,默认情况下,最多可创建 25 个 400 RU/s 的固定大小容器(仅支持使用 Azure Cosmos DB SDK 进行创建),或 5 个不受限容器。When using the Azure Cosmos DB Emulator, by default, you can create up to 25 fixed size containers at 400 RU/s (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers. 有关如何更改此值的详细信息,请参阅设置 PartitionCount 值一文。For more information on how to change this value, see Set the PartitionCount value article.

  • 此模拟器没有像云服务一样提供各种 Azure Cosmos DB 一致性级别The emulator does not offer different Azure Cosmos DB consistency levels like the cloud service does.

  • 此模拟器未提供多区域复制The emulator does not offer multi-region replication.

  • 因为 Azure Cosmos DB 模拟器副本并不总是能反映出 Azure Cosmos DB 服务中的最新更改,因此应始终使用 Azure Cosmos DB 容量规划器来准确估计应用程序的吞吐量 (RU) 需求。Because the copy of your Azure Cosmos DB Emulator might not always be up to date with the most recent changes in the Azure Cosmos DB service, you should always refer to the Azure Cosmos DB capacity planner to accurately estimate the throughput (RUs) needs of your application.

  • 模拟器支持的最大 ID 属性大小为 254 个字符。The emulator supports a maximum ID property size of 254 characters.

安装模拟器Install the emulator

安装模拟器之前,请确保满足以下硬件和软件要求:Before you install the emulator, make sure you have the following hardware and software requirements:

  • 所需软件:Software requirements:

    • 当前支持 Windows Server 2016、2019 或 Windows 10 主机操作系统。Currently Windows Server 2016, 2019 or Windows 10 host OS are supported. 当前不支持启用了 Active Directory 的主机操作系统。The host OS with Active Directory enabled is currently not supported.
    • 64 位操作系统64-bit operating system
  • 最低硬件要求:Minimum hardware requirements:

    • 2-GB RAM2-GB RAM
    • 10-GB 可用硬盘空间10-GB available hard disk space
  • 若要安装、配置和运行 Azure Cosmos DB 模拟器,必须在计算机上具有管理特权。To install, configure, and run the Azure Cosmos DB Emulator, you must have administrative privileges on the computer. 模拟器将添加一个证书,并设置防火墙规则,以便运行其服务。The emulator will add a certificate and also set the firewall rules in order to run its services. 因此,模拟器需要管理员权限才能执行此类操作。Therefore admin rights are necessary for the emulator to be able to execute such operations.

若要开始,请在本地计算机上下载并安装最新版本的 Azure Cosmos DB 模拟器To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer. 如果在安装模拟器时遇到任何问题,请参阅模拟器故障排除一文来进行调试。If you run into any issues when installing the emulator, see the emulator troubleshooting article to debug.

根据你的系统要求,你可以在 Windows用于 Windows 的 DockerLinux 或 macOS 上运行模拟器,如本文后续部分所述。Depending upon your system requirements, you can run the emulator on Windows, Docker for Windows, Linux, or macOS as described in next sections of this article.

检查模拟器更新Check for emulator updates

模拟器的每个版本都附带了一组功能更新或 bug 修复。Each version of emulator comes with a set of feature updates or bug fixes. 若要查看可用版本,请阅读模拟器发行说明一文。To see the available versions, read the emulator release notes article.

安装后,如果已使用默认设置,则与模拟器对应的数据将保存在 %LOCALAPPDATA%\CosmosDBEmulator 位置。After installation, if you have used the default settings, the data corresponding to the emulator is saved at %LOCALAPPDATA%\CosmosDBEmulator location. 你可以使用可选的数据路径设置来配置一个不同的位置,即作为命令行参数/DataPath=PREFERRED_LOCATIONYou can configure a different location by using the optional data path settings; that is the /DataPath=PREFERRED_LOCATION as the command-line parameter. 在 Azure Cosmos DB 模拟器的一个版本中创建的数据不保证在使用不同版本时可以访问。The data created in one version of the Azure Cosmos DB Emulator is not guaranteed to be accessible when using a different version. 如果需要长期保存数据,建议将该数据存储在 Azure Cosmos 帐户中而不是 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 account, instead of the Azure Cosmos DB Emulator.

在 Windows 上使用模拟器Use the emulator on Windows

默认情况下,Azure Cosmos DB 模拟器将安装在 C:\Program Files\Azure Cosmos DB Emulator 位置。The Azure Cosmos DB Emulator is installed at C:\Program Files\Azure Cosmos DB Emulator location by default. 若要在 Windows 上启动 Azure Cosmos DB 模拟器,请选择“开始”按钮或按 Windows 键。To start the Azure Cosmos DB Emulator on Windows, select the Start button or press the Windows key. 开始键入“Azure Cosmos DB 模拟器”,并从应用程序列表中选择该模拟器。Begin typing Azure Cosmos DB Emulator, and select the emulator from the list of applications.

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

在模拟器启动后,Windows 任务栏通知区域中会显示一个图标。When the emulator has started, you'll see an icon in the Windows taskbar notification area. 它会在浏览器中自动打开 Azure Cosmos 数据资源管理器,URL 为 https://localhost:8081/_explorer/index.htmlIt automatically opens the Azure Cosmos data explorer in your browser at this URL https://localhost:8081/_explorer/index.html URL.

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

还可以通过命令行或 PowerShell 命令启动和停止模拟器。You can also start and stop the emulator from the command-line or PowerShell commands. 有关详细信息,请参阅命令行工具参考一文。For more information, see the command-line tool reference article.

默认情况下,Azure Cosmos DB 模拟器在本地计算机(“localhost”)上运行,侦听端口 8081。The Azure Cosmos DB Emulator by default runs on the local machine ("localhost") listening on port 8081. 地址显示为 https://localhost:8081/_explorer/index.htmlThe address appears as https://localhost:8081/_explorer/index.html. 如果关闭数据资源管理器后要重新打开它,可以在浏览器中打开该 URL 或通过 Windows 任务栏图标中的 Azure Cosmos DB 模拟器启动,如下所示。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 DB Emulator in the Windows Tray Icon as shown below.

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

在用于 Windows 的 Docker 上使用模拟器Use the emulator on Docker for Windows

可以在 Windows Docker 容器中运行 Azure Cosmos DB 模拟器。You can run the Azure Cosmos DB Emulator on the Windows Docker container. 有关 docker pull 命令,请参阅 Docker 中心;有关 Dockerfile 和详细信息,请参阅 GitHubSee the Docker Hub for the docker pull command and GitHub for the Dockerfile and more information. 当前,该模拟器不适合于用于 Oracle Linux 的 Docker。Currently the emulator does not work on Docker for Oracle Linux. 根据以下说明在用于 Windows 的 Docker 上运行模拟器:Use the following instructions to run the emulator on Docker for Windows:

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

  2. 接下来,通过从你喜欢使用的 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
  3. 若要启动映像,请运行以下命令,具体取决于命令行或 PowerShell 环境:To start the image, run the following commands depending on the command line or the PowerShell environment:

    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

    基于 Windows 的 Docker 映像并非总是与每个 Windows 主机操作系统都兼容。Windows based Docker images might not be generally compatible with every Windows host OS. 例如,默认的 Azure Cosmos DB 模拟器映像仅与 Windows 10 和 Windows Server 2016 兼容。For instance, the default Azure Cosmos DB Emulator image is only compatible with Windows 10 and Windows Server 2016. 如果需要与 Windows Server 2019 兼容的映像,请改为运行以下命令:If you need an image that is compatible with Windows Server 2019, run the following command instead:

    docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%hostDirectory%,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/winsrv2019/azure-cosmos-emulator:latest


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

  4. 现在,使用来自响应的模拟器终结点和主密钥,并将 TLS/SSL 证书导入到主机中。Now use the emulator endpoint and primary key from the response and import the TLS/SSL certificate into your host. 若要导入 TLS/SSL 证书,请从管理员命令提示符处运行以下步骤:To import the TLS/SSL certificate, run the following steps from an admin command prompt:

    cd  %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
    powershell .\importcert.ps1
  5. 如果你在模拟器启动之后关闭了交互式 shell,则会关闭模拟器的容器。If you close the interactive shell after the emulator has started, it will shut down the emulator's container. 若要重新打开数据资源管理器,请在浏览器中导航到以下 URL。To reopen 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.html

如果你有在 Linux docker 容器中运行的 .NET 客户端应用程序,并且你在主机上运行 Azure Cosmos DB 模拟器,请根据下一部分的说明将证书导入到 Linux docker 容器中。If you have a .NET client application running on a Linux docker container and if you are running Azure Cosmos DB Emulator on a host machine, use the instructions in the next section to import the certificate into the Linux docker container.

在 Docker 容器中运行时重新生成模拟器证书Regenerate the emulator certificates when running on a Docker container

在 Docker 容器中运行模拟器时,每次停止并重启相应的容器都会重新生成与模拟器关联的证书。When running the emulator in a Docker container, the certificates associated with the emulator are regenerated every time you stop and restart the respective container. 因此,必须在每个容器启动后重新导入证书。Because of that you have to re-import the certificates after each container start. 若要解决此限制,可以使用 Docker Compose 文件将 Docker 容器绑定到特定的 IP 地址和容器映像。To work around this limitation, you can use a Docker compose file to bind the Docker container to a particular IP address and a container image.

例如,你可以在 Docker Compose 文件中使用以下配置,确保根据你的要求设置其格式:For example, you can use the following configuration within the Docker compose file, make sure to format it per your requirement:

version: '2.4' # Do not upgrade to 3.x yet, unless you plan to use swarm/docker stack: https://github.com/docker/compose/issues/4513

    external: false
      driver: default
        - subnet: ""


  # First create a directory that will hold the emulator traces and certificate to be imported
  # set hostDirectory=C:\emulator\bind-mount
  # mkdir %hostDirectory%

    container_name: "azurecosmosemulator"
    hostname: "azurecosmosemulator"
    image: 'mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator'
    platform: windows
    tty: true
    mem_limit: 3GB
        - '8081:8081'
        - '8900:8900'
        - '8901:8901'
        - '8902:8902'
        - '10250:10250'
        - '10251:10251'
        - '10252:10252'
        - '10253:10253'
        - '10254:10254'
        - '10255:10255'
        - '10256:10256'
        - '10350:10350'
        - '${hostDirectory}:C:\CosmosDB.Emulator\bind-mount'

在 Linux 或 macOS 上使用模拟器Use the emulator on Linux or macOS

目前 Azure Cosmos DB 模拟器只能在 Windows 上运行。Currently the Azure Cosmos DB Emulator can only be run on Windows. 如果你使用 Linux 或 macOS,则可以在某个托管在虚拟机监控程序(例如 Parallels 或 VirtualBox)中的 Windows 虚拟机中运行模拟器。If you are using Linux or macOS, you can run the emulator in a Windows virtual machine hosted in a hypervisor such as Parallels or VirtualBox.


每次重启虚拟机监控程序中托管的 Windows 虚拟机时,都必须重新导入证书,因为虚拟机的 IP 地址会发生更改。Every time you restart the Windows virtual machine that is hosted in a hypervisor, you have to reimport the certificate because the IP address of the virtual machine changes. 如果已将虚拟机配置为保留 IP 地址,则不需要导入证书。Importing the certificate isn't required in case you have configured the virtual machine to preserve the IP address.

通过以下步骤在 Linux 或 macOS 环境中使用模拟器:Use the following steps to use the emulator on Linux or macOS environments:

  1. 在 Windows 虚拟机中运行以下命令,并记下 IPv4 地址:Run the following command from the Windows virtual machine and make a note of the IPv4 address:

  2. 在应用程序中更改终结点 URL,以便使用由 ipconfig.exe 返回的 IPv4 地址,而不是使用 localhostWithin your application, change the endpoint URL to use the IPv4 address returned by ipconfig.exe instead of localhost.

  3. 在 Windows VM 中,使用以下选项从命令行启动 Azure Cosmos DB 模拟器。From the Windows VM, launch the Azure Cosmos DB Emulator from the command line using the following options. 有关命令行支持的参数的详细信息,请参阅模拟器命令行工具参考For details on the parameters supported by the command line, see the emulator command-line tool reference:

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM +4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
  4. 最后,你需要解决在 Linux 或 Mac 环境中运行的应用程序与模拟器之间的证书信任过程问题。Finally, you need to resolve the certificate trust process between the application running on the Linux or Mac environment and the emulator. 可以使用以下两个选项之一来解决证书问题:You can use one of the following two options to resolve the certificate:

    1. 将模拟器 TLS/SSL 证书导入到 Linux 或 Mac 环境中,或者Import the emulator TLS/SSL certificate into the Linux or Mac environment or
    2. 在应用程序中禁用 TLS/SSL 验证Disable the TLS/SSL validation in the application

选项 1:导入模拟器 TLS/SSL 证书Option 1: Import the emulator TLS/SSL certificate

以下部分介绍了如何将模拟器 TLS/SSL 证书导入到 Linux 和 macOS 环境中。The following sections show how to import the emulator TLS/SSL certificate into Linux and macOS environments.

Linux 环境Linux environment

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

  1. 以 PFX 格式导出证书Export the certificate in PFX format. 选择导出私钥时,PFX 选项可用。The PFX option 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. 更新 TLS/SSL 证书,这将更新 /etc/ssl/certs/ 文件夹。Update the TLS/SSL certificates, which will update the /etc/ssl/certs/ folder.


macOS 环境macOS environment

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

  1. 以 PFX 格式导出证书Export the certificate in PFX format. 选择导出私钥时,PFX 选项可用。The PFX option 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.

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

选项 2:在应用程序中禁用 SSL 验证Option 2: Disable the SSL validation in the application

建议仅出于开发目的禁用 SSL 验证,并且在生产环境中运行时不应这样做。Disabling SSL validation is only recommended for development purposes and should not be done when running in a production environment. 下面的示例演示了如何对 .NET 和 Node.js 应用程序禁用 SSL 验证。The following examples show how to disable SSL validation for .NET and Node.js applications.

对于在与 .NET Standard 2.1 或更高版本兼容的框架中运行的任何应用程序,我们可以利用 CosmosClientOptions.HttpClientFactoryFor any application running in a framework compatible with .NET Standard 2.1 or later, we can leverage the CosmosClientOptions.HttpClientFactory:

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    HttpClientFactory = () =>
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
            ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator

        return new HttpClient(httpMessageHandler);
    ConnectionMode = ConnectionMode.Gateway

CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

启用对本地网络上的模拟器的访问权限Enable access to emulator on a local network

如果你有多台计算机使用单个网络,在一台计算机上设置了模拟器,而你想要从其他计算机访问它,If you have multiple machines using a single network, and if you set up the emulator on one machine and want to access it from other machine. 那么,在这种情况下,你需要启用对本地网络上的模拟器的访问权限。In such case, you need to enable access to the emulator 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.

使用模拟器时对连接进行身份验证Authenticate connections when using emulator

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

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


Azure Cosmos DB 模拟器支持的主密钥仅可用于该模拟器。The primary key supported by the Azure Cosmos DB 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 DB Emulator.


如果是使用 /Key 选项启动的模拟器,请使用所生成的密钥而不是默认密钥 C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==If you have started the emulator with the /Key option, then use the generated key instead of the default key C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. 有关 /Key 选项的详细信息,请参阅命令行工具参考For more information about /Key option, see Command-line tool reference.

使用模拟器连接到不同的 APIConnect to different APIs with the emulator


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

// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(

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

在桌面上运行 Azure Cosmos DB 模拟器后,可以使用 Azure Cosmos DB API for MongoDB 与该模拟器进行交互。Once you have the Azure Cosmos DB Emulator running on your desktop, you can use the Azure Cosmos DB's API for MongoDB to interact with the emulator. 命令提示符下,以管理员身份使用“/EnableMongoDbEndpoint”启动模拟器。Start the 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 DB 模拟器后,可使用 Azure Cosmos DB 表 API SDK 与该模拟器进行交互。Once you have the Azure Cosmos DB Emulator running on your desktop, you can use the Azure Cosmos DB Table API SDK to interact with the emulator. 命令提示符处,以管理员身份使用“/EnableTableEndpoint”启动模拟器。Start the 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.

  1. 安装 Python 2.7Install Python 2.7

  2. 安装 Cassandra CLI/CQLSHInstall Cassandra CLI/CQLSH

  3. 在常规命令提示符窗口中运行以下命令: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
  4. 在 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 promptwith "/EnableGremlinEndpoint". 或者,也可设置环境变量 AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=trueAlternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

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

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

  3. 在常规命令提示符窗口中运行以下命令: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  }}
  4. 在 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()

卸载本地模拟器Uninstall the local emulator

使用以下步骤卸载模拟器:Use the following steps to uninstall the emulator:

  1. 退出所有打开的本地模拟器实例,方法是:在系统任务栏上右键单击“Azure Cosmos DB 模拟器”图标,然后选择“退出”。 Exit all the open instances of the local emulator by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then select Exit. 退出所有实例可能需要一分钟。It may take a minute for all instances to exit.

  2. 在 Windows 搜索框中,键入“应用和功能”,然后选择“应用和功能(系统设置)”结果 。In the Windows search box, type Apps & features and select Apps & features (System settings) result.

  3. 在应用列表中,滚动到“Azure Cosmos DB 模拟器”并将其选中,单击“卸载”,然后确认并再次选择“卸载” 。In the list of apps, scroll to the Azure Cosmos DB Emulator, select it, click Uninstall, then confirm and select Uninstall again.

后续步骤Next steps

在本文中,你已了解如何使用本地模拟器进行免费的本地开发。In this article, you've learned how to use the local emulator for free local development. 你现在可以继续学习下面的文章:You can now proceed to the next articles: