Alterações significativas no EF Core 11 (EF11)

Esta página documenta a API e as alterações de comportamento que têm o potencial de interromper a atualização de aplicativos existentes do EF Core 10 para o EF Core 11. Verifique as alterações interruptivas anteriores se estiver atualizando a partir de uma versão anterior do Entity Framework Core:

Resumo

Observação

Se você estiver usando Microsoft.Data.Sqlite, consulte a seção separada abaixo sobre alterações interruptivas do Microsoft.Data.Sqlite.

Alteração interruptiva Impact
A E/S síncrona via o provedor do Azure Cosmos DB foi totalmente removida Medium
Microsoft. Data.SqlClient foi atualizado para 7.0 Medium
O EF Core agora é gerado por padrão quando nenhuma migração é encontrada Baixo
EFOptimizeContext A propriedade MSBuild foi removida Baixo
os pacotes de ferramentas EF não fazem mais referência a Microsoft. EntityFrameworkCore.Design Baixo
As propriedades do SqlVector não são mais carregadas por padrão Baixo
Cosmos: coleções de propriedade vazias agora retornam uma coleção vazia em vez de nula Baixo

Alterações de impacto médio

A E/S síncrona via o provedor do Azure Cosmos DB foi totalmente removida

Problema de acompanhamento nº 37059

Comportamento antigo

A E/S síncrona via provedor do Azure Cosmos DB não tem suporte desde o EF 9.0 (nota); chamar qualquer API de E/S síncrona, como ToList ou SaveChanges, lançava uma exceção, a menos que optar por uma configuração especial estivesse configurado. Quando a aceitação estava configurada, as APIs de E/S síncrona funcionaram como antes, fazendo com que o provedor executasse o bloqueio "síncrono em vez de assíncrono" no SDK do Azure Cosmos DB, o que poderia resultar em deadlocks e outros problemas de desempenho.

Novo comportamento

A partir do EF Core 11.0, o EF agora sempre é gerado quando uma API de E/S síncrona é chamada. Não há como optar por voltar a usar APIs de E/S de sincronização.

Por que

O bloqueio síncrono em métodos assíncronos ("síncrono em vez de assíncrono") é altamente desaconselhado e pode levar a deadlock e outros problemas de desempenho. Como o SDK do Azure Cosmos DB é compatível apenas com métodos assíncronos, o provedor do EF Cosmos também é compatível.

Atenuações

Converta seu código para usar APIs de E/S assíncronas em vez das de E/S de sincronização. Por exemplo, substitua chamadas para SaveChanges() por await SaveChangesAsync().

Microsoft. Data.SqlClient foi atualizado para 7.0

Comportamento antigo

EF Core 10 usou Microsoft.Data.SqlClient 6.x, que incluiu dependências de autenticação Azure/Entra ID (como Azure.Core, Azure.Identity e Microsoft.Identity.Client) no pacote principal.

Novo comportamento

O EF Core 11 agora depende de Microsoft. Data.SqlClient 7.0. Essa versão remove as dependências de autenticação Azure/Entra ID (anteriormente Azure Active Directory) do pacote principal. Se seu aplicativo usa Entra ID autenticação (por exemplo, ActiveDirectoryDefault, ActiveDirectoryInteractive, ActiveDirectoryManagedIdentity ou ActiveDirectoryServicePrincipal), agora você deve instalar o pacote Microsoft.Data.SqlClient.Extensions.Azure separadamente.

Além disso, SqlAuthenticationMethod.ActiveDirectoryPassword foi marcado como obsoleto.

Para obter mais detalhes, consulte o Microsoft. Notas de versão do Data.SqlClient 7.0.

Por que

Essa alteração foi feita em Microsoft.Data.SqlClient para reduzir o inchaço de dependências para aplicativos que não usam autenticação do Azure, o que é especialmente benéfico para implantação em contêiner e desenvolvimento local.

Atenuações

Se o aplicativo usa a autenticação Entra ID e SQL Server, adicione uma referência ao pacote Microsoft.Data.SqlClient.Extensions.Azure em seu projeto.

<PackageReference Include="Microsoft.Data.SqlClient.Extensions.Azure" Version="7.0.0" />

Nenhuma alteração de código é necessária além de adicionar essa referência de pacote. Se você usar SqlAuthenticationMethod.ActiveDirectoryPassword, migre para um método de autenticação moderno, como ActiveDirectoryDefault ou ActiveDirectoryInteractive.

Alterações de baixo impacto

O EF Core agora é gerado por padrão quando nenhuma migração é encontrada

Problema de acompanhamento nº 35218

Comportamento antigo

Anteriormente, ao chamar Migrate ou MigrateAsync em um banco de dados sem migrações no assembly, o EF Core registrava uma mensagem informativa e retornava sem aplicar nenhuma alteração.

Novo comportamento

A partir do EF Core 11.0, o EF Core gera uma exceção por padrão quando nenhuma migração é encontrada no assembly. Isso é consistente com o PendingModelChangesWarning comportamento introduzido no EF 9.0.

Por que

A chamada Migrate() ou MigrateAsync() quando nenhuma migração existe normalmente indica uma configuração incorreta. Em vez de continuar silenciosamente e deixar o banco de dados em um estado potencialmente incorreto, o EF Core agora alerta os desenvolvedores para esse problema imediatamente.

Atenuações

Se você chamar Migrate() intencionalmente sem ter nenhuma migração (por exemplo, caso você gerencie o esquema de banco de dados por outros meios), remova a chamada Migrate() ou suprima a exceção configurando os avisos:

options.ConfigureWarnings(w => w.Ignore(RelationalEventId.MigrationsNotFound))

Ou para registrar o evento, em vez de gerar.

options.ConfigureWarnings(w => w.Log(RelationalEventId.MigrationsNotFound))

EFOptimizeContext A propriedade MSBuild foi removida

Problema de acompanhamento nº 35079

Comportamento antigo

Anteriormente, a EFOptimizeContext propriedade MSBuild poderia ser definida para habilitar o true modelo compilado e a geração de código de consulta pré-compilado durante a build ou a publicação:

<EFOptimizeContext Condition="'$(Configuration)'=='Release'">true</EFOptimizeContext>

Novo comportamento

A partir do EF Core 11.0, a EFOptimizeContext propriedade MSBuild foi removida. A geração de código agora é controlada exclusivamente por meio das propriedades EFScaffoldModelStage e EFPrecompileQueriesStage. Quando PublishAOT está definido como true, a geração de código é habilitada automaticamente durante a publicação sem precisar de nenhuma propriedade adicional.

Por que

As propriedades EFScaffoldModelStage e EFPrecompileQueriesStage já fornecem controle refinado sobre quando ocorre a geração de código. EFOptimizeContext era uma porta de habilitação redundante.

Atenuações

Substitua os usos de EFOptimizeContext pelas propriedades EFScaffoldModelStage e EFPrecompileQueriesStage. Estas podem ser definidas como publish ou build para controlar em qual estágio a geração de código ocorre.

<EFScaffoldModelStage>publish</EFScaffoldModelStage>
<EFPrecompileQueriesStage>publish</EFPrecompileQueriesStage>

Qualquer outro valor (por exemplo, none) desabilita a geração correspondente.

Se você tiver PublishAOT definido como true, a geração de código será habilitada automaticamente durante a publicação e nenhuma configuração adicional será necessária.

Os pacotes de ferramentas EF não fazem mais referência Microsoft.EntityFrameworkCore.Design

Problema de acompanhamento nº 37739

Comportamento antigo

Anteriormente, os pacotes NuGet Microsoft.EntityFrameworkCore.Tools e Microsoft.EntityFrameworkCore.Tasks tinham uma dependência de Microsoft.EntityFrameworkCore.Design.

Novo comportamento

A partir do EF Core 11.0, os pacotes NuGet Microsoft.EntityFrameworkCore.Tools e Microsoft.EntityFrameworkCore.Tasks não têm mais dependência de Microsoft.EntityFrameworkCore.Design.

Por que

Não havia nenhuma dependência rígida no código em Microsoft.EntityFrameworkCore.Design, e essa dependência estava causando problemas ao usar o Microsoft.EntityFrameworkCore.Tools mais recente com projetos direcionados a estruturas mais antigas.

Atenuações

Se o projeto depender de Microsoft.EntityFrameworkCore.Design sendo trazido transitivamente por meio dos pacotes de ferramentas, adicione uma referência direta em seu projeto.

<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="11.0.0" PrivateAssets="all" />

As propriedades do SqlVector não são mais carregadas por padrão

Problema de acompanhamento nº 37279

Comportamento antigo

Anteriormente, ao consultar entidades com propriedades SqlVector<T>, EF Core incluía a coluna de vetor em declarações SELECT e preenchia a propriedade da entidade retornada.

Novo comportamento

A partir do EF Core 11.0, as propriedades SqlVector<T> não são mais incluídas em declarações SELECT ao materializar entidades. A propriedade será null nas entidades retornadas.

As propriedades de vetor ainda podem ser usadas em WHERE e em cláusulasORDER BY, incluindo com VectorDistance() e VectorSearch(), mas elas simplesmente não serão incluídas na projeção de entidade.

Por que

As colunas de vetor podem ser muito grandes, contendo centenas ou milhares de valores de ponto flutuante. Na grande maioria dos casos, os vetores são gravados no banco de dados e, em seguida, usados para pesquisa, sem a necessidade de serem lidos novamente. Excluí-los do SELECT por padrão evita a transferência desnecessária de dados.

Atenuações

Observação

Um mecanismo que permite escolher que propriedades de vetor sejam novamente carregadas automaticamente será introduzido posteriormente na versão 11 do EF Core.

Se você precisar ler valores de vetor de volta, use uma projeção explícita:

var embeddings = await context.Blogs
    .Select(b => new { b.Id, b.Embedding })
    .ToListAsync();

Cosmos: conjuntos de propriedade vazios agora retornam um conjunto vazio, em vez de nulo

Problema de acompanhamento nº 36577

Comportamento antigo

Anteriormente, ao consultar entidades por meio do provedor do Azure Cosmos DB em que um conjunto próprio não continha itens, a propriedade do conjunto estava null na entidade materializada.

Novo comportamento

A partir do EF Core 11.0, o provedor de Azure Cosmos DB inicializa corretamente coleções de propriedade vazias, retornando uma coleção vazia em vez de null.

Por que

O comportamento anterior de materializar conjuntos vazios de propriedade como null constituiu um erro.

Atenuações

Se o seu código verificar explicitamente as propriedades do conjunto de sua propriedade para null detectar que o conjunto está vazio, essas verificações poderão ser simplesmente removidas, pois o conjunto agora é sempre inicializado.

// Before
if (entity.OwnedCollection is null or { Count: 0 })
{
    // treated as empty
}

// After
if (entity.OwnedCollection is { Count: 0 })
{
    // treated as empty
}

Alterações interruptivas do Microsoft.Data.Sqlite

Observação

SQLitePCLRaw é uma biblioteca externa mantida pela comunidade que não pertence nem é mantida por Microsoft. Microsoft.Data.Sqlite depende dele para se conectar ao SQLite.

Resumo

Alteração interruptiva Impact
Os pacotes SQLite habilitados para criptografia foram removidos Medium
Alguns pacotes de pacote SQLitePCLRaw foram removidos Medium

Alterações de impacto médio

Os pacotes SQLite habilitados para criptografia foram removidos

Acompanhamento do problema #5108

Comportamento antigo

Anteriormente, o SQLitePCLRaw.bundle_e_sqlcipher pacote NuGet fornecia builds SQLite com criptografia habilitada sem custo.

Novo comportamento

Começando com SQLitePCLRaw 3.0 (usado por Microsoft. Data.Sqlite 11.0), o pacote SQLitePCLRaw.bundle_e_sqlcipher foi preterido e removido do NuGet. Os builds SQLite habilitados para criptografia sem custo não são mais distribuídos.

Por que

O pacote sem custo SQLitePCLRaw.bundle_e_sqlcipher anterior não foi devidamente mantido, o que é uma preocupação significativa para o software de criptografia, onde as vulnerabilidades de segurança podem ficar sem correção. O mantenedor SQLitePCLRaw removeu esses builds na versão 3.0 em favor de alternativas pagas e mantidas profissionalmente que fornecem atualizações de segurança contínuas.

Atenuações

Se você precisar de criptografia SQLite, terá as seguintes opções:

Para obter mais detalhes, consulte Opções de Criptografia SQLite para uso com SQLitePCLRaw e Notas de Versão SQLitePCLRaw 3.0.

Alguns pacotes de pacote SQLitePCLRaw foram removidos

Acompanhamento do problema #5108

Comportamento antigo

Anteriormente, os pacotes SQLitePCLRaw.bundle_sqlite3, SQLitePCLRaw.bundle_winsqlite3, SQLitePCLRaw.bundle_green e SQLitePCLRaw.bundle_e_sqlite3mc forneceram uma maneira conveniente de configurar o SQLitePCLRaw com o provedor SQLite correspondente.

Novo comportamento

A partir do SQLitePCLRaw 3.0 (usado pelo Microsoft.Data.Sqlite 11.0), esses pacotes foram removidos. Se o aplicativo dependesse de um desses pacotes, agora você deverá referenciar o pacote de provedor correspondente e inicializá-lo explicitamente.

Por que

Cada um desses pacotes de pacote continha apenas uma única linha de código de configuração e adicionava sobrecarga de empacotamento desnecessária. Os pacotes de provedor correspondentes ainda têm suporte.

Atenuações

Substitua o pacote de pacote removido pelo pacote do provedor correspondente e adicione o código de inicialização explícito.

Se estiver usando bundle_sqlite3 ou bundle_winsqlite3, substitua a referência do pacote:

<!-- Old -->
<PackageReference Include="SQLitePCLRaw.bundle_sqlite3" Version="2.x.x" />
<!-- or -->
<PackageReference Include="SQLitePCLRaw.bundle_winsqlite3" Version="2.x.x" />

<!-- New -->
<PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="3.x.x" />
<!-- or -->
<PackageReference Include="SQLitePCLRaw.provider.winsqlite3" Version="3.x.x" />

Em seguida, adicione a inicialização explícita antes de usar o SQLite:

// For sqlite3
static void Init()
{
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
}

// For winsqlite3
static void Init()
{
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_winsqlite3());
}

Se estiver usando bundle_green, o caminho de migração recomendado será alternar para SQLitePCLRaw.bundle_e_sqlite3. Como alternativa, use SQLitePCLRaw.config.e_sqlite3 emparelhado com um pacote de biblioteca nativa separado, como SourceGear.sqlite3, que permite que você atualize a versão do SQLite de forma independente:

<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="3.x.x" />

Se você objetivar apenas iOS e quiser continuar usando a biblioteca SQLite do sistema, referencie o provedor diretamente:

<PackageReference Include="SQLitePCLRaw.core" Version="3.x.x" />
<PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="3.x.x" />

E inicialize-o explicitamente:

static void Init()
{
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
}

Observação

Se você estiver usando SQLitePCLRaw.bundle_e_sqlite3, nenhuma alteração será necessária, basta atualizar o número da versão. Consulte as Notas de Versão do SQLitePCLRaw 3.0 para obter detalhes.

  • Last updated on