Referenz zu Entity Framework Core-Tools – .NET Core CLI
Die Befehlszeilenschnittstellentools (CLI) für Entity Framework Core führen Entwurfszeitentwicklungsaufgaben aus. Sie erstellen beispielsweise Migrationen, wenden Migrationen an und generieren Code für ein Modell basierend auf einer vorhandenen Datenbank. 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 Tools der Paket-Manager-Konsole anstelle der CLI-Tools verwenden. Paket-Manager-Konsolentools automatisch:
- Funktioniert mit dem aktuellen Projekt, das in der Paket-Manager-Konsole ausgewählt wurde, ohne dass Sie die Verzeichnisse manuell wechseln müssen.
- Öffnet Dateien, die von einem Befehl generiert wurden, nachdem der Befehl abgeschlossen wurde.
- Ermöglicht die Vervollständigung 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 ihr 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 die EF Core CLI-Tools ordnungsgemäß installiert sind:
dotnet ef
Die Ausgabe des Befehls identifiziert die Version der verwendeten Tools:
_/\__
---==/ \\
___ ___ |. \|\
| __|| __| | ) \\\
| _| | _| \_/ | //|\\
|___||_| / \\\/\\
Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065
<Usage documentation follows, not shown.>
Aktualisieren der Tools
Verwenden Sie dotnet tool update --global dotnet-ef , um die globalen Tools auf die neueste verfügbare Version zu aktualisieren. Wenn Sie die Tools lokal in Ihrem Projekt installiert haben, verwenden Sie dotnet tool update dotnet-ef. Installieren Sie eine bestimmte Version, indem Sie an Ihren Befehl anfügen --version <VERSION> . Weitere Informationen finden Sie im Abschnitt Update der Dokumentation zu dotnet-Tools.
Verwenden der Tools
Bevor Sie die Tools verwenden, müssen Sie möglicherweise ein Startprojekt erstellen oder die Umgebung festlegen.
Zielprojekt und Startprojekt
Die Befehle beziehen sich auf ein Projekt und ein Startprojekt.
Das Projekt wird auch als Zielprojekt bezeichnet, da die Befehle Dateien hinzufügen oder entfernen. Standardmäßig ist das Projekt im aktuellen Verzeichnis das Zielprojekt. Sie können ein anderes Projekt als Zielprojekt angeben, indem Sie die
--projectDas Startprojekt wird von den Tools erstellt und ausgeführt. Die Tools müssen Anwendungscode zur Entwurfszeit 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 ein anderes Projekt als Startprojekt angeben, indem Sie die
--startup-project
Start- und Zielprojekt sind oft dasselbe Projekt. Ein typisches Szenario, in dem es sich um separate Projekte handelt, ist folgendes:
- Die 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 Vom EF Core-Kontext getrennten Klassenbibliothek zu platzieren.
Andere Zielframeworks
Die CLI-Tools funktionieren mit .NET Core-Projekten und .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 darin besteht, als Startprojekt für die Tools zu fungieren. Das Projekt kann ein Dummyprojekt ohne echten Code sein – es wird nur benötigt, um ein Ziel für die Tools bereitzustellen.
Warum ist ein Dummyprojekt erforderlich? Wie bereits erwähnt, müssen die Tools Anwendungscode zur Entwurfszeit ausführen. Dazu müssen sie die .NET Core-Runtime verwenden. Wenn sich das EF Core-Modell in einem Projekt befindet, das auf .NET Core oder .NET Framework ausgerichtet ist, leihen die EF Core-Tools die Laufzeit aus dem Projekt. Dies ist nicht möglich, wenn sich das EF Core-Modell in einer .NET Standard-Klassenbibliothek befindet. .NET Standard ist keine tatsächliche .NET-Implementierung. Dies ist eine Spezifikation einer Reihe von APIs, die von .NET-Implementierungen unterstützt werden müssen. Daher reicht .NET Standard nicht aus, damit die EF Core-Tools Anwendungscode ausführen können. Das Dummyprojekt, das Sie für die Verwendung 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 über die Befehlszeile angeben. Diese und alle zusätzlichen Argumente werden an Program.CreateHostBuilder übergeben.
dotnet ef database update -- --environment Production
Tipp
Das -- Token weist darauf hin dotnet ef , alles, was folgt, als Argument zu behandeln und nicht zu versuchen, sie als Optionen zu analysieren. Alle zusätzlichen Argumente, die nicht von dotnet ef verwendet werden, werden an die App weitergeleitet.
Allgemeine Optionen
| Option | Short | BESCHREIBUNG |
|---|---|---|
--json |
JSON-Ausgabe anzeigen | |
--context <DBCONTEXT> |
-c |
Die DbContext-Klasse, die verwendet werden soll. Nur Klassenname oder vollständig qualifiziert mit Namespaces. Wenn diese Option weggelassen wird, sucht 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 Zielframeworkmoniker für das Zielframework. Verwenden Sie, wenn die Projektdatei mehrere Zielframeworks angibt und Sie eines davon auswählen möchten. | |
--configuration <CONFIGURATION> |
Die Buildkonfiguration, z. B.: Debug oder 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 das Projekt nicht. Vorgesehen, um verwendet zu werden, wenn der Build auf dem neuesten Stand ist. | |
--help |
-h |
Zeigt Hilfeinformationen an |
--verbose |
-v |
Zeigt eine ausführliche Ausgabe an. |
--no-color |
Die Ausgabe nicht einfärben. | |
--prefix-output |
Präfixausgabe mit Ebene. |
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 an, welche Datenbank gelöscht, aber nicht gelöscht wird. |
Die allgemeinen Optionen sind oben aufgeführt.
dotnet ef database update
Aktualisierungen die Datenbank zur letzten Migration oder zu einer angegebenen 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 bewirkt, dass alle Migrationen wiederhergestellt werden. Wenn keine Migration angegeben ist, wird der Befehl standardmäßig auf die letzte Migration festgelegt. |
Optionen:
| Option | BESCHREIBUNG |
|---|---|
--connection <CONNECTION> |
Die Verbindungszeichenfolge für die Datenbank. Der Standardwert ist die in AddDbContext oder OnConfiguringangegebene . |
Die allgemeinen Optionen sind oben aufgeführt.
In den folgenden Beispielen wird die Datenbank auf eine angegebene Migration aktualisiert. Die erste verwendet den Migrationsnamen, der zweite verwendet die Migrations-ID und eine angegebene Verbindung:
dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string
dotnet ef dbcontext info
Ruft Informationen zu einem Typ ab DbContext .
Die allgemeinen Optionen sind oben aufgeführt.
dotnet ef dbcontext list
Listet verfügbare DbContext Typen auf.
Die allgemeinen Optionen sind oben aufgeführt.
dotnet ef dbcontext optimize
Generiert eine kompilierte Version des Modells, das DbContextvon verwendet wird.
Weitere Informationen finden Sie unter Kompilierte Modelle .
Optionen:
| Option | Short | BESCHREIBUNG |
|---|---|---|
--output-dir <PATH> |
-o |
Das Verzeichnis, in das Dateien eingefügt werden sollen. Pfade sind relativ zum Projektverzeichnis. |
--namespace <NAMESPACE> |
-n |
Der Namespace, der für alle generierten Klassen verwendet werden soll. Standardmäßig wird aus dem Stammnamespace und dem Ausgabeverzeichnis sowie generiert CompiledModels. |
Die allgemeinen Optionen sind oben aufgeführt.
Im folgenden Beispiel werden die Standardeinstellungen verwendet und funktioniert, wenn nur eine DbContext im Projekt 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. Bei ASP.NET Core 2.x-Projekten kann der Wert name=<Name der Verbindungszeichenfolge> sein. In diesem Fall stammt der Name aus den Konfigurationsquellen, die für das Projekt eingerichtet sind. |
<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, um das Modell zu konfigurieren (sofern möglich). Wenn diese Option weggelassen wird, wird nur die Fluent-API verwendet. |
--context <NAME> |
-c |
Der Name der DbContext zu generierenden Klasse. |
--context-dir <PATH> |
Das Verzeichnis, in dem die DbContext Klassendatei abgelegt werden soll. Pfade sind relativ zum Projektverzeichnis. Namespaces werden von den Ordnernamen abgeleitet. |
|
--context-namespace <NAMESPACE> |
Der Namespace, der für die generierte Klasse verwendet werden DbContext soll. Hinweis: überschreibt --namespace. |
|
--force |
-f |
Überschreibt vorhandene Dateien. |
--output-dir <PATH> |
-o |
Das Verzeichnis, in dem Entitätsklassendateien abgelegt werden sollen. Pfade sind relativ zum Projektverzeichnis. |
--namespace <NAMESPACE> |
-n |
Der Namespace, der für alle generierten Klassen verwendet werden soll. Standardmäßig wird aus dem Stammnamespace und dem Ausgabeverzeichnis generiert. |
--schema <SCHEMA_NAME>... |
Die Schemas von Tabellen und Sichten, für die Entitätstypen generiert werden sollen. Um mehrere Schemas anzugeben, wiederholen Sie --schema für jedes Schema. Wenn diese Option weggelassen wird, werden alle Schemas eingeschlossen. Wenn diese Option verwendet wird, werden alle Tabellen und Sichten in den Schemas in das Modell eingeschlossen, auch wenn sie nicht explizit mithilfe von --table eingeschlossen werden. |
|
--table <TABLE_NAME>... |
-t |
Die Tabellen und Ansichten, für die Entitätstypen generiert werden sollen. Um mehrere Tabellen anzugeben, wiederholen -t Sie oder --table für jede Tabelle. Tabellen oder Sichten in einem bestimmten Schema können im Format "schema.table" oder "schema.view" eingefügt werden. Wenn diese Option weggelassen wird, werden alle Tabellen und Sichten eingeschlossen. |
--use-database-names |
Verwenden Sie Tabellen-, Sicht-, Sequenz- und Spaltennamen genau so, wie sie in der Datenbank angezeigt werden. Wenn diese Option weggelassen wird, werden Datenbanknamen so geändert, dass sie den C#-Namensstilkonventionen besser entsprechen. | |
--no-onconfiguring |
Unterdrückt die Generierung der OnConfiguring -Methode in der generierten DbContext Klasse. |
|
--no-pluralize |
Verwenden Sie nicht den Pluralisierer. |
Die allgemeinen Optionen sind oben aufgeführt.
Im folgenden Beispiel werden alle Schemas und Tabellen gerüstet und die neuen Dateien im Ordner Models abgelegt.
dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models
Im folgenden Beispiel werden nur ausgewählte Tabellen gerüstet 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 dem Konfigurationssatz des Projekts mit dem Geheimnis-Manager-Tool gelesen.
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 das Gerüstbau einer OnConfiguring Methode übersprungen. Dies kann hilfreich sein, wenn Sie dbContext außerhalb der -Klasse konfigurieren möchten. Beispielsweise konfigurieren ASP.NET Core Apps sie 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 dbContext. Umgeht alle Migrationen.
Optionen:
| Option | Short | BESCHREIBUNG |
|---|---|---|
--output <FILE> |
-o |
Die Datei, in die das Ergebnis geschrieben werden soll. |
Die allgemeinen Optionen sind oben 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 verwendet, um die Dateien auszugeben. Pfade sind relativ zum Zielprojektverzeichnis. Der Standardwert ist "Migrationen". |
--namespace <NAMESPACE> |
-n |
Der Namespace, der für die generierten Klassen verwendet werden soll. Wird standardmäßig aus dem Ausgabeverzeichnis generiert. |
Die allgemeinen Optionen sind oben 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ündeln Sie auch die .NET-Runtime, damit sie nicht auf dem Computer installiert werden muss. | |
--target-runtime <RUNTIME_IDENTIFIER> |
-r |
Die Zielruntime, für die Bündelung ausgeführt werden soll. |
Die allgemeinen Optionen sind oben aufgeführt.
dotnet ef migrations list
Listet verfügbare Migrationen auf.
Optionen:
| Option | BESCHREIBUNG |
|---|---|
--connection <CONNECTION> |
Die Verbindungszeichenfolge für die Datenbank. Der Standardwert ist die in AddDbContext oder OnConfiguring angegebene. |
--no-connect |
Stellen Sie keine Verbindung mit der Datenbank her. |
Die allgemeinen Optionen sind oben aufgeführt.
dotnet ef migrations remove
Entfernt die letzte Migration und rollt die Codeänderungen, die für die neueste Migration vorgenommen wurden.
Optionen:
| Option | Short | BESCHREIBUNG |
|---|---|---|
--force |
-f |
Stellen Sie die neueste Migration zurück, und führen Sie ein Rollback von Code- und Datenbankänderungen durch, die für die neueste Migration vorgenommen wurden. Setzt das Rollback nur für die Codeänderungen fort, wenn beim Herstellen einer Verbindung mit der Datenbank ein Fehler auftritt. |
Die allgemeinen Optionen sind oben aufgeführt.
dotnet ef migrations script
Generiert ein SQL-Skript aus Migrationen.
Argumente:
| Argument | BESCHREIBUNG |
|---|---|
<FROM> |
Die beginnende Migration. 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 endende Migration. Standardmäßig wird die letzte Migration verwendet. |
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 allgemeinen Optionen sind oben 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