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

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

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

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

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

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. Креатехостбуилдер, что позволяет указать среду в командной строке:

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 scaffold

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

Аргументы:

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

Параметры:

Параметр Short Описание
--data-annotations -d Используйте атрибуты для настройки модели (по возможности). Если этот параметр пропущен, используется только API-интерфейс Fluent.
--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.ConfigУресервицес. Добавлено в 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. Обход всех миграций. Добавлено в EF Core 3,0.

Параметры:

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

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

dotnet ef migrations add

Добавляет новый перенос.

Аргументы:

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

Параметры:

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

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

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 Transaction. Добавлено в EF Core 5,0.

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

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

dotnet ef migrations script 0 InitialCreate

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

dotnet ef migrations script 20180904195021_InitialCreate

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