Freigeben über

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

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 .NET-Projekten.

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

Warning

Dieser Artikel verwendet eine lokale Datenbank, bei der der Benutzer nicht authentifiziert werden muss. Produktions-Apps sollten die sicherste verfügbare Authentifizierungsmethode nutzen. Weitere Informationen zur Authentifizierung für bereitgestellte Test- und Produktions-Apps finden Sie unter Sichere Authentifizierungs-Flows.

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.

Startprojekt und Zielprojekt sind oft identisch. Ein typisches Szenario mit separaten Projekten ist folgendes:

  • Die EF Core-Kontext- und Entitätsklassen befinden sich in einer .NET-Klassenbibliothek.
  • Eine .NET-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-Konsolentools funktionieren mit .NET- oder .NET Framework-Projekten. Apps mit dem EF Core-Modell in einer .NET Standard-Klassenbibliothek verfügen möglicherweise nicht über ein .NET- oder .NET Framework-Projekt. Dies gilt beispielsweise für Xamarin- und Universelle Windows-Plattform-Apps. In solchen Fällen können Sie ein .NET- oder .NET Framework-Konsolen-App-Projekt erstellen, dessen einziger Zweck das Startprojekt für die Tools ist. Das Projekt kann ein Dummyprojekt ohne realen Code sein. Es wird nur zur Bereitstellung eines Ziels für Tools benötigt.

Important

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- oder .NET Framework-Laufzeit verwenden. Wenn sich das EF Core-Modell in einem Projekt befindet, das auf .NET oder .NET Framework abzielt, leihen die EF Core-Tools die Laufzeit aus dem 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 Description
-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.

Tip

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

Add-Migration

Fügt eine neue Migration hinzu.

Parameters:

Parameter Description
-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.

Parameters:

Parameter Description
-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.

Parameters:

Parameter Description
-WhatIf Zeigen Sie, welche Datenbank gelöscht werden würde, löschen Sie sie aber nicht.
-Connection <String> Die Verbindungszeichenfolge für die Datenbank. Standard ist die in AddDbContext oder OnConfiguring angegebene. In EF Core 11 hinzugefügt.

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.

Parameters:

Parameter Description
-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.

Parameters:

Parameter Description
-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.

Note

Die PMC Tools generieren aktuell keinen Code, der für die NativeAOT Kompilierung und vorkompilierte Abfragen benötigt wird.

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).

Parameters:

Parameter Description
-Force Rückgängigmachen der Migration (Rollback der auf die Datenbank angewendeten Änderungen).
-Connection <String> Die Verbindungszeichenfolge für die Datenbank. Standard ist die in AddDbContext oder OnConfiguring angegebene. In EF Core 11 hinzugefügt.
-Offline Entfernen Sie die Migration, ohne eine Verbindung mit der Datenbank herzustellen. In EF Core 11 hinzugefügt.

Die allgemeinen Parameter sind oben aufgeführt.

Note

Die -Offline- und -Force-Parameter können nicht zusammen verwendet werden, da -Force eine Datenbankverbindung erfordert, um zu überprüfen, ob die Migration angewendet wurde, bevor sie rückgängig gemacht wird.

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.

Parameters:

Parameter Description
-Connection <String> Die Verbindungszeichenfolge für die Datenbank. Der Wert kann 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.

Example:

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

Das folgende Beispiel liest die Verbindungszeichenfolge über Konfiguration.

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

Script-DbContext

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

Parameters:

Parameter Description
-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.

Parameters:

Parameter Description
-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.

Tip

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 Description
-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.

Tip

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

Weitere Ressourcen

  • Last updated on