通过

使用 .NET 和 Entity Framework Core 连接并查询 Azure SQL 数据库

适用于：Azure SQL 数据库

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

先决条件

配置数据库服务器

要与 Azure SQL 数据库建立安全的无密码连接，需要特定的数据库配置。 确认 Azure 中的逻辑服务器上的以下设置，在本地和托管环境中正确连接到 Azure SQL 数据库：

  1. 对于本地开发连接，请确保逻辑服务器配置为允许本地计算机 IP 地址和其他 Azure 服务进行连接：

    • 导航到服务器的“网络”页。

    • 切换“所选网络”单选按钮以显示其他配置选项。

    • 选择“添加客户端 IPv4 地址(xx.xx.xx.xx)”以添加防火墙规则，这会启用来自本地计算机 IPv4 地址的连接。 或者，还可以选择“+ 添加防火墙规则”，输入所选的特定 IP 地址。

    • 确保选中“允许 Azure 服务和资源访问此服务器”复选框。

      显示如何配置防火墙规则的屏幕截图。

      警告

      对于生产方案，不建议启用“允许 Azure 服务和资源访问此服务器”设置。 实际应用程序应实现更安全的方法，例如更强的防火墙限制或虚拟网络配置。

      若要详细了解数据库安全配置，可以阅读以下资源：

  2. 还必须为服务器启用 Microsoft Entra 身份验证，并为其分配 Microsoft Entra 管理员帐户。 对于本地开发连接，Microsoft Entra 管理员帐户应该是你也可以在本地用于登录到 Visual Studio 或 Azure CLI 的帐户。 可以在逻辑服务器的“Microsoft Entra ID”页上验证是否为服务器启用了 Microsoft Entra 身份验证。

    显示如何启用 Microsoft Entra 身份验证的屏幕截图。

  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 9.0 并取消选中 “使用控制器”。 本快速入门教程使用最小 API 模板来简化终结点的创建和配置过程。

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

将 Entity Framework Core 添加到项目

要使用 .NET 和 Entity Framework Core 连接到 Azure SQL 数据库，需要使用以下方法之一将三个 NuGet 包添加到项目：

  1. 在“解决方案资源管理器”窗口中，右键单击项目的“依赖项”节点，然后选择“管理 NuGet 包”。

  2. 在出现的窗口中，搜索“EntityFrameworkCore”。 找到并安装以下包：

  • Microsoft.EntityFrameworkCore：提供基本的 Entity Framework Core 功能
  • Microsoft.EntityFrameworkCore.SqlServer：提供用于连接到逻辑服务器的额外组件
  • Microsoft.EntityFrameworkCore.Design：支持运行实体框架迁移
  • Microsoft.EntityFrameworkCore.Tools：提供对 Visual Studio 包管理器控制台工具的支持（仅限 PowerShell）
  • Swashbuckle.AspNetCore：可选 - 支持 SwaggerUI 与应用终结点的交互

添加代码以连接到 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 文件（用于本地开发）或环境变量（用于托管生产场景）中检索无密码数据库连接字符串。
    • 将 Entity Framework Core DbContext 类注册到 .NET 依赖关系注入容器。 可以在 Entity Framework Core 的DbContext文档中阅读有关 的详细信息。
    • 使用 SwaggerUI 配置 .NET 9.0 OpenAPI 支持，以提供可用于与应用终结点和数据库交互的 UI。
    • 添加终结点以检索和添加数据库中的实体。
    • 定义一个 Person 类来表示 Persons 数据库表中的单个记录，并且定义一个 PersonDbContext 类以注册到 .NET 依赖注入容器。

运行迁移以创建数据库

若要使用 Entity Framework Core 更新数据库架构以匹配数据模型，必须使用迁移。 迁移可以创建并以增量方式更新数据库架构，使其与应用程序的数据模型保持同步。 你可以在迁移概述中详细了解此模式。

  1. 打开项目根目录的终端窗口。

  2. 运行以下命令，生成可以创建数据库的初始迁移：

    Add-Migration InitialCreate

  1. 项目目录中应显示一个 Migrations 文件夹，以及一个前面附加了唯一编号的名为 InitialCreate 的文件。 使用以下命令运行迁移以创建数据库：

    Update-Database

Entity Framework Core 工具根据 PersonDbContext 类在 Azure 中创建数据库架构。

在本地测试应用

应用已准备好在本地进行测试。 请确保使用设置为数据库管理员的同一帐户登录到 Visual Studio 或 Azure CLI。

  1. 按下 Visual Studio 顶部的“运行”按钮，启动 API 项目。

  2. 在 Swagger UI 页上，展开 POST 方法并选择“试用”。

  3. 修改示例 JSON 以包含名字和家族名称的值。 选择“执行”，将新记录添加到数据库中。 API 返回成功的响应。

    显示如何测试 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 中创建应用服务资源。

      显示如何使用 Visual Studio 进行部署的屏幕截图。

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

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

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

部署完成后，Visual Studio 会启动浏览器来显示托管应用。 应该会看到来自默认端点的Hello world消息。 但是，此时数据库终结点在 Azure 上无法正常工作。 你仍然需要在应用服务和 SQL 数据库之间配置安全连接，才能检索数据。

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

若要将应用服务实例连接到 Azure SQL 数据库，需要执行以下步骤：

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

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

服务连接器是一种工具，可简化 Azure 中不同服务之间经过身份验证的连接。 服务连接器目前支持使用 Azure CLI 无密码扩展将应用服务连接到 SQL 数据库。

  1. 安装或升级服务连接器无密码扩展：

    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

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

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

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

重要

尽管此解决方案提供了一种简单的入门方法，但这不是企业生产环境的最佳做法。 在这些情况下，应用不应使用单个提升权限的身份执行所有操作。 你应尝试为特定任务配置具有特定权限的多个标识，实现最低特权原则。 有关配置数据库角色和安全性的详细信息，请参阅：

测试已部署的应用程序

浏览到应用的 URL，测试与 Azure SQL 数据库的连接是否正常工作。 可以在应用服务的概述页上找到应用的 URL。 将 /person 路径附加到 URL 的末尾，可以浏览到在本地测试的同一终结点。

你在本地创建的人员应会显示在浏览器中。 恭喜，应用程序现在已连接到本地和托管环境中的 Azure SQL 数据库。

清理资源

使用完 Azure SQL 数据库后，请删除资源以避免意外成本。

  1. 在 Azure 门户搜索栏中，搜索 Azure SQL 并选择匹配结果。

  2. 在数据库列表中找到并选择数据库。

  3. 在 Azure SQL 数据库的“概述”页上，选择“删除”。

  4. 在打开的Azure您确定要删除...页面上，输入数据库名称以确认，然后选择删除。

注意

如果将示例应用部署到 Azure，请确保还要搜索和删除应用服务资源，以避免意外成本。

相关内容