Azure Cosmos DB Shell 的 Visual Studio Code 扩展

Azure Cosmos DB Shell Visual Studio Code 扩展提供无缝的集成体验，用于直接从代码编辑器管理和查询 Cosmos DB 数据库。

安装

方法 1：VS Code Marketplace（建议）

1. 打开 VS Code

   • 在计算机上启动Visual Studio Code

2. 开放扩展市场

   • 单击“扩展”图标（Ctrl+Shift+X/ Cmd+Shift+X）
   • 或者转到“查看 > 扩展”

3. 搜索 Cosmos DB

   • 在搜索框中键入“Cosmos DB”
   • 查找 Microsoft 提供的“Azure Cosmos DB”扩展

4. 安装扩展

   • 单击“安装”按钮
   • 等待安装完成
   • 如果系统提示，请重新加载 VS Code

方法 2：从 VSIX 文件安装

1. 下载扩展

   • 从发行页面下载 vscode-cosmosdb-0.33.3.vsix（或最新版本）

2. 安装扩展

   • 打开 VS Code
   • 转到扩展 （Ctrl+Shift+X / Cmd+Shift+X）
   • 单击“...”菜单并选择“从 VSIX 安装”
   • 选择下载的文件

3. 完成安装

   • 等待安装完成
   • 如果系统提示，请重新加载 VS Code

要求

• VS Code 版本：1.85 或更高版本
• Supported Platforms：Windows、macOS、Linux
• 磁盘空间：约 50 MB

Features

1. 资源管理器

在分层树视图中浏览 Cosmos DB 资源。

功能：

• 查看帐户中的所有数据库
• 查看容器及其属性
• 浏览容器中的文档
• 显示分区键和索引信息

访问：

• 单击活动栏中的 Cosmos DB 图标
• 或者转到“查看 > Cosmos DB 资源管理器”

2. 快速启动

直接从 VS Code 启动 Cosmos DB Shell。

方法：

• 命令面板

  • 按 Ctrl+Shift+P （macOS 上的 Cmd+Shift+P）
  • 键入“Cosmos DB Shell： Open”
  • 按 Enter

• 资源管理器上下文菜单

  • 右键单击数据库或容器
  • 选择“在 Shell 中打开”

• 状态栏

  • 单击状态栏中的 Cosmos DB 图标

3. 命令面板集成

直接从命令面板执行 Cosmos DB Shell 命令。

可用命令：

• Cosmos DB Shell: Open - 启动 shell
• Cosmos DB Shell: Connect - 切换帐户
• Cosmos DB Shell: Disconnect - 关闭连接
• Cosmos DB Shell: Start MCP Server - 启用 MCP
• Cosmos DB Shell: Stop MCP Server - 禁用 MCP
• Cosmos DB Shell: Settings - 访问扩展设置

访问命令：

1. 按 Ctrl+Shift+P （Cmd+Shift+P）
2. 键入命令名称
3. 按 Enter

4. Azure帐户集成

与Azure帐户无缝集成。

功能：

• 使用 Azure 帐户进行自动身份验证
• 支持多个订阅
• 托管标识集成
• Microsoft Entra ID支持

配置：

1. 使用Azure帐户登录（首次使用时提示）
2. 选择订阅和资源组
3. 选择要连接的 Cosmos DB 帐户

5. MCP 服务器集成

为 AI 集成启用模型上下文协议服务器。

访问：

1. 打开命令面板 （Ctrl+Shift+P）
2. 键入“Cosmos DB：启动 MCP 服务器”
3. 在 VS Code settings.json 中配置设置

配置：

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.port": 6128,
  "cosmosDB.shell.MCP.startOnLaunch": true
}

入门

步骤 1：安装扩展

按照上面的 “安装” 部分进行操作。

步骤 2：连接到帐户

1. 单击活动栏中的 Cosmos DB 图标
2. 使用Azure帐户登录（如果出现提示）
3. 选择订阅和 Cosmos DB 帐户
4. 资源管理器显示您的数据库和容器

步骤 3：打开 Cosmos DB Shell

1. 按 Ctrl+Shift+P （Cmd+Shift+P）
2. 键入“Cosmos DB Shell： Open”
3. 按 Enter 键以启动集成 Shell

步骤 4：开始查询

# Navigate to a database
> cd mydb

# List containers
> ls

# Query documents
> query "SELECT * FROM c"

使用资源

探索数据库

在资源资源管理器中：

1. 扩展 Cosmos DB 帐户
2. 查看所有数据库
3. 展开数据库，查看容器
4. 右键单击可显示上下文菜单选项

可用的操作：

• 创建数据库
• 删除数据库
• 创建容器
• 刷新

使用容器

右键单击“容器选项”

• 在 Shell 中打开 - 在容器上下文中启动 Shell
• 查询文档 - 执行 SQL 查询
• 创建文档 - 添加新文档
• 删除容器 - 删除容器
• 查看属性 - 显示容器元数据

管理文档

文档操作：

• 查看文档内容
• 创建新文档
• 更新文档
• 删除文档
• 复制文档标识符

集成终端

使用集成终端执行 Shell 操作。

启动终端

1. 查看 > 集成终端（Ctrl+`）
2. 或单击底部的“终端”选项卡

运行命令

# In the integrated terminal
cosmosdbshell

# Navigate and query
> cd mydb
> ls
> query "SELECT * FROM c"

设置和配置

访问扩展设置

1. 打开设置 （Ctrl+， / Cmd+，）
2. 搜索“Cosmos DB”
3. 根据需要修改设置

可用设置

配置示例

{
  "cosmosDB.autoconnect": true,
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.port": 6128,
  "cosmosDB.queryTimeout": 60000
}

键盘快捷方式

提示和技巧

1.快速访问常用容器

1. 单击容器名称旁边的星形图标
2. 容器显示在“收藏夹”部分中
3. 无需展开树即可快速访问

2. 多容器查询

使用多个终端选项卡处理不同的容器：

1. 打开终端 （Ctrl+'）
2. 右键单击以创建新终端选项卡
3. 在每个选项卡中连接到不同的容器

3.保存查询结果

将查询结果导出到文件：

# In integrated terminal
query "SELECT * FROM c" > results.json

4.设置 JSON 输出格式

在集成终端中使用 jq：

query "SELECT * FROM c" | jq '.[]'

5. 键盘导航

• 选项卡：在面板之间移动
• 箭头键：导航树
• Enter：打开所选项目
• 删除：删除所选资源

故障排除

扩展不会加载

问题： Cosmos DB 扩展未显示在 VS Code 中

解决方案：

1. 验证 VS Code 版本是否为 1.85 或更高版本

2. 检查是否已安装扩展程序：

   • 转到扩展（Ctrl+Shift+X）
   • 搜索“Cosmos DB”
   • 验证是否已安装Microsoft的“Azure Cosmos DB”扩展

3. 重启 VS Code

4. 清除扩展缓存：

   • 删除 .vscode/extensions 文件夹
   • 重新安装扩展

无法连接到帐户

问题： “需要登录”或身份验证失败

解决方案：

1. 打开命令面板 （Ctrl+Shift+P）
2. 键入“Azure：注销”
3. 键入“Azure：登录”
4. 完成浏览器身份验证
5. 选择订阅和资源组

MCP 服务器不会启动

问题： MCP 服务器无法在扩展中启动

解决方案：

1. 检查端口 6128 未被占用：

   # Windows
   netstat -ano | findstr 6128
   
   # macOS/Linux
   lsof -i :6128
   

2. 在设置中尝试不同的端口：

   "cosmosDB.shell.MCP.port": 6129
   

3. 检查防火墙设置

4. 查看“输出”面板以查看错误

Shell 不响应

问题： Cosmos DB Shell 已冻结或无响应

解决方案：

1. 尝试按 Ctrl+C 以中断
2. 关闭并重新打开终端
3. 重启 VS Code
4. 检查网络连接
5. 验证 Cosmos DB 帐户是否可访问

扩展速度缓慢

问题： 扩展缓慢或资源繁重

解决方案：

1. 禁用自动连接：

   "cosmosDB.autoconnect": false
   

2. 降低刷新频率

3. 关闭不必要的资源管理器项目

4. 查看 VS Code 活动监视器（帮助>关于）

5. 如果冲突，请禁用其他扩展

后续步骤

• 命令参考 - 了解所有可用的命令
• 快速入门指南 - 示例入门
• 模型上下文协议设置 - 启用 AI 集成
• 故障排除指南 - 解决问题
• 安全最佳做法 - 保护设置

支持

• Azure 支持
• VS Code 问题
• 报告扩展程序问题

另请参阅

• Azure Cosmos DB Shell 概述
• 安装指南
• Azure Cosmos DB 文档