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

既存の 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.

既存のアプリケーションを EF Core 2.0 を更新する必要があります。Updating an existing application to EF Core 2.0 may require:

  1. .NET Standard 2.0 をサポートしているアプリケーションのターゲットの .NET 実装をアップグレードします。Upgrading the target .NET implementation of the application to one that supports .NET Standard 2.0. 参照してくださいサポートされている .NET 実装の詳細。See Supported .NET Implementations for more details.

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

  3. すべての EF Core パッケージ (ランタイムおよびツール) を 2.0 にアップグレードします。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 the breaking changes described in the rest of this document.

ASP.NET Core が EF Core が含まれていますASP.NET Core now includes EF Core

ASP.NET Core 2.0 を対象とするアプリケーションは、サードパーティ データベース プロバイダー以外の依存関係を追加せずに EF Core 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 Core 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. ASP.NET Core アプリケーションを 2.0 にアップグレードする方法の詳細を参照してくださいサブジェクトで ASP.NET Core ドキュメントします。For more details on upgrading ASP.NET Core applications to 2.0 see the ASP.NET Core documentation on the subject.

ASP.NET Core でのアプリケーション サービスを取得する新しい方法New way of getting application services in ASP.NET Core

EF Core が 1.x で使用されるデザイン時ロジックを無効にした方法で 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 Core は呼び出しを試みる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 Core を使用してアプリケーションへのアクセス、接続文字列構成からため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 Core ツールを使用する場合、次のエラーを受信可能性があります。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 Core を使用できます。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 the 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();
    }
}

2.0 アプリケーションの更新は強く推奨され、動作する Entity Framework Core Migrations のような製品機能のために必要がときにこの新しいパターンの導入します。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>.

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 Core ツールは、プロジェクトでは、このインターフェイスの実装が検出して使用を作成する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 Core 2.0 には、2.0 データベース プロバイダーが必要です。EF Core 2.0 requires a 2.0 database provider

EF Core 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 Core 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 Core コード全体で一意になりました。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 Core のリレーショナル メタデータ API の変更EF Core relational metadata API changes

EF Core 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 が単純になり、_一般的なリレーショナル メタデータ コンセプト_へのあらゆるアクセスが .SqlServer.Sqlite などではなく、.Relational の呼び出しで常に行われます。たとえば、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 Core を使用して内部IServiceProvider(依存関係注入コンテナー) の内部実装します。EF Core uses an internal IServiceProvider (a dependency injection container) for its internal implementation. アプリケーションでは、EF Core を作成し、このプロバイダーは、特殊なケースで以外の管理を許可する必要があります。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

IsReadOnlyBeforeSaveIsReadOnlyAfterSave、およびIsStoreGeneratedAlways廃止され、置き換えBeforeSaveBehaviorAfterSaveBehaviorします。IsReadOnlyBeforeSave, IsReadOnlyAfterSave, 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 (for example, 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 Core 2.0 で新しいClientSetNull省略可能なリレーションシップの既定値としての動作が導入されています。In EF Core 2.0, a new ClientSetNull behavior has been introduced as the default for optional relationships. この動作は、SetNull追跡対象のエンティティのセマンティクスとRestrictEF Core を使用して作成されたデータベースの動作。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 Core 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" />