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

[アーティクル]
08/24/2023

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 プロジェクト用の環境はコマンドラインで指定できます。この引数と追加の引数は 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>`		ビルド構成 (`Debug` や `Release` など)。
`--runtime <IDENTIFIER>`		パッケージを復元するターゲットランタイムの識別子。ランタイム ID (RID) の一覧については、RID カタログに関するページをご覧ください。
`--no-build`		プロジェクトをビルドしません。ビルドが最新であるときに使用することを想定しています。
`--help`	`-h`	ヘルプ情報を表示します。
`--verbose`	`-v`	詳細出力を表示します。
`--no-color`		出力を色分けしません。
`--prefix-output`		レベルを含むプレフィックス出力。

追加の引数はすべてアプリケーションに渡されます。

`dotnet ef database drop`

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

"オプション:

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

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

`dotnet ef database update`

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

引数:

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

"オプション:

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

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

次の例では、データベースを指定された移行に更新します。 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 で使用されるモデルのコンパイル済みバージョンを生成します。

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

"オプション:

オプション	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` をオーバーライドします。
`--force`	`-f`	既存のファイルを上書きします。
`--output-dir <PATH>`	`-o`	エンティティクラスファイルを格納するディレクトリ。パスは、プロジェクトディレクトリに対する相対パスです。
`--namespace <NAMESPACE>`	`-n`	生成されるすべてのクラスに使用する名前空間。既定値は、ルート名前空間と出力ディレクトリから生成されます。
`--schema <SCHEMA_NAME>...`		エンティティ型を生成するテーブルとビューのスキーマ。複数のスキーマを指定するには、それぞれについて `--schema` を繰り返します。このオプションを省略すると、すべてのスキーマが含まれます。このオプションを使うと、--table を使用して明示的に含まれていない場合でも、スキーマ内のすべてのテーブルとビューがモデルに含まれます。
`--table <TABLE_NAME>...`	`-t`	エンティティ型を生成するテーブルとビュー。複数のテーブルを指定するには、それぞれについて `-t` または `--table` を繰り返します。特定のスキーマのテーブルまたはビューは、"schema.table" または "schema.view" の形式を使って含めることができます。このオプションを省略すると、すべてのテーブルとビューが含まれます。
`--use-database-names`		テーブル、ビュー、シーケンス、および列名は、データベースに示されるとおりに使用します。このオプションを省略すると、データベース名が、C# の名前スタイル規則により厳密に準拠するように変更されます。
`--no-onconfiguring`		生成された `DbContext` クラスの `OnConfiguring` メソッドの生成を抑制します。
`--no-pluralize`		pluralizer を使用しません。

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

次の例では、すべてのスキーマとテーブルをスキャフォールディングし、新しいファイルを 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 でこれを構成します。

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`	生成されるクラスに使用する名前空間。既定値は、出力ディレクトリから生成されます。

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

`dotnet ef migrations bundle`

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

"オプション:

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

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

`dotnet ef migrations has-pending-model-changes`

Note

このコマンドは EF Core 8.0 で追加されました。

前回の移行以降にモデルに変更が加えられたかどうかを確認します。

"オプション:

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

`dotnet ef migrations list`

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

"オプション:

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

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

`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 トランザクションステートメントを生成しません。

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

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

dotnet ef migrations script 0 InitialCreate

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

dotnet ef migrations script 20180904195021_InitialCreate

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

ツールのインストール

インストールを検証する

ツールを更新する

ツールの使用

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

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

ASP.NET Core 環境

共通のオプション

`dotnet ef database drop`

`dotnet ef database update`

`dotnet ef dbcontext info`

`dotnet ef dbcontext list`

`dotnet ef dbcontext optimize`

`dotnet ef dbcontext scaffold`

`dotnet ef dbcontext script`

`dotnet ef migrations add`

`dotnet ef migrations bundle`

`dotnet ef migrations has-pending-model-changes`

`dotnet ef migrations list`

`dotnet ef migrations remove`

`dotnet ef migrations script`

その他のリソース

フィードバック

その他のリソース

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

ツールのインストール

インストールを検証する

ツールを更新する

ツールの使用

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

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

ASP.NET Core 環境

共通のオプション

dotnet ef database drop

dotnet ef database update

dotnet ef dbcontext info

dotnet ef dbcontext list

dotnet ef dbcontext optimize

dotnet ef dbcontext scaffold

dotnet ef dbcontext script

dotnet ef migrations add

dotnet ef migrations bundle

dotnet ef migrations has-pending-model-changes

dotnet ef migrations list

dotnet ef migrations remove

dotnet ef migrations script

その他のリソース

フィードバック

その他のリソース

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

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

`dotnet ef database drop`

`dotnet ef database update`

`dotnet ef dbcontext info`

`dotnet ef dbcontext list`

`dotnet ef dbcontext optimize`

`dotnet ef dbcontext scaffold`

`dotnet ef dbcontext script`

`dotnet ef migrations add`

`dotnet ef migrations bundle`

`dotnet ef migrations has-pending-model-changes`

`dotnet ef migrations list`

`dotnet ef migrations remove`

`dotnet ef migrations script`