Поделиться через

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

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

При использовании 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.
  • Консольное приложение .NET или веб-приложение ссылается на библиотеку классов.

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

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

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

Important

Xamarin.Android, Xamarin.iOS, Xamarin.Mac теперь интегрированы непосредственно в .NET (начиная с .NET 6) в качестве .NET для Android, .NET для iOS и .NET для macOS. Если вы создаете эти типы проектов сегодня, они должны быть обновлены до проектов в стиле пакета SDK для .NET для продолжения поддержки. Дополнительные сведения об обновлении проектов Xamarin до .NET см. в документации по обновлению с Xamarin до .NET & .NET MAUI.

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

базовая среда ASP.NET

Среду для проектов ASP.NET Core можно указать в командной строке. Это и все дополнительные аргументы передаются в Program.CreateHostBuilder.

dotnet ef database update -- --environment Production

Tip

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

Распространенные параметры

Option Short Description
--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 Добавьте уровень в качестве префикса к выводу.

Все дополнительные аргументы передаются приложению.

dotnet ef database drop

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

Options:

Option Short Description
--force -f Не подтверждайте.
--dry-run Показать, какая база данных будет удалена, но не удаляйте ее.
--connection <CONNECTION> Строка подключения к базе данных. По умолчанию выбирается указанный в AddDbContext или OnConfiguring. Добавлено в EF Core 11.

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

dotnet ef database update

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

Arguments:

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

Options:

Option Description
--connection <CONNECTION> Строка подключения к базе данных. По умолчанию выбирается тот, который указан в AddDbContext или OnConfiguring.

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

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

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, и предварительно компилирует запросы.

См. скомпилированные модели для получения дополнительной информации.

Options:

Option Short Description
--output-dir <PATH> -o Каталог, в который нужно поместить файлы. Пути относительны к каталогу проекта.
--namespace <NAMESPACE> -n Пространство имен, используемое для всех созданных классов. По умолчанию создается из корневого пространства имен и выходного каталога плюс CompiledModels.
--suffix <SUFFIX> Суффикс для присоединения ко имени всех созданных файлов. Например .g , можно использовать для указания того, что эти файлы содержат созданный код
--no-scaffold Не создавайте скомпилированную модель. Используется при создании скомпилированной модели.
--precompile-queries Создайте предварительно скомпилированные запросы. Это необходимо для компиляции NativeAOT, если целевой проект содержит любые запросы.
--nativeaot Создание дополнительного кода в скомпилированной модели, необходимой для компиляции NativeAOT и предварительно скомпилированных запросов

Note

Поддержка NativeAOT и предварительно скомпилированные запросы считаются экспериментальными в EF 9 и могут резко измениться в следующем выпуске.

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

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

dotnet ef dbcontext optimize

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

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

dotnet ef dbcontext scaffold

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

Arguments:

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

Options:

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

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

Следующий пример создает каркас для всех схем и таблиц и помещает новые файлы в папку 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

В следующем примере считывается строка подключения из набора конфигураций проекта с помощью средства 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

В следующем примере пропускается формирование шаблонов OnConfiguring метода. Это может быть полезно, если требуется настроить DbContext за пределами класса. Например, приложения ASP.NET Core обычно настраивают его в Startup.ConfigureServices.

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

dotnet ef dbcontext script

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

Options:

Option Short Description
--output <FILE> -o Файл для записи результата.

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

dotnet ef migrations add

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

Arguments:

Argument Description
<NAME> Имя миграции.

Options:

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

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

dotnet ef migrations bundle

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

Options:

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

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

dotnet ef migrations has-pending-model-changes

Note

Эта команда была добавлена в EF Core 8.0.

Проверяет, были ли изменения внесены в модель с момента последней миграции.

Options:

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

dotnet ef migrations list

Перечисляет доступные миграции.

Options:

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

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

dotnet ef migrations remove

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

Options:

Option Short Description
--force -f Отмените последнюю миграцию, откатив обратно изменения кода и базы данных, выполненные для последней миграции. Продолжает отмену изменений в коде только при возникновении ошибки при подключении к базе данных.
--connection <CONNECTION> Строка подключения к базе данных. По умолчанию выбирается тот, который указан в AddDbContext или OnConfiguring. Добавлено в EF Core 11.
--offline Удалите миграцию без подключения к базе данных. Добавлено в EF Core 11.

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

Note

Параметры --offline и --force нельзя использовать вместе, поскольку --force требует подключения к базе данных, чтобы проверить, была ли миграция применена перед обратным применением.

dotnet ef migrations script

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

Arguments:

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

Options:

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

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

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

dotnet ef migrations script 0 InitialCreate

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

dotnet ef migrations script 20180904195021_InitialCreate

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

  • Last updated on