Entity Framework Core narzędzi — Menedżer pakietów Console w programie Visual Studio

Narzędzia Menedżer pakietów Console (PMC) Entity Framework Core do wykonywania zadań programistyki w czasie projektowania. Na przykład tworzą migracje, stosują migracje i generują kod dla modelu na podstawie istniejącej bazy danych. Polecenia są uruchamiane wewnątrz Visual Studio przy użyciu konsoli Menedżer pakietów. Te narzędzia działają zarówno z projektami .NET Framework, jak i .NET Core.

Jeśli nie korzystasz z Visual Studio, zalecamy użycie EF Core wiersza polecenia. Narzędzia interfejs wiersza polecenia platformy .NET Core są międzyplatformowe i uruchamiane w wierszu polecenia.

Instalowanie narzędzi

Zainstaluj narzędzia Menedżer pakietów Console, uruchamiając następujące polecenie w Menedżer pakietów Console:

Install-Package Microsoft.EntityFrameworkCore.Tools

Zaktualizuj narzędzia, uruchamiając następujące polecenie w Menedżer pakietów Console.

Update-Package Microsoft.EntityFrameworkCore.Tools

Weryfikowanie instalacji

Sprawdź, czy narzędzia zostały zainstalowane, uruchamiając to polecenie:

Get-Help about_EntityFrameworkCore

Dane wyjściowe wyglądają następująco (nie informują o tym, której wersji narzędzi używasz):


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

TOPIC
    about_EntityFrameworkCore

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

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

Korzystanie z narzędzi

Przed rozpoczęciem korzystania z narzędzi:

  • Poznaj różnicę między projektem docelowym i startowym.
  • Dowiedz się, jak używać narzędzi z .NET Standard bibliotek klas.
  • W ASP.NET Core projektu ustaw środowisko.

Projekt docelowy i projekt startowy

Polecenia odwołują się do projektu iprojektu startowego.

  • Projekt jest również nazywany projektem docelowym , ponieważ to w nim polecenia dodają lub usuwają pliki. Domyślnie projekt Domyślny wybrany w konsoli Menedżer pakietów jest projektem docelowym. Możesz określić inny projekt jako projekt docelowy przy użyciu parametru -Project .

  • Projekt startowy to projekt, który są kompilowane i uruchamiane przez narzędzia. Narzędzia muszą wykonywać kod aplikacji w czasie projektowania, aby uzyskać informacje o projekcie, takie jak ciąg połączenia bazy danych i konfiguracja modelu. Domyślnie wartością Projectw Eksplorator rozwiązań jest projekt startowy. Inny projekt można określić jako projekt startowy przy użyciu parametru -StartupProject .

Projekt startowy i projekt docelowy są często tym samym projektem. Typowy scenariusz, w którym są to oddzielne projekty, ma miejsce wtedy, gdy:

  • Klasa EF Core i klasy jednostek znajdują się w bibliotece klas .NET Core.
  • Aplikacja konsolowa lub aplikacja internetowa .NET Core odwołuje się do biblioteki klas.

Kod migracji można również umieścić w bibliotece klas oddzielonej od EF Core klas.

Inne struktury docelowe

Narzędzia Menedżer pakietów działają z programem .NET Core lub .NET Framework projektami. Aplikacje, które mają EF Core modelu w bibliotece klas .NET Standard, mogą nie mieć projektu .NET Core .NET Framework projektu. Dotyczy to na przykład platformy Xamarin i platforma uniwersalna systemu Windows aplikacji. W takich przypadkach można utworzyć projekt aplikacji konsolowej .NET Core lub .NET Framework, którego jedynym celem jest działanie jako projekt startowy dla narzędzi. Projekt może być fikcyjnym projektem bez rzeczywistego kodu — jest potrzebny tylko do zapewnienia obiektu docelowego dla narzędzi.

Dlaczego jest wymagany fikcyjny projekt? Jak wspomniano wcześniej, narzędzia muszą wykonywać kod aplikacji w czasie projektowania. Aby to zrobić, muszą używać środowiska uruchomieniowego .NET Core lub .NET Framework uruchomieniowego. Gdy model EF Core znajduje się w projekcie przeznaczonym dla programu .NET Core lub .NET Framework, narzędzia EF Core wypożyczają środowisko uruchomieniowe z projektu. Nie mogą tego zrobić, jeśli EF Core znajduje się w .NET Standard klas. Ten .NET Standard nie jest rzeczywistą implementacją .NET; Jest to specyfikacja zestawu interfejsów API, które muszą obsługiwać implementacje .NET. W .NET Standard nie jest wystarczająca dla EF Core do wykonywania kodu aplikacji. Fikcyjny projekt, który utworzysz do użycia jako projekt startowy, zapewnia konkretną platformę docelową, do której narzędzia mogą załadować bibliotekę .NET Standard klas.

ASP.NET Core środowiska

Aby określić środowisko dla ASP.NET Core, ustaw env:ASPNETCORE_ENVIRONMENT przed uruchomieniem poleceń.

Począwszy od EF Core 5.0, dodatkowe argumenty mogą być również przekazywane do Program.CreateHostBuilder, co umożliwia określenie środowiska w wierszu polecenia:

Update-Database -Args '--environment Production'

Typowe parametry

W poniższej tabeli przedstawiono parametry, które są wspólne dla wszystkich EF Core polecenia:

Parametr Opis
-Context <String> Klasa DbContext do użycia. Tylko nazwa klasy lub w pełni kwalifikowana z przestrzeniami nazw. Jeśli ten parametr zostanie pominięty, EF Core znajdzie klasę kontekstu. Jeśli istnieje wiele klas kontekstu, ten parametr jest wymagany.
-Project <String> Projekt docelowy. Jeśli ten parametr zostanie pominięty, domyślny projekt Menedżer pakietów Console jest używany jako projekt docelowy.
-StartupProject <String> Projekt startowy. Jeśli ten parametr zostanie pominięty, projekt startowy we właściwościach rozwiązania będzie używany jako projekt docelowy.
-Args <String> Argumenty przekazane do aplikacji. Dodano w EF Core 5.0.
-Verbose Pokaż pełne dane wyjściowe.

Aby wyświetlić informacje pomocy dotyczące polecenia, użyj polecenia programu Get-Help PowerShell.

Porada

Parametry Context, Projecti obsługują StartupProject rozszerzanie karty.

Add-Migration

Dodaje nową migrację.

Parametry:

Parametr Opis
-Name <String> Nazwa migracji. Jest to parametr pozytowy, który jest wymagany.
-OutputDir <String> Katalog używa pliku wyjściowego . Ścieżki są względne względem katalogu projektu docelowego. Wartość domyślna to "Migracje".
-Namespace <String> Przestrzeń nazw do użycia dla wygenerowanych klas. Wartość domyślna to wygenerowana z katalogu wyjściowego. Dodano w EF Core 5.0.

Typowe parametry są wymienione powyżej.

Bundle-Migration

Tworzy plik wykonywalny w celu zaktualizowania bazy danych.

Parametry:

Parametr Opis
-Output <String> Ścieżka pliku wykonywalnego do utworzenia.
-Force Zastąp istniejące pliki.
-SelfContained Należy również poinstalować pakiet środowiska uruchomieniowego .NET, aby nie trzeba było go instalować na maszynie.
-TargetRuntime <String> Docelowe środowisko uruchomieniowe, dla których ma być powiązane pakiet.
-Framework <String> Docelowa framework. Wartość domyślna to pierwsza w projekcie.

Typowe parametry są wymienione powyżej.

Drop-Database

Porzuca bazę danych.

Parametry:

Parametr Opis
-WhatIf Pokaż, która baza danych zostanie porzucona, ale nie upuść jej.

Typowe parametry są wymienione powyżej.

Get-DbContext

Wyświetla listę dostępnych typów i pobiera DbContext je.

Typowe parametry są wymienione powyżej.

Get-Migration

Wyświetla listę dostępnych migracji. Dodano w EF Core 5.0.

Parametry:

Parametr Opis
-Connection <String> Parametrów połączenia z bazą danych. Wartość domyślna to określona w AddDbContext lub OnConfiguring.
-NoConnect Nie łącz się z bazą danych.

Typowe parametry są wymienione powyżej.

Optimize-DbContext

Generuje skompilowaną wersję modelu używaną przez .DbContext Dodano w EF Core 6.

Aby uzyskać więcej informacji, zobacz Compiled models (Skompilowane modele).

Parametry:

Parametr Opis
-OutputDir <String> Katalog, w którym mają być umieszczane pliki. Ścieżki są względne względem katalogu projektu.
-Namespace <String> Przestrzeń nazw do użycia dla wszystkich wygenerowanych klas. Wartość domyślna to wygenerowana z głównej przestrzeni nazw i katalogu wyjściowego plus CompiledModels.

Typowe parametry są wymienione powyżej.

W poniższym przykładzie użyto wartości domyślnych i działa, jeśli w DbContext projekcie istnieje tylko jedna:

Optimize-DbContext

Poniższy przykład optymalizuje model pod kątem kontekstu o określonej nazwie i umieszcza go w oddzielnym folderze i przestrzeni nazw:

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

Remove-Migration

Usuwa ostatnią migrację (wycofuje zmiany kodu, które zostały wykonane dla migracji).

Parametry:

Parametr Opis
-Force Przywróć migrację (wycofaj zmiany, które zostały zastosowane do bazy danych).

Typowe parametry są wymienione powyżej.

Scaffold-DbContext

Generuje kod dla typów jednostek DbContext i dla bazy danych. Aby program wygenerował Scaffold-DbContext typ jednostki, tabela bazy danych musi mieć klucz podstawowy.

Parametry:

Parametr Opis
-Connection <String> Parametrów połączenia z bazą danych. W ASP.NET Core 2.x wartością może być nazwa=<nazwa parametrów połączenia>. W takim przypadku nazwa pochodzi ze źródeł konfiguracji, które są konfiguracyjne dla projektu. Jest to parametr pozytowy, który jest wymagany.
-Provider <String> Dostawca do użycia. Zazwyczaj jest to nazwa pakietu NuGet, na przykład: Microsoft.EntityFrameworkCore.SqlServer. Jest to parametr pozytowy, który jest wymagany.
-OutputDir <String> Katalog, w którym mają być umieszczane pliki klas jednostek. Ścieżki są względne względem katalogu projektu.
-ContextDir <String> Katalog, w którym ma być DbContext umieszczany plik. Ścieżki są względne względem katalogu projektu.
-Namespace <String> Przestrzeń nazw do użycia dla wszystkich wygenerowanych klas. Wartość domyślna to wygenerowana z głównej przestrzeni nazw i katalogu wyjściowego. Dodano w EF Core 5.0.
-ContextNamespace <String> Przestrzeń nazw do użycia dla wygenerowanej DbContext klasy. Uwaga: zastępuje .-Namespace Dodano w EF Core 5.0.
-Context <String> Nazwa klasy do DbContext wygenerowania.
-Schemas <String[]> Schematy tabel do generowania typów jednostek. Jeśli ten parametr zostanie pominięty, zostaną uwzględnione wszystkie schematy.
-Tables <String[]> Tabele do generowania typów jednostek. Jeśli ten parametr zostanie pominięty, zostaną uwzględnione wszystkie tabele.
-DataAnnotations Użyj atrybutów, aby skonfigurować model (jeśli to możliwe). Jeśli ten parametr zostanie pominięty, używany jest tylko interfejs API Fluent.
-UseDatabaseNames Używaj nazw tabel i kolumn dokładnie tak, jak są wyświetlane w bazie danych. Jeśli ten parametr zostanie pominięty, nazwy baz danych zostaną zmienione, aby bardziej odpowiadały konwencjom stylu nazw języka C#.
-Force Zastąp istniejące pliki.
-NoOnConfiguring Nie wygeneruj .DbContext.OnConfiguring Dodano w EF Core 5.0.
-NoPluralize Nie używaj pluralizatora. Dodano w EF Core 5.0.

Typowe parametry są wymienione powyżej.

Przykład:

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

Przykład tworzenia szkieletu tylko wybranych tabel i tworzenia kontekstu w oddzielnym folderze o określonej nazwie i przestrzeni nazw:

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

Poniższy przykład odczytuje ciąg połączenia z konfiguracji projektu, która prawdopodobnie zostanie ustawiona przy użyciu narzędzia Secret Manager.

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

Script-DbContext

Generuje skrypt SQL z DbContext. Pomija wszelkie migracje.

Parametry:

Parametr Opis
-Output <String> Plik, w który ma być zapisywany wynik.

Typowe parametry są wymienione powyżej.

Script-Migration

Generuje skrypt SQL, który stosuje wszystkie zmiany z jednej wybranej migracji do innej wybranej migracji.

Parametry:

Parametr Opis
-From <String> Migracja początkowa. Migracje mogą być identyfikowane za pomocą nazwy lub identyfikatora. Liczba 0 to specjalny przypadek, który oznacza przed pierwszą migracją. Wartość domyślna to 0.
-To <String> Końcowa migracja. Wartość domyślna to ostatnia migracja.
-Idempotent Wygeneruj skrypt, który może być używany w bazie danych podczas dowolnej migracji.
-NoTransactions Nie wygeneruj SQL transakcji. Dodano w EF Core 5.0.
-Output <String> Plik, w który ma być zapisywany wynik. Jeśli ten parametr zostanie pominięty, plik zostanie utworzony z wygenerowaną nazwą w tym samym folderze, w którym są tworzone pliki środowiska uruchomieniowego aplikacji, na przykład: /obj/Debug/netcoreapp2.1/ghbkztfz.sql/.

Typowe parametry są wymienione powyżej.

Porada

Parametry To, Fromi obsługują Output rozszerzanie karty.

Poniższy przykład tworzy skrypt dla migracji InitialCreate (z bazy danych bez żadnych migracji) przy użyciu nazwy migracji.

Script-Migration 0 InitialCreate

Poniższy przykład tworzy skrypt dla wszystkich migracji po migracji InitialCreate przy użyciu identyfikatora migracji.

Script-Migration 20180904195021_InitialCreate

Update-Database

Aktualizuje bazę danych do ostatniej migracji lub do określonej migracji.

Parametr Opis
-Migration <String> Migracja docelowa. Migracje mogą być identyfikowane za pomocą nazwy lub identyfikatora. Liczba 0 jest specjalnym przypadekem, który oznacza przed pierwszą migracją i powoduje przywrócenie wszystkich migracji. Jeśli migracja nie jest określona, polecenie domyślnie do ostatniej migracji.
-Connection <String> Parametrów połączenia z bazą danych. Wartość domyślna to określona w pliku AddDbContext lub OnConfiguring. Dodano w EF Core 5.0.

Typowe parametry są wymienione powyżej.

Porada

Parametr Migration obsługuje rozszerzanie karty.

Poniższy przykład przywraca wszystkie migracje.

Update-Database 0

Poniższe przykłady aktualizują bazę danych do określonej migracji. Pierwszy używa nazwy migracji, a drugi używa identyfikatora migracji i określonego połączenia:

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

Dodatkowe zasoby