Dokumentacja narzędzi Entity Framework Core Tools — interfejs wiersza polecenia platformy .NETEntity Framework Core tools reference - .NET CLI

Narzędzia interfejsu wiersza polecenia (CLI) dla Entity Framework Core wykonują zadania deweloperskie czasu projektowania.The command-line interface (CLI) tools for Entity Framework Core perform design-time development tasks. Na przykład tworzą migracje, stosują migracje i generują kod dla modelu na podstawie istniejącej bazy danych.For example, they create migrations, apply migrations, and generate code for a model based on an existing database. Polecenia są rozszerzeniem dla międzyplatformowego polecenia dotnet , które jest częścią zestaw .NET Core SDK.The commands are an extension to the cross-platform dotnet command, which is part of the .NET Core SDK. Te narzędzia współpracują z projektami .NET Core.These tools work with .NET Core projects.

Jeśli używasz programu Visual Studio, zalecamy użycie narzędzi konsoli Menedżera pakietów :If you're using Visual Studio, we recommend the Package Manager Console tools instead:

  • Automatycznie pracują z bieżącym projektem wybranym w konsoli Menedżera pakietów bez konieczności ręcznego przełączania katalogów.They automatically work with the current project selected in the Package Manager Console without requiring that you manually switch directories.
  • Automatycznie otwierają pliki wygenerowane przez polecenie po zakończeniu polecenia.They automatically open files generated by a command after the command is completed.

Instalowanie narzędziInstalling the tools

Procedura instalacji zależy od typu projektu i wersji:The installation procedure depends on project type and version:

  • EF Core 3. xEF Core 3.x
  • ASP.NET Core wersja 2,1 lub nowszaASP.NET Core version 2.1 and later
  • EF Core 2. xEF Core 2.x
  • EF Core 1. xEF Core 1.x

EF Core 3. xEF Core 3.x

  • dotnet ef musi być zainstalowana jako narzędzie globalne lub lokalne.dotnet ef must be installed as a global or local tool. Większość deweloperów zainstaluje dotnet ef jako narzędzie globalne przy użyciu następującego polecenia:Most developers will install dotnet ef as a global tool with the following command:

    dotnet tool install --global dotnet-ef
    

    Możesz również użyć dotnet ef jako narzędzia lokalnego.You can also use dotnet ef as local tool. Aby użyć go jako narzędzia lokalnego, Przywróć zależności projektu, które deklaruje jako zależność narzędzia przy użyciu pliku manifestu narzędzia.To use it as a local tool, restore the dependencies of a project that declares it as a tooling dependency using a tool manifest file.

  • Zainstaluj zestaw .NET Core SDK 3,0.Install the .NET Core SDK 3.0. Zestaw SDK należy zainstalować nawet w przypadku najnowszej wersji programu Visual Studio.The SDK has to be installed even if you have the latest version of Visual Studio.

  • Zainstaluj najnowszy pakiet Microsoft.EntityFrameworkCore.Design.Install the latest Microsoft.EntityFrameworkCore.Design package.

    dotnet add package Microsoft.EntityFrameworkCore.Design
    

ASP.NET Core 2.1 +ASP.NET Core 2.1+

  • Zainstaluj bieżącą zestaw .NET Core SDK.Install the current .NET Core SDK. Zestaw SDK należy zainstalować nawet w przypadku najnowszej wersji programu Visual Studio 2017.The SDK has to be installed even if you have the latest version of Visual Studio 2017.

    Jest to wszystkie niezbędne dla ASP.NET Core 2.1 +, ponieważ pakiet Microsoft.EntityFrameworkCore.Design jest zawarty w pakiecie Microsoft. AspNetCore. app.This is all that is needed for ASP.NET Core 2.1+ because the Microsoft.EntityFrameworkCore.Design package is included in the Microsoft.AspNetCore.App metapackage.

EF Core 2. x (nie ASP.NET Core)EF Core 2.x (not ASP.NET Core)

Polecenia dotnet ef są zawarte w zestaw .NET Core SDK, ale w celu włączenia poleceń, aby zainstalować pakiet Microsoft.EntityFrameworkCore.Design.The dotnet ef commands are included in the .NET Core SDK, but to enable the commands you have to install the Microsoft.EntityFrameworkCore.Design package.

  • Zainstaluj bieżącą zestaw .NET Core SDK.Install the current .NET Core SDK. Zestaw SDK należy zainstalować nawet w przypadku najnowszej wersji programu Visual Studio.The SDK has to be installed even if you have the latest version of Visual Studio.

  • Zainstaluj najnowszy stabilny pakiet Microsoft.EntityFrameworkCore.Design.Install the latest stable Microsoft.EntityFrameworkCore.Design package.

    dotnet add package Microsoft.EntityFrameworkCore.Design
    

EF Core 1. xEF Core 1.x

  • Zainstaluj zestaw .NET Core SDK w wersji 2.1.200.Install the .NET Core SDK version 2.1.200. Nowsze wersje nie są zgodne z narzędziami interfejsu wiersza polecenia dla EF Core 1,0 i 1,1.Later versions are not compatible with CLI tools for EF Core 1.0 and 1.1.

  • Skonfiguruj aplikację tak, aby korzystała z wersji zestawu SDK 2.1.200, modyfikując jej plik Global. JSON .Configure the application to use the 2.1.200 SDK version by modifying its global.json file. Ten plik jest zwykle zawarty w katalogu rozwiązania (jeden powyżej projektu).This file is normally included in the solution directory (one above the project).

  • Edytuj plik projektu i Dodaj Microsoft.EntityFrameworkCore.Tools.DotNet jako element DotNetCliToolReference.Edit the project file and add Microsoft.EntityFrameworkCore.Tools.DotNet as a DotNetCliToolReference item. Określ wersję najnowszej wersji 1. x, na przykład: 1.1.6.Specify the latest 1.x version, for example: 1.1.6. Zobacz przykład pliku projektu na końcu tej sekcji.See the project file example at the end of this section.

  • Zainstaluj najnowszą wersję 1. x pakietu Microsoft.EntityFrameworkCore.Design, na przykład:Install the latest 1.x version of the Microsoft.EntityFrameworkCore.Design package, for example:

    dotnet add package Microsoft.EntityFrameworkCore.Design -v 1.1.6
    

    Po dodaniu obu odwołań do pakietu plik projektu wygląda następująco:With both package references added, the project file looks something like this:

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp1.1</TargetFramework>
      </PropertyGroup>
      <ItemGroup>
        <PackageReference Include="Microsoft.EntityFrameworkCore.Design"
                          Version="1.1.6"
                           PrivateAssets="All" />
      </ItemGroup>
      <ItemGroup>
         <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
                                Version="1.1.6" />
      </ItemGroup>
    </Project>
    

    Odwołanie do pakietu z PrivateAssets="All" nie jest ujawnione dla projektów, które odwołują się do tego projektu.A package reference with PrivateAssets="All" isn't exposed to projects that reference this project. To ograniczenie jest szczególnie przydatne w przypadku pakietów, które są zwykle używane tylko podczas projektowania.This restriction is especially useful for packages that are typically only used during development.

Weryfikuj instalacjęVerify installation

Uruchom następujące polecenia, aby upewnić się, że narzędzia interfejsu wiersza polecenia EF Core są prawidłowo zainstalowane:Run the following commands to verify that EF Core CLI tools are correctly installed:

dotnet restore
dotnet ef

Dane wyjściowe polecenia określają wersję narzędzi w użyciu:The output from the command identifies the version of the tools in use:


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

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

<Usage documentation follows, not shown.>

Korzystanie z narzędziUsing the tools

Przed rozpoczęciem korzystania z narzędzi, może być konieczne utworzenie projektu startowego lub ustawienie środowiska.Before using the tools, you might have to create a startup project or set the environment.

Projekt docelowy i projekt startowyTarget project and startup project

Polecenia odnoszą się do projektu i projektu startowego.The commands refer to a project and a startup project.

  • Projekt jest również znany jako projekt docelowy , ponieważ jest to miejsce, w którym polecenia dodają lub usuwają pliki.The project is also known as the target project because it's where the commands add or remove files. Domyślnie projekt w bieżącym katalogu jest projektem docelowym.By default, the project in the current directory is the target project. Możesz określić inny projekt jako projekt docelowy przy użyciu opcji --project .You can specify a different project as target project by using the --project option.

  • Projekt startowy jest tym, że narzędzia kompilują i uruchamiają.The startup project is the one that the tools build and run. Narzędzia muszą wykonywać kod aplikacji w czasie projektowania, aby uzyskać informacje o projekcie, takie jak parametry połączenia bazy danych i Konfiguracja modelu.The tools have to execute application code at design time to get information about the project, such as the database connection string and the configuration of the model. Domyślnie projekt w bieżącym katalogu jest projektem startowym.By default, the project in the current directory is the startup project. Możesz określić inny projekt jako projekt startowy przy użyciu opcji --startup-project .You can specify a different project as startup project by using the --startup-project option.

Projekt startowy i projekt docelowy są często tymi samymi projektami.The startup project and target project are often the same project. Typowy scenariusz, w którym są oddzielnymi projektami, to:A typical scenario where they are separate projects is when:

  • EF Core kontekstu i klasy jednostek znajdują się w bibliotece klas .NET Core.The EF Core context and entity classes are in a .NET Core class library.
  • Aplikacja konsolowa platformy .NET Core lub aplikacja internetowa odwołuje się do biblioteki klas.A .NET Core console app or web app references the class library.

Możliwe jest również umieszczenie kodu migracji w bibliotece klas odrębnie od kontekstu EF Core.It's also possible to put migrations code in a class library separate from the EF Core context.

Inne platformy doceloweOther target frameworks

Narzędzia interfejsu wiersza polecenia współpracują z projektami .NET Core i projektami .NET Framework.The CLI tools work with .NET Core projects and .NET Framework projects. Aplikacje, które mają model EF Core w bibliotece klas .NET Standard mogą nie mieć projektu .NET Core lub .NET Framework.Apps that have the EF Core model in a .NET Standard class library might not have a .NET Core or .NET Framework project. Na przykład jest to prawdziwe w aplikacjach Xamarin i platforma uniwersalna systemu Windows.For example, this is true of Xamarin and Universal Windows Platform apps. W takich przypadkach można utworzyć projekt aplikacji konsolowej .NET Core, którego jedynym celem jest działanie jako projekt startowy dla narzędzi.In such cases, you can create a .NET Core console app project whose only purpose is to act as startup project for the tools. Projekt może być fikcyjnym projektem bez kodu rzeczywistego — jest to konieczne tylko udostępnienie elementu docelowego dla narzędzi.The project can be a dummy project with no real code — it is only needed to provide a target for the tooling.

Dlaczego jest wymagany projekt fikcyjny?Why is a dummy project required? Jak wspomniano wcześniej, narzędzia muszą wykonać kod aplikacji w czasie projektowania.As mentioned earlier, the tools have to execute application code at design time. W tym celu należy użyć środowiska uruchomieniowego platformy .NET Core.To do that, they need to use the .NET Core runtime. Gdy model EF Core znajduje się w projekcie, który jest przeznaczony dla programu .NET Core lub .NET Framework, narzędzia EF Core zażyczą sobie środowisko uruchomieniowe z projektu.When the EF Core model is in a project that targets .NET Core or .NET Framework, the EF Core tools borrow the runtime from the project. Nie można tego zrobić, jeśli model EF Core znajduje się w .NET Standardej bibliotece klas.They can't do that if the EF Core model is in a .NET Standard class library. .NET Standard nie jest rzeczywistą implementacją platformy .NET; jest to specyfikacja zestawu interfejsów API, które muszą być obsługiwane przez implementacje platformy .NET.The .NET Standard is not an actual .NET implementation; it's a specification of a set of APIs that .NET implementations must support. W związku z tym .NET Standard nie są wystarczające dla narzędzi EF Core do wykonywania kodu aplikacji.Therefore .NET Standard is not sufficient for the EF Core tools to execute application code. Projekt fikcyjny tworzony do użycia jako projekt startowy zapewnia konkretną platformę docelową, do której narzędzia mogą ładować .NET Standard biblioteki klas.The dummy project you create to use as startup project provides a concrete target platform into which the tools can load the .NET Standard class library.

Środowisko ASP.NET CoreASP.NET Core environment

Aby określić środowisko dla projektów ASP.NET Core, należy ustawić zmienną środowiskową ASPNETCORE_ENVIRONMENT przed uruchomieniem poleceń.To specify the environment for ASP.NET Core projects, set the ASPNETCORE_ENVIRONMENT environment variable before running commands.

Typowe opcjeCommon options

OpcjaOption OpisDescription
--json Pokaż dane wyjściowe JSON.Show JSON output.
-c --context <DBCONTEXT> Klasa DbContext do użycia.The DbContext class to use. Nazwa klasy lub w pełni kwalifikowana z przestrzeniami nazw.Class name only or fully qualified with namespaces. Jeśli ta opcja zostanie pominięta, EF Core odnajdzie klasę kontekstową.If this option is omitted, EF Core will find the context class. Jeśli istnieje wiele klas kontekstu, ta opcja jest wymagana.If there are multiple context classes, this option is required.
-p --project <PROJECT> Ścieżka względna do folderu projektu projektu docelowego.Relative path to the project folder of the target project. Wartość domyślna to bieżący folder.Default value is the current folder.
-s --startup-project <PROJECT> Ścieżka względna do folderu projektu projektu startowego.Relative path to the project folder of the startup project. Wartość domyślna to bieżący folder.Default value is the current folder.
--framework <FRAMEWORK> Moniker platformy docelowej dla platformy docelowej.The Target Framework Moniker for the target framework. Użyj, gdy plik projektu określa wiele platform docelowych i chcesz wybrać jedną z nich.Use when the project file specifies multiple target frameworks, and you want to select one of them.
--configuration <CONFIGURATION> Konfiguracja kompilacji, na przykład: Debug lub Release.The build configuration, for example: Debug or Release.
--runtime <IDENTIFIER> Identyfikator docelowego środowiska uruchomieniowego, dla którego mają zostać przywrócone pakiety.The identifier of the target runtime to restore packages for. Aby uzyskać listę identyfikatorów środowiska uruchomieniowego (RID), zobacz wykaz identyfikatorów RID.For a list of Runtime Identifiers (RIDs), see the RID catalog.
-h --help Pokaż informacje pomocy.Show help information.
-v --verbose Pokaż pełne dane wyjściowe.Show verbose output.
--no-color Nie Koloruj danych wyjściowych.Don't colorize output.
--prefix-output Przedrostka danych wyjściowych z poziomem.Prefix output with level.

porzucanie bazy danych programu dotnet EFdotnet ef database drop

Odrzuca bazę danych.Drops the database.

Opcje:Options:

OpcjaOption OpisDescription
-f --force Nie potwierdzaj.Don't confirm.
--dry-run Pokazuje, która baza danych zostanie porzucona, ale nie Porzuć jej.Show which database would be dropped, but don't drop it.

Aktualizacja bazy danych dotnet EFdotnet ef database update

Aktualizuje bazę danych do ostatniej migracji lub do określonej migracji.Updates the database to the last migration or to a specified migration.

ArgumentuArguments:

ArgumentArgument OpisDescription
<MIGRATION> Migracja docelowa.The target migration. Migracje mogą być identyfikowane według nazwy lub identyfikatora.Migrations may be identified by name or by ID. Liczba 0 jest szczególnym przypadkiem przed pierwszą migracją i powoduje przywrócenie wszystkich migracji.The number 0 is a special case that means before the first migration and causes all migrations to be reverted. Jeśli migracja nie zostanie określona, polecenie domyślnie przestanie być ostatnią migracją.If no migration is specified, the command defaults to the last migration.

Poniższe przykłady umożliwiają zaktualizowanie bazy danych do określonej migracji.The following examples update the database to a specified migration. Pierwsza z nich używa nazwy migracji, a druga używa identyfikatora migracji:The first uses the migration name and the second uses the migration ID:

dotnet ef database update InitialCreate
dotnet ef database update 20180904195021_InitialCreate

informacje dotyczące kontekstu dotnet EFdotnet ef dbcontext info

Pobiera informacje o typie DbContext.Gets information about a DbContext type.

Lista kontekstowa dotnet EFdotnet ef dbcontext list

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

Szkielet EF DbContextdotnet ef dbcontext scaffold

Generuje kod dla DbContext i typów jednostek dla bazy danych.Generates code for a DbContext and entity types for a database. Aby to polecenie generowało typ jednostki, tabela bazy danych musi mieć klucz podstawowy.In order for this command to generate an entity type, the database table must have a primary key.

ArgumentuArguments:

ArgumentArgument OpisDescription
<CONNECTION> Parametry połączenia z bazą danych.The connection string to the database. W przypadku projektów ASP.NET Core 2. x wartością może być Nazwa =<nazwa parametrów połączenia > .For ASP.NET Core 2.x projects, the value can be name=<name of connection string>. W takim przypadku nazwa pochodzi ze źródeł konfiguracji skonfigurowanych dla projektu.In that case the name comes from the configuration sources that are set up for the project.
<PROVIDER> Dostawca do użycia.The provider to use. Zazwyczaj jest to nazwa pakietu NuGet, na przykład: Microsoft.EntityFrameworkCore.SqlServer.Typically this is the name of the NuGet package, for example: Microsoft.EntityFrameworkCore.SqlServer.

Opcje:Options:

OpcjaOption OpisDescription
-c-d --data-annotations Użyj atrybutów, aby skonfigurować model (tam, gdzie to możliwe).Use attributes to configure the model (where possible). Jeśli ta opcja zostanie pominięta, używany jest tylko interfejs API Fluent.If this option is omitted, only the fluent API is used.
-c --context <NAME> Nazwa klasy DbContext do wygenerowania.The name of the DbContext class to generate.
--context-dir <PATH> Katalog, w którym ma zostać umieszczony plik klasy DbContext.The directory to put the DbContext class file in. Ścieżki są względne dla katalogu projektu.Paths are relative to the project directory. Przestrzenie nazw są wyprowadzane z nazw folderów.Namespaces are derived from the folder names.
-f --force Zastąp istniejące pliki.Overwrite existing files.
-o --output-dir <PATH> Katalog, w którym mają zostać umieszczone pliki klas jednostek.The directory to put entity class files in. Ścieżki są względne dla katalogu projektu.Paths are relative to the project directory.
--schema <SCHEMA_NAME>... Schematy tabel, dla których mają zostać wygenerowane typy jednostek.The schemas of tables to generate entity types for. Aby określić wiele schematów, powtórz --schema dla każdej z nich.To specify multiple schemas, repeat --schema for each one. W przypadku pominięcia tej opcji są uwzględniane wszystkie schematy.If this option is omitted, all schemas are included.
-t --table <TABLE_NAME>...--table <TABLE_NAME>... Tabele, dla których mają zostać wygenerowane typy jednostek.The tables to generate entity types for. Aby określić wiele tabel, powtórz -t lub --table dla każdej z nich.To specify multiple tables, repeat -t or --table for each one. W przypadku pominięcia tej opcji są uwzględniane wszystkie tabele.If this option is omitted, all tables are included.
--use-database-names Nazwy tabel i kolumn należy używać dokładnie tak, jak pojawiają się one w bazie danych.Use table and column names exactly as they appear in the database. Jeśli ta opcja zostanie pominięta, nazwy baz danych są zmieniane na bardziej ścisłe, zgodne z C# konwencjami stylu nazwy.If this option is omitted, database names are changed to more closely conform to C# name style conventions.

Poniższy przykład szkieletuje wszystkie schematy i tabele i umieszcza nowe pliki w folderze models .The following example scaffolds all schemas and tables and puts the new files in the Models folder.

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

Poniższy przykład szkieletuje tylko wybrane tabele i tworzy kontekst w osobnym folderze o określonej nazwie:The following example scaffolds only selected tables and creates the context in a separate folder with a specified name:

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

Dodawanie migracji dotnet EFdotnet ef migrations add

Dodaje nową migrację.Adds a new migration.

ArgumentuArguments:

ArgumentArgument OpisDescription
<NAME> Nazwa migracji.The name of the migration.

Opcje:Options:

OpcjaOption OpisDescription
-o --output-dir <PATH> Katalog (i podrzędna przestrzeń nazw) do użycia.The directory (and sub-namespace) to use. Ścieżki są względne dla katalogu projektu.Paths are relative to the project directory. Wartość domyślna to "migracje".Defaults to "Migrations".

Lista migracji dotnetdotnet ef migrations list

Wyświetla listę dostępnych migracji.Lists available migrations.

Usuwanie migracji dotnetdotnet ef migrations remove

Usuwa ostatnią migrację (przywraca zmiany kodu, które zostały wykonane podczas migracji).Removes the last migration (rolls back the code changes that were done for the migration).

Opcje:Options:

OpcjaOption OpisDescription
-f --force Przywróć migrację (Wycofaj zmiany, które zostały zastosowane do bazy danych).Revert the migration (roll back the changes that were applied to the database).

skrypt migracji dotnetdotnet ef migrations script

Generuje skrypt SQL z migracji.Generates a SQL script from migrations.

ArgumentuArguments:

ArgumentArgument OpisDescription
<FROM> Rozpoczynanie migracji.The starting migration. Migracje mogą być identyfikowane według nazwy lub identyfikatora.Migrations may be identified by name or by ID. Liczba 0 to specjalny przypadek, który oznacza przed pierwszą migracją.The number 0 is a special case that means before the first migration. Wartość domyślna wynosi 0.Defaults to 0.
<TO> Kończenie migracji.The ending migration. Wartość domyślna to Ostatnia migracja.Defaults to the last migration.

Opcje:Options:

OpcjaOption OpisDescription
-o --output <FILE> Plik, w którym ma zostać zapisany skrypt.The file to write the script to.
-i --idempotent Generuj skrypt, którego można użyć w bazie danych w dowolnej migracji.Generate a script that can be used on a database at any migration.

Poniższy przykład tworzy skrypt migracji InitialCreate:The following example creates a script for the InitialCreate migration:

dotnet ef migrations script 0 InitialCreate

Poniższy przykład tworzy skrypt dla wszystkich migracji po migracji InitialCreate.The following example creates a script for all migrations after the InitialCreate migration.

dotnet ef migrations script 20180904195021_InitialCreate

Dodatkowe zasobyAdditional resources