Microsoft SQL Server EF Core 数据库提供程序

此数据库提供程序允许将 Entity Framework Core 与 Microsoft SQL Server（包括 Azure SQL 和 Azure Synapse Analytics）一起使用。 该提供程序作为 Entity Framework Core 项目的组成部分进行维护。

Install

安装 Microsoft.EntityFrameworkCore.SqlServer NuGet 包。

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

使用情况和配置

项目引用 nuget 包后，按如下所示配置 EF for SQL Server：

public class MyContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlServer("<CONNECTION STRING>");
    }
}

将 EF 与依赖项注入（例如 ASP.NET）配合使用时，请使用以下内容：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<MyContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MyContext")));

EF SQL Server 提供程序使用 Microsoft.Data.SqlClient 作为其基础 ADO.NET 提供程序。 有关 SqlClient 接受的连接字符串的详细信息， 请参阅此页面。

兼容性级别

可以选择使用数据库的兼容级别配置 EF;更高的兼容性级别允许使用较新的功能，并相应地配置 EF 使它使用这些功能。 如果未显式配置兼容级别，则会选择合理的默认值，该默认值可能无法利用最新的功能。 因此，建议明确配置需要的兼容性级别。

请注意，这仅涵盖 EF 自己的兼容性级别配置（影响它生成的 SQL）但不会影响实际数据库中配置的兼容级别。 在较新版本的 SQL Server 上托管的数据库仍可能配置兼容性级别较低，从而导致它们不支持最新功能，因此可能需要更改数据库中的兼容性级别。 有关兼容性级别的详细信息， 请参阅文档。

要配置 EF 的兼容性级别，请按如下方式使用 UseCompatibilityLevel()：

optionsBuilder.UseSqlServer("<CONNECTION STRING>", o => o.UseCompatibilityLevel(170));

JSON 索引

从 EF Core 11.0 开始，SQL Server提供程序可以为映射到 JSON 列的复杂类型内的路径创建和搭建SQL Server JSON 索引。

例如，以下代码将复杂类型映射到 JSON 列，并在嵌套属性上创建 JSON 索引：

modelBuilder.Entity<Customer>()
    .ComplexProperty(c => c.Contact, b => b.ToJson().HasColumnType("json"));

modelBuilder.Entity<Customer>()
    .HasIndex("Contact.Address.City");

当支持 SQL Server JSON 索引时，迁移操作会生成类似于以下内容的 SQL：

CREATE JSON INDEX [IX_Customers_Contact_Address_City]
ON [Customers]([Contact]) FOR (N'$.Address.City');

同一 JSON 列中的多个路径可以一起编制索引：

modelBuilder.Entity<Customer>()
    .HasIndex(["Contact.Address.City", "Contact.PhoneNumber"]);

通过 JSON 数组的路径可以使用数值索引器，例如 Orders[0].Number。 SQL Server JSON 索引不支持每个数组元素的通配符索引。

连接弹性

EF 包括自动重试失败的数据库命令的功能;有关详细信息， 请参阅文档。 使用 UseAzureSql 和 UseAzureSynapse时，会自动使用特定于这些数据库的相应设置设置来设置连接复原能力。 否则，在使用 UseSqlServer 时，请按照连接复原文档中的说明，用 EnableRetryOnFailure 配置提供程序。

在某些情况下， UseSqlServer 可以在无法控制的代码中调用。 从 EF 9 开始，若要在这类场景中启用连接复原，请事先调用ConfigureSqlEngine(c => c.EnableRetryOnFailureByDefault())（在使用UseAzureSql和UseAzureSynapse时，这不是必须的）。

备注和注意事项

  • Microsoft.Data.SqlClient 包的交付频率高于 EF Core 提供程序。 若要利用新功能和 bug 修复，可以向最新版本的 Microsoft.Data.SqlClient 添加直接包引用。
  • EF SQL Server 提供程序使用 Microsoft.Data.SqlClient，而不是较旧的 System.Data.Client;如果项目直接依赖于 SqlClient，请确保它引用 Microsoft.Data.SqlClient 包。 有关 Microsoft.Data.SqlClient 和 System.Data.SqlClient 之间的差异的详细信息， 请参阅此博客文章。

支持的数据库引擎

  • Microsoft SQL Server （2019 及更高版本）
  • Azure SQL 数据库
  • Azure Synapse Analytics
  • Last updated on