Entity Framework Core-Toolsreferenz – .NET Core-CLI
Die Befehlszeilenschnittstellen-Tools (Command-Line Interface, CLI) für Entity Framework Core führen Entwicklungsaufgaben zur Entwurfszeit aus. Sie erstellen beispielsweise Migrationen, wenden Migrationen an und generieren basierend auf einer vorhandenen Datenbank Code für ein Modell. Die Befehle sind eine Erweiterung des plattformübergreifenden dotnet-Befehls, der Teil des .NET Core SDK ist. Diese Tools funktionieren mit .NET Core-Projekten.
Wenn Sie Visual Studio verwenden, sollten Sie die Paket-Manager-Konsolentools anstelle der CLI-Tools verwenden. Die Paket-Manager-Konsolen-Tools führen Folgendes automatisch aus:
- Zusammenarbeit mit dem aktuell in der Paket-Manager-Konsole ausgewählten Projekt, ohne dass Sie manuell zwischen den Verzeichnissen wechseln müssen.
- Öffnen von Dateien, die von einem Befehl generiert wurden, nachdem der Befehl abgeschlossen wurde.
- Vervollständigung per TAB-TASTE von Befehlen, Parametern, Projektnamen, Kontexttypen und Migrationsnamen.
Installieren der Tools
dotnet ef kann entweder als globales oder lokales Tool installiert werden. Die meisten Entwickler bevorzugen das Installieren von dotnet ef als globales Tool mithilfe des folgenden Befehls:
dotnet tool install --global dotnet-ef
Für die Verwendung als lokales Tool stellen Sie die Abhängigkeiten eines Projekts wieder her, das das Tool mithilfe einer Toolmanifestdatei als Toolabhängigkeit deklariert.
Aktualisieren Sie das Tool mithilfe des folgenden Befehls:
dotnet tool update --global dotnet-ef
Bevor Sie die Tools für ein bestimmtes Projekt verwenden können, müssen Sie das Microsoft.EntityFrameworkCore.Design-Paket hinzufügen.
dotnet add package Microsoft.EntityFrameworkCore.Design
Überprüfen der Installation
Führen Sie die folgenden Befehle aus, um zu überprüfen, ob EF Core CLI-Tools ordnungsgemäß installiert sind:
dotnet ef
Die Ausgabe des Befehls identifiziert die verwendete Version der Tools:
_/\__
---==/ \\
___ ___ |. \|\
| __|| __| | ) \\\
| _| | _| \_/ | //|\\
|___||_| / \\\/\\
Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065
<Usage documentation follows, not shown.>
Aktualisieren der Tools
Aktualisieren Sie mit dotnet tool update --global dotnet-ef die globalen Tools auf die neueste verfügbare Version. Wenn die Tools lokal in Ihrem Projekt installiert sind, verwenden Sie dotnet tool update dotnet-ef. Installieren Sie eine bestimmte Version, indem Sie Ihrem Befehl --version <VERSION> anfügen. Weitere Informationen finden Sie im Abschnitt Update der Dotnet-Tooldokumentation.
Verwenden der Tools
Bevor Sie die Tools verwenden, müssen Sie möglicherweise ein Startprojekt erstellen oder die Umgebung festlegen.
Ziel- und Startprojekt
Die Befehle beziehen sich auf ein Projekt und ein Startprojekt.
Das Projekt wird auch als Zielprojekt bezeichnet, da dort die Befehle Dateien hinzufügen oder entfernen. Standardmäßig ist das Projekt im aktuellen Verzeichnis das Zielprojekt. Sie können mit der Option
--projectDas Startprojekt ist dasjenige, das die Tools erstellen und ausführen. Die Tools müssen zur Entwurfszeit Anwendungscode ausführen, um Informationen zum Projekt abzurufen, z. B. die Datenbankverbindungszeichenfolge und die Konfiguration des Modells. Standardmäßig ist das Projekt im aktuellen Verzeichnis das Startprojekt. Sie können mit der Option
--startup-project
Startprojekt und Zielprojekt sind oft identisch. Ein typisches Szenario mit separaten Projekten ist folgendes:
- EF Core-Kontext und Entitätsklassen befinden sich in einer .NET Core-Klassenbibliothek.
- Eine .NET Core-Konsolen-App oder Web-App verweist auf die Klassenbibliothek.
Es ist auch möglich, Migrationscode in einer Klassenbibliothek getrennt vom EF Core-Kontext unterzubringen.
Andere Zielframeworks
Die CLI-Tools funktionieren sowohl mit .NET Core- als auch mit .NET Framework-Projekten. Apps mit dem EF Core-Modell in einer .NET Standard-Klassenbibliothek verfügen möglicherweise nicht über ein .NET Core- oder .NET Framework-Projekt. Dies gilt beispielsweise für Xamarin- und Universelle Windows-Plattform-Apps. In solchen Fällen können Sie ein .NET Core-Konsolen-App-Projekt erstellen, dessen einziger Zweck ist, als Startprojekt für die Tools zu dienen. Das Projekt kann ein Dummyprojekt ohne realen Code sein. Es wird nur zur Bereitstellung eines Ziels für Tools benötigt.
Warum ist ein Dummyprojekt erforderlich? Wie bereits erwähnt, müssen die Tools zur Entwurfszeit Anwendungscode ausführen. Dazu müssen sie die .NET Core-Laufzeit verwenden. Wenn sich das EF Core-Modell in einem Projekt befindet, das auf .NET Core oder .NET Framework abzielt, leihen sich die EF Core-Tools die Laufzeit vom Projekt. Dies können sie nicht, wenn sich das EF Core-Modell in einer .NET Standard-Klassenbibliothek befindet. .NET Standard ist keine tatsächliche .NET-Implementierung, sondern eine Spezifikation einer Reihe von APIs, die .NET-Implementierungen unterstützen müssen. Daher reicht .NET Standard nicht aus, damit die EF Core-Tools Anwendungscode ausführen können. Das Dummyprojekt, das Sie als Startprojekt erstellen, stellt eine konkrete Zielplattform bereit, in die die Tools die .NET Standard-Klassenbibliothek laden können.
ASP.NET Core-Umgebung
Sie können die Umgebung für ASP.NET Core-Projekte in der Befehlszeile angeben. Dies und alle zusätzlichen Argumente werden an Program.CreateHostBuilder übergeben.
dotnet ef database update -- --environment Production
Tipp
Das ---Token weist dotnet ef an, alles Nachfolgende als Argument zu behandeln und nicht zu versuchen, es als Optionen zu parsen. Alle zusätzlichen Argumente, die von dotnet ef nicht verwendet werden, werden an die App weitergeleitet.
Allgemeine Optionen
| Option | Short | Beschreibung |
|---|---|---|
--json |
Zeigen Sie die JSON-Ausgabe an. | |
--context <DBCONTEXT> |
-c |
Die DbContext-Klasse, die verwendet werden soll. Nur Klassenname oder vollqualifiziert mit Namespaces. Wenn diese Option ausgelassen wird, findet EF Core die Kontextklasse. Wenn mehrere Kontextklassen vorhanden sind, ist diese Option erforderlich. |
--project <PROJECT> |
-p |
Relativer Pfad zum Projektordner des Zielprojekts. Der Standardwert ist der aktuelle Ordner. |
--startup-project <PROJECT> |
-s |
Relativer Pfad zum Projektordner des Startprojekts. Der Standardwert ist der aktuelle Ordner. |
--framework <FRAMEWORK> |
Der für das Zielframework verwendete Zielframeworkmoniker. Verwenden Sie diese Option, wenn die Projektdatei mehrere Zielframeworks angibt, und Sie eines davon auswählen möchten. | |
--configuration <CONFIGURATION> |
Die Buildkonfiguration, z. B.: Debug or Release. |
|
--runtime <IDENTIFIER> |
Der Bezeichner der Ziellaufzeit, für die Pakete wiederhergestellt werden sollen. Eine Liste der Runtime-IDs (RIDs) finden Sie unter RID-Katalog. | |
--no-build |
Erstellen Sie nicht das Projekt. Soll verwendet werden, wenn der Build auf dem neuesten Stand ist. | |
--help |
-h |
Zeigt Hilfeinformationen an |
--verbose |
-v |
Zeigt eine ausführliche Ausgabe an. |
--no-color |
Färben Sie die Ausgabe nicht ein. | |
--prefix-output |
Stellen Sie der Ausgabe eine Ebene voran. |
Alle zusätzlichen Argumente werden an die Anwendung übergeben.
dotnet ef database drop
Löscht die Datenbank.
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--force |
-f |
Bestätigen Sie nicht. |
--dry-run |
Zeigen Sie, welche Datenbank gelöscht werden würde, löschen Sie sie aber nicht. |
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef database update
Aktualisiert die Datenbank auf die letzte Migration oder eine angegebene Migration.
Argumente:
| Argument | Beschreibung |
|---|---|
<MIGRATION> |
Die Zielmigration. Migrationen können anhand des Namens oder der ID identifiziert werden. Die Zahl 0 ist ein Sonderfall, der vor der ersten Migration bedeutet und alle Migrationen rückgängig macht. Wenn keine Migration angegeben ist, wird der Befehl standardmäßig für die letzte Migration verwendet. |
Optionen:
| Option | Beschreibung |
|---|---|
--connection <CONNECTION> |
Die Verbindungszeichenfolge für die Datenbank. Standard ist die in AddDbContext oder OnConfiguring angegebene. |
Die gängigsten Optionen sind unten aufgeführt.
In den folgenden Beispielen wird die Datenbank auf eine angegebene Migration aktualisiert. Im ersten wird der Migrationsname und im zweiten werden die Migrations-ID und eine angegebene Verbindung verwendet:
dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string
dotnet ef dbcontext info
Ruft Informationen zu einem DbContext-Typ ab.
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef dbcontext list
Listet alle verfügbaren DbContext-Typen auf.
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef dbcontext optimize
Generiert eine kompilierte Version des Modells, die von DbContext verwendet wird.
Weitere Informationen finden Sie unter Kompilierte Modelle.
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--output-dir <PATH> |
-o |
Das Verzeichnis, in dem Dateien abgelegt werden sollen. Die Pfade sind relativ zum Projektverzeichnis. |
--namespace <NAMESPACE> |
-n |
Der für alle generierten Klassen zu verwendende Namespace. Wird standardmäßig aus dem Stammnamespace und dem Ausgabeverzeichnis plus CompiledModels generiert. |
Die gängigsten Optionen sind unten aufgeführt.
Im folgenden Beispiel werden die Standardeinstellungen verwendet, und dies funktioniert, wenn im Projekt nur ein DbContext vorhanden ist:
dotnet ef dbcontext optimize
Im folgenden Beispiel wird das Modell für den Kontext mit dem angegebenen Namen optimiert und in einem separaten Ordner und Namespace platziert:
dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext
dotnet ef dbcontext scaffold
Generiert Code für einen DbContext und Entitätstypen für eine Datenbank. Damit dieser Befehl einen Entitätstyp generieren kann, muss die Datenbanktabelle über einen Primärschlüssel verfügen.
Argumente:
| Argument | Beschreibung |
|---|---|
<CONNECTION> |
Die Verbindungszeichenfolge für die Datenbank. Für ASP.NET Core 2.x-Projekte kann der Wert name=<Name der Verbindungszeichenfolge> sein. In diesem Fall stammt der Name aus den für das Projekt eingerichteten Konfigurationsquellen. |
<PROVIDER> |
Der zu verwendende Anbieter. In der Regel ist dies der Name des NuGet-Pakets, z. B.: Microsoft.EntityFrameworkCore.SqlServer. |
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--data-annotations |
-d |
Verwenden Sie Attribute zum Konfigurieren des Modells (sofern möglich). Wenn diese Option ausgelassen wird, wird nur die Fluent-API verwendet. |
--context <NAME> |
-c |
Der Name der zu generierenden DbContext-Klasse. |
--context-dir <PATH> |
Das Verzeichnis, in dem die DbContext-Datei abgelegt werden soll. Die Pfade sind relativ zum Projektverzeichnis. Namespaces werden von den Ordnernamen abgeleitet. |
|
--context-namespace <NAMESPACE> |
Der Name des für die generierte DbContext-Klasse verwendeten Namespace. Hinweis: Überschreibt --namespace. |
|
--force |
-f |
Überschreibt vorhandene Dateien. |
--output-dir <PATH> |
-o |
Das Verzeichnis, in das Entitätsklassendateien eingefügt werden sollen. Die Pfade sind relativ zum Projektverzeichnis. |
--namespace <NAMESPACE> |
-n |
Der für alle generierten Klassen zu verwendende Namespace. Wird standardmäßig aus dem Stammnamespace und dem Ausgabeverzeichnis generiert. |
--schema <SCHEMA_NAME>... |
Die Schemas von Tabellen und Ansichten, für die Entitätstypen generiert werden sollen. Um mehrere Schemas anzugeben, wiederholen Sie --schema für jedes Schema. Wenn diese Option ausgelassen wird, werden alle Schemas einbezogen. Bei Verwendung dieser Option werden alle Tabellen und Sichten in den Schemas auch dann in das Modell einbezogen, wenn sie nicht explizit mit „--table“ einbezogen werden. |
|
--table <TABLE_NAME>... |
-t |
Die Tabellen und Ansichten, für die Entitätstypen generiert werden sollen. Um mehrere Tabellen anzugeben, wiederholen Sie -t oder --table für jedes Schema. Tabellen oder Sichten in einem bestimmten Schema können im Format „schema.table“ bzw. „schema.view“ eingefügt werden. Wenn diese Option ausgelassen wird, werden alle Tabellen und Sichten einbezogen. |
--use-database-names |
Verwenden Sie Tabellen-, Ansichts-, Sequenz- und Spaltennamen genau so, wie sie in der Datenbank vorkommen. Wenn diese Option ausgelassen wird, werden Datenbanknamen so geändert, dass sie eher den C#-Namensstilkonventionen entsprechen. | |
--no-onconfiguring |
Unterdrückt die Generierung der OnConfiguring-Methode in der generierten DbContext Klasse. |
|
--no-pluralize |
Verwenden Sie den Pluralizer nicht. |
Die gängigsten Optionen sind unten aufgeführt.
Im folgenden Beispiel wird der Gerüstbau für alle Schemas und Tabellen durchgeführt, und die neuen Dateien werden im Ordner Models abgelegt.
dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models
Im folgenden Beispiel wird Gerüstbau nur für ausgewählte Tabellen durchgeführt und der Kontext in einem separaten Ordner mit einem angegebenen Namen und Namespace erstellt:
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
Im folgenden Beispiel wird die Verbindungszeichenfolge aus der Konfiguration des Projekts gelesen, die mit dem Secret Manager-Tool festgelegt wurde.
dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer
Im folgenden Beispiel wird der Gerüstbau für eine OnConfiguring-Methode übersprungen. Dies kann nützlich sein, wenn Sie den DbContext außerhalb der Klasse konfigurieren möchten. ASP.NET Core-Apps beispielsweise konfigurieren ihn in der Regel in 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
Generiert ein SQL-Skript aus dem DbContext. Umgeht alle Migrationen.
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--output <FILE> |
-o |
Die Datei, in die das Ergebnis geschrieben werden soll. |
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef migrations add
Fügt eine neue Migration hinzu.
Argumente:
| Argument | Beschreibung |
|---|---|
<NAME> |
Der Name der Migration. |
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--output-dir <PATH> |
-o |
Das Verzeichnis, das zum Ausgeben der Dateien verwendet wird. Die Pfade sind relativ zum Zielprojektverzeichnis. Standardmäßig wird „Migrations“ verwendet. |
--namespace <NAMESPACE> |
-n |
Der für die generierten Klassen zu verwendende Namespace. Wird standardmäßig aus dem Ausgabeverzeichnis generiert. |
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef migrations bundle
Erstellt eine ausführbare Datei zum Aktualisieren der Datenbank.
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--output <FILE> |
-o |
Der Pfad der zu erstellenden ausführbaren Datei. |
--force |
-f |
Überschreibt vorhandene Dateien. |
--self-contained |
Bündelt auch die .NET-Laufzeit, damit sie nicht auf dem Computer installiert werden muss. | |
--target-runtime <RUNTIME_IDENTIFIER> |
-r |
Die Ziellaufzeit, für die gebündelt wird. |
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef migrations has-pending-model-changes
Hinweis
Dieser Befehl wurde in EF Core 8.0 hinzugefügt.
Überprüft, ob seit der letzten Migration Änderungen am Modell vorgenommen wurden.
Optionen:
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef migrations list
Listet verfügbare Migrationen auf.
Optionen:
| Option | Beschreibung |
|---|---|
--connection <CONNECTION> |
Die Verbindungszeichenfolge für die Datenbank. Der Standard ist die in AddDbContext oder OnConfiguring angegebene. |
--no-connect |
Stellen Sie keine Verbindung mit der Datenbank her. |
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef migrations remove
Entfernt die letzte Migration. Für die für die letzte Migration vorgenommenen Codeänderungen wird ein Rollback ausgeführt.
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--force |
-f |
Macht die letzte Migration rückgängig. Für die für die letzte Migration vorgenommenen Code- und Datenbankänderungen wird ein Rollback ausgeführt. Führt nur ein Rollback für die Codeänderungen aus, wenn beim Herstellen einer Verbindung mit der Datenbank ein Fehler auftritt. |
Die gängigsten Optionen sind unten aufgeführt.
dotnet ef migrations script
Generiert ein SQL-Skript aus Migrationen.
Argumente:
| Argument | Beschreibung |
|---|---|
<FROM> |
Die Ausgangsmigration. Migrationen können anhand des Namens oder der ID identifiziert werden. Die Zahl 0 ist ein Sonderfall, der vor der ersten Migration bedeutet. Der Standardwert ist 0. |
<TO> |
Die Endmigration. Standard ist die letzte Migration. |
Optionen:
| Option | Short | Beschreibung |
|---|---|---|
--output <FILE> |
-o |
Die Datei, in die das Skript geschrieben werden soll. |
--idempotent |
-i |
Generieren Sie ein Skript, das bei jeder Migration für eine Datenbank verwendet werden kann. |
--no-transactions |
Generieren Sie keine SQL-Transaktionsanweisungen. |
Die gängigsten Optionen sind unten aufgeführt.
Im folgenden Beispiel wird ein Skript für die InitialCreate-Migration erstellt:
dotnet ef migrations script 0 InitialCreate
Im folgenden Beispiel wird ein Skript für alle Migrationen nach der InitialCreate-Migration erstellt.
dotnet ef migrations script 20180904195021_InitialCreate
