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 --project Option verwenden.

  • Das 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 Option verwenden.

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

Zusätzliche Ressourcen