Skip to content

Documents the OpenApiGenerationEnvironment MSBuild property #37589

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wadepickett merged 4 commits into from
Sep 4, 2026
Merged

Documents the OpenApiGenerationEnvironment MSBuild property #37589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9f12612
Document OpenApiGenerationEnvironment
snemeckayova Sep 4, 2026
9e1e6ef
Add .NET 11 moniker
snemeckayova Sep 4, 2026
9ccb26b
Rename openapi-generation-environment-preview-7.md to openapi-generat…
wadepickett Sep 4, 2026
d6c073c
Fix OpenAPI generation environment include reference
wadepickett Sep 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion aspnetcore/fundamentals/openapi/aspnetcore-openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -294,6 +294,26 @@ Some apps may be configured to emit multiple OpenAPI documents. Multiple OpenAPI
</PropertyGroup>
```

:::moniker-end

:::moniker range=">= aspnetcore-11.0"

#### Select the app environment
Comment thread
snemeckayova marked this conversation as resolved.

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
<PropertyGroup>
<OpenApiGenerationEnvironment>Development</OpenApiGenerationEnvironment>
</PropertyGroup>
```

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:
Expand Down
4 changes: 3 additions & 1 deletion aspnetcore/release-notes/aspnetcore-11.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.md)]

## Authentication and authorization

This section describes new features for authentication and authorization.
Expand Down
15 changes: 15 additions & 0 deletions aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment.md
View file
Open in desktop

@Youssef1313 Youssef1313 Sep 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wadepickett For other features, it looks like we are not consistent in file names whether we use the preview version number in file name or not. Do you have recommendation?

@wadepickett wadepickett Sep 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Youssef1313, You are right, it is not consistant, thanks for pointing out the issue. I don't see a reason for keeping the preview versions in the file name for the What's new include files. I think they just started that way long ago at some point and then were perpetuated. I think even the current AI agent related to this is includijng them, which I'll fix.

.
So this:
aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment-preview-7.md

Would become:
aspnetcore/release-notes/aspnetcore-11/includes/openapi-generation-environment.md

I will fix all of them in a new PR after this one.

@wadepickett wadepickett Sep 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went ahead and fixed the new file name here. I will correct the rest of them in a new PR.

Original file line number Diff line number Diff line change
@@ -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
<PropertyGroup>
<OpenApiGenerationEnvironment>Development</OpenApiGenerationEnvironment>
</PropertyGroup>
```

For more information, see <xref:fundamentals/openapi/aspnetcore-openapi#customize-build-time-document-generation>.

Thank you [@ldsenow](https://github.com/ldsenow) for this contribution!
Loading