你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 .NET 和 Microsoft.Data.SqlClient 库连接并查询 Azure SQL 数据库

  • 项目

适用于：Azure SQL 数据库

本快速入门教程介绍了如何使用 .NET 和 Microsoft.Data.SqlClient 库将应用程序连接到 Azure SQL 数据库中的数据库并执行查询。 本快速入门按照建议的无密码方法连接到数据库。 可以在无密码中心了解有关无密码连接的详细信息。

先决条件

配置数据库

要与 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 最小 Web API。

  1. 在 Visual Studio 菜单中，导航到“文件”>“新建”>“项目...”。

  2. 在对话框窗口中，在项目模板搜索框中输入“ASP.NET”，然后选择 ASP.NET Core Web API 结果。 选择对话框底部的“下一步”。

  3. 在“项目名称”处，输入“DotNetSQL”。 保留其余字段的默认值，然后选择“下一步”。

  4. 对于“框架”，选择“.NET 7.0”，并取消选中“使用控制器(取消选中以使用最小 API)。 本快速入门教程使用最小 API 模板来简化终结点的创建和配置过程。

  5. 选择“创建”。 此时新项目在 Visual Studio 环境中打开。

添加 Microsoft.Data.SqlClient 库

要使用 .NET 连接到 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 应用服务

应用已准备好部署到 Azure。 Visual Studio 可以创建 Azure 应用服务并在单个工作流中部署应用程序。

  1. 确保应用已停止运行并成功生成。

  2. 在 Visual Studio 的“解决方案资源管理器”窗口中，右键单击顶级项目节点，然后选择“发布”。

  3. 在发布对话框中，选择“Azure”作为部署目标，然后选择“下一步”。

  4. 对于特定目标，选择“Azure 应用服务(Windows)”，然后选择“下一步”。

  5. 选择 + 图标，创建要部署到的新应用服务，并输入以下值：

    • 名称：保留默认值。

    • 订阅名称：选择要部署到的订阅。

    • 资源组：选择“新建”，创建名为 msdocs-dotnet-sql 的新资源组。

    • 托管计划：选择“新建”，打开托管计划对话框。 保留默认值，并选择“确定”。

    • 选择“创建”以关闭原始对话框。 Visual Studio 会在 Azure 中创建应用服务资源。

      A screenshot showing how to deploy with Visual Studio.

  6. 创建资源后，确保在应用服务列表中选中它，然后选择“下一步”。

  7. 在“API 管理”步骤中，选中底部的“跳过此步骤”复选框，然后选择“完成”。

  8. 在“完成”步骤中，如果对话框未自动关闭，请选择“关闭”。

  9. 选择发布配置文件摘要右上角的“发布”，将应用部署到 Azure。

部署完成后，Visual Studio 会启动浏览器以显示托管的应用，但此时该应用在 Azure 上还无法正常工作。 你仍然需要在应用服务和 SQL 数据库之间配置安全连接，才能检索数据。

将应用服务连接到 Azure SQL 数据库

若要在应用服务实例和 Azure SQL 数据库之间创建无密码连接，需要执行以下步骤：

  1. 为应用服务创建托管标识。 应用中包含的 Microsoft.Data.SqlClient 库将自动发现托管标识，就像它发现本地 Visual Studio 用户一样。
  2. 创建 SQL 数据库用户，并将它与应用服务托管标识相关联。
  3. 将 SQL 角色分配给允许读取、写入以及可能的其他权限的数据库用户。

可以使用多种工具实现这些步骤：

服务连接器是一种工具，可简化 Azure 中不同服务之间经过身份验证的连接。 服务连接器目前支持通过 Azure CLI 使用 az webapp connection create sql 命令将应用服务连接到 SQL 数据库。 这个命令完成了上面提到的三个步骤。

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

可以验证服务连接器对应用服务设置所做的更改。

  1. 导航到应用服务的“标识”页。 在“系统分配”选项卡下，“状态”应设置为“开”。 此值表示已经为应用启用了系统分配的托管标识。

  2. 导航到应用服务的“配置”页。 在“连接字符串”选项卡下，应会看到名为“AZURE_SQL_CONNECTIONSTRING”的连接字符串。 选择“单击以显示值”文本，查看生成的无密码连接字符串。 此连接字符串的名称与你在应用中配置的名称一致，因此，在 Azure 中运行时可以自动发现它。

重要

尽管此解决方案提供了一种简单的入门方法，但它并不是适用于生产级环境的最佳做法。 在这些情况下，应用不应使用单个提升的标识执行所有操作。 你应尝试为特定任务配置具有特定权限的多个标识，实现最低特权原则。

若要详细了解如何配置数据库角色和安全性，可以阅读以下资源：

测试已部署的应用程序

  1. 选择“应用服务概述”页顶部的“浏览”按钮，启动应用的根 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 上随即打开“确定要删除...”页，键入数据库名称进行确认，然后选择“删除”。