La mise à niveau des applications à partir de versions précédentes vers EF Core 2.0Upgrading applications from previous versions to EF Core 2.0

Nous avons saisi l’occasion pour affiner considérablement nos API existantes et les comportements de 2.0.We have taken the opportunity to significantly refine our existing APIs and behaviors in 2.0. Il existe quelques améliorations qui peuvent nécessiter la modification du code d’application existant, même si nous pensons que pour la majorité des applications l’impact sera faible, dans la plupart des cas nécessitant la recompilation et modifications guidées minimales pour remplacer les API obsolètes.There are a few improvements that can require modifying existing application code, although we believe that for the majority of applications the impact will be low, in most cases requiring just recompilation and minimal guided changes to replace obsolete APIs.

Procédures est courant de toutes les ApplicationsProcedures Common to All Applications

La mise à jour une application existante vers EF Core 2.0 peut nécessiter :Updating an existing application to EF Core 2.0 may require:

  1. La mise à niveau de la plateforme .NET cible de l’application pour qu’il prend en charge .NET Standard 2.0.Upgrading the target .NET platform of the application to one that supports .NET Standard 2.0. Consultez plateformes prises en charge pour plus d’informations.See Supported Platforms for more details.

  2. Identifier un fournisseur pour la base de données cible qui est compatible avec EF Core 2.0.Identify a provider for the target database which is compatible with EF Core 2.0. Consultez EF Core 2.0 requiert un fournisseur de base de 2.0 données ci-dessous.See EF Core 2.0 requires a 2.0 database provider below.

  3. Mise à niveau tous les packages EF Core (runtime et des outils) vers la version 2.0.Upgrading all the EF Core packages (runtime and tooling) to 2.0. Reportez-vous à installation d’EF Core pour plus d’informations.Refer to Installing EF Core for more details.

  4. Apporter des modifications de code nécessaire pour compenser les dernières modifications.Make any necessary code changes to compensate for breaking changes. Consultez le modifications avec rupture section ci-dessous pour plus d’informations.See the Breaking Changes section below for more details.

Applications ASP.NET CoreASP.NET Core applications

  1. Consultez en particulier le nouveau modèle pour l’initialisation du fournisseur de service de l’application décrites ci-dessous.See in particular the new pattern for initializing the application's service provider described below.

Conseil

L’adoption de ce nouveau modèle lors de la mise à jour des applications vers la version 2.0 est vivement recommandée et est obligatoire pour les fonctionnalités de produit, comme des Migrations Entity Framework Core fonctionne.The adoption of this new pattern when updating applications to 2.0 is highly recommended and is required in order for product features like Entity Framework Core Migrations to work. L’autre alternative courante consiste à implémenter IDesignTimeDbContextFactory<TContext >.The other common alternative is to implement IDesignTimeDbContextFactory<TContext>.

  1. Les applications ciblant ASP.NET Core 2.0 peuvent utiliser EF Core 2.0 sans dépendances supplémentaires en plus des fournisseurs de base de données tiers.Applications targeting ASP.NET Core 2.0 can use EF Core 2.0 without additional dependencies besides third party database providers. Toutefois, les applications ciblant des versions antérieures d’ASP.NET Core doivent mettre à niveau vers ASP.NET Core 2.0 pour pouvoir utiliser EF Core 2.0.However, applications targeting previous versions of ASP.NET Core need to upgrade to ASP.NET Core 2.0 in order to use EF Core 2.0. Pour plus d’informations sur la mise à niveau vers la version 2.0, les applications ASP.NET Core, consultez la documentation ASP.NET Core sur le sujet.For more details on upgrading ASP.NET Core applications to 2.0 see the ASP.NET Core documentation on the subject.

Nouvelle façon d’obtenir des services d’applicationNew way of getting application services

Le modèle recommandé pour les applications web ASP.NET Core a été mis à jour pour 2.0 d’une manière qui a interrompu la logique au moment du design QU'EF Core est utilisé dans la version 1.x.The recommended pattern for ASP.NET Core web applications has been updated for 2.0 in a way that broke the design-time logic EF Core used in 1.x. Précédemment au moment du design, EF Core tentait d’appeler Startup.ConfigureServices directement afin d’accéder au fournisseur de service de l’application.Previously at design-time, EF Core would try to invoke Startup.ConfigureServices directly in order to access the application's service provider. Dans ASP.NET Core 2.0, la Configuration est initialisée à l’extérieur de la Startup classe.In ASP.NET Core 2.0, Configuration is initialized outside of the Startup class. Applications à l’aide d’EF Core généralement accèdent leur chaîne de connexion à partir de la Configuration, Startup en lui-même n’est plus suffisante.Applications using EF Core typically access their connection string from Configuration, so Startup by itself is no longer sufficient. Si vous mettez à niveau une application 1.x de ASP.NET Core, vous pouvez recevoir l’erreur suivante lorsque vous utilisez les outils EF Core.If you upgrade an ASP.NET Core 1.x application, you may receive the following error when using the EF Core tools.

Aucun constructeur sans paramètre a été trouvé sur « ApplicationContext ».No parameterless constructor was found on 'ApplicationContext'. Ajoutez un constructeur sans paramètre à « ApplicationContext » ou ajouter une implémentation de « IDesignTimeDbContextFactory<ApplicationContext>» dans le même assembly que 'ApplicationContext'Either add a parameterless constructor to 'ApplicationContext' or add an implementation of 'IDesignTimeDbContextFactory<ApplicationContext>' in the same assembly as 'ApplicationContext'

Un nouveau hook au moment du design a été ajouté dans le modèle de valeur par défaut d’ASP.NET Core 2.0.A new design-time hook has been added in ASP.NET Core 2.0's default template. La méthode statique Program.BuildWebHost méthode permet d’EF Core pour accéder à fournisseur de services de l’application au moment du design.The static Program.BuildWebHost method enables EF Core to access the application's service provider at design time. Si vous mettez à niveau une application 1.x de ASP.NET Core, vous devez mettre à jour vous Program classe ressemble à ce qui suit.If you are upgrading an ASP.NET Core 1.x application, you will need to update you Program class to resemble the following.

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2._0App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

IDbContextFactory renomméIDbContextFactory renamed

Afin de prendre en charge les modèles de diverses applications et de donner aux utilisateurs de contrôler la façon leurs DbContext est utilisé au moment du design, nous vous proposons, dans le passé, la IDbContextFactory<TContext> interface.In order to support diverse application patterns and give users more control over how their DbContext is used at design time, we have, in the past, provided the IDbContextFactory<TContext> interface. Au moment du design, les outils EF Core détecte des implémentations de cette interface dans votre projet et utilisez-le pour créer DbContext objets.At design-time, the EF Core tools will discover implementations of this interface in your project and use it to create DbContext objects.

Cette interface a un nom très général qui induire en erreur certains utilisateurs à essayer de nouveau l’utiliser pour d’autres DbContext-création de scénarios.This interface had a very general name which mislead some users to try re-using it for other DbContext-creating scenarios. Ils ont été prises au dépourvu lorsque les outils EF puis a tenté d’utiliser leur implémentation au moment du design et a provoqué des commandes telles que Update-Database ou dotnet ef database update échec.They were caught off guard when the EF Tools then tried to use their implementation at design-time and caused commands like Update-Database or dotnet ef database update to fail.

Afin de communiquer la sémantique au moment du design forte de cette interface, nous avons renommé à IDesignTimeDbContextFactory<TContext>.In order to communicate the strong design-time semantics of this interface, we have renamed it to IDesignTimeDbContextFactory<TContext>.

Pour 2.0 libérer le IDbContextFactory<TContext> existe toujours, mais est marqué comme obsolète.For the 2.0 release the IDbContextFactory<TContext> still exists but is marked as obsolete.

DbContextFactoryOptions suppriméesDbContextFactoryOptions removed

En raison des modifications d’ASP.NET Core 2.0 décrites ci-dessus, nous avons découvert que DbContextFactoryOptions était n’est plus nécessaire sur le nouveau IDesignTimeDbContextFactory<TContext> interface.Because of the ASP.NET Core 2.0 changes described above, we found that DbContextFactoryOptions was no longer needed on the new IDesignTimeDbContextFactory<TContext> interface. Voici les alternatives que vous devez utiliser à la place.Here are the alternatives you should be using instead.

DbContextFactoryOptionsDbContextFactoryOptions AlternativeAlternative
ApplicationBasePathApplicationBasePath AppContext.BaseDirectoryAppContext.BaseDirectory
ContentRootPathContentRootPath Directory.GetCurrentDirectory()Directory.GetCurrentDirectory()
EnvironmentNameEnvironmentName Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")

Répertoire de travail au moment du design modifiéDesign-time working directory changed

Les modifications de ASP.NET Core 2.0 requises également le répertoire de travail utilisé par dotnet ef pour s’aligner avec le répertoire de travail utilisé par Visual Studio lors de l’exécution de votre application.The ASP.NET Core 2.0 changes also required the working directory used by dotnet ef to align with the working directory used by Visual Studio when running your application. Un effet secondaire observable de ce est que SQLite noms de fichiers sont désormais relatif du répertoire du projet et non au répertoire de sortie comme à réaliser.One observable side effect of this is that SQLite filenames are now relative to the project directory and not the output directory like they used to be.

EF Core 2.0 requiert un fournisseur de base de 2.0 donnéesEF Core 2.0 requires a 2.0 database provider

Pour EF Core 2.0 nous avons apporté plusieurs simplifications et les améliorations dans les fournisseurs de base de données de façon fonctionne.For EF Core 2.0 we have made many simplifications and improvements in the way database providers work. Cela signifie que les fournisseurs 1.0.x et 1.1.x ne fonctionnera pas avec EF Core 2.0.This means that 1.0.x and 1.1.x providers will not work with EF Core 2.0.

Les fournisseurs SQL Server et SQLite sont fournis par l’équipe EF et les 2.0 versions sera disponibles dans le cadre de 2.0 release.The SQL Server and SQLite providers are shipped by the EF team and 2.0 versions will be available as part of the 2.0 release. Les fournisseurs tiers open source pour SQL Compact, PostgreSQL, et MySQL sont mis à jour pour 2.0.The open-source third party providers for SQL Compact, PostgreSQL, and MySQL are being updated for 2.0. Pour tous les autres fournisseurs, veuillez contacter le rédacteur de fournisseur.For all other providers, please contact the provider writer.

Événements de journalisation et de diagnostic ont été modifiés.Logging and Diagnostics events have changed

Remarque : ces modifications ne devraient pas avoir un impact sur la plupart des codes d’application.Note: these changes should not impact most application code.

Les ID d’événement pour les messages envoyés à un ILogger ont été modifiés dans 2.0.The event IDs for messages sent to an ILogger have changed in 2.0. Les ID d’événement sont maintenant uniques dans le code EF Core.The event IDs are now unique across EF Core code. En outre, ces messages suivent désormais le modèle standard de la journalisation structurée utilisé, par exemple, par le modèle MVC.These messages now also follow the standard pattern for structured logging used by, for example, MVC.

Les catégories d’enregistreurs d’événements ont également changé.Logger categories have also changed. Il existe désormais un jeu connu de catégories accessibles par le biais de DbLoggerCategory.There is now a well-known set of categories accessed through DbLoggerCategory.

DiagnosticSource événements utilisent désormais les mêmes noms de ID d’événement correspondants ILogger messages.DiagnosticSource events now use the same event ID names as the corresponding ILogger messages. Les charges utiles d’événement sont tous les types nominaux dérivés EventData.The event payloads are all nominal types derived from EventData.

ID d’événement, les types de charge utile et les catégories sont décrits dans le CoreEventId et RelationalEventId classes.Event IDs, payload types, and categories are documented in the CoreEventId and the RelationalEventId classes.

ID ont également été déplacés à partir de Microsoft.EntityFrameworkCore.Infraestructure pour le nouvel espace de noms Microsoft.EntityFrameworkCore.Diagnostics.IDs have also moved from Microsoft.EntityFrameworkCore.Infraestructure to the new Microsoft.EntityFrameworkCore.Diagnostics namespace.

Modifications de métadonnées relationnelles API EF CoreEF Core relational metadata API changes

EF Core 2.0 génère désormais un IModel différent par fournisseur utilisé.EF Core 2.0 will now build a different IModel for each different provider being used. Cela est généralement transparent pour l’application.This is usually transparent to the application. Il en résulte une simplification des API de métadonnées de niveau inférieur, au point que tout accès aux concepts de métadonnées relationnelles communs est toujours établi par le biais d’un appel à .Relational au lieu de .SqlServer, .Sqlite, etc. Par exemple, 1.1.x code similaire à celui-ci :This has facilitated a simplification of lower-level metadata APIs such that any access to common relational metadata concepts is always made through a call to .Relational instead of .SqlServer, .Sqlite, etc. For example, 1.1.x code like this:

var tableName = context.Model.FindEntityType(typeof(User)).SqlServer().TableName;

Doit maintenant être écrit comme suit :Should now be written like this:

var tableName = context.Model.FindEntityType(typeof(User)).Relational().TableName;

Au lieu d’utiliser des méthodes telles que ForSqlServerToTable, méthodes d’extension sont désormais disponibles pour écrire du code conditionnel basé sur le fournisseur actuel en cours d’utilisation.Instead of using methods like ForSqlServerToTable, extension methods are now available to write conditional code based on the current provider in use. Exemple :For example:

modelBuilder.Entity<User>().ToTable(
    Database.IsSqlServer() ? "SqlServerName" : "OtherName");

Notez que cette modification s’applique uniquement aux API/métadonnées qui est définie pour tous les fournisseurs relationnelles.Note that this change only applies to APIs/metadata that is defined for all relational providers. Les API et les métadonnées reste la même lorsqu’il est spécifique à un seul fournisseur.The API and metadata remains the same when it is specific to only a single provider. Par exemple, les index ordonnés en clusters sont spécifiques à SQL Server, donc ForSqlServerIsClustered et .SqlServer().IsClustered() doit toujours être utilisé.For example, clustered indexes are specific to SQL Sever, so ForSqlServerIsClustered and .SqlServer().IsClustered() must still be used.

Ne pas prendre le contrôle du fournisseur de services EFDon’t take control of the EF service provider

EF Core utilise un interne IServiceProvider (un conteneur d’injection de dépendance) pour son implémentation interne.EF Core uses an internal IServiceProvider (a dependency injection container) for its internal implementation. Les applications doivent autoriser EF Core créer et gérer ce fournisseur, sauf dans des cas spéciaux.Applications should allow EF Core to create and manage this provider except in special cases. Fortement envisager de supprimer tous les appels à UseInternalServiceProvider.Strongly consider removing any calls to UseInternalServiceProvider. Si une application a besoin d’appeler UseInternalServiceProvider, puis pensez à signalant un problème donc nous pouvons examiner d’autres façons de gérer votre scénario.If an application does need to call UseInternalServiceProvider, then please consider filing an issue so we can investigate other ways to handle your scenario.

Appel AddEntityFramework, AddEntityFrameworkSqlServer, etc. n’est pas requis par code d’application, sauf si UseInternalServiceProvider est également appelée.Calling AddEntityFramework, AddEntityFrameworkSqlServer, etc. is not required by application code unless UseInternalServiceProvider is also called. Supprimer tous les appels à AddEntityFramework ou AddEntityFrameworkSqlServer, etc. AddDbContext doit toujours être utilisé dans la même façon qu’avant.Remove any existing calls to AddEntityFramework or AddEntityFrameworkSqlServer, etc. AddDbContext should still be used in the same way as before.

Bases de données en mémoire doivent être nommés.In-memory databases must be named

La base de données en mémoire sans nom global a été supprimée et à la place toutes les bases de données en mémoire doivent être nommés.The global unnamed in-memory database has been removed and instead all in-memory databases must be named. Exemple :For example:

optionsBuilder.UseInMemoryDatabase("MyDatabase");

Cela crée/utilise une base de données portant le nom « MyDatabase ».This creates/uses a database with the name “MyDatabase”. Si UseInMemoryDatabase est appelée à nouveau avec le même nom, la même base de données en mémoire est utilisé, ce qui lui permet d’être partagé par plusieurs instances de contexte.If UseInMemoryDatabase is called again with the same name, then the same in-memory database will be used, allowing it to be shared by multiple context instances.

Modifications de l’API en lecture seuleRead-only API changes

IsReadOnlyBeforeSave, IsReadOnlyAfterSave, et IsStoreGeneratedAlways ont été obsolète et remplacé par BeforeSaveBehavior et AfterSaveBehavior.IsReadOnlyBeforeSave, IsReadOnlyAfterSave, and IsStoreGeneratedAlways have been obsoleted and replaced with BeforeSaveBehavior and AfterSaveBehavior. Ces comportements s’appliquent à n’importe quelle propriété (générées par le magasin non seulement des propriétés) et déterminer comment la valeur de la propriété doit être utilisée lors de l’insertion dans une ligne de base de données (BeforeSaveBehavior) ou lorsque la mise à jour existant de base de données ligne (AfterSaveBehavior).These behaviors apply to any property (not only store-generated properties) and determine how the value of the property should be used when inserting into a database row (BeforeSaveBehavior) or when updating an existing database row (AfterSaveBehavior).

Propriétés marquées comme étant ValueGenerated.OnAddOrUpdate (par exemple, pour les colonnes calculées) par défaut ignore toute valeur actuellement définie sur la propriété.Properties marked as ValueGenerated.OnAddOrUpdate (for example, for computed columns) will by default ignore any value currently set on the property. Cela signifie qu’une valeur générée par le magasin sera toujours obtenue indépendamment de si n’importe quelle valeur a été définie ou modifiée sur l’entité suivie.This means that a store-generated value will always be obtained regardless of whether any value has been set or modified on the tracked entity. Cela peut être modifié en définissant un autre Before\AfterSaveBehavior.This can be changed by setting a different Before\AfterSaveBehavior.

Nouveau comportement de suppression ClientSetNullNew ClientSetNull delete behavior

Dans les versions précédentes, DeleteBehavior.Restrict avait un comportement pour les entités suivies par le contexte que plus fermé mise en correspondance SetNull sémantique.In previous releases, DeleteBehavior.Restrict had a behavior for entities tracked by the context that more closed matched SetNull semantics. Dans EF Core 2.0, un nouveau ClientSetNull comportement a été introduit en tant que la valeur par défaut pour les relations facultatives.In EF Core 2.0, a new ClientSetNull behavior has been introduced as the default for optional relationships. Ce comportement a SetNull sémantique pour les entités suivies et Restrict comportement pour les bases de données créées à l’aide d’EF Core.This behavior has SetNull semantics for tracked entities and Restrict behavior for databases created using EF Core. Dans notre expérience, il s’agit des plus attendue/comportements utiles pour les entités suivies et la base de données.In our experience, these are the most expected/useful behaviors for tracked entities and the database. DeleteBehavior.Restrict est maintenant respectée pour les entités suivies lorsque la valeur pour les relations facultatives.DeleteBehavior.Restrict is now honored for tracked entities when set for optional relationships.

Packages au moment du design de fournisseur supprimésProvider design-time packages removed

Le Microsoft.EntityFrameworkCore.Relational.Design package a été supprimé.The Microsoft.EntityFrameworkCore.Relational.Design package has been removed. Son contenu ont été consolidés en Microsoft.EntityFrameworkCore.Relational et Microsoft.EntityFrameworkCore.Design.It's contents were consolidated into Microsoft.EntityFrameworkCore.Relational and Microsoft.EntityFrameworkCore.Design.

Cela se propage dans les packages au moment du design de fournisseur.This propagates into the provider design-time packages. Ces packages (Microsoft.EntityFrameworkCore.Sqlite.Design, Microsoft.EntityFrameworkCore.SqlServer.Design, etc.) ont été supprimés et leur contenu consolidées dans les packages fournisseur principal.Those packages (Microsoft.EntityFrameworkCore.Sqlite.Design, Microsoft.EntityFrameworkCore.SqlServer.Design, etc.) were removed and their contents consolidated into the main provider packages.

Pour activer Scaffold-DbContext ou dotnet ef dbcontext scaffold dans EF Core 2.0, il vous suffit de référencer le package de fournisseur unique :To enable Scaffold-DbContext or dotnet ef dbcontext scaffold in EF Core 2.0, you only need to reference the single provider package:

<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer"
    Version="2.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools"
    Version="2.0.0"
    PrivateAssets="All" />
<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
    Version="2.0.0" />