Provedor de banco de dados Microsoft SQL Server EF Core

Esse provedor de banco de dados permite que o Entity Framework Core seja usado com o Microsoft SQL Server (incluindo o SQL do Azure e o Azure Synapse Analytics). O provedor é mantido como parte do Entity Framework Core Project.

Install

Instale o pacote NuGet Microsoft.EntityFrameworkCore.SqlServer.

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Install-Package Microsoft.EntityFrameworkCore.SqlServer

Uso e configuração

Depois que seu projeto fizer referência ao pacote nuget, configure o EF para SQL Server da seguinte maneira:

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

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

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

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

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

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

O fornecedor do EF SQL Server utiliza o Microsoft.Data.SqlClient como seu fornecedor de ADO.NET subjacente. Para mais informações sobre as cadeias de ligação aceites pelo SqlClient, consulte esta página.

Nível de compatibilidade

Opcionalmente, você pode configurar o EF com o nível de compatibilidade do seu banco de dados; níveis de compatibilidade mais altos permitem recursos mais recentes, e configurar o EF de acordo faz com que ele use esses recursos. Se você não configurar explicitamente um nível de compatibilidade, será escolhido um padrão razoável que pode não aproveitar os recursos mais recentes. Como resultado, é recomendável configurar explicitamente o nível de compatibilidade que você gostaria de ter.

Observe que isso cobre apenas a própria configuração do EF do nível de compatibilidade - afetando, por exemplo, o SQL que ele gera - mas não afeta o nível de compatibilidade configurado em seu banco de dados real. Os bancos de dados hospedados em versões mais recentes do SQL Server ainda podem ser configurados com níveis de compatibilidade mais baixos, fazendo com que eles não ofereçam suporte aos recursos mais recentes, portanto, talvez seja necessário alterar o nível de compatibilidade em seu banco de dados também. Para obter mais informações sobre níveis de compatibilidade, consulte a documentação.

Para configurar o EF com um nível de compatibilidade, use UseCompatibilityLevel() da seguinte forma:

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

Índices JSON

A partir do EF Core 11.0, o fornecedor do SQL Server pode criar e estruturar índices JSON do SQL Server para caminhos dentro de tipos complexos mapeados para colunas JSON.

Por exemplo, o seguinte mapeia um tipo complexo para uma coluna JSON e cria um índice JSON sobre uma propriedade aninhada:

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

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

Quando os índices JSON do SQL Server são suportados, as migrações geram SQL de forma semelhante a:

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

Múltiplos caminhos dentro da mesma coluna JSON podem ser indexados em conjunto:

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

Os caminhos através de arrays JSON podem usar indexadores numéricos, por exemplo Orders[0].Number. Os índices JSON do SQL Server não suportam índices coringa sobre todos os elementos do array.

Resiliência da conexão

O EF inclui funcionalidade para repetir automaticamente comandos de banco de dados com falha; Para obter mais informações, consulte a documentação. Ao usar UseAzureSql e UseAzureSynapse, a resiliência da conexão é configurada automaticamente com as configurações apropriadas específicas para esses bancos de dados. Caso contrário, ao usar UseSqlServer, configure o provedor com EnableRetryOnFailure, conforme mostrado na documentação de resiliência da ligação.

Em alguns casos, UseSqlServer pode ser chamado em código que você não pode controlar. A partir do EF 9, para habilitar a resiliência de conexão em tais cenários, ligue ConfigureSqlEngine(c => c.EnableRetryOnFailureByDefault()) com antecedência (isso não é necessário com UseAzureSql e UseAzureSynapse).

Notas e ressalvas

• O pacote Microsoft.Data.SqlClient é fornecido com mais frequência do que o provedor EF Core. Se você quiser aproveitar os novos recursos e correções de bugs, você pode adicionar uma referência direta de pacote para a versão mais recente do Microsoft.Data.SqlClient.
• O provedor EF SQL Server usa Microsoft.Data.SqlClient e não o antigo System.Data.Client; se o seu projeto tem uma dependência direta do SqlClient, certifique-se de que ele faz referência ao pacote Microsoft.Data.SqlClient. Para obter mais informações sobre as diferenças entre Microsoft.Data.SqlClient e System.Data.SqlClient, consulte esta postagem no blog.

Mecanismos de banco de dados suportados

• Microsoft SQL Server (a partir de 2019)
• Base de Dados SQL do Azure
• Azure Synapse Analytics