From 9f126127ca083ab3ea73f8ba20171a20e825d523 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?So=C5=88a=20Neme=C4=8Dkayov=C3=A1?= <109719150+snemeckayova@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:06:22 +0200 Subject: [PATCH 1/4] Document OpenApiGenerationEnvironment --- .../fundamentals/openapi/aspnetcore-openapi.md | 14 +++++++++++++- aspnetcore/release-notes/aspnetcore-11.md | 4 +++- .../openapi-generation-environment-preview-7.md | 15 +++++++++++++++ 3 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 8af31a98ba3e..697068f939fb 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -5,7 +5,7 @@ author: wadepickett description: Learn how to generate and customize OpenAPI documents in an ASP.NET Core app. monikerRange: '>= aspnetcore-6.0' ms.author: wpickett -ms.date: 08/19/2026 +ms.date: 09/04/2026 uid: fundamentals/openapi/aspnetcore-openapi --- # Generate OpenAPI documents @@ -294,6 +294,18 @@ Some apps may be configured to emit multiple OpenAPI documents. Multiple OpenAPI ``` +#### Select the app environment + +Starting in .NET 11, set the `OpenApiGenerationEnvironment` property to select the app environment used during build-time OpenAPI document generation. The property sets the host's environment for the generation process, equivalent to setting the `ASPNETCORE_ENVIRONMENT` or `DOTNET_ENVIRONMENT` environment variable: + +```xml + + Development + +``` + +Selecting the environment enables environment-specific configuration, such as settings from `appsettings.Development.json`, and environment-dependent document transformations to affect the generated document. The property doesn't change the environment used when the app runs normally. + ### Customize runtime behavior during build-time document generation Build-time OpenAPI document generation functions by launching the apps entrypoint with a mock server implementation. A mock server is required to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the apps entrypoint is invoked, any logic in the apps startup is invoked. This includes code that injects services into the [DI container](xref:fundamentals/dependency-injection) or reads from configuration. In some scenarios, it's necessary to restrict the code paths when the app's entry point is invoked from build-time document generation. These scenarios include: diff --git a/aspnetcore/release-notes/aspnetcore-11.md b/aspnetcore/release-notes/aspnetcore-11.md index 296d16e72b04..2d74bee91e08 100644 --- a/aspnetcore/release-notes/aspnetcore-11.md +++ b/aspnetcore/release-notes/aspnetcore-11.md @@ -4,7 +4,7 @@ ai-usage: ai-assisted author: wadepickett description: Learn about the new features in ASP.NET Core in .NET 11. ms.author: wpickett -ms.date: 08/26/2026 +ms.date: 09/04/2026 uid: aspnetcore-11 --- # What's new in ASP.NET Core in .NET 11 @@ -69,6 +69,8 @@ This section describes new features for OpenAPI. [!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-server-sent-events-preview-7.md)] +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md)] + ## Authentication and authorization This section describes new features for authentication and authorization. diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md new file mode 100644 index 000000000000..c6b963e9f239 --- /dev/null +++ b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md @@ -0,0 +1,15 @@ +### Select an environment for build-time OpenAPI document generation + +Build-time OpenAPI document generation supports selecting the app environment with the `OpenApiGenerationEnvironment` MSBuild property. The property sets the host's environment for the generation process, equivalent to setting the `ASPNETCORE_ENVIRONMENT` or `DOTNET_ENVIRONMENT` environment variable. Environment-specific configuration and document transformations can therefore affect the generated OpenAPI document without requiring the environment variable to be set before running `dotnet build`. + +Set the property in the project file: + +```xml + + Development + +``` + +For more information, see . + +Thank you [@ldsenow](https://github.com/ldsenow) for this contribution! \ No newline at end of file From 9e1e6efc4655dce1c7b9850973e0400cd870429a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?So=C5=88a=20Neme=C4=8Dkayov=C3=A1?= <109719150+snemeckayova@users.noreply.github.com> Date: Fri, 4 Sep 2026 18:17:34 +0200 Subject: [PATCH 2/4] Add .NET 11 moniker --- aspnetcore/fundamentals/openapi/aspnetcore-openapi.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 697068f939fb..7ca47477dc29 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -294,6 +294,10 @@ Some apps may be configured to emit multiple OpenAPI documents. Multiple OpenAPI ``` +:::moniker-end + +:::moniker range=">= aspnetcore-11.0" + #### Select the app environment Starting in .NET 11, set the `OpenApiGenerationEnvironment` property to select the app environment used during build-time OpenAPI document generation. The property sets the host's environment for the generation process, equivalent to setting the `ASPNETCORE_ENVIRONMENT` or `DOTNET_ENVIRONMENT` environment variable: @@ -306,6 +310,10 @@ Starting in .NET 11, set the `OpenApiGenerationEnvironment` property to select t Selecting the environment enables environment-specific configuration, such as settings from `appsettings.Development.json`, and environment-dependent document transformations to affect the generated document. The property doesn't change the environment used when the app runs normally. +:::moniker-end + +:::moniker range=">= aspnetcore-10.0" + ### Customize runtime behavior during build-time document generation Build-time OpenAPI document generation functions by launching the apps entrypoint with a mock server implementation. A mock server is required to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the apps entrypoint is invoked, any logic in the apps startup is invoked. This includes code that injects services into the [DI container](xref:fundamentals/dependency-injection) or reads from configuration. In some scenarios, it's necessary to restrict the code paths when the app's entry point is invoked from build-time document generation. These scenarios include: From 9ccb26b5156bded45157b6a354b8b161d08947e1 Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 4 Sep 2026 15:39:13 -0700 Subject: [PATCH 3/4] Rename openapi-generation-environment-preview-7.md to openapi-generation-environment.md --- ...vironment-preview-7.md => openapi-generation-environment.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename aspnetcore/release-notes/aspnetcore-11/includes/{openapi-generation-environment-preview-7.md => openapi-generation-environment.md} (99%) diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment.md similarity index 99% rename from aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md rename to aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment.md index c6b963e9f239..bc547a03d938 100644 --- a/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md +++ b/aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment.md @@ -12,4 +12,4 @@ Set the property in the project file: For more information, see . -Thank you [@ldsenow](https://github.com/ldsenow) for this contribution! \ No newline at end of file +Thank you [@ldsenow](https://github.com/ldsenow) for this contribution! From d6c073cba7cdb74f54fb5f9ac35c833fdeeee28e Mon Sep 17 00:00:00 2001 From: Wade Pickett Date: Fri, 4 Sep 2026 15:43:11 -0700 Subject: [PATCH 4/4] Fix OpenAPI generation environment include reference Updated OpenAPI generation environment include file reference. --- aspnetcore/release-notes/aspnetcore-11.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/release-notes/aspnetcore-11.md b/aspnetcore/release-notes/aspnetcore-11.md index 2d74bee91e08..6049a9b3b4c1 100644 --- a/aspnetcore/release-notes/aspnetcore-11.md +++ b/aspnetcore/release-notes/aspnetcore-11.md @@ -69,7 +69,7 @@ This section describes new features for OpenAPI. [!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-server-sent-events-preview-7.md)] -[!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md)] +[!INCLUDE[](~/release-notes/aspnetcore-11/includes/openapi-generation-environment.md)] ## Authentication and authorization