Freigeben über

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 --project ein anderes Projekt als Zielprojekt angeben.

  • Das 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 ein anderes Projekt als Startprojekt angeben.

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.

Wichtig

Xamarin.Android, Xamarin.iOS, Xamarin.Mac sind jetzt direkt in .NET (beginnend mit .NET 6) als .NET für Android, .NET für iOS und .NET für macOS integriert. Wenn Sie noch heute mit diesen Projekttypen erstellen, sollten sie auf .NET SDK-Stilprojekte aktualisiert werden, um weiterhin Unterstützung zu erhalten. Weitere Informationen zum Upgrade von Xamarin-Projekten auf .NET finden Sie in der Dokumentation Upgrade von Xamarin auf .NET & .NET MAUI.

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, das von abfragen DbContext und vorkompiliert 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.
--suffix <SUFFIX> Das Suffix, das an den Namen aller generierten Dateien angefügt werden soll. Es kann z. B. verwendet werden, um anzugeben, dass diese Dateien generierten Code enthalten. .g
--no-scaffold Generieren Sie kein kompiliertes Modell. Dies wird verwendet, wenn das kompilierte Modell bereits generiert wurde.
--precompile-queries Generieren sie vorkompilierte Abfragen. Dies ist für die NativeAOT-Kompilierung erforderlich, wenn das Zielprojekt Abfragen enthält.
--nativeaot Generieren sie zusätzlichen Code im kompilierten Modell, das für die NativeAOT-Kompilierung und vorkompilierte Abfragen erforderlich ist.

Hinweis

NativeAOT-Unterstützung und vorkompilierte Abfragen gelten als experimentell in EF 9 und können sich in der nächsten Version erheblich ändern.

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;Integrated Security=true;" 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

Zusätzliche Ressourcen