Entity Framework Core ツールのリファレンス - Visual Studio のパッケージ マネージャー コンソール
Entity Framework Core 用のパッケージ マネージャー コンソール (PMC) ツールは、デザイン時の開発タスクを実行します。 たとえば、移行の作成、移行の適用、既存のデータベースに基づくモデルの作成などを行います。 コマンドは、パッケージ マネージャー コンソールを使用して Visual Studio 内で実行されます。 これらのツールは、.NET Framework プロジェクトと .NET Core プロジェクトの両方に使えます。
Visual Studio を使用していない場合は、代わりに EF Core コマンド ライン ツールを使用することをお勧めします。 .NET Core CLI ツールはクロスプラットフォームであり、コマンド プロント内で実行されます。
警告
この記事では、ユーザーの認証を必要としないローカル データベースを使用します。 運用アプリでは、使用可能な最も安全な認証フローを使用する必要があります。 デプロイされたテスト アプリと運用アプリの認証の詳細については、「セキュリティで保護された認証フロー」をご覧ください。
ツールのインストール
パッケージ マネージャー コンソールで次のコマンドを実行して、パッケージ マネージャー コンソール ツールをインストールします。
Install-Package Microsoft.EntityFrameworkCore.Tools
パッケージ マネージャー コンソールで次のコマンドを実行して、ツールを更新します。
Update-Package Microsoft.EntityFrameworkCore.Tools
インストールの確認
次のコマンドを実行して、ツールがインストールされていることを確認します。
Get-Help about_EntityFrameworkCore
出力は次のようになります (使用しているツールのバージョンは示されません)。
_/\__
---==/ \\
___ ___ |. \|\
| __|| __| | ) \\\
| _| | _| \_/ | //|\\
|___||_| / \\\/\\
TOPIC
about_EntityFrameworkCore
SHORT DESCRIPTION
Provides information about the Entity Framework Core Package Manager Console Tools.
<A list of available commands follows, omitted here.>
ツールを使用する
ツールを使用する前に:
- ターゲット プロジェクトとスタートアップ プロジェクトの違いを理解する。
- .NET Standard クラス ライブラリでツールを使用する方法を学習する。
- ASP.NET Core プロジェクトの場合は、環境を設定する。
ターゲット プロジェクトとスタートアップ プロジェクト
コマンドは、"プロジェクト" と "スタートアップ プロジェクト" を参照します。
"プロジェクト" は、コマンドでファイルを追加または削除する場所であるため、"ターゲット プロジェクト" とも呼ばれます。 既定では、パッケージ マネージャー コンソールで選択される既定のプロジェクトがターゲット プロジェクトです。
-Project"スタートアップ プロジェクト" は、ツールによって構築され、実行されるプロジェクトです。 ツールでは、デザイン時にアプリケーション コードを実行して、データベース接続文字列やモデルの構成など、プロジェクトに関する情報を取得する必要があります。 既定では、ソリューション エクスプローラーのスタートアップ プロジェクトが、スタートアップ プロジェクトです。
-StartupProject
多くの場合、スタートアップ プロジェクトとターゲット プロジェクトは同じプロジェクトです。 これらが別個のプロジェクトである一般的なシナリオは、次のような場合です。
- EF Core コンテキストとエンティティ クラスが、.NET Core クラス ライブラリ内にある。
- .NET Core コンソール アプリまたは Web アプリでクラス ライブラリを参照する。
EF Core コンテキストとは別のクラス ライブラリに移行コードを配置することもできます。
その他のターゲット フレームワーク
パッケージ マネージャー コンソール ツールは、.NET Core または .NET Framework プロジェクトで機能します。 EF Core モデルが .NET Standard クラス ライブラリ内にあるアプリには、.NET Core または .NET Framework プロジェクトがない場合があります。 たとえば、Xamarin およびユニバーサル Windows プラットフォーム アプリがこれに該当します。 このような場合、ツールのスタートアップ プロジェクトとして機能することのみを目的とする .NET Core または .NET Framework コンソール アプリ プロジェクトを作成できます。 このプロジェクトは、実際のコードを持たないダミー プロジェクトにすることができます。これは、ツールのターゲットを提供するためにのみ必要です。
ダミー プロジェクトはなぜ必要なのでしょうか? 前にも述べたとおり、ツールでは、デザイン時にアプリケーション コードを実行する必要があります。 そのためには、ツールで .NET Core または .NET Framework ランタイムを使用する必要があります。 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 に渡されます。
Update-Database -Args '--environment Production'
共通パラメーター
次の表に、すべての EF Core コマンドに共通するパラメーターを示します。
| パラメーター | 説明 |
|---|---|
-Context <String> |
使用する DbContext クラス。 クラス名のみ、または名前空間で完全修飾された名前。 このパラメーターを省略すると、EF Core によってコンテキスト クラスが検出されます。 複数のコンテキスト クラスがある場合、このパラメーターが必要です。 |
-Project <String> |
ターゲット プロジェクト。 このパラメーターを省略すると、パッケージ マネージャー コンソールの既定プロジェクトがターゲット プロジェクトとして使用されます。 |
-StartupProject <String> |
スタートアップ プロジェクト。 このパラメーターを省略すると、ソリューション プロパティのスタートアップ プロジェクトがターゲット プロジェクトとして使用されます。 |
-Args <String> |
アプリケーションに渡される引数。 |
-Verbose |
詳細出力を表示します。 |
コマンドに関するヘルプ情報を表示するには、PowerShell の Get-Help コマンドを使用します。
ヒント
Context、Project、StartupProject の各パラメーターでは、タブ拡張がサポートされます。
Add-Migration
新しい移行を追加します。
パラメーター:
| パラメーター | 説明 |
|---|---|
-Name <String> |
移行の名前。 これは、位置指定パラメーターであり、必須です。 |
-OutputDir <String> |
ファイルの出力に使用するディレクトリ。 パスは、ターゲット プロジェクト ディレクトリに対する相対パスです。 既定値は "Migrations" です。 |
-Namespace <String> |
生成されるクラスに使用する名前空間。 既定値は、出力ディレクトリから生成されます。 |
共通パラメーターは、上記のとおりです。
Bundle-Migration
データベースを更新するための実行可能ファイルを作成します。
パラメーター:
| パラメーター | 説明 |
|---|---|
-Output <String> |
作成する実行可能ファイルのパス。 |
-Force |
既存のファイルを上書きします。 |
-SelfContained |
.NET ランタイムもバンドルして、それをマシンにインストールする必要がないようにします。 |
-TargetRuntime <String> |
バンドルするターゲット ランタイム。 |
-Framework <String> |
ターゲット フレームワーク。 既定では、プロジェクト内の最初のものです。 |
共通パラメーターは、上記のとおりです。
Drop-Database
データベースをドロップします。
パラメーター:
| パラメーター | 説明 |
|---|---|
-WhatIf |
ドロップされるデータベースを表示しますが、ドロップは行われません。 |
共通パラメーターは、上記のとおりです。
Get-DbContext
使用可能な DbContext 型に関する情報を一覧表示し、取得します。
共通パラメーターは、上記のとおりです。
Get-Migration
使用可能な移行を一覧表示します。
パラメーター:
| パラメーター | 説明 |
|---|---|
-Connection <String> |
データベースへの接続文字列。 既定値は、AddDbContext または OnConfiguring で指定された文字列です。 |
-NoConnect |
データベースに接続しません。 |
共通パラメーターは、上記のとおりです。
Optimize-DbContext
DbContext で使用されるモデルのコンパイル済みバージョンを生成します。
詳細については、「コンパイル済みモデル」を参照してください。
パラメーター:
| パラメーター | 説明 |
|---|---|
-OutputDir <String> |
ファイルを格納するディレクトリ。 パスは、プロジェクト ディレクトリに対する相対パスです。 |
-Namespace <String> |
生成されるすべてのクラスに使用する名前空間。 既定値は、ルート名前空間、および出力ディレクトリと CompiledModels から生成されます。 |
共通パラメーターは、上記のとおりです。
Note
現在、PMC ツールでは、NativeAOT コンパイルとプリコンパイル済みクエリに必要なコードの生成はサポートされていません。
次の例では既定値を使用します。これは、プロジェクトに DbContext が 1 つしかない場合に機能します。
Optimize-DbContext
次の例では、指定された名前を持つコンテキストに対してモデルを最適化し、それを個別のフォルダーと名前空間に配置します。
Optimize-DbContext -OutputDir Models -Namespace BlogModels -Context BlogContext
Remove-Migration
最後の移行を削除します (移行のために行われたコード変更をロールバックします)。
パラメーター:
| パラメーター | 説明 |
|---|---|
-Force |
移行を元に戻します (データベースに適用された変更をロールバックします)。 |
共通パラメーターは、上記のとおりです。
Scaffold-DbContext
DbContext のコードとデータベースのエンティティ型を生成します。 Scaffold-DbContext でエンティティ型を生成するには、データ テーブルに主キーが含まれている必要があります。
パラメーター:
| パラメーター | 説明 |
|---|---|
-Connection <String> |
データベースへの接続文字列。 値には、接続文字列>の name=<name を指定できます。 その場合、名前はプロジェクト用に設定された 構成ソース から取得されます。 これは、位置指定パラメーターであり、必須です。 |
-Provider <String> |
使用するプロバイダー。 通常、これは、NuGet パッケージの名前です (例: Microsoft.EntityFrameworkCore.SqlServer)。 これは、位置指定パラメーターであり、必須です。 |
-OutputDir <String> |
エンティティ クラス ファイルを格納するディレクトリ。 パスは、プロジェクト ディレクトリに対する相対パスです。 |
-ContextDir <String> |
DbContext ファイルを格納するディレクトリ。 パスは、プロジェクト ディレクトリに対する相対パスです。 |
-Namespace <String> |
生成されるすべてのクラスに使用する名前空間。 既定値は、ルート名前空間と出力ディレクトリから生成されます。 |
-ContextNamespace <String> |
生成される DbContext クラスに使用する名前空間。 注: -Namespace をオーバーライドします。 |
-Context <String> |
生成する DbContext クラスの名前。 |
-Schemas <String[]> |
エンティティ型を生成するテーブルとビューのスキーマ。 このパラメーターを省略すると、すべてのスキーマが含まれます。 このオプションを使うと、-Table を使用して明示的に含まれていない場合でも、スキーマ内のすべてのテーブルとビューがモデルに含まれます。 |
-Tables <String[]> |
エンティティ型を生成するテーブルとビュー。 特定のスキーマのテーブルまたはビューは、"schema.table" または "schema.view" の形式を使って含めることができます。 このパラメーターを省略すると、すべてのテーブルとビューが含まれます。 |
-DataAnnotations |
属性を使用してモデルを構成します (可能な場合)。 このパラメーターを省略すると、fluent API のみが使用されます。 |
-UseDatabaseNames |
テーブル、ビュー、シーケンス、および列名は、データベースに示されるとおりに使用します。 このパラメーターを省略すると、データベース名が、C# の名前スタイル規則により厳密に準拠するように変更されます。 |
-Force |
既存のファイルを上書きします。 |
-NoOnConfiguring |
DbContext.OnConfiguring を生成しません。 |
-NoPluralize |
pluralizer を使用しません。 |
共通パラメーターは、上記のとおりです。
例:
Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models
選択したテーブルのみをスキャフォールディングし、指定した名前と名前空間を持つ個別のフォルダーにコンテキストを作成する例:
Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models -Tables "Blog","Post" -ContextDir Context -Context BlogContext -ContextNamespace New.Namespace
次の例 Configuration を使用して接続文字列を読み取ります。
Scaffold-DbContext "Name=ConnectionStrings:Blogging" Microsoft.EntityFrameworkCore.SqlServer
Script-DbContext
SQL スクリプトを DbContext から生成します。 すべての移行をバイパスします。
パラメーター:
| パラメーター | 説明 |
|---|---|
-Output <String> |
結果の書き込み先となるファイル。 |
共通パラメーターは、上記のとおりです。
Script-Migration
選択されたある移行のすべての変更を、選択された別の移行に適用する SQL スクリプトを生成します。
パラメーター:
| パラメーター | 説明 |
|---|---|
-From <String> |
開始移行。 移行は、名前または ID で識別できます。 数値 0 は特殊なケースで、"最初の移行の前" を意味します。 既定値は 0 です。 |
-To <String> |
終了移行。 既定値は、最後の移行です。 |
-Idempotent |
任意の移行時にデータベースで使用できるスクリプトを生成します。 |
-NoTransactions |
SQL トランザクション ステートメントを生成しません。 |
-Output <String> |
結果の書き込み先となるファイル。 このパラメーターを省略すると、アプリのランタイム ファイルが作成されたフォルダーと同じフォルダーに生成された名前でファイルが作成されます (例: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/)。 |
共通パラメーターは、上記のとおりです。
ヒント
To、From、Output の各パラメーターでは、タブ拡張がサポートされます。
次の例では、移行名を使用して、(移行のないデータベースから) InitialCreate 移行のスクリプトを生成します。
Script-Migration 0 InitialCreate
次の例では、移行 ID を使用して、InitialCreate 移行後のすべての移行のスクリプトを生成します。
Script-Migration 20180904195021_InitialCreate
Update-Database
データベースを最後の移行または指定された移行に更新します。
| パラメーター | 説明 |
|---|---|
-Migration <String> |
ターゲット移行。 移行は、名前または ID で識別できます。 数値 0 は特殊なケースで、"最初の移行の前" を意味し、すべての移行を元に戻します。 移行を指定しない場合、コマンドでは、既定値が最後の移行に設定されます。 |
-Connection <String> |
データベースへの接続文字列。 既定値は、AddDbContext または OnConfiguring で指定された文字列です。 |
共通パラメーターは、上記のとおりです。
ヒント
Migration パラメーターでは、タブ拡張がサポートされます。
次の例では、すべての移行を元に戻します。
Update-Database 0
次の例では、データベースを指定された移行に更新します。 1 つ目は移行名を使用し、2 つ目は、移行 ID と指定された接続を使用します。
Update-Database InitialCreate
Update-Database 20180904195021_InitialCreate -Connection your_connection_string
その他のリソース
.NET