Udostępnij za pośrednictwem

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 programu Visual Studio rozważ użycie narzędzi konsoli Menedżer pakietów zamiast narzędzi interfejsu wiersza polecenia. Menedżer pakietów Narzędzia konsoli 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 wykonywania polecenia.
  • Zapewnia uzupełnianie kart poleceń, parametrów, nazw projektów, typów kontekstu i nazw migracji.

Instalowanie narzędzi

dotnet ef 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 ją 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 określonym projekcie należy dodać Microsoft.EntityFrameworkCore.Design do niego pakiet.

dotnet add package Microsoft.EntityFrameworkCore.Design

Sprawdzanie 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

Użyj dotnet tool update --global dotnet-ef polecenia , aby zaktualizować narzędzia globalne 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> polecenie . 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 odnoszą 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 jest tym, który narzędzia kompilują i uruchamiają. Narzędzia muszą wykonywać kod aplikacji w czasie projektowania, aby uzyskać informacje o projekcie, takie jak baza danych parametry połączenia 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 projekt docelowy są często tym samym projektem. Typowy scenariusz, w którym są oddzielnymi projektami, jest następujący:

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

Można również umieścić kod migracji w bibliotece klas oddzielnie od kontekstu platformy EF Core.

Inne platformy docelowe

Narzędzia interfejsu wiersza polecenia współpracują z projektami platformy .NET Core i projektami programu .NET Framework. Aplikacje, które mają model EF Core w bibliotece klas platformy .NET Standard, mogą nie mieć projektu .NET Core lub .NET Framework. Dotyczy to na przykład 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.

Ważny

Xamarin.Android, Xamarin.iOS, Xamarin.Mac są teraz zintegrowane bezpośrednio z platformą .NET (począwszy od platformy .NET 6) jako .NET dla systemów Android, .NET dla systemów iOS i .NET dla systemu macOS. Jeśli kompilujesz już dziś te typy projektów, powinny one zostać uaktualnione do projektów w stylu zestawu SDK platformy .NET w celu zapewnienia ciągłej pomocy technicznej. Aby uzyskać więcej informacji na temat uaktualniania projektów platformy Xamarin do platformy .NET, zobacz dokumentację Uaktualnianie z platformy Xamarin do platformy .NET & .NET MAUI.

Dlaczego wymagany jest fikcyjny projekt? Jak wspomniano wcześniej, narzędzia muszą wykonywać kod aplikacji w czasie projektowania. W tym celu 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 platformy .NET Standard.

środowisko ASP.NET Core

Środowisko dla projektów ASP.NET Core można określić w wierszu polecenia. Te i wszelkie dodatkowe argumenty są przekazywane do programu Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Napiwek

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

Typowe opcje

Opcja Krótkie 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, 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 Względna ścieżka do folderu projektu startowego. Wartość domyślna to bieżący folder.
--framework <FRAMEWORK> Moniker platformy docelowej dla platformy docelowej. Użyj polecenia , 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 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.

Wszystkie dodatkowe argumenty są przekazywane do aplikacji.

dotnet ef database drop

Usuwa bazę danych.

Opcje:

Opcja Krótkie opis
--force -f Nie potwierdzaj.
--dry-run Pokaż, która baza danych zostanie porzucona, ale nie upuść 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 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 do bazy danych. Domyślnie jest to wartość określona w AddDbContext elem lub OnConfiguring.

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żywaną DbContext przez zapytania prekompilowane i .

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

Opcje:

Opcja Krótkie 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.
--suffix <SUFFIX> Sufiks do dołączenia do nazwy wszystkich wygenerowanych plików. Można na przykład .g wskazać, że te pliki zawierają wygenerowany kod
--no-scaffold Nie generuj skompilowanego modelu. Jest to używane, gdy skompilowany model został już wygenerowany.
--precompile-queries Generowanie wstępnie skompilowanych zapytań. Jest to wymagane w przypadku kompilacji NativeAOT, jeśli projekt docelowy zawiera jakiekolwiek zapytania
--nativeaot Generowanie dodatkowego kodu w skompilowanym modelu wymaganym do kompilacji nativeAOT i wstępnie skompilowanych zapytań

Uwaga

Obsługa nativeAOT i wstępnie skompilowane zapytania są uznawane za eksperymentalne w programie EF 9 i mogą ulec radykalnej zmianie w następnej wersji.

Poniżej wymieniono typowe opcje .

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

dotnet ef dbcontext optimize

Poniższy przykład optymalizuje model dla kontekstu o określonej nazwie 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 do bazy danych. W przypadku projektów ASP.NET Core 2.x wartość może mieć wartość name=<name parametry 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ótkie 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 płynny interfejs API.
--context <NAME> -c Nazwa DbContext klasy do wygenerowania.
--context-dir <PATH> Katalog, w który ma DbContext być umieszczony 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.
--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.
--schema <SCHEMA_NAME>... Schematy tabel i widoków 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. Jeśli ta opcja jest używana, wszystkie tabele i widoki w schematach zostaną uwzględnione w modelu, nawet jeśli nie zostaną jawnie uwzględnione przy użyciu --table.
--table <TABLE_NAME>... -t Tabele i widoki do generowania typów jednostek. Aby określić wiele tabel, powtórz -t lub --table dla każdego z nich. Tabele lub widoki w określonym schemacie można uwzględnić przy użyciu formatu "schema.table" lub "schema.view". Jeśli ta opcja zostanie pominięta, zostaną uwzględnione wszystkie tabele i widoki.
--use-database-names Użyj nazw tabel, widoków, sekwencji 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.
--no-pluralize Nie używaj pluralizatora.

Poniżej wymieniono typowe opcje .

Poniższy przykład umożliwia tworzenie szkieletów 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ładowy szkielet tworzy 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 aplikacje ASP.NET Core zwykle konfigurują je w pliku Startup.ConfigureServices.

dotnet ef dbcontext scaffold "Server=(localdb)\mssqllocaldb;Database=Blogging;Integrated Security=true;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring

dotnet ef dbcontext script

Generuje skrypt SQL z obiektu DbContext. Pomija wszelkie migracje.

Opcje:

Opcja Krótkie 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ótkie 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ść domyślna do wygenerowania z katalogu wyjściowego.

Poniżej wymieniono typowe opcje .

dotnet ef migrations bundle

Tworzy plik wykonywalny w celu zaktualizowania bazy danych.

Opcje:

Opcja Krótkie opis
--output <FILE> -o Ścieżka pliku wykonywalnego do utworzenia.
--force -f Zastąp istniejące pliki.
--self-contained Należy również powiązać środowisko uruchomieniowe platformy .NET, aby nie trzeba było go instalować na maszynie.
--target-runtime <RUNTIME_IDENTIFIER> -r Docelowe środowisko uruchomieniowe do pakietu.

Poniżej wymieniono typowe opcje .

dotnet ef migrations has-pending-model-changes

Uwaga

To polecenie zostało dodane w programie EF Core 8.0.

Sprawdza, czy od czasu ostatniej migracji wprowadzono jakiekolwiek zmiany w modelu.

Opcje:

Poniżej wymieniono typowe opcje .

dotnet ef migrations list

Wyświetla listę dostępnych migracji.

Opcje:

Opcja opis
--connection <CONNECTION> Parametry połączenia do bazy danych. Wartość domyślna to określona w elemecie AddDbContext lub OnConfiguring.
--no-connect Nie łącz się z bazą danych.

Poniżej wymieniono typowe opcje .

dotnet ef migrations remove

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

Opcje:

Opcja Krótkie opis
--force -f Przywróć najnowszą migrację, przywracając zarówno kod, jak i zmiany bazy danych, które zostały wykonane na potrzeby najnowszej migracji. W dalszym ciągu wycofywanie zmienia się 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 na podstawie migracji.

Argumenty:

Argument opis
<FROM> Rozpoczynanie migracji. Migracje mogą być identyfikowane według nazwy lub identyfikatora. Numer 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ótkie 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.

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 migracji InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Dodatkowe zasoby