排查使用 Azure Cosmos DB 模拟器时出现的问题Troubleshoot issues when using the Azure Cosmos DB Emulator

适用于: 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 模拟器时遇到的问题。Use the tips in this article to help troubleshoot issues you encounter when installing or using the Azure Cosmos DB Emulator.

如果安装了新版本的模拟器并遇到错误,请务必重置数据。If you installed a new version of the emulator and are experiencing errors, ensure you reset your data. 重置数据的方法如下:在系统任务栏上右键单击“Azure Cosmos DB 模拟器”图标,然后单击“重置数据...”。You can reset your data by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then clicking Reset Data…. 如果仍无法消除错误,可卸载该模拟器和所有旧版模拟器(如有),删除“C:\Program files\Azure Cosmos DB Emulatorr”目录,并卸载模拟器。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. 如果重置数据没有用,也可导航到 %LOCALAPPDATA%\CosmosDBEmulator 位置并删除该文件夹。Alternatively if resetting the data doesn't work, navigate to %LOCALAPPDATA%\CosmosDBEmulator location and delete the folder.

排查损坏的 Windows 性能计数器Troubleshoot corrupted windows performance counters

  • 如果 Azure Cosmos DB 模拟器崩溃,请从 %LOCALAPPDATA%\CrashDumps 文件夹收集转储文件,对其进行压缩,然后从 Azure 门户打开支持工单。If the Azure Cosmos DB Emulator crashes, collect the 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

解决连接问题Troubleshoot connectivity issues

  • 如果遇到连接问题,请收集跟踪文件,对其进行压缩,然后在 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.

  • 如果遇到“禁止”-“消息”:“正在使用传输协议或密码中禁止的加密方法发出请求。请检查帐户 SSL/TLS 允许的最低协议设置…”连接问题,这可能是 OS 中发生全局更改(例如,预览体验计划预览版 20170)或启用 TLS 1.3 作为默认值的浏览器设置导致的。If you encounter "Forbidden","message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting..." connectivity issues, this might be caused by global changes in the OS (for example Insider Preview Build 20170) or the browser settings that enable TLS 1.3 as default. 使用 SDK 对 Cosmos 模拟器执行请求时,可能会发生类似错误,例如“Microsoft.Azure.Documents.DocumentClientException:正在使用传输协议或密码中禁止的加密方法发出请求。请检查帐户 SSL/TLS 允许的最低协议设置”。Similar error might occur when using the SDK to execute a request against the Cosmos emulator, such as Microsoft.Azure.Documents.DocumentClientException: Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting. 此时这是预期情况,因为 Cosmos 模拟器仅接受并使用 TLS 1.2 协议。This is expected at this time since Cosmos emulator only accepts and works with TLS 1.2 protocol. 建议的解决方法是将设置和默认值更改为 TLS 1.2;例如,在 IIS 管理器中,导航到“站点”->“默认网站”,找到端口 8081 的“网站绑定”并进行编辑,以禁用 TLS 1.3。The recommended work-around is to change the settings and default to TLS 1.2; for instance, in IIS Manager navigate to "Sites" -> "Default Web Sites" and locate the "Site Bindings" for port 8081 and edit them to disable TLS 1.3. 可以通过“设置”选项对 Web 浏览器执行类似操作。Similar operation can be performed for the Web browser via the "Settings" options.

  • 在模拟器运行时,如果计算机进入了睡眠模式或运行了任何 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. 导航到安装了模拟器的路径:Navigate to the path where the emulator is installed:

    cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
  2. 关闭模拟器,监视系统任务栏,确保该程序已关闭。Shut down the emulator and watch the system tray to make sure the program has shut down. 该过程可能需要一分钟时间。It may take a minute to complete. 你也可在 Azure Cosmos DB 模拟器用户界面中选择“退出”。You can also select Exit in the Azure Cosmos DB Emulator user interface.

    Microsoft.Azure.Cosmos.Emulator.exe /shutdown
  3. 使用以下命令开始日志记录:Start logging with the following command:

    Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
  4. 启动模拟器Launch the emulator

  5. 再现问题。Reproduce the problem. 如果数据资源管理器无法运行,只需等待几秒钟,待浏览器打开以捕获错误。If the data explorer is not working, you only need to wait for the browser to open for a few seconds to catch the error.

  6. 使用以下命令停止日志记录:Stop logging with the following command:

    Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces
  7. 导航到 %ProgramFiles%\Azure Cosmos DB Emulator 路径,查找 docdbemulator_000001.etl 文件。Navigate to %ProgramFiles%\Azure Cosmos DB Emulator path 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.

后续步骤Next steps

本文介绍了如何调试本地模拟器的问题。In this article, you've learned how to debug issues with the local emulator. 你现在可以继续学习下面的文章:You can now proceed to the next articles: