Справочник по средствам Entity Framework Core — интерфейс командной строки .NET Core
Средства интерфейса командной строки для 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
Среду для проектов ASP.NET Core можно указать в командной строке. Это и все дополнительные аргументы передаются в Program.CreateHostBuilder.
dotnet ef database update -- --environment Production
Совет
Маркер -- направляет dotnet ef для обработки всего следующего как аргумента и не пытается проанализировать их как параметры. Все дополнительные аргументы, не используемые dotnet ef приложением, перенаправляются в приложение.
Распространенные параметры
| Вариант | Короткие | 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
Удаляет базу данных.
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--force |
-f |
Не подтвердите. |
--dry-run |
Показать, какая база данных будет удалена, но не удаляйте ее. |
Общие параметры перечислены выше.
dotnet ef database update
Обновляет базу данных до последней миграции или указанной миграции.
Аргументы:
| Аргумент | Description |
|---|---|
<MIGRATION> |
Целевая миграция. Миграции могут быть определены по имени или по идентификатору. Число 0 — это особый случай, который означает перед первой миграцией и приводит к отмене всех миграций. Если миграция не указана, команда по умолчанию используется для последней миграции. |
Параметры:
| Вариант | Описание |
|---|---|
--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 запросами и предварительно компилируемыми запросами.
Дополнительные сведения см . в скомпилированных моделях .
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--output-dir <PATH> |
-o |
Каталог, в который нужно поместить файлы. Пути относительны к каталогу проекта. |
--namespace <NAMESPACE> |
-n |
Пространство имен, используемое для всех созданных классов. По умолчанию создается из корневого пространства имен и выходного каталога плюс CompiledModels. |
--suffix <SUFFIX> |
Суффикс для присоединения ко имени всех созданных файлов. Например .g , можно использовать для указания того, что эти файлы содержат созданный код |
|
--no-scaffold |
Не создавайте скомпилированную модель. Используется при создании скомпилированной модели. | |
--precompile-queries |
Создайте предварительно скомпилированные запросы. Это необходимо для компиляции NativeAOT, если целевой проект содержит любые запросы. | |
--nativeaot |
Создание дополнительного кода в скомпилированной модели, необходимой для компиляции NativeAOT и предварительно скомпилированных запросов |
Примечание.
Поддержка NativeAOT и предварительно скомпилированные запросы считаются экспериментальными в EF 9 и могут резко измениться в следующем выпуске.
Общие параметры перечислены выше.
В следующем примере используются параметры по умолчанию и работает, если в проекте есть только один DbContext :
dotnet ef dbcontext optimize
В следующем примере модель оптимизирована для контекста с указанным именем и помещает ее в отдельную папку и пространство имен:
dotnet ef dbcontext optimize -o Models -n BlogModels -c BlogContext
dotnet ef dbcontext scaffold
Создает код для DbContext типов сущностей для базы данных. Чтобы эта команда создавала тип сущности, таблица базы данных должна иметь первичный ключ.
Аргументы:
| Аргумент | Description |
|---|---|
<CONNECTION> |
Строка подключения к базе данных. Для проектов ASP.NET Core 2.x значение может быть name=<name of строка подключения>. В этом случае имя поступает из источников конфигурации, настроенных для проекта. |
<PROVIDER> |
Используемый поставщик. Обычно это имя пакета NuGet, например: Microsoft.EntityFrameworkCore.SqlServer |
Параметры:
| Вариант | Короткие | 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;User Id=myUsername;Password=myPassword;" Microsoft.EntityFrameworkCore.SqlServer --no-onconfiguring
dotnet ef dbcontext script
Создает скрипт SQL из DbContext. Обход любых миграций.
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--output <FILE> |
-o |
Файл для записи результата. |
Общие параметры перечислены выше.
dotnet ef migrations add
Добавляет новую миграцию.
Аргументы:
| Аргумент | Description |
|---|---|
<NAME> |
Имя миграции. |
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--output-dir <PATH> |
-o |
Каталог, используемый для вывода файлов. Пути относительно целевого каталога проекта. По умолчанию используется значение "Миграции". |
--namespace <NAMESPACE> |
-n |
Пространство имен, используемое для созданных классов. По умолчанию создается из выходного каталога. |
Общие параметры перечислены выше.
dotnet ef migrations bundle
Создает исполняемый файл для обновления базы данных.
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--output <FILE> |
-o |
Путь к создаваемому исполняемому файлу. |
--force |
-f |
Перезаписать существующие файлы. |
--self-contained |
Кроме того, пакет среды выполнения .NET, поэтому его не нужно устанавливать на компьютере. | |
--target-runtime <RUNTIME_IDENTIFIER> |
-r |
Целевая среда выполнения для упаковки. |
Общие параметры перечислены выше.
dotnet ef migrations has-pending-model-changes
Примечание.
Эта команда была добавлена в EF Core 8.0.
Проверяет, были ли изменения внесены в модель с момента последней миграции.
Параметры:
Общие параметры перечислены выше.
dotnet ef migrations list
Перечисляет доступные миграции.
Параметры:
| Вариант | Описание |
|---|---|
--connection <CONNECTION> |
Строка подключения к базе данных. Значение по умолчанию указано в AddDbContext или OnConfiguring. |
--no-connect |
Не подключайтесь к базе данных. |
Общие параметры перечислены выше.
dotnet ef migrations remove
Удаляет последнюю миграцию, откатив изменения кода, выполненные для последней миграции.
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--force |
-f |
Верните последнюю миграцию, откатив изменения кода и базы данных, выполненные для последней миграции. Продолжает откат только изменения кода при возникновении ошибки при подключении к базе данных. |
Общие параметры перечислены выше.
dotnet ef migrations script
Создает скрипт SQL из миграций.
Аргументы:
| Аргумент | Description |
|---|---|
<FROM> |
Начальная миграция. Миграции могут быть определены по имени или по идентификатору. Число 0 — это особый случай, который означает перед первой миграцией. Значение по умолчанию — 0. |
<TO> |
Окончание миграции. По умолчанию используется последняя миграция. |
Параметры:
| Вариант | Короткие | Description |
|---|---|---|
--output <FILE> |
-o |
Файл для записи скрипта. |
--idempotent |
-i |
Создайте скрипт, который можно использовать в базе данных при любой миграции. |
--no-transactions |
Не создавайте инструкции транзакций SQL. |
Общие параметры перечислены выше.
В следующем примере создается скрипт для миграции InitialCreate:
dotnet ef migrations script 0 InitialCreate
В следующем примере создается скрипт для всех миграций после миграции InitialCreate.
dotnet ef migrations script 20180904195021_InitialCreate
