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

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

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 クラス ライブラリにあります。
• .NET コンソール アプリまたは Web アプリは、クラス ライブラリを参照します。

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

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

CLI ツールは、.NET ランタイムを使用してアプリケーション コードを実行する必要があります。 ツールのスタートアップ プロジェクトとして、.NET MAUI、WinUI、Blazor WebAssembly、Azure Functionsなどのプラットフォーム固有のアプリケーションを使用しないでください。 代わりに、IDesignTimeDbContextFactory<TContext>を使用して通常のクロスプラットフォーム .NET プロジェクトに移行を配置し、そのプロジェクトをターゲット プロジェクトとスタートアップ プロジェクトの両方として使用します。 個別の移行Projectの使用を参照してください。

ツールを実行するプロセスは、ターゲット アセンブリとスタートアップ アセンブリを読み込める必要があります。 たとえば、64 ビット ツール プロセスでは、x86 のみのスタートアップ アセンブリを読み込めません。 AnyCPU 移行プロジェクトを優先します。 デザイン時の依存関係に特定のアーキテクチャが必要な場合は、一致する.NET SDK を明示的に呼び出します。 --runtime オプションは、ランタイム識別子の復元を制御します。現在のツール プロセスのアーキテクチャは変更されません。

ASP.NET Core 環境

ASP.NET Core プロジェクト用の環境はコマンドラインで指定できます。 これと追加の引数は Program.CreateHostBuilder に渡されます。

dotnet ef database update -- --environment Production

共通オプション

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

dotnet ef database drop

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

Options:

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

dotnet ef database update

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

Arguments:

Options:

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

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

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

次の例では、新しい移行を作成し、1 つの手順でデータベースに適用します。

dotnet ef database update InitialCreate --add
dotnet ef database update AddProducts --add --output-dir Migrations/Products --namespace MyApp.Migrations

dotnet ef dbcontext info

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

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

dotnet ef dbcontext list

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

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

dotnet ef dbcontext optimize

DbContextによって使用されるモデルのコンパイル済みバージョンを生成し、クエリをプリコンパイルします。

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

Options:

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

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

dotnet ef dbcontext optimize

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

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

dotnet ef dbcontext scaffold

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

Arguments:

Options:

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

次の例では、すべてのスキーマとテーブルをスキャフォールディングし、新しいファイルを 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;Integrated Security=true;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

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

Options:

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

dotnet ef migrations add

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

Arguments:

Options:

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

dotnet ef migrations bundle

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

Options:

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

dotnet ef migrations has-pending-model-changes

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

Options:

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

dotnet ef migrations list

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

Options:

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

dotnet ef migrations remove

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

Options:

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

dotnet ef migrations script

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

--output指定されていない場合、コマンドはスクリプトを標準出力に書き込みます。

Arguments:

Options:

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

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

dotnet ef migrations script 0 InitialCreate

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

dotnet ef migrations script 20180904195021_InitialCreate

構成ファイル

EF Core 11 以降では、 dotnet ef は JSON 構成ファイルから既定のオプション値を読み込むことができます。 これにより、複数の呼び出しで同じコマンド ライン オプションを繰り返す必要が減ります。

ファイルの場所と検出

dotnet-ef.json ディレクトリ内に .config という名前のファイルを配置します。

<repository root>/
└── .config/
    └── dotnet-ef.json

dotnet ef実行すると、現在の作業ディレクトリからディレクトリ ツリーがウォークアップされ、検出された最初の.config/dotnet-ef.json ファイルが使用されます。 つまり、リポジトリのルートにファイルを配置でき、任意のサブディレクトリから使用されます。

サポートされているプロパティ

構成ファイルは、次の省略可能なプロパティを持つ JSON オブジェクトです。

{
  "project": "src/App.Infrastructure",
  "startupProject": "src/App.Api",
  "framework": "net11.0",
  "configuration": "Debug",
  "context": "AppDbContext",
  "runtime": "win-x64",
  "verbose": true,
  "noColor": false,
  "prefixOutput": false
}

すべてのプロパティは省略可能です。 必要なプロパティのみを含めます。

その他のリソース

• Migrations
• リバース エンジニアリング
• コンパイル済みモデル