實驗室 04：建構多語言資料解決方案

Microsoft Azure 使用者介面

基於 Microsoft 雲端工具的動態性質，您可能會遇到在本訓練內容開發後變更的 Azure UI。 因此，實驗指示可能無法正確對應實驗步驟。

當社群提醒 Microsoft 需要做修改時，我們會更新此訓練課程。 然而，雲端更新經常發生，所以您可能會在此訓練內容更新前遇到 UI 的變更。 如果發生這種情況，請適應變更，然後視需要在實驗中調整。

指示

在您開始使用 Intune 之前

登入實驗室環境

使用下列認證登入您的 Windows 11 虛擬機器 (VM)：

• 使用者名稱：Admin
• 密碼：Pa55w.rd

注意：您的講師會提供連線至虛擬實驗室環境的指示。

檢閱已安裝的應用程式

尋找 Windows 11 桌面上的工作列。 工作列包含此次實驗中會用到的應用程式圖示，包括：

• Microsoft Edge
• 檔案總管
• Visual Studio Code

實驗情境

在本實驗中，您將建立 Azure Cosmos DB 資源和儲存體帳戶資源。 使用 C# 和 .NET，您將存取 Cosmos DB 資源並將資料上傳至其中。

此外，由於 Contoso 可能想要透過使用者易用的介面存取 Cosmos DB 中的資料，因此您將實作 .NET 解決方案，以在網頁瀏覽器中存取和顯示 Cosmos DB 資料。

架構圖

練習 1：在 Azure 中建立資料存放區資源

工作 1：開啟 Azure 入口網站

1. 在工作列上，選取 Microsoft Edge 圖示。

2. 在開啟的瀏覽器視窗中，瀏覽至 Azure 入口網站 (https://portal.azure.com)，然後使用此實驗要使用的帳戶登入。

   注意：如果這是您第一次登入 Azure 入口網站，系統會提供入口網站的導覽。 選取 [開始使用] 跳過導覽，並開始使用入口網站。

工作 2：建立 Azure Cosmos DB 帳戶資源

1. 在 Azure 入口網站中使用 [搜尋資源、服務及文件] 文字輸入框，搜尋 Azure Cosmos DB，然後在結果清單中選取 [Azure Cosmos DB]。

2. 在 [Azure Cosmos DB]** 窗格上，選取 [+ 建立]**。

3. 在 [建立 Azure Cosmos DB 帳戶]** 刀鋒視窗上，選取 [Azure Cosmos DB for NoSQL]** 方塊中的 [建立]**。

4. 在 [建立 Azure Cosmos DB 帳戶 - Azure Cosmos DB for NoSQL]** 頁面的 [基本]** 索引標籤上執行下列動作，然後選取 [檢閱 + 建立]**：

   設定	動作
   [訂閱] 清單	保留預設值
   [資源群組] 區段	選取 [新建]
   [名稱] 文字輸入框	輸入 Polyglotdata 後選取 [確定]
   [AccountName] 文字輸入框	輸入 polycosmos [您的名稱]
   [位置] 下拉式清單	選取位置最接近實驗用的電腦且可建立 Cosmos DB 帳戶的 Azure 區域
   [容量模式]** 區段	選取 [無伺服器]

   下列螢幕擷取畫面顯示 [建立 Azure Cosmos DB 帳戶 - Azure Cosmos DB for NoSQL] 頁面上的設定。

   

5. 在 [建立 Azure Cosmos DB 帳戶 - Azure Cosmos DB for NoSQL]** 頁面的 [檢閱 + 建立]** 索引標籤上，檢閱您在先前步驟所選取的選項。

6. 選取 [建立]，使用您指定的設定來建立 Azure Cosmos DB 帳戶。

   注意：等候建立工作完成，再繼續進行實驗。

7. 選取 [前往資源] 。

8. 在 [Azure Cosmos DB 帳戶]** 窗格上尋找 [設定]** 區段，然後選取 [金鑰]** 連結。

9. 在 [索引鍵]** 窗格的 [讀寫索引鍵]** 索引標籤上，將 [URI]**、[主要索引鍵]** 和 [主要連接字串]** 文字輸入框的值記錄到記事本中。 您會在稍後的實驗中用到這些值。

   注意：您需要使用眼睛圖示來顯示主索引鍵和主要連接字串，這樣才能將它們複製到剪貼簿中。

工作 3：建立 Azure 儲存體帳戶資源

1. 在 Azure 入口網站中，使用 [搜尋資源、服務和文件] 文字輸入框，搜尋儲存體帳戶，然後在結果清單中選取 [儲存體帳戶]。

2. 在 [儲存體帳戶] 刀鋒視窗上，選取 [+ 建立]。

3. 在 [建立儲存體帳戶] 刀鋒視窗的 [基本] 索引標籤上，執行下列動作，然後選取 [檢閱]：

   設定	動作
   [訂閱] 清單	保留預設值
   [資源群組] 區段	選取 PolyglotData
   [儲存體帳戶名稱] 文字輸入框	輸入 polystor [您的名稱]
   [區域] 下拉式清單	選取您稍早在此練習中建立 Cosmos DB 帳戶的相同區域
   主要服務	無變更
   [效能] 區段	選取 [標準]
   [備援] 下拉式清單	選取 [本地備援儲存體 (LRS)]

   下列螢幕擷取畫面顯示 [建立儲存體帳戶] 窗格上的設定。

   

4. 在 [建立儲存體帳戶] 刀鋒視窗的 [檢閱] 索引標籤上，檢閱您在先前步驟所選取的選項。

5. 選取 [建立]，使用您指定的設定來建立儲存體帳戶。

   注意：等候建立工作完成，再繼續進行實驗。

檢閱

在此練習中，您建立了將在此實驗實作的多語言資料解決方案所需的 Azure 資源。 您所建立的 Azure 資源包括 Azure Cosmos DB 帳戶和 Azure 儲存體帳戶。

練習 2：檢閱並上傳資料

工作 1：將影像上傳到 Azure Blob 儲存體

1. 在 Azure 入口網站的瀏覽窗格中，瀏覽回 [儲存體帳戶] 窗格，然後選取您在此實驗上一個練習中建立的 polystor[您的名稱] 儲存體帳戶。

2. 在 [polystor[您的名稱]] 儲存體帳戶窗格上，選取 [資料儲存體] 區段中的 [容器] 連結。

3. 在 [容器] 區段中選取 [+ 容器]。

4. 在 [新增容器] 快顯視窗中執行下列動作，然後選取 [建立]：

   設定	動作
   [名稱] 文字輸入框	輸入 images

5. 回到 [容器]** 區段中，瀏覽至新建立的 **images 容器。

6. 在 [容器] 窗格上尋找 [設定] 區段，然後選取 [屬性] 連結。

7. 在 [屬性]** 窗格中，記下 **URL 文字輸入框中的值並將其記錄到記事本中。 您會在稍後的實驗中用到此值。

8. 接下來按一下 [共用存取權杖]**，並透過按一下 [產生 SAS 權杖和 URL]** 來產生具有預設設定的存取權杖。 將 Blob SAS 權杖的值記錄到記事本中，稍後您將需要它。

   注意：在記事本中您現在應該有 5 個值。 用於您的 Cosmos DB 帳戶的 URI、主要索引鍵和主要連接字串。 然後是用於您的 Blob 容器的 URL 和 SAS 權杖。

9. 尋找並選取窗格上的 [概觀] 連結。

10. 在窗格上選取 [上傳]。

11. 在 [上傳 Blob] 快顯中執行下列動作：

    a. 在 [檔案] 區段中，選取 [瀏覽檔案] 或使用拖放功能。

    b. 在 [檔案總管] 視窗中，瀏覽至 Allfiles (F):\Allfiles\Labs\04\Starter\Images，選取所有 42 個的個別 .jpg 影像檔，然後選取 [開啟]。

    c. 確定已選取 [如果檔案已經存在，則將其覆寫]，然後選取 [上傳]。

    注意：等候所有 Blob 上傳後，再繼續進行實驗。

工作 2：檢閱 JSON 資料

1. 從實驗用的電腦啟動 Visual Studio Code。

2. 從 [檔案] 功能表中選取 [開啟檔案]，瀏覽至 Allfiles (F):\Allfiles\Labs\04\Starter\AdventureWorks\AdventureWorks.Upload，選取 models.json，然後選取 [開啟]。

3. 檢閱 models.json 檔案的格式，並請注意該檔案包含 JSON 物件的陣列，以及屬於產品屬性的物件巢狀陣列。

   注意：這會決定您在將 JSON 檔案上傳至 Cosmos DB 集合之前，要定義哪些類別來將 JSON 檔案的內容還原序列化。

4. 請注意，在 models.json 檔案中，其中一個屬性名為 Category。

   注意：您將使用 Category 屬性來定義目標 Cosmos DB 集合的資料分割。

5. 關閉 Visual Studio Code。

工作 3：建立 Cosmos DB 資料庫和集合，並執行 JSON 資料上傳

1. 在 [開始] 畫面上選取 [Visual Studio Code] 圖格。

2. 從 [檔案] 功能表選取 [開啟資料夾]。

3. 在開啟的 [檔案總管] 視窗中，瀏覽至 Allfiles (F):\Allfiles\Labs\04\Starter\AdventureWorks，然後選取 [選取資料夾]。

4. 在 [Visual Studio Code] 視窗的 [功能表列] 上選取 [終端]，然後選取 [新增終端]。

5. 在終端中，確認目前目錄已設為 AdventureWorks (若尚未設定請進行變更)，然後執行下列命令以將終端內容切換為 AdventureWorks.Upload 資料夾：

   cd .\AdventureWorks.Upload\
   

   注意：執行下一個步驟之前，請開啟 [Windows 檔案總管]，然後從 Allfiles (F):\Allfiles\Labs\04\Starter\AdventureWorks\AdventureWorks.Upload\AdventureWorks.Upload.csproj 檔案中移除 [唯讀] 屬性

6. 從終端提示中執行下列命令，將 Azure Cosmos DB .NET 用戶端程式庫新增至目前開啟的專案：

   注意：在繼續進行下列命令之前，請確定您目前位於以下路徑：(F):\Allfiles\Labs\04\Starter\AdventureWorks\AdventureWorks.Upload\

   dotnet add package Microsoft.Azure.Cosmos --version 3.28.0
   

   注意：dotnet add package 命令會從 NuGet 新增 Microsoft.Azure.Cosmos 封裝。 如需詳細資訊，請參閱 Microsoft.Azure.Cosmos。

7. 觀察列印在終端中的組建結果。 組建應在沒有錯誤或警告訊息的情況下成功完成。

8. 在 [Visual Studio Code]** 視窗的 [Explorer]** 窗格中展開 AdventureWorks.Upload 專案。

9. 開啟 Program.cs 檔案。

10. 在 Program.cs 檔案中檢閱 using 指示詞，請注意，這其中包含 Microsoft.Azure.Cosmos、System.IO; 、System.Text.Json、System.Threading.Tasks 和 System.Collections.Generic。 這可讓您將 JSON 項目從實驗用電腦的本機檔案以非同步方式上傳至 Cosmos DB 資料庫中的集合。

11. 在 Program.cs 檔案的第 14 行中，將空白字串取代成您稍早在本實驗中記錄的 Cosmos DB 帳戶的 URI 屬性，以設定 EndpointUrl 的值。 請務必將該值括在雙引號中。 這是您在記事本中記錄的第一個值。

12. 在第 15 行中，將空白字串取代成您稍早在本實驗記錄的 Cosmos DB 帳戶的 PRIMARY KEY 屬性，以設定 AuthorizationKey 的值。 請務必將該值括在雙引號中。 這是您在記事本中記錄的第二個值。

13. 在第 18 行中，將空白字串取代成 “/Category” 以設定 PartitionKey 的值。

14. 在第 19 行中，將空白字串取代成 “F:\\Allfiles\\Labs\\04\\Starter\\AdventureWorks\\AdventureWorks.Upload\\models.json” ，以設定 JsonFilePath 的值。

15. 在 try 區塊內，請注意 CosmosClient 類別的 CreateDatabaseIfNotExistsAsync 方法的引動過程。 若資料庫不存在，則此過程會予以建立。

16. 請注意Database類別的 DefineContainer 方法的引動過程。 若容器不存在，則此過程會建立可裝載 JSON 項目的容器。

    注意：DefineContainer 方法包含成本最小化的選項，可讓您修改預設的索引編制原則 (自動編制所有屬性的索引)。

17. 請注意，using 陳述式使用 StreamReader 物件從文字檔讀取 JSON 項目，並將其還原序列化為 Program.cs 檔案中進一步定義的 Model 類別物件。

18. 請注意 ForEach 迴圈，該迴圈會逐一查看已還原序列化的物件集合，並以非同步方式將各個物件插入目標集合中。

19. 檢閱Model和Product類別，該類別可反映您稍早在本實驗中檢閱的 JSON 格式檔案中儲存的物件格式。

20. 儲存並關閉 Program.cs 檔案。

    注意：如果您收到檔案為唯讀的提示，請選取 [覆寫]。

21. 在終端中，執行下列命令來還原任何遺漏的 NuGet 套件，並在資料夾中組建專案：

    dotnet build
    

    注意：dotnet build 命令會在組建資料夾中的所有專案之前，自動還原任何遺漏的 NuGet 套件。

22. 從終端提示執行下列命令，即可執行 .NET Core 主控台應用程式：

    dotnet run
    

    注意：dotnet run 命令會自動組建專案上的任何變更，然後在未附加偵錯工具的情況下啟動 Web 應用程式。 此命令會輸出指示資料載入進度的訊息，包括插入目標集合的項目數量，以及插入作業的所需時長。

23. 執行列印在終端中的命令並觀察其結果。 執行應該會順利完成，並顯示將 119 個項目插入目標 Cosmos DB 集合中的訊息。

24. 選取 [終止終端] (資源回收筒圖示)，關閉終端窗格和任何相關的程序。

工作 4：驗證 JSON 資料上傳

1. 在您的實驗用電腦上，切換至顯示 Azure 入口網站的 Microsoft Edge 瀏覽器視窗。

2. 在 Azure 入口網站中，選取 [搜尋資源、服務和文件] 文字輸入框，在 [最近的資源] 清單中，選取您稍早在此實驗室中建立的 polycosmos[您的名稱] Azure Cosmos DB 帳戶。

3. 在 [Azure Cosmos DB 帳戶]** 窗格上尋找並選取窗格上的 [資料總管]** 連結。

4. 在 [資料總管] 窗格中展開 [零售] 資料庫節點。

5. 展開 [線上] 容器節點，然後選取 [新增 SQL 查詢]。

   注意：此選項的標籤可能是隱藏的。 您可以將滑鼠游標暫留在 [資料總管] 窗格中的圖示上，以顯示標籤。

6. 在 [查詢] 索引標籤上，輸入下列文字：

   SELECT * FROM models
   

7. 選取 [執行查詢]，然後觀察查詢所傳回的 JSON 項目清單。

8. 回到查詢編輯器，以下列文字取代現有的文字：

   SELECT VALUE COUNT(1) FROM models
   

9. 選取 [執行查詢]，然後觀察 COUNT 彙總作業的結果。 它應該輸出 119，其符合插入的項目數。

10. 切換回 Visual Studio Code 視窗。

檢閱

在此練習中，您使用了適用於 Azure Cosmos DB 的 .NET SDK 將資料插入 Azure Cosmos DB。 您接下來實作的 Web 應用程式將會使用此資料。

練習 3：設定 .NET Web 應用程式

工作 1：更新資料存放區的參考並組建 Web 應用程式

1. 在 [Visual Studio Code]** 視窗的 [Explorer]** 窗格中展開 AdventureWorks.Web 專案。

2. 開啟 appsettings.json 檔案。

3. 在 JSON 物件的第 3 行中尋找 ConnectionStrings.AdventureWorksCosmosCoNtext 路徑。 請注意，目前的值是空白的：

   "ConnectionStrings": {
       "AdventureWorksCosmosContext": "",
   },
   

4. 更新 AdventureWorksCosmosCoNtext 屬性的值，將其設為您稍早在此實驗室中記錄的 Azure Cosmos DB 帳戶的主要連接字串。 這是您在記事本中記錄的第三個值。

5. 在 JSON 物件的第 6 行中尋找 Settings.BlobContainerUrl 屬性。 請注意，目前的值是空白的：

   "Settings": {
       "BlobContainerUrl": "",
       "BlobSASToken": ""
   }
   

6. 透過將 BlobContainerUrl 和 BlobSASToken 屬性的值設定為名為 images 的 Azure 儲存體 Blob 容器的 URL 屬性以及您稍早在本實驗中相應記錄的 Blob SAS 權杖值來更新它們的屬性。 這是您在記事本中記錄的第四個和第五個值。

7. 儲存 appsettings.json 檔案並將其關閉。

   注意：如果您收到檔案為唯讀的提示，請選取 [覆寫]。

8. 在 [Visual Studio Code]** 視窗中，以滑鼠右鍵按一下檔案總管窗格中的 **AdventureWorks.Context 資料夾，然後選取 [在整合式終端機中開啟]**。

   

   注意：在您執行下一個步驟之前，請開啟 Windows 檔案總管，然後從 Allfiles (F):\Allfiles\Labs\04\Starter\AdventureWorks\AdventureWorks.Context\AdventureWorks.Context.csproj 檔案中移除唯讀屬性

9. 從終端提示中，確認目前目錄已設為 AdventureWorks.CoNtext (若尚未設定請進行變更)，然後執行下列命令以從 NuGet 匯入 Microsoft.Azure.Cosmos：

   注意：在繼續進行下列命令之前，請確定您目前位於以下路徑：(F):\Allfiles\Labs\04\Starter\AdventureWorks\AdventureWorks.Context\

   dotnet add package Microsoft.Azure.Cosmos --version 3.28.0
   

10. 從終端機提示字元中，執行以下命令來建置 AdventureWorks.Context 專案：

    dotnet build
    

11. 觀察列印在終端中的組建結果。 組建應在沒有錯誤或警告訊息的情況下成功完成。

工作 2：設定 Azure Cosmos DB 的連線能力

1. 在 [Visual Studio Code]** 視窗的 [Explorer]** 窗格中，展開 AdventureWorks.Context 專案。

2. 從 AdventureWorks.Context 資料夾節點的捷徑功能表中選取 [新增檔案]。

3. 在新的檔案提示中輸入 AdventureWorksCosmosCoNtext.cs。

4. 從 AdventureWorksCosmosContext.cs 檔案的程式碼編輯器索引標籤中，新增下列程式碼：

   using AdventureWorks.Models;
   using Microsoft.Azure.Cosmos;
   using Microsoft.Azure.Cosmos.Linq;
   using System;
   using System.Collections.Generic;
   using System.Linq;
   using System.Threading.Tasks;
   
   namespace AdventureWorks.Context
   {
       /* AdventureWorksCosmosContext class will implement the
       IAdventureWorksProductContext interface */
      public class AdventureWorksCosmosContext : IAdventureWorksProductContext
      {
           /* Create a new read-only Container variable named _container */
           private readonly Container _container;
   
         public AdventureWorksCosmosContext(string connectionString, string database = "Retail", string container = "Online")
         {
           /* Create a new instance of the CosmosClient class, and then obtain
             both a Database and Container instance from the client */
           _container = new CosmosClient(connectionString)
           .GetDatabase(database)
           .GetContainer(container);
         }
   
         public async Task<Model> FindModelAsync(Guid id)
         {
           /* Create a LINQ query, transform it into an iterator, iterate over the result set,
              and then return the single item in the result set */
           var iterator = _container.GetItemLinqQueryable<Model>()
           .Where(m => m.id == id).ToFeedIterator<Model>();
           List<Model> matches = new List<Model>();
           while (iterator.HasMoreResults)
           {
               var next = await iterator.ReadNextAsync();
               matches.AddRange(next);
           }
   
           return matches.SingleOrDefault();
         }
   
         public async Task<List<Model>> GetModelsAsync()
         {
           /* Run an SQL query, get the query result iterator, iterate over the result set,
               and then return the union of all results */
           string query = $@"SELECT * FROM items";
           var iterator = _container.GetItemQueryIterator<Model>(query);
           List<Model> matches = new List<Model>();
           while (iterator.HasMoreResults)
           {
               var next = await iterator.ReadNextAsync();
               matches.AddRange(next);
           }
   
           return matches;
         }
   
         public async Task<Product> FindProductAsync(Guid id)
         {
           /* Run an SQL query, get the query result iterator, iterate over the result set,
              and then return the single item in the result set */
           string query = $@"SELECT VALUE products
                       FROM models
                       JOIN products in models.Products
                       WHERE products.id = '{id}'";
           var iterator = _container.GetItemQueryIterator<Product>(query);
           List<Product> matches = new List<Product>();
           while (iterator.HasMoreResults)
           {
               var next = await iterator.ReadNextAsync();
               matches.AddRange(next);
           }
   
           return matches.SingleOrDefault();
         }
   
      }
   }
   

5. 儲存並關閉 AdventureWorksCosmosContext.cs 檔案。

6. 從終端提示中將目前目錄設為 AdventureWorks.Context，並執行下列命令來組建 .NET Web 應用程式：

   dotnet build
   

   注意：如果有任何建置錯誤，請檢閱 AdventureWorksCosmosContext.cs file in the Allfiles > (F):\Allfiles\Labs\04\Solution\AdventureWorks\AdventureWorks.Context 資料夾。

工作 3：檢閱 .NET 應用程式啟動邏輯

1. 在 [Visual Studio Code]** 視窗的 [Explorer]** 窗格中展開 AdventureWorks.Web 專案。

2. 開啟 Startup.cs 檔案。

3. 在 Startup 類別中，注意現有的 ConfigureProductService 方法：

   public void ConfigureProductService(IServiceCollection services)
   {
       services.AddScoped<IAdventureWorksProductContext, AdventureWorksCosmosContext>(provider =>
           new AdventureWorksCosmosContext(
               _configuration.GetConnectionString(nameof(AdventureWorksCosmosContext))
           )
       );
   }
   

   注意：產品服務會使用 Cosmos DB 作為其資料庫。

4. 在不進行任何修改的情況下關閉 Startup.cs 檔案。

工作 4：驗證 .NET 應用程式是否成功連線到資料存放區

1. 從 Visual Studio Code 的終端提示執行下列命令，將您的終端內容切換至 AdventureWorks.Web 資料夾：

   cd ..\AdventureWorks.Web\
   

2. 從終端提示執行下列命令，以執行 ASP.NET Web 應用程式：

   注意：在繼續進行下列命令之前，請確定您目前位於以下路徑：(F):\Allfiles\Labs\04\Starter\AdventureWorks\AdventureWorks.Web\

   dotnet run
   

   注意：dotnet run 命令會自動組建專案上的任何變更，然後在未附加偵錯工具的情況下啟動 Web 應用程式。 此命令會輸出執行中應用程式的 URL 和任何指派的連接埠。

3. 在工作列上，選取 Microsoft Edge 圖示。

4. 在開啟的瀏覽器視窗中，瀏覽至目前執行的 Web 應用程式 (http://localhost:5000)。

5. 在 Web 應用程式中，觀察從首頁顯示的型號清單。

6. 尋找 Touring-1000 型號，然後選取 [檢視詳細資料]。

7. 在 Touring-1000 產品詳細資料頁面上，檢閱選項清單。

8. 關閉顯示 Web 應用程式的瀏覽器視窗。

9. 切換至 [Visual Studio Code] 視窗，然後選取 [終止終端] (資源回收筒圖示) 以關閉目前開啟的終端和任何相關的程序。

檢閱

在此練習中，您撰寫了 C# 程式碼，以使用 .NET SDK 查詢 Azure Cosmos DB 集合。