你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
适用于:Azure SQL 数据库
本快速入门介绍如何将应用连接到Azure SQL 数据库中的数据库,并使用.NET和Entity Framework Core进行查询。 本快速入门采用推荐的无密码方法连接到数据库。 想了解更多关于无密码连接的信息,请访问 无密码中心。
先决条件
- 一个 Azure 订阅。
- 一个配置了 Microsoft Entra ID(旧称 Azure Active Directory)身份验证的 SQL 数据库。 你可以使用快速入门工具创建一个:创建单个数据库 - Azure SQL 数据库。
- .NET 10.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 数据库:
对于本地开发连接,请确保已将 Azure SQL 逻辑服务器配置为允许本地计算机 IP 地址和其他 Azure 服务进行连接:
在 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 菜单栏中,转到 File>New>Project。
在对话框中,输入
ASP.NET项目模板搜索框,选择 ASP.NET Core Web API 结果。 选择对话框底部的“下一步”。在项目名称中,输入
DotNetSQL。 保留其余字段的默认值,然后选择“ 下一步”。对于框架,选择 .NET 10.0,取消勾选“使用控制器”。 本快速入门教程使用最小 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:支持运行实体框架迁移 -
Microsoft.EntityFrameworkCore.Tools:提供对 Visual Studio 包管理器控制台工具的支持(仅限 PowerShell) -
Microsoft.AspNetCore.OpenApi:可选 - 支持 OpenAPI 文档生成 -
Swashbuckle.AspNetCore.SwaggerUI:可选 - 提供与应用端点的OpenAPI UI交互
添加代码以连接到 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 数据库:
向
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 后,相同的代码将发现并应用与托管应用关联的托管标识,稍后会对其进行配置。将
Program.cs文件的内容替换为以下代码: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) => 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(DbContextOptions<PersonDbContext> options) : DbContext(options) { public DbSet<Person> Person { get; set; } }前面的代码处理以下步骤:
- 从
appsettings.Development.json文件(用于本地开发)或环境变量(用于托管生产场景)中检索无密码数据库连接字符串。 - 将 Entity Framework Core
DbContext类注册到 .NET 依赖关系注入容器。 可以在 Entity Framework Core 的DbContext文档中阅读有关 的详细信息。 - 配置 .NET 10.0 OpenAPI 支持,配合 SwaggerUI,提供一个你可以与应用端点和数据库交互的界面。
- 添加终结点以检索和添加数据库中的实体。
- 定义一个
Person类来表示Persons数据库表中的单个记录,并且定义一个PersonDbContext类以注册到 .NET 依赖注入容器。
- 从
运行迁移以创建数据库
要用 Entity Framework Core 更新数据库模式以匹配你的数据模型,可以使用迁移。 迁移可以创建并以增量方式更新数据库架构,使其与应用程序的数据模型保持同步。 想了解更多关于这一模式的信息,请参阅 迁徙概览。
打开项目根目录的终端窗口。
运行以下命令,生成可以创建数据库的初始迁移:
Add-Migration InitialCreate项目目录中应显示一个
Migrations文件夹,以及一个前面附加了唯一编号的名为InitialCreate的文件。 运行以下命令迁移以创建数据库,Entity Framework Core 工具根据PersonDbContext类在 Azure 中创建数据库架构。Update-Database
在本地测试应用
应用已准备好本地测试。 请确保使用设置为数据库管理员的同一帐户登录到 Visual Studio 或 Azure CLI。
选择 Visual Studio 顶部的运行按钮以启动 API 项目。
在 Swagger UI 页面上(例如
https://localhost:<port>/swagger),展开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 会启动浏览器来显示托管应用。 你会看到默认端点的 Hello world 消息。 但是,此时数据库终结点在 Azure 上无法正常工作。 你仍然需要在应用服务和 SQL 数据库之间配置安全连接,才能检索数据。
将应用服务连接到 Azure SQL 数据库
要将 App Service 实例连接到 Azure SQL 数据库,请完成以下步骤:
为应用服务创建托管标识。 应用中包含的
Microsoft.Data.SqlClient库会像发现本地 Visual Studio 用户一样,自动发现托管身份。创建 SQL 数据库用户,并将它与应用服务托管标识相关联。
将 SQL 角色分配给允许读取、写入以及可能的其他权限的数据库用户。
你可以使用多种工具来实现这些步骤:
服务连接器是一种工具,可简化 Azure 中不同服务之间经过身份验证的连接。 Service Connector 目前支持通过 Azure CLI 无密码扩展将应用服务连接到 SQL 数据库。
安装或升级服务连接器无密码扩展:
az extension add --name serviceconnector-passwordless --upgrade通过系统分配的管理身份执行
az webapp connection create 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您确定要删除...页面上,输入数据库名称以确认,然后选择删除。
注意
如果你将示例应用部署到 Azure,确保同时搜索并删除 App Service 资源,以避免不必要的费用。