以前のバージョンから EF コア 2.0 へのアプリケーションのアップグレードUpgrading applications from previous versions to EF Core 2.0

すべてのアプリケーションに共通の手順Procedures Common to All Applications

EF コア 2.0 に既存のアプリケーションの更新が必要です。Updating an existing application to EF Core 2.0 may require:

  1. .NET 標準 2.0 をサポートしているアプリケーションのターゲットの .NET プラットフォームをアップグレードします。Upgrading the target .NET platform of the application to one that supports .NET Standard 2.0. 参照してくださいサポートされているプラットフォーム詳細についてはします。See Supported Platforms for more details.

  2. EF コア 2.0 と互換性があるターゲット データベースのプロバイダーを識別します。Identify a provider for the target database which is compatible with EF Core 2.0. 参照してくださいEF コア 2.0 には、2.0 データベース プロバイダーが必要があります以下です。See EF Core 2.0 requires a 2.0 database provider below.

  3. 2.0 へのすべての EF Core パッケージ (ランタイムおよびツール) をアップグレードします。Upgrading all the EF Core packages (runtime and tooling) to 2.0. 参照してくださいEF Core のインストール詳細についてはします。Refer to Installing EF Core for more details.

  4. 重大な変更を補正するために必要なコード変更を加えます。Make any necessary code changes to compensate for breaking changes. 参照してください、の重大な変更詳細については、後述の「します。See the Breaking Changes section below for more details.

ASP.NET Core アプリケーションASP.NET Core applications

  1. 具体的にを参照してください、アプリケーションのサービス プロバイダーを初期化するための新しいパターン以下で説明します。See in particular the new pattern for initializing the application's service provider described below.

ヒント

この新しいパターンを強くお勧めし、Entity Framework の中核となる移行と同様に、製品の機能の動作するために必要な 2.0 アプリケーションの更新うちに導入します。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. 他の一般的な手段実装IDesignTimeDbContextFactory<TContext >です。The other common alternative is to implement IDesignTimeDbContextFactory<TContext>.

  1. ASP.NET Core 2.0 を対象とするアプリケーションでは、サード パーティ製データベース プロバイダーに加えて追加の依存関係なく、EF コア 2.0 を使用できます。Applications targeting ASP.NET Core 2.0 can use EF Core 2.0 without additional dependencies besides third party database providers. ただし、以前のバージョンの ASP.NET Core をターゲットとするアプリケーションでは、EF コア 2.0 を使用するために ASP.NET 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. 2.0 に ASP.NET Core アプリケーションのアップグレードに関する詳細を参照してくださいASP.NET Core のドキュメントにあるサブジェクトにです。For more details on upgrading ASP.NET Core applications to 2.0 see the ASP.NET Core documentation on the subject.

互換性に影響する変更点Breaking Changes

大幅に改良、既存の Api 2.0 で動作する機会を移動しました。We have taken the opportunity to significantly refine our existing APIs and behaviors in 2.0. 既存のアプリケーション コードの変更が必要になる改良がいくつか行われて、アプリケーションの大部分のあることが影響を再コンパイルして古い Api を置換する最小限の画面の指示に従って変更だけを必要とするほとんどの場合、低なります。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.

アプリケーション サービスを取得する新しい方法New way of getting application services

1.x で EF コアが使用されるデザイン時のロジックを無効にした方法で 2.0 の ASP.NET Core web アプリケーションに対して、推奨パターンが更新されました。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. 以前のデザイン時に、EF コアを試行を呼び出すStartup.ConfigureServicesアプリケーションのサービス プロバイダーにアクセスするために直接できます。Previously at design-time, EF Core would try to invoke Startup.ConfigureServices directly in order to access the application's service provider. 外部の ASP.NET Core 2.0 の構成が初期化されて、Startupクラスです。In ASP.NET Core 2.0, Configuration is initialized outside of the Startup class. 通常 EF コアを使用してアプリケーションへのアクセス、接続文字列構成からためStartup自体では十分なできなくします。Applications using EF Core typically access their connection string from Configuration, so Startup by itself is no longer sufficient. ASP.NET Core 1.x アプリケーションをアップグレードする場合は、EF コア ツールを使用する場合、次のエラーを受信可能性があります。If you upgrade an ASP.NET Core 1.x application, you may receive the following error when using the EF Core tools.

パラメーターなしコンス トラクターは、'ApplicationContext' で見つかりませんでした。No parameterless constructor was found on 'ApplicationContext'. パラメーターなしのコンス トラクターを 'ApplicationContext' に追加するか、追加の実装 'IDesignTimeDbContextFactory<ApplicationContext>' 'ApplicationContext' と同じアセンブリ内Either add a parameterless constructor to 'ApplicationContext' or add an implementation of 'IDesignTimeDbContextFactory<ApplicationContext>' in the same assembly as 'ApplicationContext'

ASP.NET Core 2.0 の既定のテンプレートで、新しいデザイン時フックが追加されました。A new design-time hook has been added in ASP.NET Core 2.0's default template. 静的なProgram.BuildWebHostメソッドにより、EF のコアがデザイン時に、アプリケーションのサービス プロバイダーにアクセスします。The static Program.BuildWebHost method enables EF Core to access the application's service provider at design time. ASP.NET Core 1.x アプリケーションをアップグレードする場合は、更新する必要があります。Programクラスを、次のようになります。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 の名前を変更IDbContextFactory renamed

さまざまなアプリケーション パターンをサポートし、方法をより細かく制御できるようにするために、DbContext使用は、デザイン時にある、以前は、指定、IDbContextFactory<TContext>インターフェイス。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. デザイン時に、EF コア ツールはプロジェクトでこのインターフェイスの実装を見つけてを使用して作成DbContextオブジェクト。At design-time, the EF Core tools will discover implementations of this interface in your project and use it to create DbContext objects.

このインターフェイスには、一部のユーザーに再を使用してその他の誤解する可能性が非常に一般的な名前が必要があるDbContextのシナリオを作成します。This interface had a very general name which mislead some users to try re-using it for other DbContext-creating scenarios. デザイン時にその実装を使用する EF ツールが、試みられたときにガード オフ キャッチおよびのようなコマンドの原因となったUpdate-Databaseまたはdotnet ef database updateが失敗します。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.

このインターフェイスの強力なデザイン時のセマンティクスを通信するために名前を変更しましたにIDesignTimeDbContextFactory<TContext>です。In order to communicate the strong design-time semantics of this interface, we have renamed it to IDesignTimeDbContextFactory<TContext>.

2.0 リリース、IDbContextFactory<TContext>引き続き存在しますが、不使用とマークされます。For the 2.0 release the IDbContextFactory<TContext> still exists but is marked as obsolete.

DbContextFactoryOptions の削除DbContextFactoryOptions removed

変更のため、ASP.NET Core 2.0 上で説明した、ことを確認しましたDbContextFactoryOptionsが不要になった新しいIDesignTimeDbContextFactory<TContext>インターフェイスです。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. ここでは、代替の代わりに使用する必要があります。Here are the alternatives you should be using instead.

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

デザイン時の作業ディレクトリが変更されましたDesign-time working directory changed

使用される作業ディレクトリにも必要な ASP.NET Core 2.0 変更dotnet efアプリケーションを実行するときに、Visual Studio で使用される作業ディレクトリに合うようにします。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. この監視可能な副作用 1 つは、ファイル名は今すぐに対する相対パス、プロジェクト ディレクトリと出力ディレクトリではなく、使用するようにその SQLite です。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 コア 2.0 2.0 データベース プロバイダーが必要です。EF Core 2.0 requires a 2.0 database provider

EF コア 2.0 は、多くの簡素化と機能強化データベース プロバイダーの方法で作業を行いました。For EF Core 2.0 we have made many simplifications and improvements in the way database providers work. これは 1.0.x および 1.1.x プロバイダーは、EF コア 2.0 では動作しないことを意味します。This means that 1.0.x and 1.1.x providers will not work with EF Core 2.0.

EF チームによって、SQL Server と SQLite プロバイダーが付属してでき 2.0 バージョンは 2.0 の一部としてリリースされます。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. オープン ソース サード パーティ プロバイダー SQL CompactPostgreSQL、およびMySQL 2.0 の更新中です。The open-source third party providers for SQL Compact, PostgreSQL, and MySQL are being updated for 2.0. その他のすべてのプロバイダーでは、プロバイダーの作成者に問い合わせてください。For all other providers, please contact the provider writer.

ログ記録と診断イベントが変更されましたLogging and Diagnostics events have changed

注: これらの変更では、ほとんどのアプリケーション コードを影響はありません。Note: these changes should not impact most application code.

イベント Id に送信されたメッセージについて、 ILoggerが 2.0 に変更します。The event IDs for messages sent to an ILogger have changed in 2.0. イベント Id は、EF コア コード全体では一意ようになりました。The event IDs are now unique across EF Core code. これらのメッセージようになりましたもパターンに従う、標準の構造化されたログ記録の例については、MVC で使用します。These messages now also follow the standard pattern for structured logging used by, for example, MVC.

ロガーのカテゴリも変更します。Logger categories have also changed. これで、よく知られた一連のカテゴリを使用してアクセスがあるDbLoggerCategoryです。There is now a well-known set of categories accessed through DbLoggerCategory.

DiagnosticSourceイベントは、対応するとして同じイベント ID 名を使用するようになりましたILoggerメッセージ。DiagnosticSource events now use the same event ID names as the corresponding ILogger messages. イベント ペイロードは、すべての標準型から派生したEventDataです。The event payloads are all nominal types derived from EventData.

イベント Id、ペイロードの種類、およびカテゴリは、『、 CoreEventIdRelationalEventIdクラスです。Event IDs, payload types, and categories are documented in the CoreEventId and the RelationalEventId classes.

Id は、新しい Microsoft.EntityFrameworkCore.Diagnostics 名前空間にも Microsoft.EntityFrameworkCore.Infraestructure から移動されました。IDs have also moved from Microsoft.EntityFrameworkCore.Infraestructure to the new Microsoft.EntityFrameworkCore.Diagnostics namespace.

EF コア リレーショナル メタデータ API の変更EF Core relational metadata API changes

EF コア 2.0 はこれで、異なるビルドIModelプロバイダーごとに異なる使用されています。EF Core 2.0 will now build a different IModel for each different provider being used. これは通常、アプリケーションに対して透過的です。This is usually transparent to the application. これが容易になります下位レベルのメタデータ Api の単純化するいずれかにアクセスするよう_リレーショナル メタデータの一般的な概念_への呼び出しが行われる常に.Relationalの代わりに.SqlServer.Sqlite, などです。たとえば、1.1.x コード次のようにします。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;

次のようになりました記述する必要があります。Should now be written like this:

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

などのメソッドを使用する代わりにForSqlServerToTable、拡張メソッドは現在使用中の現在のプロバイダーに基づく条件付きのコードを記述できます。Instead of using methods like ForSqlServerToTable, extension methods are now available to write conditional code based on the current provider in use. 例:For example:

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

この変更は、定義されている Api/メタデータにのみ適用する注_すべて_リレーショナル プロバイダー。Note that this change only applies to APIs/metadata that is defined for all relational providers. API とメタデータは、1 つのプロバイダーのみに固有であるときに、同じです。The API and metadata remains the same when it is specific to only a single provider. たとえば、クラスター化インデックスは SQL Sever、特定ようにForSqlServerIsClustered.SqlServer().IsClustered()まだを使用する必要があります。For example, clustered indexes are specific to SQL Sever, so ForSqlServerIsClustered and .SqlServer().IsClustered() must still be used.

EF サービス プロバイダーを制御することがありません。Don’t take control of the EF service provider

EF コアを使用して、内部IServiceProvider(依存関係の注入コンテナーなど) ため、内部の実装です。EF Core uses an internal IServiceProvider (i.e. a dependency injection container) for its internal implementation. アプリケーションでは、EF のコアを作成し、特殊なケースで以外は、このプロバイダーを管理するを許可する必要があります。Applications should allow EF Core to create and manage this provider except in special cases. 呼び出しの削除を検討してくださいUseInternalServiceProviderです。Strongly consider removing any calls to UseInternalServiceProvider. アプリケーションを呼び出す必要がある場合UseInternalServiceProvider、しを検討してください問題をファイリングシナリオを処理するには、その他の方法で調査を行えるようにします。If an application does need to call UseInternalServiceProvider, then please consider filing an issue so we can investigate other ways to handle your scenario.

呼び出すAddEntityFrameworkAddEntityFrameworkSqlServer、しない限り、アプリケーション コードによってなどが必要ありませんUseInternalServiceProviderとも呼ばれます。Calling AddEntityFramework, AddEntityFrameworkSqlServer, etc. is not required by application code unless UseInternalServiceProvider is also called. 呼び出しの既存の削除AddEntityFrameworkまたはAddEntityFrameworkSqlServerなどAddDbContext必要がありますも使用する同じ方法で以前と同様です。Remove any existing calls to AddEntityFramework or AddEntityFrameworkSqlServer, etc. AddDbContext should still be used in the same way as before.

インメモリ データベースを指定する必要があります。In-memory databases must be named

名前のないメモリ内のグローバル データベースが削除され、代わりにメモリ内のすべてのデータベースを名前必要があります。The global unnamed in-memory database has been removed and instead all in-memory databases must be named. 例:For example:

optionsBuilder.UseInMemoryDatabase("MyDatabase");

これを作成/は"MyDatabase"という名前のデータベースが使用します。This creates/uses a database with the name “MyDatabase”. 場合UseInMemoryDatabaseが再度呼び出され、同じ名前を持つ、複数のコンテキストのインスタンスで共有することができるメモリ内の同じデータベースが使用されます。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.

読み取り専用の API の変更Read-only API changes

IsReadOnlyBeforeSaveIsReadOnlyAferSave、およびIsStoreGeneratedAlways廃止され、で置き換えられましたBeforeSaveBehaviorAfterSaveBehaviorです。IsReadOnlyBeforeSave, IsReadOnlyAferSave, and IsStoreGeneratedAlways have been obsoleted and replaced with BeforeSaveBehavior and AfterSaveBehavior. これらの動作は、任意のプロパティ (ストア生成のプロパティだけでなく) に適用され、データベースの行に挿入するときに、プロパティの値を使用する方法を決定 (BeforeSaveBehavior) ときに、行をデータベースを既存の更新または (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).

としてマークされているプロパティValueGenerated.OnAddOrUpdate (例: 計算列) が既定では無視してプロパティに設定されている任意の値。Properties marked as ValueGenerated.OnAddOrUpdate (e.g. for computed columns) will by default ignore any value currently set on the property. これは、任意の値が設定または追跡対象エンティティで変更されたかどうかに関係なくストア生成の値が常に取得することを意味します。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. これは、別の設定で変更できますBefore\AfterSaveBehaviorです。This can be changed by setting a different Before\AfterSaveBehavior.

新しい ClientSetNull 削除の動作New ClientSetNull delete behavior

以前のリリースでDeleteBehavior.Restrictがエンティティの動作がコンテキストによって追跡以上の一致した閉じたことSetNullセマンティクスです。In previous releases, DeleteBehavior.Restrict had a behavior for entities tracked by the context that more closed matched SetNull semantics. EF コア 2.0 で新しいClientSetNull動作が省略可能なリレーションシップの既定値として導入されました。In EF Core 2.0, a new ClientSetNull behavior has been introduced as the default for optional relationships. この動作は、SetNull追跡対象のエンティティのセマンティクスとRestrictEF コアを使用して作成されたデータベースの動作です。This behavior has SetNull semantics for tracked entities and Restrict behavior for databases created using EF Core. 経験では、これらは、追跡対象のエンティティとデータベースの最も期待/役に立つの動作です。In our experience, these are the most expected/useful behaviors for tracked entities and the database. DeleteBehavior.Restrict省略可能なリレーションシップを設定すると、追跡対象のエンティティのようになりました受け入れられます。DeleteBehavior.Restrict is now honored for tracked entities when set for optional relationships.

プロバイダーのデザイン時パッケージの削除Provider design-time packages removed

Microsoft.EntityFrameworkCore.Relational.Designパッケージが削除されました。The Microsoft.EntityFrameworkCore.Relational.Design package has been removed. ファイルの内容を統合していたMicrosoft.EntityFrameworkCore.RelationalMicrosoft.EntityFrameworkCore.Designです。It's contents were consolidated into Microsoft.EntityFrameworkCore.Relational and Microsoft.EntityFrameworkCore.Design.

プロバイダーのデザイン時パッケージに反映されます。This propagates into the provider design-time packages. それらのパッケージ (Microsoft.EntityFrameworkCore.Sqlite.DesignMicrosoft.EntityFrameworkCore.SqlServer.Designなど) が削除し、その内容がメイン プロバイダーのパッケージに統合します。Those packages (Microsoft.EntityFrameworkCore.Sqlite.Design, Microsoft.EntityFrameworkCore.SqlServer.Design, etc.) were removed and their contents consolidated into the main provider packages.

有効にするScaffold-DbContextまたはdotnet ef dbcontext scaffoldEF コア 2.0 でのみ参照する必要が 1 つのプロバイダーのパッケージ。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" />