EF Core Add Migration

Adding a migration in EF Core is the process of capturing model changes since the last migration and generating migration files from those changes. To create those migration files, an Add Migration command must be run. This command compares the current context with the last migration created (if there was one) to detect what has changed in the model.

There are 2 ways to run the Add Migration command and both will be covered in this article:

  • Add-Migration: When using the Package Manager Console (PMC)
  • dotnet ef migrations add: When using the .NET Command Line Interface (.NET CLI)
EF Core Add Migration

The Add Migration command is one of the 3 main migration commands:

How to use the Add Migration command with PMC in EF Core?

To use the Add-Migration command with the Package Manager Console (PMC) in EF Core:

  1. First, open the Package Manager Console in Visual Studio.
  2. Ensure the default project in the console is the one containing your EF Core DbContext.
  3. Enter the following command:
|
Add-Migration [MigrationName]

NOTE: Replace [MigrationName] by the name you want to give to your migration.

See Package Manager Console Parameters for additional parameters options.

Add Migration - PMC Example

How to use the Add Migration command with .NET CLI in EF Core?

To use the dotnet ef migrations add command with the .NET Command Line Interface (.NET CLI) in EF Core:

  1. Open a command prompt or terminal.
  2. Navigate to the directory containing your context.
  3. Run the following command:
|
dotnet ef migrations add [MigrationName]

NOTE: Replace [MigrationName] by the name you want to give to your migration.

See Command Line Parameters for additional parameters options.

Add Migration - CLI Example

What does the Add-Migration command do in EF Core?

When you use the Add-Migration command with PMC or dotnet ef migrations add with .NET CLI, both utilize EF Core Tools to perform several tasks:

  1. First, EF Core Tools look at your DbContext and Model.
  2. Then, EF Core Tools compare the current context against the one from the Model Snapshot (if there is one) to find any changes.
  3. Based on this comparison, new migration files are generated. These files contain the necessary code to apply and revert those changes in the database.
  4. After creating a new migration, you can apply it to your database with the Update-Database command or remove it using the Remove-Migration command.
Add Migration Tasks

What are the parameters for the Add Migration command in EF Core?

Package Manager Console (PMC)

The Add-Migration command with PMC offers several options. While specifying the migration name is mandatory (the console will ask for one if not specified), all other options are optional:

Option Description
-Name The name of the migration you want to create. While the -Name parameter is there, it's often simpler to directly specify the migration name as the first parameter. For example, Add-Migration AddingEFExtensions will create a migration named AddingEFExtensions.
-OutputDir The output directory relative to the project where migration files will be created. For example, Add-Migration AddingEFExtensions -OutputDir MyMigrationDirectoryName will create the migration file in the MyMigrationDirectoryName directory.
-Namespace The namespace to use for the generated classes in the migration file. If omitted, the following namespace [ProjectNamespace].[OutputDirectoryName] will be used. For example, Add-Migration AddingEFExtensions -Namespace Z.MyMigrationNamespace will add classes in the Z.MyMigrationNamespace namespace.
-Context The context class to use to generate the migration file, it can be either the name or the fullname including namespaces. For example, Add-Migration AddingEFExtensions -Context Z.MyContextName will generate a migration for the Z.MyContextName context.
-Project The project containing the context used to generate the migration file. If omitted, the default project in the Package Manager Console is used. For example, Add-Migration AddingEFExtensions -Project Z.MyProjectName will generate a migration for the context in the Z.MyProjectName project.
-StartupProject The project with the configurations and settings. If omitted, the startup project of your solution is used. For example, Add-Migration AddingEFExtensions -StartupProject Z.MyStartupProjectName will make a migration using the configurations and settings of the Z.MyStartupProjectName project.
language-csharp
|
Add-Migration [MigrationName] -OutputDir MyMigrationDirectoryName -Namespace Z.MyMigrationNamespace -Context Z.MyContextName -Project Z.MyProjectName -StartupProject Z.MyStartupProjectName

Tips:

  • DO NOT use -Name. Directly specify the name as the first parameter of the Add-Migration command.
  • DO NOT use -OutputDir after the first migration. EF Core Tools can automatically locate the output directory for later migrations.
  • DO NOT use -Project. Instead, select the default project in the console (personal preference).

NOTE: The -Project option specifies which project contains the context, while the -StartupProject option indicates the project that has the application's configurations and settings.

.NET Command Line Interface (.NET CLI)

For those who work outside of Visual Studio or prefer the command line, EF Core Tools provide similar features for .NET CLI but with a bit different syntax:

Option Short Description
[MigrationName] The name of your migration. It's placed directly after the add command in dotnet ef migrations add [MigrationName].
--output-dir -o The output folder related to the project.
--namespace -n The namespace for the created classes in the migration file.
--context -c The context class used to create the migration file.
--project -p The project that has the context for making the migration file.
--startup-project -s The project with the configurations and settings.
language-csharp
|
dotnet ef migrations add AddingEFExtensions -o MyMigrationDirectoryName -n Z.MyMigrationNamespace -c Z.MyContextName -p Z.MyProjectName -s Z.MyStartupProjectName

NOTE: Check the documentation above about Package Manager Console Parameters for more examples and tips.

Troubleshooting

How to fix in EF Core: The term 'Add-Migration' is not recognized as the name of a cmdlet, function, script file, or operable program.
Exception Message:
PM> Add-Migration AddingEFExtensions
Add-Migration : The term 'Add-Migration' is not recognized as the name of a cmdlet, 
function, script file, or operable program. Check the spelling of the name, or if a path 
was included, verify that the path is correct and try again.
At line:1 char:1
+ Add-Migration AddingEFExtensions
+ ~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Add-Migration:String) [], CommandNotFoundExc 
   eption
    + FullyQualifiedErrorId : CommandNotFoundException
 
Exception - The term Add Migration is not recognized
Cause:

This error arises when the Microsoft.EntityFrameworkCore.Tools package is not referenced in your Migrations Project.

Solution:

Make sure you have installed or referenced the Microsoft.EntityFrameworkCore.Tools package in your Migrations Project.

You can add this package via the NuGet Package Manager with:

Install-Package Microsoft.EntityFrameworkCore.Tools

Or through the .NET CLI with:

dotnet add package Microsoft.EntityFrameworkCore.Tools

How to fix in EF Core: Your startup project '[StartupProjectName]' doesn't reference Microsoft.EntityFrameworkCore.Design. This package is required for the Entity Framework Core Tools to work. Ensure your startup project is correct, install the package, and try again.
Exception Message:
PM> Add-Migration AddingEFExtensions
Build started...
Build succeeded.
Your startup project 'Z.MyStartupProjectName' doesn't reference Microsoft.EntityFrameworkCore.Design. This package is required for the Entity Framework Core Tools to work. Ensure your startup project is correct, install the package, and try again.
Exception - Startup project not reference Microsoft.EntityFrameworkCore.Design
Cause:

This error arises when the Microsoft.EntityFrameworkCore.Design package is not referenced in your Startup Project.

Solution:

Make sure you have installed or referenced the Microsoft.EntityFrameworkCore.Design package in your Startup Project.

You can add this package via the NuGet Package Manager with:

Install-Package Microsoft.EntityFrameworkCore.Design

Or through the .NET CLI with:

dotnet add package Microsoft.EntityFrameworkCore.Design

How to fix in EF Core: dotnet command not found - Could not execute because the specified command or file was not found.
Exception Message:
dotnet ef migrations add [MigrationName]
Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET program, but dotnet-ef does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.
Exception - dotnet command not found
Cause:

This error arises when the dotnet-ef tool is not installed globally or locally when using .NET Command Line Interface (.NET CLI).

Solution:

Install the dotnet-ef tool:

// for the latest version:
dotnet tool install --global dotnet-ef

// for a specific version:
dotnet tool install --global dotnet-ef --version 8.*
dotnet tool install --global dotnet-ef --version 7.*
dotnet tool install --global dotnet-ef --version 6.*
dotnet tool install --global dotnet-ef --version 5.*
dotnet tool install --global dotnet-ef --version 3.*


Date Modified: 2023-09-19
Author:

Edit this page in GitHub

Got any EF Core Question?