Aspire 集成指南使用 Aspire.Microsoft.EntityFrameworkCore.SqlServer 为 EF Core 接入 Azure SQL / SQL Server【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本篇文章围绕 .NET Aspire 官方组件Aspire.Microsoft.EntityFrameworkCore.SqlServer展开讲解如何在 Aspire 应用中为 Entity Framework Core 的DbContext一键接入 Azure SQL 与 MS SQL Server 数据库。读完本文你将掌握组件的安装与注册方式、连接字符串与配置提供程序的使用、Microsoft Entra IDAzure AD认证的底层机制以及 AppHost 中Aspire.Hosting.SqlServer的端到端编排用法并了解连接池、重试、健康检查与 OpenTelemetry 遥测是如何被自动开启的。组件概述一条命令获得完整的 SQL Server 数据访问能力该组件的作用是在基于IHostApplicationBuilder构建的 Aspire 应用中注册一个连接 Azure SQL / MS SQL Server 数据库的 Entity Framework CoreDbContext服务并自动启用以下能力见 AspireSqlServerEFCoreSqlClientExtensions.csDbContext 连接池通过AddDbContextPoolTContext注册减少实例创建开销连接弹性重试默认开启EnableRetryOnFailure()对失败的数据库命令自动重试健康检查注册AddDbContextCheckTContext可供 Dashboard 与探针使用日志沿用 EF Core 自带的日志机制无需额外注册 LoggerFactory参见 EF Core 文档说明遥测通过AddSqlClientInstrumentation()接入 OpenTelemetry SQL Client 插桩收集追踪数据。从 csprojAspire.Microsoft.EntityFrameworkCore.SqlServer.csproj可以看到它依赖Microsoft.EntityFrameworkCore.SqlServer、Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore、OpenTelemetry.Extensions.Hosting与OpenTelemetry.Instrumentation.SqlClient等包这些依赖共同构成了上述能力栈。快速开始环境前提一个可访问的 Azure SQL 或 MS SQL Server 数据库数据库对应的连接字符串。安装 NuGet 包在目标项目中通过 .NET CLI 安装组件dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer用法示例方式一AddSqlServerDbContext —— 注册即用在AppHost项目的AppHost.cs中注意实际生产项目中注册代码应写在引用该连接字符串的服务项目的Program.cs里调用AddSqlServerDbContextTContext扩展方法通过依赖注入容器注册DbContext。方法接收一个连接名称参数builder.AddSqlServerDbContextMyDbContext(sqldata);随后即可通过构造函数注入获取MyDbContext例如在 Web API 控制器中private readonly MyDbContext _context; public ProductsController(MyDbContext context) { _context context; }方式二EnrichSqlServerDbContext —— 为已注册的 DbContext 补全能力如果因为业务需要你已经用其他方式注册了DbContext例如想自定义UseSqlServer的选项则改用EnrichSqlServerDbContext为它补齐重试、健康检查与遥测能力var connectionString builder.Configuration.GetConnectionString(catalogdb); builder.Services.AddDbContextPoolCatalogDbContext(dbContextOptionsBuilder dbContextOptionsBuilder.UseSqlServer(connectionString)); builder.EnrichSqlServerDbContextCatalogDbContext();两种方式的行为差异从源码可以确认AddSqlServerDbContext会先调用EnsureDbContextNotRegisteredTContext()若DbContext已被注册会抛出InvalidOperationException提示改用Enrich方法测试 AspireSqlServerEFCoreSqlClientExtensionsTests.cs 中的ThrowsWhenDbContextIsRegisteredBeforeAspireComponent验证了这一点EnrichSqlServerDbContext不会从ConnectionStrings配置节读取连接字符串因为它被调用时DbContext已经注册完成连接字符串应已在注册处配置好。EnrichSqlServerDbContext在重试配置上有更精细的处理见源码 AspireSqlServerEFCoreSqlClientExtensions.cs若当前已存在SqlServerRetryingExecutionStrategy或其子类用户自定义重试策略则保留用户的策略不会覆盖若用户配置了自定义ExecutionStrategy而DisableRetry未设为true会抛出异常提示需要显式禁用重试避免两种策略冲突若配置的CommandTimeout与DbContextOptions中已有的值冲突同样会抛出InvalidOperationException提示。配置详解组件提供了多种配置 SQL 连接的方式可根据项目约定灵活选择。所有配置最终汇聚到MicrosoftEntityFrameworkCoreSqlServerSettings见 MicrosoftEntityFrameworkCoreSqlServerSettings.cs其属性如下属性类型默认值说明ConnectionStringstring?null目标 SQL Server 数据库的连接字符串DisableRetryboolfalse是否禁用连接重试默认开启重试DisableHealthChecksboolfalse是否禁用数据库健康检查默认开启DisableTracingboolfalse是否禁用 OpenTelemetry 追踪默认开启CommandTimeoutint?null命令执行等待时间秒未设置时使用 EF Core 默认值使用连接字符串组件从ConnectionStrings配置节读取连接字符串只需在调用时传入连接名builder.AddSqlServerDbContextMyDbContext(myConnection);对应的配置如 appsettings.json{ ConnectionStrings: { myConnection: Data Sourcemyserver;Initial Catalogmaster } }连接字符串的具体格式说明可参考 SqlConnection.ConnectionString 文档。从源码看AddSqlServerDbContext读取设置的顺序是先通过GetDbContextSettings从配置段绑定设置详见下文“配置优先级”随后若ConnectionStrings中存在对应连接名则用该连接字符串覆盖settings.ConnectionString最后再执行configureSettings委托——因此代码中显式设置的连接字符串优先级最高测试ConnectionStringCanBeSetInCode与ConnectionNameWinsOverConfigSection分别验证了这两种优先级关系。Microsoft Entra IDAzure AD认证要使用 Entra ID 连接 Azure SQL例如托管标识场景连接字符串需指定认证模式如AuthenticationActive Directory Default这正是Aspire.Hosting.Azure.Sql集成默认生成的连接字符串形态。底层机制重点自 Microsoft.Data.SqlClient 7.0 起Entra ID 认证提供程序不再内置在核心驱动中而是拆分到了独立的 Microsoft.Data.SqlClient.Extensions.Azure 包。本组件在 csproj 中显式引用了该包见 Aspire.Microsoft.EntityFrameworkCore.SqlServer.csproj因此这类连接字符串开箱即用无需额外安装包或编写注册代码同时组件也会传递引入Azure.Identity。测试 AspireSqlServerEFCoreSqlClientExtensionsTests.cs 中的EntraIdAuthenticationProviderIsRegistered专门验证了ActiveDirectoryDefault与ActiveDirectoryManagedIdentity两种认证提供程序都能在组件内正常解析防止后续依赖升级时回归。使用配置提供程序组件支持Microsoft.Extensions.Configuration从配置键Aspire:Microsoft:EntityFrameworkCore:SqlServer加载MicrosoftEntityFrameworkCoreSqlServerSettings。例如 appsettings.json 中禁用健康检查与追踪{ Aspire: { Microsoft: { EntityFrameworkCore: { SqlServer: { DisableHealthChecks: true, DisableTracing: true } } } } }完整的可配置项与默认值可参考组件自带的 ConfigurationSchema.json其中还列出了Microsoft.EntityFrameworkCore.*各分类的日志级别定义便于 IDE 提供智能提示。使用内联委托也可以通过ActionMicrosoftEntityFrameworkCoreSqlServerSettings configureSettings委托在代码中内联设置部分或全部选项例如禁用健康检查builder.AddSqlServerDbContextMyDbContext(sqldata, settings settings.DisableHealthChecks true);或配合Enrich方法builder.EnrichSqlServerDbContextMyDbContext(settings settings.DisableHealthChecks true);配置优先级从源码与测试归纳连接字符串configureSettings中显式赋值 ConnectionStrings:{连接名}Aspire:...:SqlServer配置段普通设置项如 CommandTimeout上下文级配置段Aspire:Microsoft:EntityFrameworkCore:SqlServer:{DbContext类型名}优先于连接级配置段Aspire:Microsoft:EntityFrameworkCore:SqlServer:{连接名}两者都优先于全局默认段Aspire:Microsoft:EntityFrameworkCore:SqlServerAdd 与 Enrich 的差异AddSqlServerDbContext在内部调用UseSqlServer并应用设置EnrichSqlServerDbContext只做“补充”不会触碰连接字符串。这些规则分别被测试AddSqlServerDbContext_WithConnectionNameAndSettings_AppliesConnectionSpecificSettings、AddSqlServerDbContext_WithConnectionSpecificAndContextSpecificSettings_PrefersContextSpecific与CommandTimeoutFromBuilderWinsOverOthers所覆盖。自定义 DbContextOptionsAddSqlServerDbContext还支持第三个可选参数ActionDbContextOptionsBuilder configureDbContextOptions用于进一步定制 EF Core 选项例如设置批大小builder.AddSqlServerDbContextMyDbContext(sqldata, configureDbContextOptions: optionsBuilder { optionsBuilder.UseSqlServer(sqlBuilder { sqlBuilder.MinBatchSize(123); }); });源码中该委托在内部UseSqlServer之后执行见 AspireSqlServerEFCoreSqlClientExtensions.cs因此可用于覆盖默认行为测试CanConfigureDbContextOptions验证了自定义选项、配置段中的CommandTimeout示例中为 608 秒以及默认重试策略会同时生效。AppHost 扩展在编排层注册 SQL Server若要在 AppHost 中声明式地创建 SQL Server 容器资源并自动注入连接信息需要安装宿主侧的集成包dotnet add package Aspire.Hosting.SqlServer然后在 AppHost 的AppHost.cs中注册数据库资源并通过WithReference将连接配置注入到服务项目var sql builder.AddSqlServer(sql).AddDatabase(sqldata); var myService builder.AddProjectProjects.MyService() .WithReference(sql);其中AddSqlServer在 SqlServerBuilderExtensions.cs 中创建SqlServerServerResourceAddDatabase在其上追加SqlServerDatabaseResource。WithReference会在MyService项目中生成名为sqldata的连接配置。随后在MyService的Program.cs中即可消费该连接builder.AddSqlServerDbContextMyDbContext(sqldata);这样 AppHost 编排层与服务消费层通过连接名sqldata实现了解耦数据库的部署形态本地容器、Azure SQL 等由 AppHost 决定而服务代码只需关注连接名。小结Aspire.Microsoft.EntityFrameworkCore.SqlServer组件把 EF Core 接入 SQL Server 的常见横切关注点连接池、重试、健康检查、日志、遥测、Entra ID 认证收敛为一次注册调用并通过“配置段 连接名 内联委托”的多层配置体系提供了充分的灵活性配合Aspire.Hosting.SqlServer的 AppHost 编排可以快速构建出可观测、可弹性伸缩的数据库访问链路。需要深入研究的读者可继续阅读组件入口实现AspireSqlServerEFCoreSqlClientExtensions.cs设置模型MicrosoftEntityFrameworkCoreSqlServerSettings.cs配置 SchemaConfigurationSchema.json行为测试AspireSqlServerEFCoreSqlClientExtensionsTests.csAppHost 侧集成SqlServerBuilderExtensions.cs【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aspire 集成指南：使用 Aspire.Microsoft.EntityFrameworkCore.SqlServer 为 EF Core 接入 Azure SQL / SQL Server
Aspire 集成指南使用 Aspire.Microsoft.EntityFrameworkCore.SqlServer 为 EF Core 接入 Azure SQL / SQL Server【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本篇文章围绕 .NET Aspire 官方组件Aspire.Microsoft.EntityFrameworkCore.SqlServer展开讲解如何在 Aspire 应用中为 Entity Framework Core 的DbContext一键接入 Azure SQL 与 MS SQL Server 数据库。读完本文你将掌握组件的安装与注册方式、连接字符串与配置提供程序的使用、Microsoft Entra IDAzure AD认证的底层机制以及 AppHost 中Aspire.Hosting.SqlServer的端到端编排用法并了解连接池、重试、健康检查与 OpenTelemetry 遥测是如何被自动开启的。组件概述一条命令获得完整的 SQL Server 数据访问能力该组件的作用是在基于IHostApplicationBuilder构建的 Aspire 应用中注册一个连接 Azure SQL / MS SQL Server 数据库的 Entity Framework CoreDbContext服务并自动启用以下能力见 AspireSqlServerEFCoreSqlClientExtensions.csDbContext 连接池通过AddDbContextPoolTContext注册减少实例创建开销连接弹性重试默认开启EnableRetryOnFailure()对失败的数据库命令自动重试健康检查注册AddDbContextCheckTContext可供 Dashboard 与探针使用日志沿用 EF Core 自带的日志机制无需额外注册 LoggerFactory参见 EF Core 文档说明遥测通过AddSqlClientInstrumentation()接入 OpenTelemetry SQL Client 插桩收集追踪数据。从 csprojAspire.Microsoft.EntityFrameworkCore.SqlServer.csproj可以看到它依赖Microsoft.EntityFrameworkCore.SqlServer、Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore、OpenTelemetry.Extensions.Hosting与OpenTelemetry.Instrumentation.SqlClient等包这些依赖共同构成了上述能力栈。快速开始环境前提一个可访问的 Azure SQL 或 MS SQL Server 数据库数据库对应的连接字符串。安装 NuGet 包在目标项目中通过 .NET CLI 安装组件dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer用法示例方式一AddSqlServerDbContext —— 注册即用在AppHost项目的AppHost.cs中注意实际生产项目中注册代码应写在引用该连接字符串的服务项目的Program.cs里调用AddSqlServerDbContextTContext扩展方法通过依赖注入容器注册DbContext。方法接收一个连接名称参数builder.AddSqlServerDbContextMyDbContext(sqldata);随后即可通过构造函数注入获取MyDbContext例如在 Web API 控制器中private readonly MyDbContext _context; public ProductsController(MyDbContext context) { _context context; }方式二EnrichSqlServerDbContext —— 为已注册的 DbContext 补全能力如果因为业务需要你已经用其他方式注册了DbContext例如想自定义UseSqlServer的选项则改用EnrichSqlServerDbContext为它补齐重试、健康检查与遥测能力var connectionString builder.Configuration.GetConnectionString(catalogdb); builder.Services.AddDbContextPoolCatalogDbContext(dbContextOptionsBuilder dbContextOptionsBuilder.UseSqlServer(connectionString)); builder.EnrichSqlServerDbContextCatalogDbContext();两种方式的行为差异从源码可以确认AddSqlServerDbContext会先调用EnsureDbContextNotRegisteredTContext()若DbContext已被注册会抛出InvalidOperationException提示改用Enrich方法测试 AspireSqlServerEFCoreSqlClientExtensionsTests.cs 中的ThrowsWhenDbContextIsRegisteredBeforeAspireComponent验证了这一点EnrichSqlServerDbContext不会从ConnectionStrings配置节读取连接字符串因为它被调用时DbContext已经注册完成连接字符串应已在注册处配置好。EnrichSqlServerDbContext在重试配置上有更精细的处理见源码 AspireSqlServerEFCoreSqlClientExtensions.cs若当前已存在SqlServerRetryingExecutionStrategy或其子类用户自定义重试策略则保留用户的策略不会覆盖若用户配置了自定义ExecutionStrategy而DisableRetry未设为true会抛出异常提示需要显式禁用重试避免两种策略冲突若配置的CommandTimeout与DbContextOptions中已有的值冲突同样会抛出InvalidOperationException提示。配置详解组件提供了多种配置 SQL 连接的方式可根据项目约定灵活选择。所有配置最终汇聚到MicrosoftEntityFrameworkCoreSqlServerSettings见 MicrosoftEntityFrameworkCoreSqlServerSettings.cs其属性如下属性类型默认值说明ConnectionStringstring?null目标 SQL Server 数据库的连接字符串DisableRetryboolfalse是否禁用连接重试默认开启重试DisableHealthChecksboolfalse是否禁用数据库健康检查默认开启DisableTracingboolfalse是否禁用 OpenTelemetry 追踪默认开启CommandTimeoutint?null命令执行等待时间秒未设置时使用 EF Core 默认值使用连接字符串组件从ConnectionStrings配置节读取连接字符串只需在调用时传入连接名builder.AddSqlServerDbContextMyDbContext(myConnection);对应的配置如 appsettings.json{ ConnectionStrings: { myConnection: Data Sourcemyserver;Initial Catalogmaster } }连接字符串的具体格式说明可参考 SqlConnection.ConnectionString 文档。从源码看AddSqlServerDbContext读取设置的顺序是先通过GetDbContextSettings从配置段绑定设置详见下文“配置优先级”随后若ConnectionStrings中存在对应连接名则用该连接字符串覆盖settings.ConnectionString最后再执行configureSettings委托——因此代码中显式设置的连接字符串优先级最高测试ConnectionStringCanBeSetInCode与ConnectionNameWinsOverConfigSection分别验证了这两种优先级关系。Microsoft Entra IDAzure AD认证要使用 Entra ID 连接 Azure SQL例如托管标识场景连接字符串需指定认证模式如AuthenticationActive Directory Default这正是Aspire.Hosting.Azure.Sql集成默认生成的连接字符串形态。底层机制重点自 Microsoft.Data.SqlClient 7.0 起Entra ID 认证提供程序不再内置在核心驱动中而是拆分到了独立的 Microsoft.Data.SqlClient.Extensions.Azure 包。本组件在 csproj 中显式引用了该包见 Aspire.Microsoft.EntityFrameworkCore.SqlServer.csproj因此这类连接字符串开箱即用无需额外安装包或编写注册代码同时组件也会传递引入Azure.Identity。测试 AspireSqlServerEFCoreSqlClientExtensionsTests.cs 中的EntraIdAuthenticationProviderIsRegistered专门验证了ActiveDirectoryDefault与ActiveDirectoryManagedIdentity两种认证提供程序都能在组件内正常解析防止后续依赖升级时回归。使用配置提供程序组件支持Microsoft.Extensions.Configuration从配置键Aspire:Microsoft:EntityFrameworkCore:SqlServer加载MicrosoftEntityFrameworkCoreSqlServerSettings。例如 appsettings.json 中禁用健康检查与追踪{ Aspire: { Microsoft: { EntityFrameworkCore: { SqlServer: { DisableHealthChecks: true, DisableTracing: true } } } } }完整的可配置项与默认值可参考组件自带的 ConfigurationSchema.json其中还列出了Microsoft.EntityFrameworkCore.*各分类的日志级别定义便于 IDE 提供智能提示。使用内联委托也可以通过ActionMicrosoftEntityFrameworkCoreSqlServerSettings configureSettings委托在代码中内联设置部分或全部选项例如禁用健康检查builder.AddSqlServerDbContextMyDbContext(sqldata, settings settings.DisableHealthChecks true);或配合Enrich方法builder.EnrichSqlServerDbContextMyDbContext(settings settings.DisableHealthChecks true);配置优先级从源码与测试归纳连接字符串configureSettings中显式赋值 ConnectionStrings:{连接名}Aspire:...:SqlServer配置段普通设置项如 CommandTimeout上下文级配置段Aspire:Microsoft:EntityFrameworkCore:SqlServer:{DbContext类型名}优先于连接级配置段Aspire:Microsoft:EntityFrameworkCore:SqlServer:{连接名}两者都优先于全局默认段Aspire:Microsoft:EntityFrameworkCore:SqlServerAdd 与 Enrich 的差异AddSqlServerDbContext在内部调用UseSqlServer并应用设置EnrichSqlServerDbContext只做“补充”不会触碰连接字符串。这些规则分别被测试AddSqlServerDbContext_WithConnectionNameAndSettings_AppliesConnectionSpecificSettings、AddSqlServerDbContext_WithConnectionSpecificAndContextSpecificSettings_PrefersContextSpecific与CommandTimeoutFromBuilderWinsOverOthers所覆盖。自定义 DbContextOptionsAddSqlServerDbContext还支持第三个可选参数ActionDbContextOptionsBuilder configureDbContextOptions用于进一步定制 EF Core 选项例如设置批大小builder.AddSqlServerDbContextMyDbContext(sqldata, configureDbContextOptions: optionsBuilder { optionsBuilder.UseSqlServer(sqlBuilder { sqlBuilder.MinBatchSize(123); }); });源码中该委托在内部UseSqlServer之后执行见 AspireSqlServerEFCoreSqlClientExtensions.cs因此可用于覆盖默认行为测试CanConfigureDbContextOptions验证了自定义选项、配置段中的CommandTimeout示例中为 608 秒以及默认重试策略会同时生效。AppHost 扩展在编排层注册 SQL Server若要在 AppHost 中声明式地创建 SQL Server 容器资源并自动注入连接信息需要安装宿主侧的集成包dotnet add package Aspire.Hosting.SqlServer然后在 AppHost 的AppHost.cs中注册数据库资源并通过WithReference将连接配置注入到服务项目var sql builder.AddSqlServer(sql).AddDatabase(sqldata); var myService builder.AddProjectProjects.MyService() .WithReference(sql);其中AddSqlServer在 SqlServerBuilderExtensions.cs 中创建SqlServerServerResourceAddDatabase在其上追加SqlServerDatabaseResource。WithReference会在MyService项目中生成名为sqldata的连接配置。随后在MyService的Program.cs中即可消费该连接builder.AddSqlServerDbContextMyDbContext(sqldata);这样 AppHost 编排层与服务消费层通过连接名sqldata实现了解耦数据库的部署形态本地容器、Azure SQL 等由 AppHost 决定而服务代码只需关注连接名。小结Aspire.Microsoft.EntityFrameworkCore.SqlServer组件把 EF Core 接入 SQL Server 的常见横切关注点连接池、重试、健康检查、日志、遥测、Entra ID 认证收敛为一次注册调用并通过“配置段 连接名 内联委托”的多层配置体系提供了充分的灵活性配合Aspire.Hosting.SqlServer的 AppHost 编排可以快速构建出可观测、可弹性伸缩的数据库访问链路。需要深入研究的读者可继续阅读组件入口实现AspireSqlServerEFCoreSqlClientExtensions.cs设置模型MicrosoftEntityFrameworkCoreSqlServerSettings.cs配置 SchemaConfigurationSchema.json行为测试AspireSqlServerEFCoreSqlClientExtensionsTests.csAppHost 侧集成SqlServerBuilderExtensions.cs【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考