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

Narzędzia interfejsu wiersza polecenia dla platformy Entity Framework Core wykonują zadania programistyczne 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ą zestawu .NET Core SDK. Te narzędzia współpracują z projektami platformy .NET Core.

W przypadku korzystania z Visual Studio rozważ użycie narzędzi konsoli Menedżer pakietów zamiast narzędzi interfejsu wiersza polecenia. narzędzia konsoli Menedżer pakietów automatycznie:

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

Instalowanie narzędzi

dotnet ef można zainstalować jako narzędzie globalne lub lokalne. Większość deweloperów preferuje instalowanie dotnet ef 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ędziową 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 określonym projekcie należy dodać Microsoft.EntityFrameworkCore.Design do niego pakiet.

dotnet add package Microsoft.EntityFrameworkCore.Design

Weryfikowanie instalacji

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

dotnet ef

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


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

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

<Usage documentation follows, not shown.>

Aktualizacja narzędzi

Służy dotnet tool update --global dotnet-ef do aktualizowania narzędzi globalnych do najnowszej dostępnej wersji. Jeśli masz narzędzia zainstalowane lokalnie w projekcie, użyj polecenia dotnet tool update dotnet-ef. Zainstaluj określoną wersję, dołączając --version <VERSION> ją 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.

Docelowy projekt i projekt startowy

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

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

  • Projekt startowy to ten, który narzędzia kompilują i uruchamiają. Narzędzia muszą wykonywać kod aplikacji w czasie projektowania, aby uzyskać informacje o projekcie, takie jak parametry połączenia bazy danych i konfiguracja modelu. Domyślnie projekt w bieżącym katalogu to projekt startowy. Możesz określić inny projekt jako projekt startowy --startup-project przy użyciu opcji .

Projekt startowy i docelowy projekt są często tym samym projektem. Typowy scenariusz, w którym są oddzielnymi projektami, jest następujący:

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

Istnieje również możliwość umieszczenia kodu migracji w bibliotece klas niezależnie od kontekstu platformy EF Core.

Inne platformy docelowe

Narzędzia interfejsu wiersza polecenia współpracują z projektami platformy .NET Core i projektami .NET Framework. Aplikacje, które mają model EF Core w bibliotece klas platformy .NET Standard, mogą nie mieć projektu platformy .NET Core lub .NET Framework. Na przykład dotyczy to aplikacji platformy Xamarin i platforma uniwersalna systemu Windows. W takich przypadkach można utworzyć projekt aplikacji konsolowej platformy .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 platformy .NET Core. Gdy model EF Core znajduje się w projekcie przeznaczonym dla platformy .NET Core lub .NET Framework, narzędzia EF Core pożyczają środowisko uruchomieniowe z projektu. Nie mogą tego zrobić, jeśli model EF Core znajduje się w bibliotece klas platformy .NET Standard. .NET Standard nie jest rzeczywistą implementacją platformy .NET; jest to specyfikacja zestawu interfejsów API, które muszą obsługiwać implementacje platformy .NET. W związku z tym platforma .NET Standard nie jest wystarczająca, aby narzędzia EF Core wykonywały kod aplikacji. Fikcyjny projekt używany jako projekt startowy udostępnia konkretną platformę docelową, w której narzędzia mogą załadować bibliotekę klas .NET Standard.

środowisko ASP.NET Core

Aby określić środowisko dla projektów ASP.NET Core, ustaw zmienną środowiskową ASPNETCORE_ENVIRONMENT przed uruchomieniem poleceń.

Począwszy od programu EF Core 5.0, można również przekazać dodatkowe argumenty do programu.CreateHostBuilder, aby określić środowisko w wierszu polecenia:

dotnet ef database update -- --environment Production

Porada

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

Typowe opcje

Opcja Krótki Opis
--json Pokaż dane wyjściowe JSON.
--context <DBCONTEXT> -c Klasa DbContext do użycia. Nazwa klasy lub tylko w pełni kwalifikowana z przestrzeniami nazw. Jeśli ta opcja zostanie pominięta, program EF Core znajdzie klasę kontekstu. Jeśli istnieje wiele klas kontekstowych, ta opcja jest wymagana.
--project <PROJECT> -p Ścieżka względna do folderu projektu docelowego. Wartość domyślna to bieżący folder.
--startup-project <PROJECT> -s Ścieżka względna do folderu projektu uruchamiania. Wartość domyślna to bieżący folder.
--framework <FRAMEWORK> Moniker struktury docelowej dla platformy docelowej. Użyj polecenia , gdy plik projektu określa wiele struktur docelowych i chcesz wybrać jedną z nich.
--configuration <CONFIGURATION> Konfiguracja kompilacji, na przykład: Debug lub Release.
--runtime <IDENTIFIER> Identyfikator docelowego środowiska uruchomieniowego do przywrócenia pakietów. Aby uzyskać listę identyfikatorów środowiska uruchomieniowego (RID), zobacz wykaz identyfikatorów RID.
--no-build Nie kompiluj projektu. Ma być używany, gdy kompilacja jest aktualna.
--help -h Pokaż informacje pomocy.
--verbose -v Pokaż pełne dane wyjściowe.
--no-color Nie koloruj danych wyjściowych.
--prefix-output Prefiks danych wyjściowych z poziomem.

Począwszy od programu EF Core 5.0, wszystkie 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 zostałaby porzucona, ale nie upuszczaj jej.

Typowe opcje są wymienione powyżej.

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 według nazwy lub identyfikatora. Liczba 0 jest specjalnym przypadkiem, co oznacza przed pierwszą migracją i powoduje przywrócenie wszystkich migracji. Jeśli migracja nie zostanie określona, polecenie zostanie domyślnie ustawione na ostatnią migrację.

Opcje:

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

Poniżej wymieniono typowe opcje .

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:

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

dotnet ef dbcontext info

Pobiera informacje o typie DbContext .

Poniżej wymieniono typowe opcje .

dotnet ef dbcontext list

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

Poniżej wymieniono typowe opcje .

dotnet ef dbcontext optimize

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

Aby uzyskać więcej informacji, zobacz Skompilowane modele .

Opcje:

Opcja Krótki Opis
--output-dir <PATH> -o Katalog do umieszczania plików. Ścieżki są względne względem katalogu projektu.
--namespace <NAMESPACE> -n Przestrzeń nazw do użycia dla wszystkich wygenerowanych klas. Domyślnie są generowane z głównej przestrzeni nazw i katalogu wyjściowego oraz CompiledModels.

Poniżej wymieniono typowe opcje .

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

dotnet ef dbcontext optimize

Poniższy przykład optymalizuje model dla kontekstu z określoną nazwą i umieszcza go w osobnym folderze i przestrzeni nazw:

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

dotnet ef dbcontext scaffold

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

Argumenty:

Argument Opis
<CONNECTION> Parametry połączenia z bazą danych. W przypadku projektów ASP.NET Core 2.x wartość może mieć wartość name=<name parametrów> połączenia. W takim przypadku nazwa pochodzi ze źródeł konfiguracji skonfigurowanych 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, zostanie użyty tylko płynny interfejs API.
--context <NAME> -c Nazwa DbContext klasy do wygenerowania.
--context-dir <PATH> Katalog, w który ma być umieszczony DbContext 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 wartość --namespace. Dodano w programie EF Core 5.0.
--force -f Zastąp istniejące pliki.
--output-dir <PATH> -o Katalog do umieszczania plików klasy jednostki. Ścieżki są względne względem katalogu projektu.
--namespace <NAMESPACE> -n Przestrzeń nazw do użycia dla wszystkich wygenerowanych klas. Domyślnie są generowane z głównej przestrzeni nazw i katalogu wyjściowego. Dodano w programie EF Core 5.0.
--schema <SCHEMA_NAME>... Schematy tabel do generowania typów jednostek dla. 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 dla. Aby określić wiele tabel, powtórz -t lub --table dla każdego z nich. Jeśli ta opcja zostanie pominięta, zostaną uwzględnione wszystkie tabele.
--use-database-names Użyj 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 były bardziej zgodne z konwencjami stylu nazw języka C#.
--no-onconfiguring Pomija generowanie OnConfiguring metody w wygenerowanej DbContext klasie. Dodano w programie EF Core 5.0.
--no-pluralize Nie używaj w liczbie mnogiej. Dodano w programie EF Core 5.0

Poniżej wymieniono typowe opcje .

Poniższy przykładowy szkielet obejmuje wszystkie schematy i tabele 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ładowy szkielet zawiera tylko wybrane tabele i tworzy kontekst w osobnym 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 parametry 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 tworzenie szkieletu OnConfiguring metody. Może to być przydatne, gdy chcesz skonfigurować element DbContext poza klasą. Na przykład ASP.NET Core aplikacje zwykle konfigurują je w pliku Startup.ConfigureServices. Dodano w programie 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 na podstawie obiektu DbContext. Pomija wszelkie migracje.

Opcje:

Opcja Krótki Opis
--output <FILE> -o Plik do zapisania wyniku.

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 służy do wyprowadzania plików. Ścieżki są względne względem docelowego katalogu projektu. Wartość domyślna to "Migrations" (Migracje).
--namespace <NAMESPACE> -n Przestrzeń nazw do użycia dla wygenerowanych klas. Wartości domyślne do wygenerowania z katalogu wyjściowego. Dodano w programie EF Core 5.0.

Typowe opcje są wymienione powyżej.

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ż spakować środowisko uruchomieniowe platformy .NET, aby nie trzeba było go instalować na maszynie.
--target-runtime <RUNTIME_IDENTIFIER> -r Docelowe środowisko uruchomieniowe do spakowania.

Typowe opcje są wymienione powyżej.

dotnet ef migrations list

Wyświetla listę dostępnych migracji.

Opcje:

Opcja Opis
--connection <CONNECTION> Parametry połączenia z bazą danych. Wartość domyślna to określona w elemecie AddDbContext lub OnConfiguring. Dodano w programie EF Core 5.0.
--no-connect Nie nawiąż połączenia z bazą danych. Dodano w programie EF Core 5.0.

Typowe opcje są wymienione powyżej.

dotnet ef migrations remove

Usuwa ostatnią migrację, cofa zmiany kodu, które zostały wykonane na potrzeby najnowszej migracji.

Opcje:

Opcja Krótki Opis
--force -f Przywróć najnowszą migrację, cofnij zarówno kod, jak i zmiany bazy danych, które zostały wykonane na potrzeby najnowszej migracji. W dalszym ciągu przywracany jest tylko kod, jeśli wystąpi błąd podczas nawiązywania połączenia z bazą danych.

Typowe opcje są wymienione powyżej.

dotnet ef migrations script

Generuje skrypt SQL na podstawie migracji.

Argumenty:

Argument Opis
<FROM> Początkowa migracja. Migracje mogą być identyfikowane według nazwy lub identyfikatora. Liczba 0 jest specjalnym przypadkiem, co oznacza przed pierwszą migracją. Wartość domyślna to 0.
<TO> Zakończenie migracji. Domyślnie jest to ostatnia migracja.

Opcje:

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

Typowe opcje są wymienione powyżej.

W poniższym przykładzie zostanie utworzony skrypt inicjowaniaUtwórz migrację:

dotnet ef migrations script 0 InitialCreate

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

dotnet ef migrations script 20180904195021_InitialCreate

Dodatkowe zasoby