通过

使用 Visual Studio 连接服务将 Azure Cosmos DB 添加到应用

使用 Visual Studio，可以使用 Connected Services 功能将以下任一项连接到 Azure Cosmos DB：

  • .NET Framework 控制台应用
  • ASP.NET 模型View-Controller （MVC） （.NET Framework）
  • ASP.NET Core
  • .NET Core（包括控制台应用、WPF、Windows 窗体、类库）
  • .NET Core 辅助角色
  • Azure Functions
  • 通用 Windows 平台应用
  • Cordova

连接的服务功能将所需的所有引用和连接代码添加到项目，并相应地修改配置文件。

先决条件

使用连接服务连接到 Azure Cosmos DB

  1. 在 Visual Studio 中打开项目。

  2. 在 解决方案资源管理器中，右键单击 连接服务 节点，然后在上下文菜单中选择“添加连接服务”。

    如果未看到 连接服务 节点，请选择 项目>连接服务>添加。

  3. 在 连接服务 选项卡中，选择 服务依赖项的 +图标。

    显示如何添加服务依赖项的屏幕截图。

  4. 在 添加依赖项 页中，选择 Azure Cosmos DB。

    显示“添加依赖项”屏幕的屏幕截图，选择“添加 Azure Cosmos DB”选项。

    如果尚未登录，请登录到 Azure 帐户。 如果没有 Azure 帐户，可以注册 免费试用版。

  5. 在 Azure Cosmos DB 界面中，选择现有的 Azure Cosmos DB，然后选择“下一步”。

    如果需要创建数据库，请转到下一步。 否则，请跳到步骤 7。

    显示如何将现有 Azure Cosmos DB 添加到项目的屏幕截图。

  6. 创建 Azure Cosmos DB：

    1. 选择 在屏幕底部创建新的 Azure Cosmos DB。

    2. 填写“Azure Cosmos DB: 新建”屏幕，然后选择“创建”。

      显示“新建 Azure Cosmos DB”界面的屏幕截图。

    3. 显示 配置 Azure Cosmos DB 对话框时，新数据库将显示在列表中。 在列表中选择新数据库，然后选择“下一步”。

  7. 输入连接字符串名称，并选择是要将连接字符串存储在本地机密文件中，还是 Azure Key Vault中。

    显示“指定连接字符串”屏幕的屏幕截图。

  8. “更改摘要”屏幕显示了在完成该过程后将对项目进行的所有修改。 如果更改看起来正常，请选择“完成”。

    显示“更改摘要”屏幕的屏幕截图。

  9. 连接显示在“连接服务”选项卡的“服务依赖项”部分下。

    显示“服务依赖项”部分的屏幕截图。

说明

对于 .NET Framework 项目，连接服务 UI 略有不同。 若要查看差异，请与本页的 Visual Studio 2019 版本进行比较。

  1. 在 Visual Studio 中打开项目。

  2. 在 解决方案资源管理器中，右键单击 连接服务 节点，并从上下文菜单中选择 “添加”以打开可用服务的菜单。

    显示“连接服务”上下文菜单选项的屏幕截图。

    如果未看到 连接服务 节点，请选择 项目>连接服务>添加。

  3. 选择“Azure Cosmos DB”。 随即显示“连接到依赖项”页。 应看到两个选项，一个用于本地模拟器，即容器上的 Azure Cosmos DB 模拟器（本地），另一个用于连接到实时 Azure Cosmos DB 服务。 从本地模拟器开始，可以降低成本并简化早期开发。 稍后可以通过重复这些步骤并选择另一个选项，迁移到实时服务。

    显示 Azure Cosmos DB 选项的屏幕截图。

    如果选择使用 Azure Cosmos DB 模拟器，请单击 “下一步” 以查看 更改摘要 屏幕，其中显示了项目的修改方式。 NuGet 包引用将添加到项目，本地模拟器的连接代码将添加到项目中。 在最后一个屏幕上单击 完成 后，将创建模拟器的容器;你将在输出窗口中看到映像下载状态。

    如果要连接到 Azure 服务，请继续执行下一步，或者尚未登录，请在继续之前登录到 Azure 帐户。 如果没有 Azure 帐户，可以注册 免费试用版。

  4. 在 Azure Cosmos DB 界面中，选择现有的 Azure Cosmos DB，然后选择“下一步”。

    如果需要创建数据库，请转到下一步。 否则，请跳到步骤 7。

    显示“将现有 Azure Cosmos DB 添加到项目”屏幕的屏幕截图。

  5. 创建 Azure Cosmos DB：

    1. 选择 在屏幕底部创建新的 Azure Cosmos DB。

    2. 填写“Azure Cosmos DB: 新建”屏幕，然后选择“创建”。

      显示“新建 Azure Cosmos DB”界面的屏幕截图。

    3. 显示 配置 Azure Cosmos DB 对话框时，新数据库将显示在列表中。 在列表中选择新数据库，然后选择“下一步”。

  6. 输入连接字符串名称，并选择是要将连接字符串存储在本地机密文件中，还是 Azure Key Vault中。

    显示“指定连接字符串”屏幕的屏幕截图。

    连接字符串将添加为机密，并在应用配置中提供。 在 ASP.NET Core 应用中，可以使用 Configuration 对象的 WebApplicationBuilder 属性访问此连接字符串。

    说明

    使用 Visual Studio 2022 版本 17.12 及更高版本，此过程使用 Microsoft Entra 托管标识（无密码身份验证方法）连接到数据库。 此屏幕上的警告意味着，在 Visual Studio 中完成此过程后，需要在 Azure CLI 中执行手动步骤。 请参阅 在 Azure Cosmos DB for NoSQL 中使用数据平面的基于角色的访问控制。

  7. “更改摘要”屏幕显示了在完成该过程后将对项目进行的所有修改。 如果更改看起来正常，请选择“完成”。

    显示“更改摘要”屏幕的屏幕截图。

  8. 在解决方案资源管理器中，双击 连接服务 节点，打开 连接服务 选项卡。连接显示在 服务依赖项 部分下：

    添加连接服务后显示“服务依赖项”的屏幕截图。

    如果单击添加的依赖项旁边的三个点，可以看到各种选项，例如 连接 重新打开向导并更改连接。 还可以单击窗口右上角的三个点，查看用于启动本地依赖项、更改设置等的选项。

  9. 默认情况下，容器中的内存限制设置为 2G，但通常情况下，运行 Azure Cosmos DB 需要更多内存。 若要解决此问题，请导航到解决方案文件夹下的 .vs/sd/<GUID>/local 文件夹。 在 Windows 资源管理器中，可能需要启用隐藏文件才能查看 .vs 文件夹。 查找并打开文件 cosmosdb1.docker-compose.yml。 设置 4G 或更高的内存限制。

    mem_limit = 4G

    若要使用新设置重启容器，请在“连接服务”选项卡的“服务依赖项”部分中，单击三个点，然后选择 “启动本地依赖项”。

说明

Azure Cosmos DB 的本地模拟器可能会引用使用 Azure Cosmos DB 临时许可证的基本映像。 如果容器未启动，请检查 Azure Cosmos DB 容器的“容器”* 窗口中的“日志”选项卡。 如果它提到 PAL 过期问题，则需要获取本地容器的最新基础映像。 从控制台提示符运行以下命令：docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest。 许可证会定期更新，过期后，刷新到最新的容器应解决此问题。 可以在 Azure Cosmos DB 模拟器 GitHub 存储库查看和报告 Azure Cosmos DB 模拟器的问题。

后续步骤

了解如何按照在 ASP.NET Core 开发环境中安全存储应用机密安全存储机密。 具体而言，若要从机密存储中读取连接字符串，可以添加代码，如通过配置 API 读取机密中所示。 代码可能如下所示，其中 builder 是 ASP.NET 核心项目模板 WebApplicationBuild 中显示的 实例：

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: builder.Configuration["CosmosDBConnectionString"]
);

CosmosClient 通过其各种方法提供对 Azure Cosmos DB 功能的访问权限。 获得 CosmosClient实例后，可以按照本指南创建 NoSQL 数据库：使用 .NET在 Azure Cosmos DB for NoSQL 中创建数据库。

相关内容