Entity Framework Core ツールのリファレンス - .NET Core CLI

Entity Framework Core 用のコマンドライン インターフェイス ツールは、デザイン時の開発タスクを実行します。 たとえば、移行の作成、移行の適用、既存のデータベースに基づくモデルの作成などを行います。 コマンドは、.NET Core SDK の一部であるクロスプラットフォーム dotnet コマンドの拡張機能です。 これらのツールは、.NET Core プロジェクトで動作しません。

Visual Studio を使用する場合は、CLI ツールではなくパッケージ マネージャー コンソール ツール を使用することを検討してください。 パッケージ マネージャーコンソール ツールは自動的に次の処理を行います。

  • ディレクトリを手動で切り替えずに、パッケージ マネージャー コンソールで現在選択されているプロジェクトと連動する。
  • コマンドの完了後に、コマンドで生成されたファイルを開く。
  • コマンド、パラメーター、プロジェクト名、コンテキスト型、移行名のタブ補完を提供する。

ツールのインストール

dotnet ef は、グローバルまたはローカルのツールとしてインストールできます。 ほとんどの開発者は、次のコマンドを使用して、dotnet ef をグローバル ツールとしてインストールする方を選びます。

dotnet tool install --global dotnet-ef

ローカル ツールとして使用するには、ツール マニフェスト ファイルを使用してツールの依存関係として宣言するプロジェクトの依存関係を復元します。

次のコマンドを使用して、ツールを更新します。

dotnet tool update --global dotnet-ef

特定のプロジェクトでツールを使用するには、その前に Microsoft.EntityFrameworkCore.Design パッケージを追加する必要があります。

dotnet add package Microsoft.EntityFrameworkCore.Design

インストールを確認する

次のコマンドを実行して、EF Core CLI ツールが正しくインストールされていることを確認します。

dotnet ef

コマンドからの出力で、使用されているツールのバージョンがわかります。


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065

<Usage documentation follows, not shown.>

ツールを更新する

グローバル ツールを利用可能な最新バージョンに更新するには、dotnet tool update --global dotnet-ef を使用します。 ツールがプロジェクトにローカルにインストールされている場合は、dotnet tool update dotnet-ef を使用します。 特定のバージョンをインストールするには、コマンドに --version <VERSION> を追加します。 詳細については、dotnet tool のドキュメントの更新に関するセクションを参照してください。

ツールの使用

ツールを使用する前に、スタートアップ プロジェクトを作成するか、環境を設定することが必要になる場合があります。

ターゲット プロジェクトとスタートアップ プロジェクト

コマンドは、"プロジェクト" と "スタートアップ プロジェクト" を参照します。

  • "プロジェクト" は、コマンドでファイルを追加または削除する場所であるため、"ターゲット プロジェクト" とも呼ばれます。 既定では、現在のディレクトリのプロジェクトがターゲット プロジェクトです。 --project オプションを使用すると、別のプロジェクトをターゲット プロジェクトとして指定できます。

  • "スタートアップ プロジェクト" は、ツールによって構築され、実行されるプロジェクトです。 ツールでは、デザイン時にアプリケーション コードを実行して、データベース接続文字列やモデルの構成など、プロジェクトに関する情報を取得する必要があります。 既定では、現在のディレクトリのプロジェクトがスタートアップ プロジェクトです。 --startup-project オプションを使用すると、別のプロジェクトをスタートアップ プロジェクトとして指定できます。

多くの場合、スタートアップ プロジェクトとターゲット プロジェクトは同じプロジェクトです。 これらが別個のプロジェクトである一般的なシナリオは、次のような場合です。

  • EF Core コンテキストとエンティティ クラスが、.NET Core クラス ライブラリ内にある。
  • .NET Core コンソール アプリまたは Web アプリでクラス ライブラリを参照する。

EF Core コンテキストとは別のクラス ライブラリに移行コードを配置することもできます。

その他のターゲット フレームワーク

CLI ツールは、.NET Core プロジェクトと .NET Framework プロジェクトの両方に使えます。 EF Core モデルが .NET Standard クラス ライブラリ内にあるアプリには、.NET Core または .NET Framework プロジェクトがない場合があります。 たとえば、Xamarin およびユニバーサル Windows プラットフォーム アプリがこれに該当します。 このような場合、ツールのスタートアップ プロジェクトとして機能することのみを目的とする .NET Core コンソール アプリ プロジェクトを作成できます。 このプロジェクトは、実際のコードを持たないダミー プロジェクトにすることができます。これは、ツールのターゲットを提供するためにのみ必要です。

ダミー プロジェクトはなぜ必要なのでしょうか? 前にも述べたとおり、ツールでは、デザイン時にアプリケーション コードを実行する必要があります。 これを行うには、.NET Core ランタイムを使用する必要があります。 EF Core モデルが、.NET Core または .NET Framework を対象とするプロジェクト内にある場合、EF Core ツールは、プロジェクトからランタイムを借用します。 EF Core モデルが .NET Standard クラス ライブラリ内にある場合、ツールは借用できません。 .NET Standard は実際の .NET 実装ではありません。これは、.NET 実装でサポートする必要がある一連の API に関する仕様です。 このため、EF Core ツールがアプリケーション コードを実行するには、.NET Standard では不十分です。 スタートアップ プロジェクトとして使用するために作成するダミー プロジェクトは、ツールで .NET Standard クラス ライブラリを読み込むことができる具象ターゲット プラットフォームを提供します。

ASP.NET Core 環境

ASP.NET Core プロジェクト用の環境を指定するには、コマンドを実行する前に、ASPNETCORE_ENVIRONMENT 環境変数を設定します。

EF Core 5.0 以降では、追加の引数を Program.CreateHostBuilder に渡すこともできます。これらを使用すると、コマンドラインで環境を指定できます。

dotnet ef database update -- --environment Production

ヒント

-- トークンは、後に続くすべてのものを引数として扱い、それらをオプションとして解析しないことを dotnet ef に指示します。 dotnet ef によって使用されない追加の引数はアプリに転送されます。

共通オプション

オプション Short 説明
--json JSON 出力を表示します。
--context <DBCONTEXT> -c 使用する DbContext クラス。 クラス名のみ、または名前空間で完全修飾された名前。 このオプションを省略した場合、EF Core によりコンテキスト クラスが検出されます。 複数のコンテキスト クラスがある場合、このオプションが必要です。
--project <PROJECT> -p ターゲット プロジェクトのプロジェクト フォルダーへの相対パス。 既定値は現在のフォルダーです。
--startup-project <PROJECT> -s スタートアップ プロジェクトのプロジェクト フォルダーへの相対パス。 既定値は現在のフォルダーです。
--framework <FRAMEWORK> ターゲット フレームワークターゲット フレームワーク モニカー。 プロジェクト ファイルで複数のターゲット フレームワークが指定され、それらのいずれかを選択する場合に使用します。
--configuration <CONFIGURATION> ビルド構成 (DebugRelease など)。
--runtime <IDENTIFIER> パッケージを復元するターゲット ランタイムの識別子。 ランタイム ID (RID) の一覧については、RID カタログに関するページをご覧ください。
--no-build プロジェクトをビルドしません。 ビルドが最新であるときに使用することを想定しています。
--help -h ヘルプ情報を表示します。
--verbose -v 詳細出力を表示します。
--no-color 出力を色分けしません。
--prefix-output レベルを含むプレフィックス出力。

EF Core 5.0 以降、追加の引数はすべてアプリケーションに渡されます。

dotnet ef database drop

データベースを削除します。

オプション:

オプション Short 説明
--force -f 確認しません。
--dry-run ドロップされるデータベースを表示しますが、ドロップは行われません。

一般的なオプションは、上記のとおりです。

dotnet ef database update

データベースを最後の移行または指定された移行に更新します。

引数:

引数 説明
<MIGRATION> ターゲット移行。 移行は、名前または ID で識別できます。 数値 0 は特殊なケースで、"最初の移行の前" を意味し、すべての移行を元に戻します。 移行を指定しない場合、コマンドでは、既定値が最後の移行に設定されます。

オプション:

オプション 説明
--connection <CONNECTION> データベースへの接続文字列。 既定値は、AddDbContext または OnConfiguring で指定された文字列です。 EF Core 5.0 で追加されました。

一般的なオプションは、上記のとおりです。

次の例では、データベースを指定された移行に更新します。 1 つ目は移行名を使用し、2 つ目は、移行 ID と指定された接続を使用します。

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string

dotnet ef dbcontext info

DbContext 型に関する情報を取得します。

一般的なオプションは、上記のとおりです。

dotnet ef dbcontext list

使用可能な DbContext 型を一覧表示します。

一般的なオプションは、上記のとおりです。

dotnet ef dbcontext optimize

DbContext で使用されるモデルのコンパイル済みバージョンを生成します。 EF Core 6 で追加されました。

詳細については、「コンパイル済みモデル」を参照してください。

オプション:

オプション Short 説明
--output-dir <PATH> -o ファイルを格納するディレクトリ。 パスは、プロジェクト ディレクトリに対する相対パスです。
--namespace <NAMESPACE> -n 生成されるすべてのクラスに使用する名前空間。 既定値は、ルート名前空間、および出力ディレクトリと CompiledModels から生成されます。

一般的なオプションは、上記のとおりです。

次の例では、既定の設定を使用し、プロジェクト内に DbContext が 1 つしかない場合に機能します。

dotnet ef dbcontext optimize

次の例では、指定された名前を持つコンテキストに対してモデルを最適化し、それを個別のフォルダーと名前空間に配置します。

dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext

dotnet ef dbcontext scaffold

DbContext のコードとデータベースのエンティティ型を生成します。 このコマンドでエンティティ型を生成するには、データ テーブルに主キーが含まれている必要があります。

引数:

引数 説明
<CONNECTION> データベースへの接続文字列。 ASP.NET Core 2.x プロジェクトの場合、値を、"name=<接続文字列の名前>" にすることができます。 その場合、名前は、プロジェクト用に設定された構成ソースから取得されます。
<PROVIDER> 使用するプロバイダー。 通常、これは、NuGet パッケージの名前です (例: Microsoft.EntityFrameworkCore.SqlServer)。

オプション:

オプション Short 説明
--data-annotations -d 属性を使用してモデルを構成します (可能な場合)。 このオプションを省略すると、fluent API のみが使用されます。
--context <NAME> -c 生成する DbContext クラスの名前。
--context-dir <PATH> DbContext クラス ファイルを格納するディレクトリ。 パスは、プロジェクト ディレクトリに対する相対パスです。 名前空間は、フォルダー名から派生します。
--context-namespace <NAMESPACE> 生成される DbContext クラスに使用する名前空間。 注: --namespace をオーバーライドします。 EF Core 5.0 で追加されました。
--force -f 既存のファイルを上書きします。
--output-dir <PATH> -o エンティティ クラス ファイルを格納するディレクトリ。 パスは、プロジェクト ディレクトリに対する相対パスです。
--namespace <NAMESPACE> -n 生成されるすべてのクラスに使用する名前空間。 既定値は、ルート名前空間と出力ディレクトリから生成されます。 EF Core 5.0 で追加されました。
--schema <SCHEMA_NAME>... エンティティ型を生成するテーブルのスキーマ。 複数のスキーマを指定するには、それぞれについて --schema を繰り返します。 このオプションを省略すると、すべてのスキーマが含まれます。
--table <TABLE_NAME>... -t エンティティ型を生成するテーブル。 複数のテーブルを指定するには、それぞれについて -t または --table を繰り返します。 このオプションを省略すると、すべてのテーブルが含まれます。
--use-database-names データベースに出現するとおりのテーブル名と列名を使用します。 このオプションを省略すると、データベース名が、C# の名前スタイル規則により厳密に準拠するように変更されます。
--no-onconfiguring 生成された DbContext クラスの OnConfiguring メソッドの生成を抑制します。 EF Core 5.0 で追加されました。
--no-pluralize pluralizer を使用しません。 EF Core 5.0 で追加されました

一般的なオプションは、上記のとおりです。

次の例では、すべてのスキーマとテーブルをスキャフォールディングし、新しいファイルを Models フォルダーに格納します。

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models

次の例では、選択したテーブルのみをスキャフォールディングし、指定した名前と名前空間を持つ個別のフォルダーにコンテキストを作成します。

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models -t Blog -t Post --context-dir Context -c BlogContext --context-namespace New.Namespace

次の例では、Secret Manager ツールを使用して設定されたプロジェクトの構成から接続文字列を読み取ります。

dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer

次の例では、OnConfiguring メソッドのスキャフォールディングをスキップします。 これは、クラスの外部で DbContext を構成する場合に便利です。 たとえば、ASP.NET Core アプリでは通常、Startup.ConfigureServices でこれを構成します。 EF Core 5.0 で追加されました。

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

SQL スクリプトを DbContext から生成します。 すべての移行をバイパスします。

オプション:

オプション Short 説明
--output <FILE> -o 結果の書き込み先となるファイル。

一般的なオプションは、上記のとおりです。

dotnet ef migrations add

新しい移行を追加します。

引数:

引数 説明
<NAME> 移行の名前。

オプション:

オプション Short 説明
--output-dir <PATH> -o ファイルの出力に使用するディレクトリ。 パスは、ターゲット プロジェクト ディレクトリに対する相対パスです。 既定値は "Migrations" です。
--namespace <NAMESPACE> -n 生成されるクラスに使用する名前空間。 既定値は、出力ディレクトリから生成されます。 EF Core 5.0 で追加されました。

一般的なオプションは、上記のとおりです。

dotnet ef migrations bundle

データベースを更新するための実行可能ファイルを作成します。

オプション:

オプション Short 説明
--output <FILE> -o 作成する実行可能ファイルのパス。
--force -f 既存のファイルを上書きします。
--self-contained .NET ランタイムもバンドルして、それをマシンにインストールする必要がないようにします。
--target-runtime <RUNTIME_IDENTIFIER> -r バンドルするターゲット ランタイム。

一般的なオプションは、上記のとおりです。

dotnet ef migrations list

使用可能な移行を一覧表示します。

オプション:

オプション 説明
--connection <CONNECTION> データベースへの接続文字列。 既定値は、AddDbContext または OnConfiguring で指定された文字列です。 EF Core 5.0 で追加されました。
--no-connect データベースに接続しません。 EF Core 5.0 で追加されました。

一般的なオプションは、上記のとおりです。

dotnet ef migrations remove

最後の移行を削除して、最新の移行のために行われたコード変更をロールバックします。

オプション:

オプション Short 説明
--force -f 最後の移行を元に戻して、最新の移行のために行われたコードおよびデータベース変更をロールバックします。 データベースへの接続中にエラーが発生した場合、コードの変更のみをロールバックします。

一般的なオプションは、上記のとおりです。

dotnet ef migrations script

移行から SQL スクリプトを生成します。

引数:

引数 説明
<FROM> 開始移行。 移行は、名前または ID で識別できます。 数値 0 は特殊なケースで、"最初の移行の前" を意味します。 既定値は 0 です。
<TO> 終了移行。 既定値は、最後の移行です。

オプション:

オプション Short 説明
--output <FILE> -o スクリプトの書き込み先のファイル。
--idempotent -i 任意の移行時にデータベースで使用できるスクリプトを生成します。
--no-transactions SQL トランザクション ステートメントを生成しません。 EF Core 5.0 で追加されました。

一般的なオプションは、上記のとおりです。

次の例では、InitialCreate 移行用のスクリプトを作成します。

dotnet ef migrations script 0 InitialCreate

次の例では、ID InitialCreate 移行後のすべての移行のスクリプトを生成します。

dotnet ef migrations script 20180904195021_InitialCreate

その他の技術情報