你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
使用 .NET 和 Entity Framework Core 连接并查询 Azure SQL 数据库
适用于:Azure SQL 数据库
本快速入门教程介绍了如何使用 .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 服务和资源访问此服务器”设置。 实际应用程序应实现更安全的方法,例如更强的防火墙限制或虚拟网络配置。
若要详细了解数据库安全配置,可以阅读以下资源:
还必须为服务器启用 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 菜单栏中,导航到“文件”>“新建”>“项目...”。
在对话框窗口中,在项目模板搜索框中输入“ASP.NET”,然后选择 ASP.NET Core Web API 结果。 选择对话框底部的“下一步”。
在“项目名称”处,输入“DotNetSQL”。 保留其余字段的默认值,然后选择“下一步”。
对于“框架”,选择“.NET 7.0”,并取消选中“使用控制器(取消选中以使用最小 API)。 本快速入门教程使用最小 API 模板来简化终结点的创建和配置过程。
选择“创建”。 此时新项目在 Visual Studio 环境中打开。
将 Entity Framework Core 添加到项目
要使用 .NET 和 Entity Framework Core 连接到 Azure SQL 数据库,需要使用以下方法之一将三个 NuGet 包添加到项目:
在“解决方案资源管理器”窗口中,右键单击项目的“依赖项”节点,然后选择“管理 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
添加代码以连接到 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 更新数据库架构以匹配数据模型,必须使用迁移。 迁移可以创建并以增量方式更新数据库架构,使其与应用程序的数据模型保持同步。 你可以在迁移概述中详细了解此模式。
打开项目根目录的终端窗口。
运行以下命令,生成可以创建数据库的初始迁移:
Add-Migration InitialCreate
项目目录中应显示一个
Migrations
文件夹,以及一个前面附加了唯一编号的名为InitialCreate
的文件。 使用以下命令运行迁移以创建数据库:Update-Database
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)”,然后选择“下一步”。
选择绿色的 + 图标,创建要部署到的目标新应用服务,并输入以下值:
创建资源后,确保在应用服务列表中选中它,然后选择“下一步”。
在“API 管理”步骤中,选中底部的“跳过此步骤”复选框,然后选择“完成”。
选择发布配置文件摘要右上角的“发布”,将应用部署到 Azure。
部署完成后,Visual Studio 会启动浏览器以显示托管的应用,但此时该应用在 Azure 上还无法正常工作。 你仍然需要在应用服务和 SQL 数据库之间配置安全连接,才能检索数据。
将应用服务连接到 Azure SQL 数据库
若要将应用服务实例连接到 Azure SQL 数据库,需要执行以下步骤:
- 为应用服务创建托管标识。 应用中包含的
Microsoft.Data.SqlClient
库将自动发现托管标识,就像它发现本地 Visual Studio 用户一样。 - 创建 SQL 数据库用户,并将它与应用服务托管标识相关联。
- 将 SQL 角色分配给允许读取、写入以及可能的其他权限的数据库用户。
可以使用多种工具实现这些步骤:
服务连接器是一种工具,可简化 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 中运行时可以自动发现它。
重要
尽管此解决方案提供了一种简单的入门方法,但它并不是适用于企业生产环境的最佳做法。 在这些情况下,应用不应使用单个提升的标识执行所有操作。 你应尝试为特定任务配置具有特定权限的多个标识,实现最低特权原则。
若要详细了解如何配置数据库角色和安全性,可以阅读以下资源:
测试已部署的应用程序
浏览到应用的 URL,测试与 Azure SQL 数据库的连接是否正常工作。 可以在应用服务的概述页上找到应用的 URL。 将 /person
路径附加到 URL 的末尾,可以浏览到在本地测试的同一终结点。
你在本地创建的人员应会显示在浏览器中。 恭喜! 现在,你的应用程序已连接到本地和托管环境中的 Azure SQL 数据库。
清理资源
使用完 Azure SQL 数据库后,请删除资源以避免意外成本。
在 Azure 门户搜索栏中,搜索 Azure SQL 并选择匹配结果。
在数据库列表中找到并选择数据库。
在 Azure SQL 数据库的“概述”页上,选择“删除”。
Azure 上随即打开“确定要删除...”页,键入数据库名称进行确认,然后选择“删除”。