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

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

项目
12/23/2023

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

先决条件

一个 Azure 订阅。
一个配置了 Microsoft Entra ID（旧称 Azure Active Directory）身份验证的 SQL 数据库。可以按照创建数据库快速入门创建数据库。
.NET 7.0 或更高版本。
具有 ASP.NET 和 Web 开发工作负载的 Visual Studio 或更高版本。
最新版本的 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 最小 Web API。

Visual Studio
.NET CLI

在 Visual Studio 菜单栏中，导航到“文件”>“新建”>“项目...”。
在对话框窗口中，在项目模板搜索框中输入“ASP.NET”，然后选择 ASP.NET Core Web API 结果。选择对话框底部的“下一步”。
在“项目名称”处，输入“DotNetSQL”。保留其余字段的默认值，然后选择“下一步”。
对于“框架”，选择“.NET 7.0”，并取消选中“使用控制器(取消选中以使用最小 API)。本快速入门教程使用最小 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：支持运行实体框架迁移

或者，还可以在“包管理器控制台”窗口中运行 Install-Package cmdlet：

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

使用 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 数据库：

向 appsettings.Development.json 文件添加 ConnectionStrings 部分，使其与以下代码一致。请记得更新 <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 文件（用于本地开发）或环境变量（用于托管生产场景）中检索无密码数据库连接字符串。

将 Entity Framework Core DbContext 类注册到 .NET 依赖关系注入容器。

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

将以下终结点添加到 Program.cs 文件底部的 app.Run() 上方，以使用 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 工具将在 Azure 中创建由 PersonDbContext 类定义的数据库架构。

在本地测试应用

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

按下 Visual Studio 顶部的“运行”按钮，启动 API 项目。
在 Swagger UI 页上，展开 POST 方法并选择“试用”。
修改示例 JSON 以包含名字和姓氏的值。选择“执行”，将新记录添加到数据库中。 API 返回成功的响应。
在 Swagger UI 页上，展开 GET 方法并选择“试用”。选择“执行”，此时会返回你刚刚创建的人员。

部署到 Azure 应用服务

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

确保应用已停止运行并成功生成。
在 Visual Studio 的“解决方案资源管理器”窗口中，右键单击顶级项目节点，然后选择“发布”。
在发布对话框中，选择“Azure”作为部署目标，然后选择“下一步”。
对于特定目标，选择“Azure 应用服务(Windows)”，然后选择“下一步”。
选择绿色的 + 图标，创建要部署到的目标新应用服务，并输入以下值：
- 名称：保留默认值。
- 订阅名称：选择要部署到的订阅。
- 资源组：选择“新建”，创建名为 msdocs-dotnet-sql 的新资源组。
- 托管计划：选择“新建”，打开托管计划对话框。保留默认值，并选择“确定”。
- 选择“创建”以关闭原始对话框。 Visual Studio 会在 Azure 中创建应用服务资源。
创建资源后，确保在应用服务列表中选中它，然后选择“下一步”。
在“API 管理”步骤中，选中底部的“跳过此步骤”复选框，然后选择“完成”。
选择发布配置文件摘要右上角的“发布”，将应用部署到 Azure。

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

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

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

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

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

服务连接器（建议）
Azure 门户

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

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

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

导航到应用服务的“标识”页。在“系统分配”选项卡下，“状态”应设置为“开”。此值表示已经为应用启用了系统分配的托管标识。
导航到应用服务的“配置”页。在“连接字符串”选项卡下，应会看到名为“AZURE_SQL_CONNECTIONSTRING”的连接字符串。选择“单击以显示值”文本，查看生成的无密码连接字符串。此连接字符串的名称与你在应用中配置的名称一致，因此，在 Azure 中运行时可以自动发现它。

在 Azure 门户中，可以使用托管标识，并针对 Azure SQL 数据库运行查询。完成以下步骤，创建从应用服务实例到 Azure SQL 数据库的无密码连接：

创建托管标识

在 Azure 门户中，导航到应用服务，并在左侧导航中选择“标识”。
在标识页上，确保已启用“启用系统分配的托管标识”选项。启用此设置后，将使用与应用服务相同的名称创建系统分配的托管标识。系统分配的标识会绑定到服务实例，并在应用被删除时随应用一起销毁。

创建数据库用户并分配角色

在 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 数据库用户，用于映射回应用服务实例的托管标识。它还向用户分配必要的 SQL 角色，允许应用读取、写入和修改数据库的数据和架构。完成此步骤后，服务就已经连接了。

重要

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

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

教程：保护 Azure SQL 数据库中的数据库

授权数据库访问 SQL 数据库

测试已部署的应用程序

浏览到应用的 URL，测试与 Azure SQL 数据库的连接是否正常工作。可以在应用服务的概述页上找到应用的 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>