From 57e8e8ab38e88c106333bb9edf5d95aa84471ba5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 22 Apr 2026 00:10:31 +0000 Subject: [PATCH 1/4] docs: add documentation for dotnet-ef JSON config defaults (PR #37966) Agent-Logs-Url: https://github.com/dotnet/EntityFramework.Docs/sessions/8f68a2f3-a94e-47c0-b349-f836985bd186 Co-authored-by: AndriySvyryd <6539701+AndriySvyryd@users.noreply.github.com> --- entity-framework/core/cli/dotnet.md | 81 ++++++++++++++++++- .../core/what-is-new/ef-core-11.0/whatsnew.md | 28 ++++++- 2 files changed, 107 insertions(+), 2 deletions(-) diff --git a/entity-framework/core/cli/dotnet.md b/entity-framework/core/cli/dotnet.md index 4d28cf8cb0..9265879227 100644 --- a/entity-framework/core/cli/dotnet.md +++ b/entity-framework/core/cli/dotnet.md @@ -2,7 +2,7 @@ title: EF Core tools reference (.NET CLI) - EF Core description: Reference guide for the Entity Framework Core .NET CLI tools author: SamMonoRT -ms.date: 11/08/2024 +ms.date: 04/22/2026 uid: core/cli/dotnet --- @@ -124,6 +124,85 @@ dotnet ef database update -- --environment Production Any additional arguments are passed to the application. +## Configuration file + +> [!NOTE] +> This feature was introduced in EF Core 11. + +Starting with EF Core 11, `dotnet ef` can load default option values from a JSON configuration file. This reduces the need to repeat the same command-line options across multiple invocations. + +### File location and discovery + +Place a file named `dotnet-ef.json` inside a `.config` directory: + +```text +/ +└── .config/ + └── dotnet-ef.json +``` + +When `dotnet ef` runs, it walks up the directory tree from the current working directory and uses the first `.config/dotnet-ef.json` file it finds. This means you can place the file at the root of your repository and it will be used from any subdirectory. + +### Supported properties + +The configuration file is a JSON object with the following optional properties: + +```json +{ + "project": "src/App.Infrastructure", + "startupProject": "src/App.Api", + "framework": "net11.0", + "configuration": "Debug", + "context": "AppDbContext", + "runtime": "win-x64", + "verbose": true, + "noColor": false, + "prefixOutput": false +} +``` + +| Property | Type | Description | +|:-----------------|:--------|:--------------------------------------------------------------------------------------------------------------------------------------------| +| `project` | string | Relative path to the target project folder. Resolved relative to the parent of the `.config` directory containing the file. | +| `startupProject` | string | Relative path to the startup project folder. Resolved relative to the parent of the `.config` directory containing the file. | +| `framework` | string | The [Target Framework Moniker](/dotnet/standard/frameworks#supported-target-framework-versions) for the target framework. | +| `configuration` | string | The build configuration, for example: `Debug` or `Release`. | +| `context` | string | The `DbContext` class to use. Class name only or fully qualified with namespaces. | +| `runtime` | string | The identifier of the target runtime to restore packages for. For a list of Runtime Identifiers (RIDs), see the [RID catalog](/dotnet/core/rid-catalog). | +| `verbose` | boolean | Enable verbose output. | +| `noColor` | boolean | Disable colored console output. | +| `prefixOutput` | boolean | Prefix output lines with their severity level. | + +All properties are optional. Only include the properties you need. + +### CLI precedence + +Explicit command-line options always take precedence over values from the configuration file. For example, if the config file specifies `"project": "src/App.Infrastructure"` but you run: + +```dotnetcli +dotnet ef migrations add Initial --project src/OtherProject +``` + +The `--project` value from the command line (`src/OtherProject`) is used. + +### Path resolution + +The `project` and `startupProject` paths in the configuration file are resolved relative to the parent directory of the `.config` folder containing the file, not relative to the current working directory. For example, given the following structure: + +```text +my-repo/ +├── .config/ +│ └── dotnet-ef.json ← contains "project": "src/App.Infrastructure" +└── src/ + └── App.Infrastructure/ +``` + +The `project` path resolves to `my-repo/src/App.Infrastructure` regardless of where you run `dotnet ef` from within `my-repo`. Absolute paths are also supported. + +### Context injection + +The `context` value from the configuration file is only applied to commands that accept a `--context` option (such as `database update`, `dbcontext optimize`, `migrations add`, and others). If you specify `--context` or `-c` on the command line, the config value is ignored. + ## `dotnet ef database drop` Deletes the database. diff --git a/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md b/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md index d445b2a51f..78900f1671 100644 --- a/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md +++ b/entity-framework/core/what-is-new/ef-core-11.0/whatsnew.md @@ -2,7 +2,7 @@ title: What's New in EF Core 11 description: Overview of new features in EF Core 11 author: roji -ms.date: 02/02/2026 +ms.date: 04/22/2026 uid: core/what-is-new/ef-core-11.0/whatsnew --- @@ -631,6 +631,32 @@ Remove-Migration -Offline Drop-Database -Connection "Server=test;Database=MyDb;..." -Force ``` + + +### Configuration file for dotnet ef + +The `dotnet ef` command-line tool now supports loading default option values from a `.config/dotnet-ef.json` configuration file. This eliminates the need to repeatedly specify the same options — such as `--project` and `--startup-project` — across every command invocation. + +When you run `dotnet ef`, the tool searches for a `.config/dotnet-ef.json` file by walking up the directory tree from the current working directory. The first file found is used. Here's an example configuration file: + +```json +{ + "project": "src/App.Infrastructure", + "startupProject": "src/App.Api", + "framework": "net11.0", + "configuration": "Debug", + "context": "AppDbContext", + "runtime": "win-x64", + "verbose": true, + "noColor": false, + "prefixOutput": false +} +``` + +Explicit command-line options always take precedence over configuration file values. Path values for `project` and `startupProject` are resolved relative to the parent of the `.config` directory containing the file. + +For more information, see [Configuration file](xref:core/cli/dotnet#configuration-file). + ## Other improvements * The EF command-line tool now writes all logging and status messages to standard error, reserving standard output only for the command's actual expected output. For example, when generating a migration SQL script with `dotnet ef migrations script`, only the SQL is written to standard output. From c4d11965dce502858684f7534524b905dad02cbc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 22 Apr 2026 00:26:35 +0000 Subject: [PATCH 2/4] docs: move Configuration file section to end of dotnet.md, remove Context injection subsection Agent-Logs-Url: https://github.com/dotnet/EntityFramework.Docs/sessions/f80a26f0-8793-4f7e-af07-35e6bf53e308 Co-authored-by: AndriySvyryd <6539701+AndriySvyryd@users.noreply.github.com> --- entity-framework/core/cli/dotnet.md | 154 ++++++++++++++-------------- 1 file changed, 75 insertions(+), 79 deletions(-) diff --git a/entity-framework/core/cli/dotnet.md b/entity-framework/core/cli/dotnet.md index 9265879227..9c0ccb9af7 100644 --- a/entity-framework/core/cli/dotnet.md +++ b/entity-framework/core/cli/dotnet.md @@ -124,85 +124,6 @@ dotnet ef database update -- --environment Production Any additional arguments are passed to the application. -## Configuration file - -> [!NOTE] -> This feature was introduced in EF Core 11. - -Starting with EF Core 11, `dotnet ef` can load default option values from a JSON configuration file. This reduces the need to repeat the same command-line options across multiple invocations. - -### File location and discovery - -Place a file named `dotnet-ef.json` inside a `.config` directory: - -```text -/ -└── .config/ - └── dotnet-ef.json -``` - -When `dotnet ef` runs, it walks up the directory tree from the current working directory and uses the first `.config/dotnet-ef.json` file it finds. This means you can place the file at the root of your repository and it will be used from any subdirectory. - -### Supported properties - -The configuration file is a JSON object with the following optional properties: - -```json -{ - "project": "src/App.Infrastructure", - "startupProject": "src/App.Api", - "framework": "net11.0", - "configuration": "Debug", - "context": "AppDbContext", - "runtime": "win-x64", - "verbose": true, - "noColor": false, - "prefixOutput": false -} -``` - -| Property | Type | Description | -|:-----------------|:--------|:--------------------------------------------------------------------------------------------------------------------------------------------| -| `project` | string | Relative path to the target project folder. Resolved relative to the parent of the `.config` directory containing the file. | -| `startupProject` | string | Relative path to the startup project folder. Resolved relative to the parent of the `.config` directory containing the file. | -| `framework` | string | The [Target Framework Moniker](/dotnet/standard/frameworks#supported-target-framework-versions) for the target framework. | -| `configuration` | string | The build configuration, for example: `Debug` or `Release`. | -| `context` | string | The `DbContext` class to use. Class name only or fully qualified with namespaces. | -| `runtime` | string | The identifier of the target runtime to restore packages for. For a list of Runtime Identifiers (RIDs), see the [RID catalog](/dotnet/core/rid-catalog). | -| `verbose` | boolean | Enable verbose output. | -| `noColor` | boolean | Disable colored console output. | -| `prefixOutput` | boolean | Prefix output lines with their severity level. | - -All properties are optional. Only include the properties you need. - -### CLI precedence - -Explicit command-line options always take precedence over values from the configuration file. For example, if the config file specifies `"project": "src/App.Infrastructure"` but you run: - -```dotnetcli -dotnet ef migrations add Initial --project src/OtherProject -``` - -The `--project` value from the command line (`src/OtherProject`) is used. - -### Path resolution - -The `project` and `startupProject` paths in the configuration file are resolved relative to the parent directory of the `.config` folder containing the file, not relative to the current working directory. For example, given the following structure: - -```text -my-repo/ -├── .config/ -│ └── dotnet-ef.json ← contains "project": "src/App.Infrastructure" -└── src/ - └── App.Infrastructure/ -``` - -The `project` path resolves to `my-repo/src/App.Infrastructure` regardless of where you run `dotnet ef` from within `my-repo`. Absolute paths are also supported. - -### Context injection - -The `context` value from the configuration file is only applied to commands that accept a `--context` option (such as `database update`, `dbcontext optimize`, `migrations add`, and others). If you specify `--context` or `-c` on the command line, the config value is ignored. - ## `dotnet ef database drop` Deletes the database. @@ -470,3 +391,78 @@ dotnet ef migrations script 20180904195021_InitialCreate * [Migrations](xref:core/managing-schemas/migrations/index) * [Reverse Engineering](xref:core/managing-schemas/scaffolding) * [Compiled models](xref:core/performance/advanced-performance-topics#compiled-models) + +## Configuration file + +> [!NOTE] +> This feature was introduced in EF Core 11. + +Starting with EF Core 11, `dotnet ef` can load default option values from a JSON configuration file. This reduces the need to repeat the same command-line options across multiple invocations. + +### File location and discovery + +Place a file named `dotnet-ef.json` inside a `.config` directory: + +```text +/ +└── .config/ + └── dotnet-ef.json +``` + +When `dotnet ef` runs, it walks up the directory tree from the current working directory and uses the first `.config/dotnet-ef.json` file it finds. This means you can place the file at the root of your repository and it will be used from any subdirectory. + +### Supported properties + +The configuration file is a JSON object with the following optional properties: + +```json +{ + "project": "src/App.Infrastructure", + "startupProject": "src/App.Api", + "framework": "net11.0", + "configuration": "Debug", + "context": "AppDbContext", + "runtime": "win-x64", + "verbose": true, + "noColor": false, + "prefixOutput": false +} +``` + +| Property | Type | Description | +|:-----------------|:--------|:--------------------------------------------------------------------------------------------------------------------------------------------| +| `project` | string | Relative path to the target project folder. Resolved relative to the parent of the `.config` directory containing the file. | +| `startupProject` | string | Relative path to the startup project folder. Resolved relative to the parent of the `.config` directory containing the file. | +| `framework` | string | The [Target Framework Moniker](/dotnet/standard/frameworks#supported-target-framework-versions) for the target framework. | +| `configuration` | string | The build configuration, for example: `Debug` or `Release`. | +| `context` | string | The `DbContext` class to use. Class name only or fully qualified with namespaces. | +| `runtime` | string | The identifier of the target runtime to restore packages for. For a list of Runtime Identifiers (RIDs), see the [RID catalog](/dotnet/core/rid-catalog). | +| `verbose` | boolean | Enable verbose output. | +| `noColor` | boolean | Disable colored console output. | +| `prefixOutput` | boolean | Prefix output lines with their severity level. | + +All properties are optional. Only include the properties you need. + +### CLI precedence + +Explicit command-line options always take precedence over values from the configuration file. For example, if the config file specifies `"project": "src/App.Infrastructure"` but you run: + +```dotnetcli +dotnet ef migrations add Initial --project src/OtherProject +``` + +The `--project` value from the command line (`src/OtherProject`) is used. + +### Path resolution + +The `project` and `startupProject` paths in the configuration file are resolved relative to the parent directory of the `.config` folder containing the file, not relative to the current working directory. For example, given the following structure: + +```text +my-repo/ +├── .config/ +│ └── dotnet-ef.json ← contains "project": "src/App.Infrastructure" +└── src/ + └── App.Infrastructure/ +``` + +The `project` path resolves to `my-repo/src/App.Infrastructure` regardless of where you run `dotnet ef` from within `my-repo`. Absolute paths are also supported. From 7e768ef721ff417990278f4123e462adb723f9d8 Mon Sep 17 00:00:00 2001 From: Andriy Svyryd Date: Tue, 21 Apr 2026 17:36:44 -0700 Subject: [PATCH 3/4] Update entity-framework/core/cli/dotnet.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- entity-framework/core/cli/dotnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/entity-framework/core/cli/dotnet.md b/entity-framework/core/cli/dotnet.md index 9c0ccb9af7..7b9c62fe6d 100644 --- a/entity-framework/core/cli/dotnet.md +++ b/entity-framework/core/cli/dotnet.md @@ -431,8 +431,8 @@ The configuration file is a JSON object with the following optional properties: | Property | Type | Description | |:-----------------|:--------|:--------------------------------------------------------------------------------------------------------------------------------------------| -| `project` | string | Relative path to the target project folder. Resolved relative to the parent of the `.config` directory containing the file. | -| `startupProject` | string | Relative path to the startup project folder. Resolved relative to the parent of the `.config` directory containing the file. | +| `project` | string | Relative or absolute path to the target project folder. Relative paths are resolved relative to the parent of the `.config` directory containing the file. | +| `startupProject` | string | Relative or absolute path to the startup project folder. Relative paths are resolved relative to the parent of the `.config` directory containing the file. | | `framework` | string | The [Target Framework Moniker](/dotnet/standard/frameworks#supported-target-framework-versions) for the target framework. | | `configuration` | string | The build configuration, for example: `Debug` or `Release`. | | `context` | string | The `DbContext` class to use. Class name only or fully qualified with namespaces. | From 16fc77599ea063eb0c5cd3f41e84ee7f21423d30 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 22 Apr 2026 00:38:04 +0000 Subject: [PATCH 4/4] docs: address review feedback on Configuration file section Agent-Logs-Url: https://github.com/dotnet/EntityFramework.Docs/sessions/d36134ff-5de1-42cc-9b3a-04db0118a4a5 Co-authored-by: AndriySvyryd <6539701+AndriySvyryd@users.noreply.github.com> --- entity-framework/core/cli/dotnet.md | 33 ++++++----------------------- 1 file changed, 6 insertions(+), 27 deletions(-) diff --git a/entity-framework/core/cli/dotnet.md b/entity-framework/core/cli/dotnet.md index 7b9c62fe6d..1f0e66d35c 100644 --- a/entity-framework/core/cli/dotnet.md +++ b/entity-framework/core/cli/dotnet.md @@ -386,12 +386,6 @@ The following example creates a script for all migrations after the InitialCreat dotnet ef migrations script 20180904195021_InitialCreate ``` -## Additional resources - -* [Migrations](xref:core/managing-schemas/migrations/index) -* [Reverse Engineering](xref:core/managing-schemas/scaffolding) -* [Compiled models](xref:core/performance/advanced-performance-topics#compiled-models) - ## Configuration file > [!NOTE] @@ -443,26 +437,11 @@ The configuration file is a JSON object with the following optional properties: All properties are optional. Only include the properties you need. -### CLI precedence - -Explicit command-line options always take precedence over values from the configuration file. For example, if the config file specifies `"project": "src/App.Infrastructure"` but you run: - -```dotnetcli -dotnet ef migrations add Initial --project src/OtherProject -``` - -The `--project` value from the command line (`src/OtherProject`) is used. - -### Path resolution - -The `project` and `startupProject` paths in the configuration file are resolved relative to the parent directory of the `.config` folder containing the file, not relative to the current working directory. For example, given the following structure: +> [!NOTE] +> Explicit command-line options always take precedence over values from the configuration file. -```text -my-repo/ -├── .config/ -│ └── dotnet-ef.json ← contains "project": "src/App.Infrastructure" -└── src/ - └── App.Infrastructure/ -``` +## Additional resources -The `project` path resolves to `my-repo/src/App.Infrastructure` regardless of where you run `dotnet ef` from within `my-repo`. Absolute paths are also supported. +* [Migrations](xref:core/managing-schemas/migrations/index) +* [Reverse Engineering](xref:core/managing-schemas/scaffolding) +* [Compiled models](xref:core/performance/advanced-performance-topics#compiled-models)