Справочник по средствам Entity Framework Core — .NET Core CLI

Средства интерфейса командной строки (CLI) для Entity Framework Core выполняют задачи разработки во время разработки. Например, они создают миграции, применяют миграции и создают код для модели на основе существующей базы данных. Команды — это расширение для кроссплатформенной команды dotnet , которая является частью пакета SDK для .NET Core. Эти средства работают с проектами .NET Core.

При использовании Visual Studio рекомендуется использовать средства консоли диспетчера пакетов вместо средств CLI. Средства консоли диспетчера пакетов автоматически:

  • Работает с текущим проектом, выбранным в консоли диспетчера пакетов , без необходимости переключения каталогов вручную.
  • Открывает файлы, созданные командой после завершения команды.
  • Предоставляет завершение вкладок команд, параметров, имен проектов, типов контекста и имен миграции.

Установка инструментов

dotnet ef можно установить как глобальное или локальное средство. Большинство разработчиков предпочитают устанавливать средство dotnet ef в качестве глобального средства, используя следующую команду:

dotnet tool install --global dotnet-ef

Чтобы использовать его в качестве локального средства, восстановите зависимости проекта, в котором оно объявляется в качестве соответствующей зависимости, с помощью файла манифеста средства.

Обновите средство с помощью следующей команды:

dotnet tool update --global dotnet-ef

Прежде чем использовать средства для определенного проекта, необходимо добавить Microsoft.EntityFrameworkCore.Design в него пакет.

dotnet add package Microsoft.EntityFrameworkCore.Design

Проверка установки

Выполните следующие команды, чтобы убедиться, что средства EF Core CLI установлены правильно:

dotnet ef

Выходные данные команды определяют версию используемых средств:


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

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

<Usage documentation follows, not shown.>

Обновление средств

Используется dotnet tool update --global dotnet-ef для обновления глобальных средств до последней доступной версии. Если средства установлены локально в проекте dotnet tool update dotnet-ef. Установите определенную версию, добавив --version <VERSION> ее в команду. Дополнительные сведения см. в разделе "Обновление" документации по инструменту dotnet.

Использование средств

Перед использованием средств может потребоваться создать запускаемый проект или задать среду.

Целевой проект и запускаемый проект

Команды ссылаются на проект и запускаемый проект.

  • Проект также называется целевым проектом, так как команда добавляет или удаляет файлы. По умолчанию проект в текущем каталоге является целевым проектом. Вы можете указать другой проект в качестве целевого проекта с помощью --project параметра.

  • Запускаемый проект — это проект, который создает и запускает средства. Средства должны выполнять код приложения во время разработки для получения сведений о проекте, таких как строка подключения к базе данных и конфигурация модели. По умолчанию проект в текущем каталоге является запускаемым проектом. Вы можете указать другой проект в качестве запускаемого --startup-project проекта с помощью параметра.

Запускаемый проект и целевой проект часто совпадают. Типичный сценарий, когда они являются отдельными проектами:

  • Контекст EF Core и классы сущностей находятся в библиотеке классов .NET Core.
  • Консольное приложение .NET Core или веб-приложение ссылается на библиотеку классов.

Кроме того, можно поместить код миграции в библиотеку классов отдельно от контекста EF Core.

Другие целевые платформы

Средства CLI работают с проектами .NET Core и платформа .NET Framework проектами. Приложения с моделью EF Core в библиотеке классов .NET Standard могут не иметь проекта .NET Core или платформа .NET Framework. Например, это относится к приложениям Xamarin и универсальная платформа Windows. В таких случаях можно создать проект консольного приложения .NET Core, цель которого — выступать в качестве запускаемого проекта для инструментов. Проект может быть фиктивным проектом без реального кода— он необходим только для предоставления целевого объекта для инструментов.

Почему требуется фиктивный проект? Как упоминалось ранее, средства должны выполнять код приложения во время разработки. Для этого им необходимо использовать среду выполнения .NET Core. Если модель EF Core находится в проекте, предназначенном для .NET Core или платформа .NET Framework, средства EF Core заимствуют среду выполнения из проекта. Они не могут сделать это, если модель EF Core находится в библиотеке классов .NET Standard. .NET Standard не является фактической реализацией .NET; Это спецификация набора API, которые должны поддерживать реализации .NET. Поэтому .NET Standard недостаточно для того, чтобы средства EF Core выполняли код приложения. Фиктивный проект, который вы создаете для использования в качестве запускаемого проекта, предоставляет конкретную целевую платформу, в которую средства могут загрузить библиотеку классов .NET Standard.

среда ASP.NET Core

Чтобы указать среду для проектов ASP.NET Core, задайте переменную среды ASPNETCORE_ENVIRONMENT перед выполнением команд.

Начиная с EF Core 5.0, дополнительные аргументы также можно передать в Program.CreateHostBuilder, чтобы указать среду в командной строке:

dotnet ef database update -- --environment Production

Совет

Маркер -- направляет dotnet ef все, что следует за аргументом, и не пытается проанализировать их как параметры. Все дополнительные аргументы, не используемые приложением dotnet ef , перенаправляются в приложение.

Общие параметры

Параметр Short Описание
--json Отображение выходных данных JSON.
--context <DBCONTEXT> -c Класс DbContext для использования. Имя класса только или полное имя с пространствами имен. Если этот параметр опущен, EF Core найдет класс контекста. Если существует несколько классов контекста, этот параметр является обязательным.
--project <PROJECT> -p Относительный путь к папке проекта целевого проекта. Значение по умолчанию — текущая папка.
--startup-project <PROJECT> -s Относительный путь к папке проекта запускаемого проекта. Значение по умолчанию — текущая папка.
--framework <FRAMEWORK> Моникер целевой платформы для целевой платформы. Используется, когда файл проекта указывает несколько целевых платформ и вы хотите выбрать один из них.
--configuration <CONFIGURATION> Конфигурация сборки, например: Debug или Release.
--runtime <IDENTIFIER> Идентификатор целевой среды выполнения для восстановления пакетов. Список идентификаторов сред выполнения (RID) см. в каталоге RID.
--no-build Не создавайте проект. Предназначено для использования при актуальной сборке.
--help -h Отображение справочных сведений.
--verbose -v Отображение подробных выходных данных.
--no-color Не цветируйте выходные данные.
--prefix-output Выходные данные префикса с уровнем.

Начиная с EF Core 5.0, все дополнительные аргументы передаются приложению.

dotnet ef database drop

Удаляет базу данных.

Параметры:

Параметр Short Описание
--force -f Не подтвердите.
--dry-run Укажите, какая база данных будет удалена, но не удаляйте ее.

Общие параметры перечислены выше.

dotnet ef database update

Обновления базу данных до последней миграции или в указанную миграцию.

Аргументы:

Аргумент Описание
<MIGRATION> Целевая миграция. Миграции могут определяться по имени или по идентификатору. Номер 0 — это особый случай, который означает , что перед первой миграцией и приведет к отмене всех миграций. Если миграция не указана, команда по умолчанию используется для последней миграции.

Параметры:

Параметр Описание
--connection <CONNECTION> Строка подключения к базе данных. По умолчанию используется один из указанных в AddDbContext параметре или OnConfiguring. Добавлен в EF Core 5.0.

Общие параметры перечислены выше.

В следующих примерах база данных обновляется до указанной миграции. Первый использует имя миграции, а второй использует идентификатор миграции и указанное соединение:

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

dotnet ef dbcontext info

Возвращает сведения о типе DbContext .

Общие параметры перечислены выше.

dotnet ef dbcontext list

Перечисляет доступные DbContext типы.

Общие параметры перечислены выше.

dotnet ef dbcontext optimize

Создает скомпилированную версию модели, используемой .DbContext Добавлено в EF Core 6.

Дополнительные сведения см. в разделе "Скомпилированные модели ".

Параметры:

Параметр Short Описание
--output-dir <PATH> -o Каталог, в который нужно поместить файлы. Пути относятся к каталогу проекта.
--namespace <NAMESPACE> -n Пространство имен, используемое для всех созданных классов. По умолчанию создается из корневого пространства имен и выходного каталога плюс CompiledModels.

Общие параметры перечислены выше.

В следующем примере используются параметры по умолчанию и работает, если в проекте есть только один DbContext :

dotnet ef dbcontext optimize

В следующем примере модель оптимизируется для контекста с указанным именем и помещает ее в отдельную папку и пространство имен:

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

dotnet ef dbcontext scaffold

Создает код для типов сущностей DbContext и типов сущностей для базы данных. Чтобы эта команда создавала тип сущности, таблица базы данных должна иметь первичный ключ.

Аргументы:

Аргумент Описание
<CONNECTION> Строка подключения к базе данных. Для ASP.NET Core проектов 2.x значение может быть name=<name строки> подключения. В этом случае имя поступает из источников конфигурации, настроенных для проекта.
<PROVIDER> Используемый поставщик. Обычно это имя пакета NuGet, например: Microsoft.EntityFrameworkCore.SqlServer.

Параметры:

Параметр Short Описание
--data-annotations -d Используйте атрибуты для настройки модели (по возможности). Если этот параметр опущен, используется только свободное API.
--context <NAME> -c Имя создаваемого DbContext класса.
--context-dir <PATH> Каталог, в который нужно поместить DbContext файл класса. Пути относятся к каталогу проекта. Пространства имен являются производными от имен папок.
--context-namespace <NAMESPACE> Пространство имен, используемое для созданного DbContext класса. Примечание. Переопределения --namespace. Добавлен в EF Core 5.0.
--force -f Перезаписать существующие файлы.
--output-dir <PATH> -o Каталог, в который нужно поместить файлы класса сущностей. Пути относятся к каталогу проекта.
--namespace <NAMESPACE> -n Пространство имен, используемое для всех созданных классов. По умолчанию создается из корневого пространства имен и выходного каталога. Добавлен в EF Core 5.0.
--schema <SCHEMA_NAME>... Схемы таблиц для создания типов сущностей. Чтобы указать несколько схем, повторите для --schema каждого из них. Если этот параметр опущен, все схемы включаются.
--table <TABLE_NAME>... -t Таблицы для создания типов сущностей. Чтобы указать несколько таблиц, повторите -t или --table для каждого из них. Если этот параметр не указан, включаются все таблицы.
--use-database-names Используйте имена таблиц и столбцов точно так же, как они отображаются в базе данных. Если этот параметр опущен, имена баз данных изменяются на более точное соответствие соглашениям о стиле имен C#.
--no-onconfiguring Подавляет создание OnConfiguring метода в созданном DbContext классе. Добавлен в EF Core 5.0.
--no-pluralize Не используйте плюрализатор. Добавлено в EF Core 5.0

Общие параметры перечислены выше.

В следующем примере шаблонов помещает все схемы и таблицы и помещает новые файлы в папку Models .

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

В следующем примере шаблонов создаются только выбранные таблицы и создается контекст в отдельной папке с указанным именем и пространством имен:

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

В следующем примере строка подключения считывается из набора конфигураций проекта с помощью средства "Диспетчер секретов".

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

В следующем примере пропускается формирование шаблонов OnConfiguring метода. Это может быть полезно, если вы хотите настроить DbContext за пределами класса. Например, ASP.NET Core приложения обычно настраивают его в Startup.ConfigureServices. Добавлен в 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

Создает скрипт SQL из DbContext. Обходит любые миграции.

Параметры:

Параметр Short Описание
--output <FILE> -o Файл для записи результата.

Общие параметры перечислены выше.

dotnet ef migrations add

Добавляет новую миграцию.

Аргументы:

Аргумент Описание
<NAME> Имя миграции.

Параметры:

Параметр Short Описание
--output-dir <PATH> -o Каталог, используемый для вывода файлов. Пути относятся к каталогу целевого проекта. По умолчанию используется значение "Миграции".
--namespace <NAMESPACE> -n Пространство имен, используемое для созданных классов. По умолчанию создается из выходного каталога. Добавлено в EF Core 5.0.

Общие параметры перечислены выше.

dotnet ef migrations bundle

Создает исполняемый файл для обновления базы данных.

Параметры:

Параметр Short Описание
--output <FILE> -o Путь к создаваемому исполняемому файлу.
--force -f Перезаписать существующие файлы.
--self-contained Кроме того, объедините среду выполнения .NET, чтобы ее не нужно было устанавливать на компьютере.
--target-runtime <RUNTIME_IDENTIFIER> -r Целевая среда выполнения для упаковки.

Общие параметры перечислены выше.

dotnet ef migrations list

Список доступных миграций.

Параметры:

Параметр Описание
--connection <CONNECTION> Строка подключения к базе данных. По умолчанию используется значение, указанное в AddDbContext или OnConfiguring. Добавлено в EF Core 5.0.
--no-connect Не подключайтесь к базе данных. Добавлено в EF Core 5.0.

Общие параметры перечислены выше.

dotnet ef migrations remove

Удаляет последнюю миграцию, откатывая изменения кода, выполненные для последней миграции.

Параметры:

Параметр Short Описание
--force -f Отмените последнюю миграцию, откатив изменения кода и базы данных, выполненные для последней миграции. Продолжает выполнять откат только изменения кода, если при подключении к базе данных возникает ошибка.

Общие параметры перечислены выше.

dotnet ef migrations script

Создает скрипт SQL из миграций.

Аргументы:

Аргумент Описание
<FROM> Начальная миграция. Миграции могут определяться по имени или по идентификатору. Номер 0 — это особый случай, который означает перед первой миграцией. Значение по умолчанию — 0.
<TO> Завершение миграции. По умолчанию используется последняя миграция.

Параметры:

Параметр Short Описание
--output <FILE> -o Файл для записи скрипта.
--idempotent -i Создайте скрипт, который можно использовать в базе данных при любой миграции.
--no-transactions Не создавайте инструкции транзакций SQL. Добавлено в EF Core 5.0.

Общие параметры перечислены выше.

В следующем примере создается скрипт для миграции InitialCreate:

dotnet ef migrations script 0 InitialCreate

В следующем примере создается скрипт для всех миграций после миграции InitialCreate.

dotnet ef migrations script 20180904195021_InitialCreate

Дополнительные ресурсы