使用 .NET 和 Entity Framework Core 連線至資料庫並查詢 Azure SQL 資料庫

適用於：Azure SQL 資料庫

本快速入門說明如何在 Azure SQL 資料庫中將應用程式連線到資料庫，並使用 .NET 和 Entity Framework Core 執行查詢。 本快速入門遵循建議的無密碼方法與資料庫連線。 您可以在無密碼中樞上深入了解無密碼連線。

必要條件

• Azure 訂用帳戶。
• 設定使用 Microsoft Entra ID (先前稱為 Azure Active Directory) 進行驗證的 SQL Database。 您可以使用 快速入門：建立單一資料庫 - Azure SQL Database 來建立一個資料庫。
• .NET 9.0 或更新版本。
• Visual Studio 或更新版，配備ASP.NET 和網頁程式開發工作負載。
• 最新版的 Azure CLI。
• 最新版的 Entity Framework Core 工具：
  • Visual Studio 使用者應該安裝 Entity Framework Core 的套件管理員主控台工具。
  • .NET CLI 使用者應安裝 Entity Framework Core 的 .NET CLI 工具。

設定資料庫伺服器

Azure SQL 資料庫的安全無密碼連線需要特定資料庫設定。 確認 Azure 中邏輯伺服器上的下列設定，以在本機和託管環境中正確連線到 Azure SQL 資料庫：

1. 針對本機開發連線，請確定您的邏輯伺服器已設定為允許本機電腦 IP 位址及其他 Azure 服務連線：

   • 瀏覽至伺服器的 [網路] 頁面。

   • 將 選取的網路 的選項按鈕切換為顯示更多設定選項。

   • 選取 [新增用戶端 IPv4 位址 (xx.xx.xx.xx)]，以新增防火牆規則，啟用來自本機電腦 IPv4 位址的連線。 或者您也可以選取 [+ 新增防火牆規則] 來輸入您選擇的特定 IP 位址。

   • 確定選取 [允許 Azure 服務和資源存取此伺服器] 核取方塊。

     

     警告

     對於實際執行場景，出於安全考量，不建議啟用 [允許 Azure 服務和資源存取此伺服器] 設定。 實際應用程式應該實作更安全的方法，例如更強大的防火牆限制或虛擬網路設定。

     可以存取下列資源，深入了解資料庫安全設定：

     • 設定 Azure SQL 資料庫防火牆規則。
     • 設定具有私人端點的虛擬網路。

2. 伺服器也必須啟用 Microsoft Entra 驗證，並已指派 Microsoft Entra 管理帳戶。 針對本機開發環境的連接，Microsoft Entra 管理員帳戶應該是一個您可以用來本機登入 Visual Studio 或 Azure CLI 的帳戶。 您可以在邏輯伺服器的 [Microsoft Entra ID] 頁面確認伺服器是否已啟用 Microsoft Entra 驗證。

   

3. 如果您使用個人 Azure 帳戶，請確定您已針對 Azure SQL 資料庫設定 Microsoft Entra，將您的帳戶指派為伺服器管理員。如果您使用公司帳戶，很可能已為您設定好 Microsoft Entra ID。

建立專案

本節中的步驟會使用 .NET CLI 或 Visual Studio 2022 建立 .NET Minimal Web API。

Visual Studio

1. 在 Visual Studio 功能表列中，瀏覽至 [檔案][新增]>[專案]。

2. 在對話方塊視窗的專案範本搜尋方塊中輸入 ASP.NET，然後選取 ASP.NET Core Web API 結果。 在對話方塊底部選擇 [下一步]。

3. 針對 [專案名稱]，請輸入 DotNetSQL。 其餘欄位保持預設值，然後選取 [下一步]。

4. 針對 [架構]，選取 [.NET 9.0]，然後取消核取 [ 使用控制器]。 本快速入門使用 Minimal API 範本來簡化建立和設定端點的作業。

5. 選擇 [建立] 。 Visual Studio 環境內將會開啟新的專案。

.NET CLI

1. 在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 DotNetSQL 的全新 Web API 應用程式。 此命令會建立簡單的 "Hello World" C# 專案，內含單一原始程式檔：Program.cs。

   dotnet new web -o DotNetSQL
   

2. 瀏覽至新建立的 DotNetSQL 目錄，然後在 Visual Studio 中開啟專案。

將 Entity Framework Core 新增至專案中

若要使用 .NET 和 Entity Framework Core 連線到 Azure SQL 資料庫，您需要使用下列其中一種方法，將三個 NuGet 套件新增至專案：

Visual Studio

1. 在 [方案總管] 視窗中，以滑鼠右鍵按一下專案的 [相依性] 節點，然後選取 [管理 NuGet 套件]。

2. 在產生的視窗中，搜尋 EntityFrameworkCore。 找出並安裝下列套件：

• Microsoft.EntityFrameworkCore：提供基本的 Entity Framework Core 功能
• Microsoft.EntityFrameworkCore.SqlServer：提供額外的元件以連線到邏輯伺服器
• Microsoft.EntityFrameworkCore.Design：提供執行 Entity Framework 移轉的支援
• Microsoft.EntityFrameworkCore.Tools：提供 Visual Studio 套件管理員控制台工具的支援（僅限 PowerShell）
• Swashbuckle.AspNetCore：選擇性 - 支援 SwaggerUI 與應用程式端點的互動

.NET CLI

使用 dotnet add package 命令安裝下列套件：

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Swashbuckle.AspNetCore

新增程式碼以連線至 Azure SQL 資料庫

Entity Framework Core 程式庫依賴 Microsoft.Data.SqlClient 和 Azure.Identity 程式庫來實作 Azure SQL 資料庫的無密碼連線。 此 Azure.Identity 程式庫提供稱為 DefaultAzureCredential 的類別，可處理 Azure 的無密碼驗證。

DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷應使用的方法。 此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法，而不需要實作環境特有的程式碼。 Azure 身分識別程式庫概觀會解釋 DefaultAzureCredential 尋找認證時的順序和位置。

完成下列步驟，使用 Entity Framework Core 和基礎 DefaultAzureCredential 類別連線到 Azure SQL 資料庫：

1. 將 ConnectionStrings 區段新增至 appsettings.Development.json 檔案，使其符合下列程式碼。 <server>.database.windows.net取代為您要連線的無密碼資料庫伺服器名稱，並以<database>資料庫名稱取代 。

   {
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning"
           }
       },
       "ConnectionStrings": {
           "AZURE_SQL_CONNECTIONSTRING": "Data Source=<server>.database.windows.net;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
       }
   }
   

   注意

   請記得更新 <your database-server-name> 資料庫連接字串中的和 <your-database-name> 佔位元。 無密碼連接字串可以安全地認可至原始檔控制，因為它們不包含任何秘密，例如使用者名稱、密碼或存取密鑰。

   無密碼連接字串包含 Authentication=Active Directory Default 的組態值，可讓 Entity Framework Core 使用 DefaultAzureCredential 連線到 Azure 服務。 當應用程式在本機執行時，會向您登入 Visual Studio 的使用者進行驗證。 應用程式部署至 Azure 之後，相同的程式代碼會探索並套用與您稍後設定之託管應用程式相關聯的受控識別。

2. 以下列程式碼來取代 Program.cs 檔案的內容：

   using Microsoft.AspNetCore.Mvc;
   using Microsoft.EntityFrameworkCore;
   
   var builder = WebApplication.CreateBuilder();
   
   builder.Services.AddOpenApi();
   
   var connection = String.Empty;
   if (builder.Environment.IsDevelopment())
   {
       builder.Configuration.AddEnvironmentVariables().AddJsonFile("appsettings.Development.json");
       connection = builder.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING");
   }
   else
   {
       connection = Environment.GetEnvironmentVariable("AZURE_SQL_CONNECTIONSTRING");
   }
   
   builder.Services.AddDbContext<PersonDbContext>(options =>
       options.UseSqlServer(connection));
   
   var app = builder.Build();
   
   if (app.Environment.IsDevelopment())
   {
       app.MapOpenApi();
       app.UseSwaggerUI(options =>
       {
           options.SwaggerEndpoint("/openapi/v1.json", "v1");
       });
   }
   
   app.MapGet("/", () => "Hello world!");
   
   app.MapGet("/Person", (PersonDbContext context) =>
   {
       return context.Person.ToList();
   });
   
   app.MapPost("/Person", (Person person, PersonDbContext context) =>
   {
       context.Add(person);
       context.SaveChanges();
   });
   
   app.Run();
   
   public class Person
   {
       public int Id { get; set; }
       public string FirstName { get; set; }
       public string LastName { get; set; }
   }
   
   public class PersonDbContext : DbContext
   {
       public PersonDbContext(DbContextOptions<PersonDbContext> options)
           : base(options)
       {
       }
   
       public DbSet<Person> Person { get; set; }
   }
   

   上述程式代碼會處理下列步驟：

   • 從 appsettings.Development.json 檔案中擷取無密碼資料庫連接字串以進行本機開發，或從裝載生產案例的環境變數中進行擷取。
   • 向 .NET 相依性插入容器註冊 Entity Framework Core DbContext 類別。 您可以在 Entity Framework Core 的DbContext文件中深入了解 。
   • 使用 SwaggerUI 設定 .NET 9.0 OpenAPI 支援，以提供可用來與應用程式端點和資料庫互動的 UI。
   • 新增端點以擷取和新增資料庫中的實體。
   • Person定義類別來代表資料庫數據表中的Persons單一記錄，以及PersonDbContext向 .NET 相依性插入容器註冊的類別。

執行移轉以建立資料庫

若要使用 Entity Framework Core 更新資料庫架構以符合您的資料模型，必須使用移轉。 移轉可以建立並以累加式更新資料庫架構，使其與應用程式的資料模型保持同步。 您可以在移轉概觀中深入了解此模式。

1. 在您的專案根目錄下開啟終端視窗。

2. 執行下列命令來產生可建立資料庫的初始移轉：

   Visual Studio

   Add-Migration InitialCreate
   

   .NET CLI

   dotnet ef migrations add InitialCreate
   

---

3. Migrations 資料夾應該會出現在您的專案目錄中，還有一個名為 InitialCreate 且前方加上獨特數字的檔案。 執行移轉以使用下列命令建立資料庫，而 Entity Framework Core 工具會在 類別所 PersonDbContext 定義的 Azure 中建立資料庫架構。

   Visual Studio

   Update-Database
   

   .NET CLI

   dotnet ef database update
   

---

在本機測試應用程式

應用程式已準備好在本機進行測試。 請確定您使用設定為資料庫管理員的相同帳戶登入 Visual Studio 或 Azure CLI。

1. 按下 Visual Studio 頂端的 [執行] 按鈕以啟動 API 專案。

2. 在 Swagger UI 頁面上，展開 POST 方法，然後選取 [試用]。

3. 修改範例 JSON 以包含名字和系列名稱的值。 選取 [執行] 以將新記錄新增至資料庫。 API 會傳回成功的回應。

   

4. GET展開 Swagger UI 頁面上的方法，然後選取 [試用]。 選取 [執行]，隨即傳回您剛才建立的人員。

部署到 Azure App Service

如此應用程式即已就緒，可開始部署至 Azure。 Visual Studio 可以建立 Azure App Service，並在單一工作流程中部署您的應用程式。

1. 請確定應用程式已停止並成功建置。

2. 在 Visual Studio 的 [方案總管] 視窗中，以滑鼠右鍵按一下最上層專案節點，然後選取 [發佈]。

3. 在發佈對話方塊中，選取 [Azure] 作為部署目標，然後選取 [下一步]。

4. 針對特定目標，選取 [Azure App Service (Windows)]，然後選取 [下一步]。

5. 選取綠色 + 圖示以建立要部署全新 App Service，並輸入下列值：

   • 名稱：保留預設值。
   • 訂用帳戶名稱：選取要部署的訂用帳戶。
   • 資源群組：選取 [新增] 並建立名為 msdocs-dotnet-sql 的新資源群組。
   • 主控方案：選取 [新增] 以開啟 [主控方案] 對話方塊。 保留預設值，然後選取 [確定]。
   • 選取建立以關閉原始對話方塊。 Visual Studio 會在 Azure 中建立 App Service 資源。

   

6. 建立資源之後，請確定您在應用程式服務清單中選取 ，然後選取 [ 下一步]。

7. 在 [API 管理]步驟上，勾選底部的 [略過此步驟] 核取方塊，然後選取 [完成]。

8. 在發行設定檔摘要的右上方選取 [發佈]，以將應用程式部署至 Azure。

部署完成時，Visual Studio 會啟動瀏覽器以顯示所裝載的應用程式。 您應該會看到 Hello world 來自預設端點的訊息。 不過，此時資料庫端點無法在 Azure 上正常運作。 您仍然需要設定 App Service 與 SQL Database 之間的安全連線，才可擷取您的資料。

將 App Service 連線到 Azure SQL 資料庫

若要將 App Service 執行個體連線至 Azure SQL 資料庫，必須執行下列步驟：

1. 建立應用服務的受管理身份識別。 應用程式中包含的連結 Microsoft.Data.SqlClient 庫會自動探索受控識別，就像探索到本機Visual Studio使用者一樣。
2. 建立 SQL Database 使用者，並將其與 App Service 受控識別關聯。
3. 將 SQL 角色指派給允許讀取、寫入和其他權限的資料庫使用者。

有多項工具可用來實作下列步驟：

服務連接器 (建議)

服務連接器是一種工具，可簡化 Azure 中不同服務之間的已驗證連線。 Service Connector 目前支援使用 Azure CLI 無密碼擴充功能將 App Service 連線到 SQL 資料庫。

1. 安裝或升級 Service Connector 無密碼擴充功能：

   az extension add --name serviceconnector-passwordless --upgrade
   

2. 執行 命令， az webapp connection create sql 以使用系統指派的受控識別，將 Web 應用程式連線到資料庫。 以適當的值取代佔位元：

   az webapp connection create sql
   -g <your-resource-group>
   -n <your-app-service-name>
   --tg <your-database-server-resource-group>
   --server <your-database-server-name>
   --database <your-database-name>
   --system-identity
   

您可以在 App Service 設定上確認服務連接器所做的變更。

1. 瀏覽至 App Service 的 [身分識別] 頁面。 在 [系統指派] 索引標籤下，[狀態] 應設定為 [開啟]。 此值表示您的應用程式已啟用系統指派的受控識別。

2. 導航到 App Service 的 [組態] 頁面。 在 [ 連接字串] 索引 標籤下，您應該會看到名為 AZURE_SQL_CONNECTIONSTRING的連接字串。 選取「按一下以顯示值」文字，檢視所生成的無密碼連線字串。 此連接字串的名稱會與您在應用程式中設定的名稱一致，因此會在 Azure 中執行時自動探索。

Azure 入口網站

Azure 入口網站可讓您使用受控識別，並針對 Azure SQL 資料庫執行查詢。 完成下列步驟，透過您的 App Service 執行個體與 Azure SQL 資料庫建立無密碼連線：

建立受控識別

1. 在 Azure 入口網站中，瀏覽至您的 App Service，然後選取左側導覽上的 [身分識別]。

2. 在身分識別頁面上，確定已啟用 [啟用系統指派的受控識別] 選項。 啟用此設定時，系統會使用與 App Service 相同的名稱建立系統指派的受控識別。 系統指派的身分識別會系結至服務執行個體，並在刪除應用程式時與應用程式一起終結。

建立資料庫使用者並指派角色

1. 在 Azure 入口網站中，瀏覽至您的 SQL 資料庫，然後選取 [查詢編輯器 (預覽)]。

2. 選取畫面右側的 **[以 <your-username> 的身分繼續]，使用您的帳戶登入資料庫。

3. 在查詢編輯器檢視上，執行下列 T-SQL 命令。 以您的應用程式服務名稱取代 <your-app-service-name> 。

   CREATE USER <your-app-service-name> FROM EXTERNAL PROVIDER;
   ALTER ROLE db_datareader ADD MEMBER <your-app-service-name>;
   ALTER ROLE db_datawriter ADD MEMBER <your-app-service-name>;
   ALTER ROLE db_ddladmin ADD MEMBER <your-app-service-name>;
   GO
   

   

   此 SQL 指令碼會建立一個 SQL 資料庫使用者，以便對應到您的 App Service 執行個體的管理身分識別。 此指令碼也會將必要的 SQL 角色指派給使用者，以允許您的應用程式讀取、寫入和修改資料庫資料和架構。 完成此步驟之後，您的服務隨即會連線。

重要

雖然此解決方案提供簡單的入門方法，但這不是企業生產環境的最佳做法。 在這些案例中，應用程式不應該使用單一提升許可權的身分識別來執行所有作業。 您應該針對特定工作設定具特定權限的多個身分識別，來實作最低權限的原則。 如需設定資料庫角色和安全性的詳細資訊，請參閱：

• 教學課程：保護 Azure SQL 資料庫中的資料庫
• 授權對 SQL 資料庫的存取

測試已部署的應用程式

瀏覽至應用程式的 URL，以測試與 Azure SQL 資料庫間的連線是否正常運作。 您可以在 App Service 概觀頁面上找到您應用程式的 URL。 將 /person 路徑附加至 URL 結尾，以瀏覽您在本機測試的相同端點。

您在本機建立的人物應該會顯示在瀏覽器裡。 恭喜您，您的應用程式現在已連線到本機和託管環境中的 Azure SQL Database。

清除資源

用完 Azure SQL 資料庫後，請刪除資源以避免非預期的成本。

Azure 入口網站

1. 在 Azure 入口網站搜尋列中，搜尋 Azure SQL 並選取相符的結果。

2. 在資料庫清單中找到並選取您的資料庫。

3. 在 Azure SQL 資料庫的 [概觀] 頁面，選取 [刪除]。

4. 在開啟的 Azure 您是否確定要刪除... 頁面，輸入資料庫的名稱以進行確認，然後選取 [刪除]。

Azure CLI

使用 az sql db delete 命令刪除資料庫。 將佔位符參數替換為您自己的值。

az sql db delete --name <database-name> --resource-group <resource-group-name> --server <logical-server-name>

注意

如果您將範例應用程式部署至 Azure，請務必同時搜尋並刪除 App Service 資源，以避免產生非預期的成本。

相關內容

• 教學課程：保護 Azure SQL 資料庫中的資料庫
• 將資料庫存取權限授與 SQL Database、SQL 受控執行個體和 Azure Synapse Analytics
• Azure SQL Database 和 SQL 受控實例安全性功能的概觀
• 使用 Azure SQL Database 和 Azure SQL 受控實例解決常見安全性需求的劇本