連線至資料庫並使用 .NET 和 Microsoft.Data.SqlClient 程式庫查詢 Azure SQL 資料庫

  • 發行項

適用於：Azure SQL 資料庫

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

必要條件

設定資料庫

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

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

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

    • 切換 [選取的網路] 選項按鈕以顯示其他組態選項。

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

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

      A screenshot showing how to configure firewall rules.

      警告

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

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

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

    A screenshot showing how to enable Microsoft Entra authentication.

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

建立專案

後續步驟會使用 .NET CLI 或 Visual Studio 2022 建立 .NET Minimal Web API。

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

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

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

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

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

新增 Microsoft.Data.SqlClient 程式庫

若要使用 .NET (C#) 連線到 Azure SQL 資料庫，請安裝 Microsoft.Data.SqlClient。 此套件可作為資料提供者，用來連線到資料庫、執行命令，以及擷取結果。

注意

請務必安裝 Microsoft.Data.SqlClient 而非 System.Data.SqlClient。 Microsoft.Data.SqlClient 是較新版本的 SQL 用戶端程式庫，可提供額外的功能。

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

  2. 在產生的視窗中，搜尋 SqlClient。 找出 Microsoft.Data.SqlClient 結果，然後選取 [安裝]。

設定連接字串

對於透過 Azure SQL 資料庫的無密碼連線進行的本機開發，請將下列 ConnectionStrings 區段新增至 appsettings.json 檔案。 將 <database-server-name> 和 <database-name> 預留位置替換為您自己的值。

"ConnectionStrings": {
    "AZURE_SQL_CONNECTIONSTRING": "Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Authentication=\"Active Directory Default\";"
}

無密碼連接字串設定 Authentication="Active Directory Default" 的組態值，指示 Microsoft.Data.SqlClient 程式庫使用名為 DefaultAzureCredential 的類連線到 Azure SQL 資料庫。 DefaultAzureCredential 可啟用 Azure 服務的無密碼連線，並由 SQL 用戶端程式庫相依的 Azure 身分識別連結庫提供。 DefaultAzureCredential 支援多個驗證方法，並在執行階段判斷針對不同環境應使用的方法。

例如，當應用程式在本機執行時，DefaultAzureCredential 會透過登入 Visual Studio 的使用者或其他本機工具 (例如 Azure CLI) 進行驗證。 應用程式部署至 Azure 後，相同的程式碼會探索並套用與託管應用程式相關聯的受控識別，此項目您稍後會加以設定。 Azure 身分識別程式庫概觀會解釋 DefaultAzureCredential 尋找認證時的順序和位置。

注意

無密碼連接字串可安全地提交至原始檔控制，因為其中不包含祕密，例如使用者名稱、密碼或存取金鑰。

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

將 Program.cs 檔案的內容替換為下列程式碼，其會執行下列重要步驟：

  • 從 appsettings.json 擷取無密碼連接字串
  • 在啟動期間 (僅測試案例) 在資料庫中建立 Persons 資料表
  • 建立 HTTP GET 端點以擷取儲存在 Persons 資料表中的所有記錄
  • 建立 HTTP POST 端點以將新記錄新增至 Persons 資料表
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// For production scenarios, consider keeping Swagger configurations behind the environment check
// if (app.Environment.IsDevelopment())
// {
    app.UseSwagger();
    app.UseSwaggerUI();
// }

app.UseHttpsRedirection();

string connectionString = app.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING")!;

try
{
    // Table would be created ahead of time in production
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "CREATE TABLE Persons (ID int NOT NULL PRIMARY KEY IDENTITY, FirstName varchar(255), LastName varchar(255));",
        conn);
    using SqlDataReader reader = command.ExecuteReader();
}
catch (Exception e)
{
    // Table may already exist
    Console.WriteLine(e.Message);
}

app.MapGet("/Person", () => {
    var rows = new List<string>();

    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand("SELECT * FROM Persons", conn);
    using SqlDataReader reader = command.ExecuteReader();

    if (reader.HasRows)
    {
        while (reader.Read())
        {
            rows.Add($"{reader.GetInt32(0)}, {reader.GetString(1)}, {reader.GetString(2)}");
        }
    }

    return rows;
})
.WithName("GetPersons")
.WithOpenApi();

app.MapPost("/Person", (Person person) => {
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "INSERT INTO Persons (firstName, lastName) VALUES (@firstName, @lastName)",
        conn);

    command.Parameters.Clear();
    command.Parameters.AddWithValue("@firstName", person.FirstName);
    command.Parameters.AddWithValue("@lastName", person.LastName);

    using SqlDataReader reader = command.ExecuteReader();
})
.WithName("CreatePerson")
.WithOpenApi();

app.Run();

最後，將 Person 類別新增至 Program.cs 檔案的底部。 此類別代表資料庫 Persons 資料表中的單一記錄。

public class Person
{
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
}

在本機執行和測試應用程式

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

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

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

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

    A screenshot showing how to test the API.

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

部署到 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 資源。

      A screenshot showing how to deploy with Visual Studio.

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

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

  8. 在 [完成] 步驟中，如果對話方塊未自動關閉，請選取 [關閉]。

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

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

將 App Service 連線到 Azure SQL 資料庫

若要在 App Service 執行個體與 Azure SQL 資料庫之間建立無密碼連線，必須執行下列步驟：

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

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

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

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

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

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

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

重要

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

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

測試已部署的應用程式

  1. 選取 App Service 概觀頁面頂端的 [瀏覽] 按鈕，以啟動應用程式的根 URL。

  2. 將 /swagger/index.html 路徑附加至 URL，以載入您在本機使用的相同 Swagger 測試頁面。

  3. 執行測試 GET 和 POST 要求，以驗證端點是否如預期般運作。

提示

如果您在測試時收到 500 內部伺服器錯誤，可能是您的資料庫網路設定所致。 驗證您的邏輯伺服器是否已使用設定資料庫章節中概述的設定進行設定。

恭喜！ 您的應用程式現在已與本機和託管環境中的 Azure SQL 資料庫建立連線。

清除資源

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

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

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

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

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