共用方式為

使用 Visual Studio 已連線的服務將 Azure Cosmos DB 新增到您的應用程式

  • 發行項

使用 Visual Studio 時，您可以使用 [已連線的服務] 功能，將下列任何一項連線到 Azure Cosmos DB：

  • .NET Framework 主控台應用程式
  • ASP.NET 模型-視圖-控制程式 (MVC) (.NET Framework)
  • ASP.NET Core
  • .NET Core (包括主控台應用程式、WPF、Windows Forms、類別庫)
  • .NET Core 背景工作角色
  • Azure Functions
  • 通用 Windows 平台應用程式
  • Xamarin
  • 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 應用程式中，您可以使用 WebApplicationBuild 物件上的 Configuration 屬性來存取此連接字串。

  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 是 WebApplicationBuild 的執行個體，會出現在 ASP.NET Core 專案範本內的 Program.cs 中：

// 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 中建立資料庫。

相關內容