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

Esta página documenta as alterações de API e comportamento que têm o potencial de interromper a atualização de aplicativos existentes do EF Core 10 para o EF Core 11. Certifique-se de revisar as alterações disruptivas anteriores se estiver a atualizar a partir de uma versão anterior do EF Core.

• Mudanças significativas no EF Core 10
• Mudanças significativas no EF Core 9
• Mudanças significativas no EF Core 8

Resumo

Alterações de impacto médio

A I/O de sincronização via o fornecedor Azure Cosmos DB foi totalmente removida

Problema de rastreamento #37059

Comportamento antigo

A E/S síncrona através do fornecedor Azure Cosmos DB não é suportada desde o EF 9.0 (note); chamar qualquer API de E/S síncrona – como ToList ou SaveChanges lançou uma exceção, exceto se um opt-in especial tiver sido configurado. Quando o opt-in estava configurado, as APIs de entrada/saída de sincronização funcionavam como antes, levando o fornecedor a executar bloqueios "sync-over-async" contra o Azure Cosmos DB SDK, o que podia resultar em deadlocks e outros problemas de desempenho.

Novo comportamento

A partir do EF Core 11.0, o EF agora sempre é lançado quando uma API de E/S síncrona é chamada. Não há como optar novamente pelo uso de APIs de E/S de sincronização.

Porquê

O bloqueio síncrono em métodos assíncronos ("sync-over-async") é altamente desencorajado e pode levar a deadlock e outros problemas de desempenho. Como o Azure Cosmos DB SDK só suporta métodos assíncronos, o fornecedor EF Cosmos também o faz.

Atenuações

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

Microsoft. O Data.SqlClient foi atualizado para a versão 7.0

Comportamento antigo

EF Core 10 usou Microsoft.Data.SqlClient 6.x, que incluía 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 do Microsoft. Data.SqlClient 7.0. Esta versão remove as dependências de autenticação do Azure/Entra ID (anteriormente Azure Active Directory) do pacote principal. Se a sua aplicação usar autenticação Entra ID (por exemplo, ActiveDirectoryDefault, ActiveDirectoryInteractive, ActiveDirectoryManagedIdentity ou ActiveDirectoryServicePrincipal), deve agora instalar o pacote Microsoft.Data.SqlClient.Extensions.Azure separadamente.

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

Para mais detalhes, consulte o Microsoft. Data.SqlClient 7.0 notas de lançamento.

Porquê

Esta alteração foi feita em Microsoft. Data.SqlClient para reduzir o excesso de dependências em aplicações que não utilizam autenticação Azure, o que é especialmente benéfico para implementações containerizadas e desenvolvimento local.

Atenuações

Se a sua aplicação usar autenticação Entra ID com SQL Server, adicione uma referência ao pacote Microsoft.Data.SqlClient.Extensions.Azure no seu projeto:

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

Não são necessárias alterações de código para além de adicionar esta referência de pacote. Se usar SqlAuthenticationMethod.ActiveDirectoryPassword, migre para um método moderno de autenticação como ActiveDirectoryDefault ou ActiveDirectoryInteractive.

Alterações de baixo impacto

O EF Core agora lança por padrão quando não são encontradas migrações

Problema de Rastreio #35218

Comportamento antigo

Anteriormente, ao chamar Migrate ou MigrateAsync numa base de dados sem migrações no assembly, o EF Core registava uma mensagem informativa e devolvia sem aplicar quaisquer alterações.

Novo comportamento

A partir do EF Core 11.0, uma exceção é lançada por padrão quando não são encontradas migrações na assemblagem. Isto é consistente com o PendingModelChangesWarning comportamento introduzido no EF 9.0.

Porquê

Chamar Migrate() ou MigrateAsync() quando não existem migrações normalmente indica uma má configuração. Em vez de continuar silenciosamente e deixar a base de dados num estado potencialmente incorreto, o EF Core agora alerta imediatamente os programadores para este problema.

Atenuações

Se chamar Migrate() intencionalmente sem qualquer migração (por exemplo, porque gere o esquema da base de dados por outros meios), remova a chamada Migrate() ou suprima a exceção configurando avisos:

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

Ou para registar o evento em vez de lançar:

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

EFOptimizeContext Propriedade MSBuild foi removida

Problema de Rastreamento #35079

Comportamento antigo

Anteriormente, a EFOptimizeContext propriedade MSBuild podia ser definida para true permitir a geração de modelos compilados e códigos de consulta pré-compilados durante a compilação ou 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 através das propriedades EFScaffoldModelStage e EFPrecompileQueriesStage. Quando PublishAOT está definido para true, a geração de código é automaticamente ativada durante a publicação, sem necessidade de qualquer propriedade adicional.

Porquê

As EFScaffoldModelStage propriedades e EFPrecompileQueriesStage já fornecem controlo detalhado sobre quando ocorre a geração de código. EFOptimizeContext era uma porta lógica de ativação redundante.

Atenuações

Substitua os usos de EFOptimizeContext pelas propriedades EFScaffoldModelStage e EFPrecompileQueriesStage. Estes podem ser definidos para publish ou build para controlar em que etapa ocorre a geração de código:

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

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

Se tiver PublishAOT definido para true, a geração de código é automaticamente ativada durante a publicação e não é necessária qualquer configuração adicional.

Os pacotes EF Tools já não fazem referência a Microsoft.EntityFrameworkCore.Design

Problema de Rastreamento #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 já não dependem do Microsoft.EntityFrameworkCore.Design.

Porquê

Não havia dependência rígida do código em Microsoft.EntityFrameworkCore.Design, e essa dependência estava a causar problemas ao usar a versão mais recente de Microsoft.EntityFrameworkCore.Tools com projetos que têm como alvo frameworks mais antigos.

Atenuações

Se o seu projeto depende de Microsoft.EntityFrameworkCore.Design ser introduzido de forma transitiva através dos pacotes de ferramentas, adicione uma referência direta a ele no seu projeto:

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

As propriedades do SqlVector já não são carregadas por defeito

Problema de Rastreio #37279

Comportamento antigo

Anteriormente, ao consultar entidades com SqlVector<T> propriedades, o EF Core incluía a coluna vetorial nas SELECT instruções e preenchia a propriedade na entidade retornada.

Novo comportamento

A partir do EF Core 11.0, as propriedades SqlVector<T> deixaram de ser incluídas nas declarações SELECT ao materializar entidades. A propriedade estará null nas entidades devolvidas.

As propriedades vetoriais ainda podem ser usadas nas cláusulas WHERE e ORDER BY, incluindo VectorDistance() e VectorSearch(); no entanto, não serão incluídas na projeção da entidade.

Porquê

As colunas vetoriais podem ser muito grandes, contendo centenas ou milhares de valores de ponto flutuante. Na grande maioria dos casos, os vetores são escritos na base de dados e depois usados para pesquisa, sem necessidade de serem lidos. Excluir SELECT por defeito evita a transferência desnecessária de dados.

Atenuações

Se precisar de ler valores vetoriais, use uma projeção explícita:

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

Cosmos: coleções vazias pertencentes agora devolvem uma coleção vazia em vez de null

Problema de Rastreio #36577

Comportamento antigo

Anteriormente, ao consultar entidades através do fornecedor Azure Cosmos DB onde uma coleção detida não continha itens, a propriedade da coleção era null na entidade materializada.

Novo comportamento

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

Porquê

O comportamento anterior de materializar coleções vazias próprias como null era um bug.

Atenuações

Se o seu código verificar explicitamente as propriedades da coleção para null detetar que a coleção está vazia, essas verificações podem simplesmente ser removidas, uma vez que a coleção está agora sempre inicializada:

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

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

Microsoft.Data.Sqlite alterações de quebra

Resumo

Alterações de impacto médio

Os pacotes SQLite com encriptação foram removidos

Problema de Seguimento #5108

Comportamento antigo

Anteriormente, o SQLitePCLRaw.bundle_e_sqlcipher pacote NuGet fornecia builds SQLite com encriptação sem custos.

Novo comportamento

Começando com SQLitePCLRaw 3.0 (usado pela Microsoft. Data.Sqlite 11.0), o pacote SQLitePCLRaw.bundle_e_sqlcipher foi obsoleto e removido do NuGet. As compilações SQLite com encriptação e sem custos deixaram de ser distribuídas.

Porquê

O anterior pacote gratuito SQLitePCLRaw.bundle_e_sqlcipher era mal mantido, o que é uma preocupação significativa para software de encriptação, onde vulnerabilidades de segurança podem não ser corrigidas. O mantenedor SQLitePCLRaw removeu estas compilações 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 precisar de encriptação SQLite, tem as seguintes opções:

• Extensão de Encriptação SQLite (SEE): Esta é a implementação oficial de encriptação da equipa SQLite. É necessária uma licença paga. Consulte https://sqlite.org/com/see.html para obter detalhes. Os pacotes NuGet estão disponíveis através do serviço de compilação SQLite do SourceGear.
• SQLCipher: Compre compilações suportadas de Zetetic, ou construa o código open source você mesmo.
• SQLite3 Múltiplas Cifras: Os pacotes NuGet estão disponíveis em SQLite3MultipleCiphers-NuGet.
  • Ao encriptar uma nova base de dados ou abrir uma base de dados existente encriptada com SQLCipher, deve configurar o esquema de cifra no cadeia de ligação usando parâmetros URI — por exemplo: Data Source=file:example.db?cipher=sqlcipher&legacy=4;Password=<password>. Veja Como abrir uma base de dados existente encriptada com SQLCipher para mais detalhes.

Para mais detalhes, consulte as opções de encriptação do SQLite para utilização com as Notas de Lançamento do SQLitePCLRaw e SQLitePCLRaw 3.0.

Alguns pacotes agrupados SQLitePCLRaw foram removidos

Problema de Seguimento #5108

Comportamento antigo

Anteriormente, os pacotes SQLitePCLRaw.bundle_sqlite3, SQLitePCLRaw.bundle_winsqlite3, SQLitePCLRaw.bundle_green, e SQLitePCLRaw.bundle_e_sqlite3mc forneciam uma forma conveniente de configurar convenientemente o SQLitePCLRaw com o fornecedor SQLite correspondente.

Novo comportamento

Começando com SQLitePCLRaw 3.0 (usado pela Microsoft. Data.Sqlite 11.0), estes pacotes foram removidos. Se a sua aplicação dependesse de um destes pacotes, deve agora referenciar o pacote de fornecedores correspondente e inicializá-lo explicitamente.

Porquê

Cada um destes pacotes continha apenas uma linha de código de configuração e acrescentava sobrecarga desnecessária ao empacotamento. Os pacotes de fornecedores correspondentes continuam a ser suportados.

Atenuações

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

Se usar bundle_sqlite3 ou bundle_winsqlite3, substitua a referência da embalagem:

<!-- 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" />

Depois, adicione inicialização explícita antes de usar 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 usar bundle_green, o caminho de migração recomendado é mudar para SQLitePCLRaw.bundle_e_sqlite3. Em alternativa, use SQLitePCLRaw.config.e_sqlite3 emparelhado com um pacote de biblioteca nativo separado como SourceGear.sqlite3, que permite atualizar a versão SQLite de forma independente:

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

Se só tem como objetivo iOS e quiser continuar a usar a biblioteca SQLite do sistema, consulte diretamente o fornecedor:

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

E inicializá-lo explicitamente:

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