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.

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

Allgemeine Optionen

Alle zusätzlichen Argumente werden an die Anwendung übergeben.

dotnet ef database drop

Löscht die Datenbank.

Optionen:

Die gängigsten Optionen sind unten aufgeführt.

dotnet ef database update

Aktualisiert die Datenbank auf die letzte Migration oder eine angegebene Migration.

Argumente:

Optionen:

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:

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:

Optionen:

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:

Die gängigsten Optionen sind unten aufgeführt.

dotnet ef migrations add

Fügt eine neue Migration hinzu.

Argumente:

Optionen:

Die gängigsten Optionen sind unten aufgeführt.

dotnet ef migrations bundle

Erstellt eine ausführbare Datei zum Aktualisieren der Datenbank.

Optionen:

Die gängigsten Optionen sind unten aufgeführt.

dotnet ef migrations has-pending-model-changes

Ü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:

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:

Die gängigsten Optionen sind unten aufgeführt.

dotnet ef migrations script

Generiert ein SQL-Skript aus Migrationen.

Argumente:

Optionen:

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

• Migrationen
• Reverse Engineering
• Kompilierte Modelle