Entity Framework Core narzędzi — interfejs wiersza polecenia platformy .NET Core

Narzędzia interfejsu wiersza polecenia (CLI) do Entity Framework Core zadań deweloperskie w czasie projektowania. Na przykład tworzą migracje,stosują migracje i generują kod dla modelu na podstawie istniejącej bazy danych. Polecenia są rozszerzeniem międzyplatformowego polecenia dotnet, które jest częścią zestaw .NET Core SDK. Te narzędzia działają z projektami .NET Core.

W przypadku Visual Studio należy rozważyć użycie narzędzi Menedżer pakietów Console zamiast narzędzi interfejsu wiersza polecenia. Menedżer pakietów narzędzia konsoli:

  • Działa z bieżącym projektem wybranym w konsoli Menedżer pakietów bez konieczności ręcznego przełączania katalogów.
  • Otwiera pliki wygenerowane przez polecenie po zakończeniu polecenia.
  • Zapewnia uzupełnianie po karcie poleceń, parametrów, nazw projektów, typów kontekstu i nazw migracji.

Instalowanie narzędzi

dotnet ef Program można zainstalować jako narzędzie globalne lub lokalne. Większość deweloperów preferuje dotnet ef instalowanie jako narzędzie globalne przy użyciu następującego polecenia:

dotnet tool install --global dotnet-ef

Aby użyć go jako narzędzia lokalnego, przywróć zależności projektu, który deklaruje go jako zależność narzędzi przy użyciu pliku manifestu narzędzia.

Zaktualizuj narzędzie przy użyciu następującego polecenia:

dotnet tool update --global dotnet-ef

Przed użyciem narzędzi w konkretnym projekcie należy dodać do niego Microsoft.EntityFrameworkCore.Design pakiet.

dotnet add package Microsoft.EntityFrameworkCore.Design

Weryfikowanie instalacji

Uruchom następujące polecenia, aby sprawdzić, czy EF Core interfejsu wiersza polecenia są poprawnie zainstalowane:

dotnet ef

Dane wyjściowe polecenia identyfikują wersję narzędzi w użyciu:


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

Entity Framework Core .NET Command-line Tools 2.1.3-rtm-32065

<Usage documentation follows, not shown.>

Aktualizacja narzędzi

Użyj dotnet tool update --global dotnet-ef narzędzia , aby zaktualizować narzędzia globalne do najnowszej dostępnej wersji. Jeśli masz narzędzia zainstalowane lokalnie w projekcie, użyj narzędzia dotnet tool update dotnet-ef . Zainstaluj określoną wersję, dołączając --version <VERSION> polecenie do polecenia . Aby uzyskać więcej informacji, zobacz sekcję Aktualizacja dokumentacji narzędzia dotnet.

Korzystanie z narzędzi

Przed użyciem narzędzi może być konieczne utworzenie projektu startowego lub ustawienie środowiska.

Projekt docelowy i projekt startowy

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

  • Projekt jest również nazywany projektem docelowym, ponieważ to w nim polecenia dodają lub usuwają pliki. Domyślnie projekt w bieżącym katalogu jest projektem docelowym. Możesz określić inny projekt jako projekt docelowy przy użyciu --project opcji .

  • Projekt startowy jest tym, który narzędzia skompilowały i uruchomiły. 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 projekt w bieżącym katalogu jest projektem startowym. Możesz określić inny projekt jako projekt startowy przy użyciu --startup-project opcji .

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

  • 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 interfejsu wiersza polecenia działają z projektami .NET Core i .NET Framework projektami. Aplikacje, które mają EF Core w bibliotece klas .NET Standard, mogą nie mieć projektu .NET Core .NET Framework projektu. Dotyczy to na przykład aplikacji platformy Xamarin i universal Windows Platform. W takich przypadkach można utworzyć projekt aplikacji konsolowej .NET Core, którego jedynym celem jest działanie jako projekt startowy dla narzędzi. Projekt może być fikcyjnym projektem bez rzeczywistego kodu — wystarczy podać element docelowy dla narzędzi.

Dlaczego wymagany jest 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. 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. Dlatego .NET Standard jest niewystarczająca dla narzędzi EF Core do wykonywania kodu aplikacji. Fikcyjny projekt, który zostanie przez Ciebie .NET Standard jako projekt startowy, udostępnia konkretną platformę docelową, na której narzędzia mogą .NET Standard biblioteki klas.

ASP.NET Core środowiska

Aby określić środowisko dla ASP.NET Core, ustaw zmienną ASPNETCORE_ENVIRONMENT środowiskową 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:

dotnet ef database update -- --environment Production

Porada

Token kieruje do traktowania wszystkiego, co następuje jako argument i nie próbuje ich --dotnet ef ująć jako opcje. Wszelkie dodatkowe argumenty, które nie dotnet ef są używane przez program, są przekazywane do aplikacji.

Typowe opcje

Opcja Krótki Opis
--json Pokaż dane wyjściowe JSON.
--context <DBCONTEXT> -c Klasa DbContext do użycia. Tylko nazwa klasy lub w pełni kwalifikowana z przestrzeniami nazw. Jeśli ta opcja zostanie pominięta, EF Core znajdzie klasę kontekstu. Jeśli istnieje wiele klas kontekstu, ta opcja jest wymagana.
--project <PROJECT> -p Ścieżka względna do folderu projektu projektu docelowego. Wartość domyślna to bieżący folder.
--startup-project <PROJECT> -s Ścieżka względna do folderu projektu projektu startowego. Wartość domyślna to bieżący folder.
--framework <FRAMEWORK> Moniker struktury docelowej dla docelowej struktury. Użyj , gdy plik projektu określa wiele platform docelowych i chcesz wybrać jedną z nich.
--configuration <CONFIGURATION> Konfiguracja kompilacji, na przykład: Debug lub Release .
--runtime <IDENTIFIER> Identyfikator docelowego środowiska uruchomieniowego, dla których mają zostać przywrócone pakiety. Aby uzyskać listę identyfikatorów środowiska uruchomieniowego (RID), zobacz katalog RID.
--no-build Nie twórz projektu. Przeznaczony do korzystania z aplikacji, gdy kompilacja jest aktualny.
--help -h Pokaż informacje pomocy.
--verbose -v Pokaż pełne dane wyjściowe.
--no-color Nie koloruj danych wyjściowych.
--prefix-output Dane wyjściowe prefiksu na poziomie.

Począwszy od EF Core 5.0, wszelkie dodatkowe argumenty są przekazywane do aplikacji.

dotnet ef database drop

Usuwa bazę danych.

Opcje:

Opcja Krótki Opis
--force -f Nie potwierdzaj.
--dry-run Pokaż, która baza danych zostanie porzucona, ale nie porzucaj jej.

Poniżej wymieniono typowe opcje.

dotnet ef database update

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

Argumenty:

Argument Opis
<MIGRATION> Migracja docelowa. Migracje mogą być identyfikowane za pomocą nazwy lub identyfikatora. Liczba 0 to specjalny przypadek, który oznacza przed pierwszą migracją i powoduje przywrócenie wszystkich migracji. Jeśli migracja nie zostanie określona, polecenie domyślnie będzie ostatniej migracji.

Opcje:

Opcja Opis
--connection <CONNECTION> Parametrów połączenia z bazą danych. Wartość domyślna to określona w AddDbContext pliku lub OnConfiguring . Dodano w EF Core 5.0.

Poniżej wymieniono typowe opcje.

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

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate --connection your_connection_string

dotnet ef dbcontext info

Pobiera informacje o DbContext typie.

Poniżej wymieniono typowe opcje.

dotnet ef dbcontext list

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

Poniżej wymieniono typowe opcje.

dotnet ef dbcontext optimize

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

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

Opcje:

Opcja Krótki Opis
--output-dir <PATH> -o Katalog, w którym mają być umieszczane pliki. Ścieżki są względne względem katalogu projektu.
--namespace <NAMESPACE> -n 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 .

Poniżej wymieniono typowe opcje.

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

dotnet ef dbcontext optimize

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

dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext

dotnet ef dbcontext scaffold

Generuje kod dla typów DbContext jednostek i dla bazy danych. Aby to polecenie wygenerowało typ jednostki, tabela bazy danych musi mieć klucz podstawowy.

Argumenty:

Argument Opis
<CONNECTION> 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.
<PROVIDER> Dostawca do użycia. Zazwyczaj jest to nazwa pakietu NuGet, na przykład: Microsoft.EntityFrameworkCore.SqlServer .

Opcje:

Opcja Krótki Opis
--data-annotations -d Użyj atrybutów, aby skonfigurować model (jeśli to możliwe). Jeśli ta opcja zostanie pominięta, używany jest tylko interfejs API Fluent.
--context <NAME> -c Nazwa klasy DbContext do wygenerowania.
--context-dir <PATH> Katalog, w którym ma być DbContext umieszczany plik klasy. Ścieżki są względne względem katalogu projektu. Przestrzenie nazw pochodzą z nazw folderów.
--context-namespace <NAMESPACE> Przestrzeń nazw do użycia dla wygenerowanej DbContext klasy. Uwaga: zastępuje --namespace . Dodano w EF Core 5.0.
--force -f Zastąp istniejące pliki.
--output-dir <PATH> -o Katalog, w którym mają być umieszczane pliki klas jednostek. Ścieżki są względne względem katalogu projektu.
--namespace <NAMESPACE> -n 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.
--schema <SCHEMA_NAME>... Schematy tabel do generowania typów jednostek. Aby określić wiele schematów, powtórz --schema dla każdego z nich. Jeśli ta opcja zostanie pominięta, zostaną uwzględnione wszystkie schematy.
--table <TABLE_NAME>... -t Tabele do generowania typów jednostek. Aby określić wiele tabel, powtórz lub -t--table dla każdej z nich. Jeśli ta opcja zostanie pominięta, zostaną uwzględnione wszystkie tabele.
--use-database-names Używaj nazw tabel i kolumn dokładnie tak, jak są wyświetlane w bazie danych. Jeśli ta opcja zostanie pominięta, nazwy baz danych zostaną zmienione tak, aby bardziej odpowiadały konwencjom stylu nazw języka C#.
--no-onconfiguring Pomija generowanie metody OnConfiguring w wygenerowanej DbContext klasie. Dodano w EF Core 5.0.
--no-pluralize Nie używaj pluralizatora. Dodano w EF Core 5.0

Poniżej wymieniono typowe opcje.

W poniższym przykładzie szkielet wszystkich schematów i tabel oraz umieszcza nowe pliki w folderze Models.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Trusted_Connection=True;" Microsoft.EntityFrameworkCore.SqlServer -o Models

Poniższy przykład tworzy szkielet tylko wybranych tabel i tworzy kontekst w oddzielnym folderze o określonej nazwie i przestrzeni nazw:

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

Poniższy przykład odczytuje ciąg połączenia z zestawu konfiguracji projektu przy użyciu narzędzia Secret Manager.

dotnet user-secrets set ConnectionStrings:Blogging "Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=Blogging"
dotnet ef dbcontext scaffold Name=ConnectionStrings:Blogging Microsoft.EntityFrameworkCore.SqlServer

Poniższy przykład pomija szkielet OnConfiguring metody. Może to być przydatne, gdy chcesz skonfigurować DbContext poza klasą. Na przykład ASP.NET Core zwykle konfigurują je w chmurze Startup.ConfigureServices. Dodano w EF Core 5.0.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

Generuje skrypt SQL z DbContext. Pomija wszelkie migracje.

Opcje:

Opcja Krótki Opis
--output <FILE> -o Plik, w który ma być zapisywany wynik.

Poniżej wymieniono typowe opcje.

dotnet ef migrations add

Dodaje nową migrację.

Argumenty:

Argument Opis
<NAME> Nazwa migracji.

Opcje:

Opcja Krótki Opis
--output-dir <PATH> -o Katalog używa pliku wyjściowego . Ścieżki są względne względem katalogu projektu docelowego. Wartość domyślna to "Migracje".
--namespace <NAMESPACE> -n Przestrzeń nazw do użycia dla wygenerowanych klas. Wartość domyślna to wygenerowana z katalogu wyjściowego. Dodano w EF Core 5.0.

Poniżej wymieniono typowe opcje.

dotnet ef migrations bundle

Tworzy plik wykonywalny w celu zaktualizowania bazy danych.

Opcje:

Opcja Krótki Opis
--output <FILE> -o Ścieżka pliku wykonywalnego do utworzenia.
--force -f Zastąp istniejące pliki.
--self-contained Należy również poinstalować pakiet środowiska uruchomieniowego .NET, aby nie trzeba było go instalować na maszynie.
--target-runtime <RUNTIME_IDENTIFIER> -r Docelowe środowisko uruchomieniowe, dla których ma być powiązane pakiet.

Poniżej wymieniono typowe opcje.

dotnet ef migrations list

Wyświetla listę dostępnych migracji.

Opcje:

Opcja Opis
--connection <CONNECTION> Parametrów połączenia z bazą danych. Wartość domyślna to określona w AddDbContext lub OnConfiguring. Dodano w EF Core 5.0.
--no-connect Nie łącz się z bazą danych. Dodano w EF Core 5.0.

Poniżej wymieniono typowe opcje.

dotnet ef migrations remove

Usuwa ostatnią migrację, cofania zmian kodu, które zostały wykonane dla najnowszej migracji.

Opcje:

Opcja Krótki Opis
--force -f Cofniesz najnowszą migrację, cofniesz zarówno zmiany kodu, jak i bazy danych, które zostały wykonane dla najnowszej migracji. Kontynuuje wycofywanie zmian kodu tylko w przypadku wystąpienia błędu podczas nawiązywania połączenia z bazą danych.

Poniżej wymieniono typowe opcje.

dotnet ef migrations script

Generuje skrypt SQL z migracji.

Argumenty:

Argument Opis
<FROM> 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> Końcowa migracja. Wartość domyślna to ostatnia migracja.

Opcje:

Opcja Krótki Opis
--output <FILE> -o Plik do zapisu skryptu.
--idempotent -i Wygeneruj skrypt, który może być używany w bazie danych podczas dowolnej migracji.
--no-transactions Nie wygeneruj SQL transakcji. Dodano w EF Core 5.0.

Poniżej wymieniono typowe opcje.

Poniższy przykład tworzy skrypt dla migracji InitialCreate:

dotnet ef migrations script 0 InitialCreate

Poniższy przykład tworzy skrypt dla wszystkich migracji po zakończeniu migracji InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Dodatkowe zasoby