Entity Framework Core-Tools-Referenz – Paket-Manager-Konsole in Visual Studio

  • Artikel

Die Paket-Manager-Konsole-Tools (PMC) für Entity Framework Core führen Entwurfszeit-Entwicklungsaufgaben aus. Sie erstellen beispielsweise Migrationen, wenden Migrationen an und generieren basierend auf einer vorhandenen Datenbank Code für ein Modell. Die Befehle werden mithilfe der Paket-Manager-Konsole in Visual Studio ausgeführt. Diese Tools funktionieren sowohl mit .NET Framework- als auch mit .NET Core-Projekten.

Wenn Sie Visual Studio nicht verwenden, empfehlen wir stattdessen die EF Core-Befehlszeilentools. Die .NET Core CLI-Tools sind plattformübergreifend und werden in einer Eingabeaufforderung ausgeführt.

Installieren der Tools

Installieren Sie die Paket-Manager-Konsolen-Tools mit folgendem Befehl in der Paket-Manager-Konsole:

Install-Package Microsoft.EntityFrameworkCore.Tools

Aktualisieren Sie die Tools mit folgendem Befehl in der Paket-Manager-Konsole:

Update-Package Microsoft.EntityFrameworkCore.Tools

Überprüfen der Installation

Stellen Sie sicher, dass die Tools installiert sind, indem Sie diesen Befehl ausführen:

Get-Help about_EntityFrameworkCore

Die Ausgabe sieht wie folgt aus (sie teilt Ihnen nicht mit, welche Version der Tools Sie verwenden):


                     _/\__
               ---==/    \\
         ___  ___   |.    \|\
        | __|| __|  |  )   \\\
        | _| | _|   \_/ |  //|\\
        |___||_|       /   \\\/\\

TOPIC
    about_EntityFrameworkCore

SHORT DESCRIPTION
    Provides information about the Entity Framework Core Package Manager Console Tools.

<A list of available commands follows, omitted here.>

Verwenden der Tools

Bevor Sie die Tools verwenden:

  • Lernen Sie den Unterschied zwischen Ziel- und Startprojekt kennen.
  • Lernen Sie, die Tools mit .NET Standard-Klassenbibliotheken zu verwenden.
  • Legen Sie die Umgebung für ASP.NET Core-Projekte fest.

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 in der Paket-Manager-Konsole ausgewählte Standardprojekt das Zielprojekt. Sie können mit dem Parameter -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 Startprojekt im Projektmappen-Explorer das Startprojekt. Sie können mit dem Parameter -StartupProject ein anderes Projekt als Startprojekt angeben.

Zielprojekt und Startprojekt 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 Paket-Manager-Konsolen-Tools funktionieren mit .NET Core- oder .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- oder .NET Framework-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- oder .NET Framework-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.

Update-Database -Args '--environment Production'

Allgemeine Parameter

Die folgende Tabelle enthält Parameter, die allen EF Core-Befehlen gemeinsam sind:

Parameter Beschreibung
-Context <String> Die DbContext-Klasse, die verwendet werden soll. Nur Klassenname oder vollqualifiziert mit Namespaces. Wenn dieser Parameter ausgelassen wird, findet EF Core die Kontextklasse. Wenn mehrere Kontextklassen vorhanden sind, ist dieser Parameter erforderlich.
-Project <String> Das Zielprojekt. Wenn dieser Parameter ausgelassen wird, wird das Standardprojekt für die Paket-Manager-Konsole als Zielprojekt verwendet.
-StartupProject <String> Das Startprojekt. Wenn dieser Parameter ausgelassen wird, wird das Startprojekt in Lösungseigenschaften als Zielprojekt verwendet.
-Args <String> An die Anwendung übergebene Argumente.
-Verbose Zeigt eine ausführliche Ausgabe an.

Verwenden Sie den Get-Help-Befehl von PowerShell, um Hilfeinformationen zu einem Befehl anzuzeigen.

Tipp

Die Parameter Context, Project und StartupProject unterstützen die Befehlsergänzung mit der Tabulatortaste.

Add-Migration

Fügt eine neue Migration hinzu.

Parameter:

Parameter Beschreibung
-Name <String> Der Name der Migration. Dies ist ein obligatorischer Positionsparameter.
-OutputDir <String> Das Verzeichnis, das zum Ausgeben der Dateien verwendet wird. Die Pfade sind relativ zum Zielprojektverzeichnis. Standardmäßig wird „Migrations“ verwendet.
-Namespace <String> Der für die generierten Klassen zu verwendende Namespace. Wird standardmäßig aus dem Ausgabeverzeichnis generiert.

Die allgemeinen Parameter sind oben aufgeführt.

Bundle-Migration

Erstellt eine ausführbare Datei zum Aktualisieren der Datenbank.

Parameter:

Parameter Beschreibung
-Output <String> Der Pfad der zu erstellenden ausführbaren Datei.
-Force Überschreibt vorhandene Dateien.
-SelfContained Bündelt auch die .NET-Laufzeit, damit sie nicht auf dem Computer installiert werden muss.
-TargetRuntime <String> Die Ziellaufzeit, für die gebündelt wird.
-Framework <String> Das Zielframework. Standardmäßig wird das erste im Projekt verwendet.

Die allgemeinen Parameter sind oben aufgeführt.

Drop-Database

Löscht die Datenbank.

Parameter:

Parameter Beschreibung
-WhatIf Zeigen Sie an, welche Datenbank gelöscht werden würde, löschen Sie sie aber nicht.

Die allgemeinen Parameter sind oben aufgeführt.

Get-DbContext

Listet über verfügbare DbContext-Typen Informationen auf und ruft sie ab.

Die allgemeinen Parameter sind oben aufgeführt.

Get-Migration

Listet verfügbare Migrationen auf.

Parameter:

Parameter Beschreibung
-Connection <String> Die Verbindungszeichenfolge für die Datenbank. Der Standard ist die in AddDbContext oder OnConfiguring angegebene.
-NoConnect Stellen Sie keine Verbindung mit der Datenbank her.

Die allgemeinen Parameter sind oben aufgeführt.

Optimize-DbContext

Generiert eine kompilierte Version des Modells, die von DbContext verwendet wird.

Weitere Informationen finden Sie unter Kompilierte Modelle.

Parameter:

Parameter Beschreibung
-OutputDir <String> Das Verzeichnis, in dem Dateien abgelegt werden sollen. Die Pfade sind relativ zum Projektverzeichnis.
-Namespace <String> Der für alle generierten Klassen zu verwendende Namespace. Wird standardmäßig aus dem Stammnamespace und dem Ausgabeverzeichnis plus CompiledModels generiert.

Die allgemeinen Parameter sind oben aufgeführt.

Im folgenden Beispiel werden die Standardwerte verwendet, und dies funktioniert, wenn im Projekt nur ein DbContext vorhanden ist:

Optimize-DbContext

Im folgenden Beispiel wird das Modell für den Kontext mit dem angegebenen Namen optimiert und in einem separaten Ordner und Namespace platziert:

Optimize-DbContext -OutputDir Models -Namespace BlogModels -Context BlogContext

Remove-Migration

Entfernt die letzte Migration (Rollback der für die Migration vorgenommenen Codeänderungen).

Parameter:

Parameter Beschreibung
-Force Rückgängigmachen der Migration (Rollback der auf die Datenbank angewendeten Änderungen).

Die allgemeinen Parameter sind oben aufgeführt.

Scaffold-DbContext

Generiert Code für einen DbContext und Entitätstypen für eine Datenbank. Damit Scaffold-DbContext einen Entitätstyp generieren kann, muss die Datenbanktabelle über einen Primärschlüssel verfügen.

Parameter:

Parameter Beschreibung
-Connection <String> 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. Dies ist ein obligatorischer Positionsparameter.
-Provider <String> Der zu verwendende Anbieter. In der Regel ist dies der Name des NuGet-Pakets, z. B.: Microsoft.EntityFrameworkCore.SqlServer. Dies ist ein obligatorischer Positionsparameter.
-OutputDir <String> Das Verzeichnis, in das Entitätsklassendateien eingefügt werden sollen. Die Pfade sind relativ zum Projektverzeichnis.
-ContextDir <String> Das Verzeichnis, in dem die DbContext-Datei abgelegt werden soll. Die Pfade sind relativ zum Projektverzeichnis.
-Namespace <String> Der für alle generierten Klassen zu verwendende Namespace. Wird standardmäßig aus dem Stammnamespace und dem Ausgabeverzeichnis generiert.
-ContextNamespace <String> Der Name des für die generierte DbContext-Klasse verwendeten Namespace. Hinweis: Überschreibt -Namespace.
-Context <String> Der Name der zu generierenden DbContext-Klasse.
-Schemas <String[]> Die Schemas von Tabellen und Ansichten, für die Entitätstypen generiert werden sollen. Wenn dieser Parameter 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.
-Tables <String[]> Die Tabellen und Ansichten, für die Entitätstypen generiert werden sollen. Tabellen oder Sichten in einem bestimmten Schema können im Format „schema.table“ bzw. „schema.view“ eingefügt werden. Wenn dieser Parameter ausgelassen wird, werden alle Tabellen und Sichten einbezogen.
-DataAnnotations Verwenden Sie Attribute zum Konfigurieren des Modells (sofern möglich). Wenn dieser Parameter ausgelassen wird, wird nur die Fluent-API verwendet.
-UseDatabaseNames Verwenden Sie Tabellen-, Ansichts-, Sequenz- und Spaltennamen genau so, wie sie in der Datenbank vorkommen. Wenn dieser Parameter ausgelassen wird, werden Datenbanknamen so geändert, dass sie eher den C#-Namensstilkonventionen entsprechen.
-Force Überschreibt vorhandene Dateien.
-NoOnConfiguring Generieren Sie nicht DbContext.OnConfiguring.
-NoPluralize Verwenden Sie den Pluralizer nicht.

Die allgemeinen Parameter sind oben aufgeführt.

Beispiel:

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models

Beispiel, in dem Gerüstbau nur für ausgewählte Tabellen durchgeführt und der Kontext in einem separaten Ordner mit einem angegebenen Namen und Namespace erstellt wird:

Scaffold-DbContext "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -OutputDir Models -Tables "Blog","Post" -ContextDir Context -Context BlogContext -ContextNamespace New.Namespace

Im folgenden Beispiel wird die Verbindungszeichenfolge aus der Konfiguration des Projekts gelesen, die möglicherweise mit dem Secret Manager-Tool festgelegt wurde.

Scaffold-DbContext "Name=ConnectionStrings:Blogging" Microsoft.EntityFrameworkCore.SqlServer

Script-DbContext

Generiert ein SQL-Skript aus dem DbContext. Umgeht alle Migrationen.

Parameter:

Parameter Beschreibung
-Output <String> Die Datei, in die das Ergebnis geschrieben werden soll.

Die allgemeinen Parameter sind oben aufgeführt.

Script-Migration

Generiert ein SQL-Skript, das alle Änderungen von einer ausgewählten Migration auf eine andere ausgewählte Migration anwendet.

Parameter:

Parameter Beschreibung
-From <String> 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 <String> Die Endmigration. Standard ist die letzte Migration.
-Idempotent Generieren Sie ein Skript, das bei jeder Migration für eine Datenbank verwendet werden kann.
-NoTransactions Generieren Sie keine SQL-Transaktionsanweisungen.
-Output <String> Die Datei, in die das Ergebnis geschrieben werden soll. WENN dieser Parameter ausgelassen wird, wird die Datei mit einem generierten Namen im selben Ordner wie die Laufzeitdateien der App erstellt, z. B.: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Die allgemeinen Parameter sind oben aufgeführt.

Tipp

Die Parameter To, From und Output unterstützen die Befehlsergänzung mit der Tabulatortaste.

Im folgenden Beispiel wird mithilfe des Migrationsnamens ein Skript für die InitialCreate-Migration (aus einer Datenbank ohne Migrationen) erstellt.

Script-Migration 0 InitialCreate

Im folgenden Beispiel wird mit der Migrations-ID ein Skript für alle Migrationen nach der InitialCreate-Migration erstellt.

Script-Migration 20180904195021_InitialCreate

Update-Database

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

Parameter Beschreibung
-Migration <String> 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.
-Connection <String> Die Verbindungszeichenfolge für die Datenbank. Standard ist die in AddDbContext oder OnConfiguring angegebene.

Die allgemeinen Parameter sind oben aufgeführt.

Tipp

Der Migration-Parameter unterstützt die Befehlsergänzung mit der Tabulatortaste.

Im folgenden Beispiel werden alle Migrationen rückgängig gemacht.

Update-Database 0

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:

Update-Database InitialCreate
Update-Database 20180904195021_InitialCreate -Connection your_connection_string

Zusätzliche Ressourcen