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

發行項
05/17/2024

適用於：Azure SQL 資料庫

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

必要條件

Azure 訂用帳戶。
設定使用 Microsoft Entra ID (先前稱為 Azure Active Directory) 進行驗證的 SQL Database。您可以使用建立資料庫快速入門建立資料庫。
.NET 7.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 資料庫：

針對本機開發連線，請確定您的邏輯伺服器已設定為允許本機電腦 IP 位址及其他 Azure 服務連線：
- 瀏覽至伺服器的 [網路] 頁面。
- 切換 [選取的網路]選項按鈕以顯示其他組態選項。
- 選取 [新增用戶端 IPv4 位址 (xx.xx.xx.xx)]，以新增防火牆規則，啟用來自本機電腦 IPv4 位址的連線。或者您也可以選取 [+ 新增防火牆規則] 來輸入您選擇的特定 IP 位址。
- 確定選取 [允許 Azure 服務和資源存取此伺服器] 核取方塊。
  警告
  
  對於實際執行場景，出於安全考量，不建議啟用 [允許 Azure 服務和資源存取此伺服器] 設定。實際應用程式應該實作更安全的方法，例如更強大的防火牆限制或虛擬網路設定。
  
  可以存取下列資源，深入了解資料庫安全設定：
  - 設定 Azure SQL 資料庫防火牆規則。
  - 設定具有私人端點的虛擬網路。
伺服器也必須啟用 Microsoft Entra 驗證，並已指派 Microsoft Entra 管理帳戶。針對本機開發連線，Microsoft Entra 管理帳戶應該也可以用於本機登入 Visual Studio 或 Azure CLI 的帳戶。您可以在邏輯伺服器的 [Microsoft Entra ID] 頁面確認伺服器是否已啟用 Microsoft Entra 驗證。
如果您使用個人 Azure 帳戶，請確定您已針對 Azure SQL 資料庫設定 Microsoft Entra，將您的帳戶指派為伺服器管理員。如果您使用公司帳戶，很可能已為您設定好 Microsoft Entra ID。

建立專案

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

Visual Studio
.NET CLI

在 Visual Studio 功能表列中，瀏覽至 [檔案]>[新增]>[專案..]。
在對話方塊視窗的專案範本搜尋方塊中輸入 ASP.NET，然後選取 ASP.NET Core Web API 結果。在對話方塊底部選擇 [下一步]。
針對 [專案名稱]，請輸入 DotNetSQL。其餘欄位保持預設值，然後選取 [下一步]。
針對 [架構]，選取 [.NET 7.0]，然後取消核取 [使用控制器 (取消核取以使用 Minimal API)]。本快速入門使用 Minimal API 範本來簡化建立和設定端點的作業。
選擇 [建立] 。 Visual Studio 環境內將會開啟新的專案。

在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 DotNetSQL 的全新 Web API 應用程式。此命令會建立簡單的 "Hello World" C# 專案，內含單一原始程式檔：Program.cs。
```
dotnet new web -o DotNetSQL
```
瀏覽至新建立的 DotNetSQL 目錄，然後在 Visual Studio 中開啟專案。

將 Entity Framework Core 新增至專案中

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

Visual Studio
.NET CLI

在 [方案總管] 視窗中，以滑鼠右鍵按一下專案的 [相依性] 節點，然後選取 [管理 NuGet 套件]。
在產生的視窗中，搜尋 EntityFrameworkCore。找出並安裝下列套件：

Microsoft.EntityFrameworkCore：提供基本的 Entity Framework Core 功能
Microsoft.EntityFrameworkCore.SqlServer：提供連線到邏輯伺服器的額外元件
Microsoft.EntityFrameworkCore.Design：提供執行 Entity Framework 移轉的支援
Microsoft.EntityFrameworkCore.Tools：提供 Visual Studio 封裝管理員控制台工具的支援（僅限 PowerShell）

或者，您也可以在 [套件管理員主控台]Install-Package 視窗中執行 Cmdlet：

Install-Package Microsoft.EntityFrameworkCore
Install-Package Microsoft.EntityFrameworkCore.SqlServer
Install-Package Microsoft.EntityFrameworkCore.Design
Install-Package Microsoft.EntityFrameworkCore.Tools

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

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

新增程式碼以連線至 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 資料庫：

將 ConnectionStrings 區段新增至 appsettings.Development.json 檔案，使其符合下列程式碼。請記得更新 <your database-server-name> 和 <your-database-name> 預留位置。

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

注意

無密碼連接字串可安全地提交至原始程式碼控制，因為其中不包含任何祕密，例如使用者名稱、密碼或存取金鑰。
```
{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "ConnectionStrings": {
        "AZURE_SQL_CONNECTIONSTRING": "Data Source=passwordlessdbserver.database.windows.net;
            Initial Catalog=passwordlessdb; Authentication=Active Directory Default; Encrypt=True;"
    }
}
```

將下列程式碼新增至讀取 Program.cs 程式碼上方的 var app = builder.Build(); 檔案。此段程式碼會執行下列工作：

從 appsettings.Development.json 檔案中擷取無密碼資料庫連接字串以進行本機開發，或從裝載生產案例的環境變數中進行擷取。

向 .NET 相依性插入容器註冊 Entity Framework Core DbContext 類別。

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));

將下列端點新增至上述 app.Run() 上方的 Program.cs 檔案底部，使用 PersonDbContext 類別擷取並新增資料庫的實體。

app.MapGet("/Person", (PersonDbContext context) =>
{
    return context.Person.ToList();
})
.WithName("GetPersons")
.WithOpenApi();

app.MapPost("/Person", (Person person, PersonDbContext context) =>
{
    context.Add(person);
    context.SaveChanges();
})
.WithName("CreatePerson")
.WithOpenApi();

最後，將 Person 和 PersonDbContext 類別新增至 Program.cs 檔案的底部。 Person 類別代表資料庫 Persons 資料表中的單一記錄。類別 PersonDbContext 代表 Person 資料庫，並可讓您透過程式碼針對此資料庫執行作業。您可以在 Entity Framework Core 的使用者入門文件中深入了解 DbContext。

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; }
}

執行移轉以建立資料庫

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

在您的專案根目錄下開啟終端視窗。
執行下列命令來產生可建立資料庫的初始移轉：
- Visual Studio
- .NET CLI
```
Add-Migration InitialCreate
```
```
dotnet ef migrations add InitialCreate
```
Migrations資料夾應該會出現在您的專案目錄中，以及前面加上數字的 InitialCreate 檔案。執行移轉，以使用下列命令建立資料庫：
- Visual Studio
- .NET CLI
```
Update-Database
```
```
dotnet ef database update
```
Entity Framework Core 工具會在 PersonDbContext 類別所定義的 Azure 中建立資料庫架構。

在本機測試應用程式

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

按下 Visual Studio 頂端的 [執行] 按鈕以啟動 API 專案。
在 Swagger UI 頁面上，展開 POST 方法，然後選取 [試用]。
修改範例 JSON 以包含名字和姓氏的值。選取 [執行] 以將新記錄新增至資料庫。 API 會傳回成功的回應。
在 Swagger UI 頁面上，展開 GET 方法，然後選取 [試用]。選取 [執行]，隨即傳回您剛才建立的人員。

部署到 Azure App Service

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

請確定應用程式已停止並成功建置。
在 Visual Studio 的 [方案總管] 視窗中，以滑鼠右鍵按一下最上層專案節點，然後選取 [發佈]。
在發佈對話方塊中，選取 [Azure] 作為部署目標，然後選取 [下一步]。
針對特定目標，選取 [Azure App Service (Windows)]，然後選取 [下一步]。
選取綠色 + 圖示以建立要部署全新 App Service，並輸入下列值：
- 名稱：保留預設值。
- 訂用帳戶名稱：選取要部署的訂用帳戶。
- 資源群組：選取 [新增] 並建立名為 msdocs-dotnet-sql 的新資源群組。
- 主控方案：選取 [新增] 以開啟 [主控方案] 對話方塊。保留預設值，然後選取 [確定]。
- 選取 [建立] 以關閉原始對話方塊。 Visual Studio 會在 Azure 中建立 App Service 資源。
建立資源之後，請確定已在應用程式服務清單中選取該資源，然後選取 [下一步]。
在 [API 管理]步驟上，勾選底部的 [略過此步驟] 核取方塊，然後選取 [完成]。
在發行設定檔摘要的右上方選取 [發佈]，以將應用程式部署至 Azure。

部署完成時，Visual Studio 會啟動瀏覽器來顯示託管的應用程式，但此時應用程式無法在 Azure 上正常運作。您仍然需要設定 App Service 與 SQL Database 之間的安全連線，才可擷取您的資料。

將 App Service 連線到 Azure SQL 資料庫

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

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

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

服務連接器 (建議)
Azure 入口網站

服務連接器是一種工具，可簡化 Azure 中不同服務之間的已驗證連線。服務連接器目前支援使用 az webapp connection create sql 命令，透過 Azure CLI 將 App Service 與 SQL Database 建立連線。這個單一命令會為您完成上述的三個步驟。

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 設定上確認服務連接器所做的變更。

瀏覽至 App Service 的 [身分識別] 頁面。在 [系統指派] 索引標籤下，[狀態] 應設定為 [開啟]。此值表示您的應用程式已啟用系統指派的受控識別。
瀏覽至 App Service 的 [組態] 頁面。在 [連接字串] 索引標籤下，您應該會看到名為 AZURE_SQL_CONNECTIONSTRING 的連接字串。選取 [按一下以顯示值] 文字，檢視產生的無密碼連接字串。此連接字串的名稱會與您在應用程式中設定的名稱一致，因此會在 Azure 中執行時自動探索該名稱。

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

建立受控識別

在 Azure 入口網站中，瀏覽至您的 App Service，然後選取左側導覽上的 [身分識別]。
在身分識別頁面上，確定已啟用 [啟用系統指派的受控識別] 選項。啟用此設定時，系統會使用與 App Service 相同的名稱建立系統指派的受控識別。系統指派的身分識別會系結至服務執行個體，並在刪除應用程式時與應用程式一起終結。

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

在 Azure 入口網站中，瀏覽至您的 SQL 資料庫，然後選取 [查詢編輯器 (預覽)]。
選取畫面右側的 **[以 <your-username> 的身分繼續]，使用您的帳戶登入資料庫。
在查詢編輯器檢視上，執行下列 T-SQL 命令：
```
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 Database 使用者，以對應回 App Service 執行個體的受控識別。此指令碼也會將必要的 SQL 角色指派給使用者，以允許您的應用程式讀取、寫入和修改資料庫資料和架構。完成此步驟之後，您的服務隨即會連線。

重要

雖然此解決方案提供簡單的入門方法，但並非企業生產環境的最佳做法。在這些案例中，應用程式不應該使用單一提升權限的身分識別來執行所有作業。您應該針對特定工作設定具特定權限的多個身分識別，來實作最低權限的原則。

您可以在下列資源上深入了解如何設定資料庫角色和安全性：

教學課程：保護 Azure SQL 資料庫中的資料庫

授權資料庫存取 SQL Database

測試已部署的應用程式

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

您在本機建立的人員應該會顯示在瀏覽器中。恭喜！您的應用程式現在已與本機和託管環境中的 Azure SQL 資料庫建立連線。

清除資源

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

Azure 入口網站
Azure CLI

在 Azure 入口網站搜尋列中，搜尋 Azure SQL 並選取相符的結果。
在資料庫清單中找到並選取您的資料庫。
在 Azure SQL 資料庫的 [概觀] 頁面，選取 [刪除]。
在開啟的 Azure 您是否確定要刪除... 頁面，輸入資料庫的名稱以進行確認，然後選取 [刪除]。

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

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

共用方式為

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

必要條件

設定資料庫伺服器

建立專案

將 Entity Framework Core 新增至專案中

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

執行移轉以建立資料庫

在本機測試應用程式

部署到 Azure App Service

將 App Service 連線到 Azure SQL 資料庫

建立受控識別

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

測試已部署的應用程式

清除資源

意見反應

其他資源

共用方式為

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

必要條件

設定資料庫伺服器

建立專案

將 Entity Framework Core 新增至專案中

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

執行移轉以建立資料庫

在本機測試應用程式

部署到 Azure App Service

將 App Service 連線到 Azure SQL 資料庫

測試已部署的應用程式

清除資源

相關內容

意見反應

其他資源