Changements cassants dans EF Core 11 (EF11)

Cette page documente les modifications d’API et de comportement susceptibles d’interrompre la mise à jour des applications existantes d’EF Core 10 vers EF Core 11. Veillez à passer en revue les modifications majeures antérieures lorsque vous mettez à jour à partir d'une version précédente d'EF Core.

• Changements cassants dans EF Core 10
• Modifications importantes dans EF Core 9
• Changements cassants dans EF Core 8

Résumé

Changements à impact moyen

L’E/S de synchronisation via le fournisseur Cosmos DB d'Azure a été entièrement supprimée.

Problème de suivi #37059

Ancien comportement

Les E/S synchrones via le fournisseur de Azure Cosmos DB n’ont pas été prises en charge depuis EF 9.0 (note) ; l’appel d’une API d’E/S de synchronisation , comme ToList ou SaveChanges a levé une exception, sauf si une option spéciale a été configurée. Lorsque l'activation a été configurée, les API d'E/S de synchronisation fonctionnaient comme auparavant, ce qui amenait le fournisseur à effectuer un blocage « sync-over-async » dans le cadre du SDK Azure Cosmos DB, susceptible de provoquer des interblocages et d'autres problèmes de performances.

Nouveau comportement

À partir d’EF Core 11.0, EF génère toujours une exception si une API d’E/S synchrone est appelée. Il n’existe aucun moyen de revenir à l’utilisation des API d’E/S de synchronisation.

Pourquoi

Le blocage synchrone sur les méthodes asynchrones (« sync-over-async ») est fortement déconseillé et peut entraîner des blocages et d’autres problèmes de performances. Étant donné que le SDK Azure Cosmos DB ne prend en charge que les méthodes asynchrones, le fournisseur EF Cosmos fait de même.

Atténuation

Convertissez votre code pour utiliser des API d’E/S asynchrones plutôt que des API d’E/S de synchronisation. Par exemple, remplacez les appels à SaveChanges() par des appels à await SaveChangesAsync().

Microsoft. Data.SqlClient a été mis à jour vers la version 7.0

Ancien comportement

EF Core 10 utilisait Microsoft.Data.SqlClient 6.x, qui incluait des dépendances d’authentification Azure/Entra ID (telles que Azure.Core, Azure.Identity et Microsoft.Identity.Client) dans le paquet principal.

Nouveau comportement

EF Core 11 dépend désormais de Microsoft. Data.SqlClient 7.0. Cette version supprime les dépendances d’authentification Azure/Entra ID (anciennement Azure Active Directory) du package principal. Si votre application utilise l’authentification Entra ID (par exemple, ActiveDirectoryDefault, ActiveDirectoryInteractive, ActiveDirectoryManagedIdentity ou ActiveDirectoryServicePrincipal), vous devez maintenant installer le package Microsoft.Data.SqlClient.Extensions.Azure séparément.

De plus, SqlAuthenticationMethod.ActiveDirectoryPassword a été défini comme obsolète.

Pour plus d’informations, consultez les notes de version de Microsoft.Data.SqlClient 7.0.

Pourquoi

Cette modification a été apportée dans Microsoft. Data.SqlClient pour réduire le ballonnement des dépendances pour les applications qui n'utilisent pas l'authentification Azure, ce qui est particulièrement bénéfique pour les déploiements en conteneur et le développement local.

Atténuation

Si votre application utilise l’authentification Entra ID avec SQL Server, ajoutez une référence au package Microsoft.Data.SqlClient.Extensions.Azure dans votre projet :

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

Aucune modification du code n’est requise au-delà de l’ajout de cette référence de package. Si vous utilisez SqlAuthenticationMethod.ActiveDirectoryPassword, migrez vers une méthode d’authentification moderne telle que ActiveDirectoryDefault ou ActiveDirectoryInteractive.

Modifications à faible impact

EF Core renvoie désormais une exception par défaut lorsqu'aucune migration n'est trouvée

Suivi du problème #35218

Ancien comportement

Auparavant, lors de l’appel Migrate ou MigrateAsync sur une base de données sans migrations dans l’assembly, EF Core a enregistré un message d’information et retourné sans appliquer de modifications.

Nouveau comportement

À compter d’EF Core 11.0, EF Core lève une exception par défaut lorsqu’aucune migration n’est trouvée dans l’assembly. Cela est cohérent avec le PendingModelChangesWarning comportement introduit dans EF 9.0.

Pourquoi

L’appel Migrate() ou MigrateAsync() le moment où aucune migration n’existe indique généralement une mauvaise configuration. Au lieu de continuer silencieusement et de laisser la base de données dans un état potentiellement incorrect, EF Core avertit désormais les développeurs de ce problème immédiatement.

Atténuation

Si vous appelez Migrate() intentionnellement sans avoir de migrations (par exemple, car vous gérez le schéma de base de données par d’autres moyens), supprimez l’appel Migrate() ou supprimez l’exception en configurant des avertissements :

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

Ou pour consigner l’événement au lieu de lever :

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

EFOptimizeContext La propriété MSBuild a été supprimée

Problème de suivi #35079

Ancien comportement

Auparavant, la EFOptimizeContext propriété MSBuild pouvait être définie pour true activer la génération de code de modèle compilé et de requête précompilée pendant la génération ou la publication :

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

Nouveau comportement

À compter d’EF Core 11.0, la EFOptimizeContext propriété MSBuild a été supprimée. La génération de code est désormais contrôlée exclusivement par les propriétés EFScaffoldModelStage et EFPrecompileQueriesStage. Quand PublishAOT est défini sur true, la génération de code est automatiquement activée pendant la publication sans nécessiter de propriété supplémentaire.

Pourquoi

Les propriétés EFScaffoldModelStage et EFPrecompileQueriesStage offrent déjà un contrôle détaillé sur le moment où la génération de code se produit. EFOptimizeContext était une porte d’activation redondante.

Atténuation

Remplacez les utilisations de EFOptimizeContext par les propriétés EFScaffoldModelStage et EFPrecompileQueriesStage. Celles-ci peuvent être définies sur publish ou build pour contrôler à quel stade la génération de code se produit :

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

Toute autre valeur (par exemple) nonedésactive la génération correspondante.

Si vous avez PublishAOT défini sur true, la génération de code est automatiquement activée lors de la publication et aucune configuration supplémentaire n’est nécessaire.

Les packages d’outils EF ne font plus référence à Microsoft.EntityFrameworkCore.Design

Suivi du problème #37739

Ancien comportement

Auparavant, les packages NuGet Microsoft.EntityFrameworkCore.Tools et Microsoft.EntityFrameworkCore.Tasks avaient une dépendance sur Microsoft.EntityFrameworkCore.Design.

Nouveau comportement

À compter d’EF Core 11.0, les packages NuGet Microsoft.EntityFrameworkCore.Tools et Microsoft.EntityFrameworkCore.Tasks n’ont plus de dépendance sur Microsoft.EntityFrameworkCore.Design.

Pourquoi

Il n’y avait aucune dépendance difficile sur le code dans Microsoft.EntityFrameworkCore.Design, et cette dépendance causait des problèmes lors de l’utilisation de la dernière Microsoft.EntityFrameworkCore.Tools avec des projets ciblant des infrastructures plus anciennes.

Atténuation

Si votre projet s’appuie sur Microsoft.EntityFrameworkCore.Design mis en transitivement par le biais des packages d’outils, ajoutez une référence directe à celui-ci dans votre projet :

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

Les propriétés SqlVector ne sont plus chargées par défaut

Problème de suivi #37279

Ancien comportement

Auparavant, lors de l’interrogation d’entités avec SqlVector<T> propriétés, EF Core incluait la colonne vectorielle dans SELECT les instructions et attribuait la propriété à l’entité retournée.

Nouveau comportement

À compter d’EF Core 11.0, SqlVector<T> les propriétés ne sont plus incluses dans SELECT les instructions lors de la matérialisation des entités. La propriété sera null sur les entités retournées.

Les propriétés de vecteur peuvent toujours être utilisées dans WHERE et ORDER BY dans des clauses, y compris avec VectorDistance() et VectorSearch(); elles ne seront simplement pas incluses dans la projection d’entité.

Pourquoi

Les colonnes vectorielles peuvent être très volumineuses, contenant des centaines ou des milliers de valeurs à virgule flottante. Dans la grande majorité des cas, les vecteurs sont écrits dans la base de données, puis utilisés pour la recherche, sans avoir à être lus. L’exclusion de SELECT ces données par défaut évite le transfert de données inutile.

Atténuation

Si vous avez besoin de lire des valeurs vectorielles de retour, utilisez une projection explicite :

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

Cosmos : les collections détenues vides retournent désormais une collection vide au lieu de null

Problème de suivi #36577

Ancien comportement

Auparavant, lorsque des entités étaient interrogées via le fournisseur Azure Cosmos DB et qu'une collection possédée ne contenait aucun élément, la propriété de collection était null dans l'entité matérialisée.

Nouveau comportement

À compter d’EF Core 11.0, le fournisseur de Azure Cosmos DB initialise correctement les collections détenues vides, retournant une collection vide au lieu de null.

Pourquoi

Le comportement précédent consistant à matérialiser des collections vides appartenant à quelqu'un comme null était un bogue.

Atténuation

Si votre code vérifie explicitement les propriétés de collection appartenant à pour détecter si la collection est vide après null, ces vérifications peuvent simplement être supprimées, car la collection est désormais toujours initialisée.

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

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

Changements cassants de Microsoft.Data.Sqlite

Résumé

Changements à impact moyen

Des packages SQLite compatibles avec le chiffrement ont été supprimés

Problème de suivi #5108

Ancien comportement

Auparavant, le SQLitePCLRaw.bundle_e_sqlcipher package NuGet fournissait des builds SQLite compatibles avec le chiffrement sans coût.

Nouveau comportement

À compter de SQLitePCLRaw 3.0 (utilisé par Microsoft. Data.Sqlite 11.0), le package SQLitePCLRaw.bundle_e_sqlcipher a été déconseillé et supprimé de NuGet. Les versions SQLite avec chiffrement gratuites ne sont plus distribuées.

Pourquoi

Le package précédent sans coût SQLitePCLRaw.bundle_e_sqlcipher a été à peine maintenu, ce qui est une préoccupation importante pour les logiciels de chiffrement où les vulnérabilités de sécurité peuvent ne pas être corrigées. L’éditeur de maintenance SQLitePCLRaw a supprimé ces builds dans la version 3.0 en faveur d’alternatives payantes gérées professionnellement qui fournissent des mises à jour de sécurité en cours.

Atténuation

Si vous avez besoin du chiffrement SQLite, vous disposez des options suivantes :

• Extension de chiffrement SQLite (SEE) : il s’agit de l’implémentation officielle du chiffrement de l’équipe SQLite. Une licence payante est requise. Pour plus d’informations, consultez https://sqlite.org/com/see.html. Les packages NuGet sont disponibles via le service de build SQLite de SourceGear.
• SQLCipher : achetez les builds prises en charge à partir de Zetetic ou générez le code open source vous-même.
• SQLite3 Multiple Ciphers : les packages NuGet sont disponibles à partir de SQLite3MultipleCiphers-NuGet.
  • Lors du chiffrement d’une nouvelle base de données ou de l’ouverture d’une base de données existante chiffrée avec SQLCipher, vous devez configurer le schéma de chiffrement dans l’chaîne de connexion à l’aide de paramètres d’URI, par exemple : Data Source=file:example.db?cipher=sqlcipher&legacy=4;Password=<password>. Découvrez comment ouvrir une base de données existante chiffrée avec SQLCipher pour plus d’informations.

Pour plus d’informations, consultez les options de chiffrement SQLite à utiliser avec SQLitePCLRaw et SQLitePCLRaw 3.0 Release Notes.

Certains packages de bundle SQLitePCLRaw ont été supprimés

Problème de suivi #5108

Ancien comportement

Auparavant, les paquets SQLitePCLRaw.bundle_sqlite3, SQLitePCLRaw.bundle_winsqlite3, SQLitePCLRaw.bundle_green, et SQLitePCLRaw.bundle_e_sqlite3mc fournissaient un moyen pratique de configurer SQLitePCLRaw avec le fournisseur SQLite correspondant.

Nouveau comportement

À compter de SQLitePCLRaw 3.0 (utilisé par Microsoft. Data.Sqlite 11.0), ces packages groupés ont été supprimés. Si votre application dépend de l’un de ces bundles, vous devez maintenant référencer le package de fournisseur correspondant et l’initialiser explicitement.

Pourquoi

Chacun de ces packages groupés ne contenait qu’une seule ligne de code de configuration et ajoutait une surcharge d’empaquetage inutile. Les packages de fournisseur correspondants sont toujours pris en charge.

Atténuation

Remplacez le package groupé supprimé par le package fournisseur correspondant et ajoutez du code d’initialisation explicite.

Si vous utilisez bundle_sqlite3 ou bundle_winsqlite3remplacez la référence du package :

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

Ajoutez ensuite une initialisation explicite avant d’utiliser 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());
}

Si vous utilisez bundle_green, le chemin de migration recommandé est de basculer vers SQLitePCLRaw.bundle_e_sqlite3. Vous pouvez également utiliser SQLitePCLRaw.config.e_sqlite3 couplé avec une bibliothèque native distincte comme SourceGear.sqlite3, ce qui vous permet de mettre à jour la version SQLite indépendamment :

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

Si vous ciblez uniquement iOS et que vous souhaitez continuer à utiliser la bibliothèque SQLite système, référencez directement le fournisseur :

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

Initialisez-le explicitement :

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