diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 03e5deff8af9..92ddd1d4859e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -82,6 +82,9 @@ When working on an issue: - [ ] Number ordered lists as "1." for every item (don't use sequential numbers) - [ ] Use backticks around content specifically for file names (`file.txt`), folders (`folder`), file paths (`folder/file.txt`), custom types (`myVariable`, `MyClass`), raw URLs in the text (`https://www.contoso.com`), URL segments (`/product/id/199`), file extensions (`.razor`), NuGet packages (`Microsoft.AspNetCore.SignalR.Client`), and code that should never be localized - [ ] For Blazor's Razor components mentioned in article text, use backticks around the name of the component (example: `Counter` component) + - [ ] Use placeholders with braces in the format `{PLACEHOLDER NAME}` when used in URIs, code examples, and other contexts where placeholders are used. Use uppercase letters with spaces between words for the placeholder name inside the braces. + - [ ] Wrong: "Launch the app and navigate to `https://localhost:/openapi/v1.json` to view the generated OpenAPI document." + - [ ] Correct: "Launch the app and navigate to `https://localhost:{PORT}/openapi/v1.json` to view the generated OpenAPI document, where the `{PORT}` placeholder is the port." - [ ] For any new or updated .md file, ensure the standard frontmatter (metadata) is included as specified in [Metadata for Microsoft Learn documentation.](https://learn.microsoft.com/en-us/contribute/content/metadata) - [ ] For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included: - [ ] Metadata `ai-usage: ai-assisted` if any AI assistance was used diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 28a209340548..81932a990742 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -1,11 +1,11 @@ --- title: Generate OpenAPI documents author: captainsafia -description: Learn how to generate and customize OpenAPI documents in an ASP.NET Core app +description: Learn how to generate and customize OpenAPI documents in an ASP.NET Core app. ms.author: safia monikerRange: '>= aspnetcore-6.0' ms.custom: mvc -ms.date: 09/22/2025 +ms.date: 09/23/2025 uid: fundamentals/openapi/aspnetcore-openapi --- # Generate OpenAPI documents @@ -14,23 +14,20 @@ uid: fundamentals/openapi/aspnetcore-openapi The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) package provides built-in support for OpenAPI document generation in ASP.NET Core. The package provides the following features: -* Support for generating [OpenAPI version 3.1] documents. -* Support for [JSON Schema draft 2020-12]. +* Support for generating [OpenAPI version 3.1](https://spec.openapis.org/oas/v3.1.1.html) documents. +* Support for [JSON Schema draft 2020-12](https://json-schema.org/specification-links#2020-12). * Support for generating OpenAPI documents at run time and accessing them via an endpoint on the app. * Support for "transformer" APIs that allow modifying the generated document. * Support for generating multiple OpenAPI documents from a single app. -* Takes advantage of JSON schema support provided by [`System.Text.Json`](/dotnet/api/system.text.json). -* Is compatible with native AoT. +* Takes advantage of JSON schema support provided by . +* Compatible with native AoT. -[OpenAPI version 3.1]: https://spec.openapis.org/oas/v3.1.1.html -[JSON Schema draft 2020-12]: https://json-schema.org/specification-links#2020-12 - -The default OpenAPI version for generated documents is`3.1`. The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi): +The default OpenAPI version for generated documents is 3.1. The version can be changed by explicitly setting the property of the in the `configureOptions` delegate parameter of : ```csharp builder.Services.AddOpenApi(options => { - // Specify the OpenAPI version to use. + // Specify the OpenAPI version to use options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0; }); ``` @@ -38,29 +35,32 @@ builder.Services.AddOpenApi(options => When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item. ```xml - - --openapi-version OpenApi3_1 + + + --openapi-version OpenApi3_1 + ``` ## Package installation -Install the `Microsoft.AspNetCore.OpenApi` package: +Install the [`Microsoft.AspNetCore.OpenApi` package](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi): -### [Visual Studio](#tab/visual-studio) +# [Visual Studio](#tab/visual-studio) Run the following command from the **Package Manager Console**: - ```powershell - Install-Package Microsoft.AspNetCore.OpenApi +```powershell +Install-Package Microsoft.AspNetCore.OpenApi ``` -### [.NET CLI](#tab/net-cli) +# [.NET CLI](#tab/net-cli) -Run the following command: +Run the following command in a command shell opened to the directory that contains the app's project file: ```dotnetcli dotnet add package Microsoft.AspNetCore.OpenApi ``` + --- ## Configure OpenAPI document generation @@ -72,7 +72,7 @@ The following code: [!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_first&highlight=3,9)] -Launch the app and navigate to `https://localhost:/openapi/v1.json` to view the generated OpenAPI document. +Launch the app and navigate to `https://localhost:{port}/openapi/v1.json` to view the generated OpenAPI document, where the `{port}` placeholder is the port. ## Options to Customize OpenAPI document generation @@ -80,23 +80,23 @@ The following sections demonstrate how to customize OpenAPI document generation. ### Generate OpenAPI document in YAML format -The OpenAPI document can be generated in either JSON or YAML format. By default, the OpenAPI document is generated in JSON format. To generate the OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example: +The OpenAPI document can be generated in either JSON or YAML format. By default, the OpenAPI document is generated in JSON format. To generate the OpenAPI document in YAML format, specify the endpoint in the call with a "`.yaml`" or "`.yml`" suffix, as shown in the following example, where the `{documentName}` placeholder is the document name: ```csharp app.MapOpenApi("/openapi/{documentName}.yaml"); ``` -Generating OpenAPI documents in YAML format at build time is currently not supported, but planned in a future preview. +Generating OpenAPI documents in YAML format at build time isn't supported but planned for a future preview. ### Customize the OpenAPI document name -Each OpenAPI document in an app has a unique name. The default document name that is registered is `v1`. +Each OpenAPI document in an app has a unique name. The default document name that is registered is `v1`: ```csharp builder.Services.AddOpenApi(); // Document name is v1 ``` -The document name can be modified by passing the name as a parameter to the call. +The document name can be modified by passing the name as a parameter to the call: ```csharp builder.Services.AddOpenApi("internal"); // Document name is internal @@ -113,7 +113,7 @@ GET http://localhost:5000/openapi/internal.json ### Customize the OpenAPI version of a generated document -By default, OpenAPI document generation creates a document that is compliant with [OpenAPI version 3.1](https://spec.openapis.org/oas/v3.1.1.html). The following code demonstrates how to modify the default version of the OpenAPI document: +By default, OpenAPI document generation creates a document that is compliant with the OpenAPI specification. The following code demonstrates how to modify the default version of the OpenAPI document: ```csharp builder.Services.AddOpenApi(options => @@ -138,7 +138,7 @@ Because the OpenAPI document is served via a route handler endpoint, any customi #### Limit OpenAPI document access to authorized users -The OpenAPI endpoint doesn't enable any authorization checks by default. However, authorization checks can be applied to the OpenAPI document. In the following code, access to the OpenAPI document is limited to those with the `tester` role: +The OpenAPI endpoint doesn't enable authorization checks by default. However, authorization checks can be applied to the OpenAPI document. In the following code, access to the OpenAPI document is limited to users with the `tester` role: [!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_mapopenapiwithauth)] @@ -163,47 +163,49 @@ builder.Services.AddOpenApi("v1"); builder.Services.AddOpenApi("v2"); ``` -Each invocation of can specify its own set of options, so that you can choose to use the same or different customizations for each OpenAPI document. +Each invocation of can specify its own set of options, so you can choose to use the same or different customizations for each OpenAPI document. The framework uses the delegate method of to determine which endpoints to include in each document. For each document, the delegate method is called for each endpoint in the app, passing the object for the endpoint. The method returns a boolean value indicating whether the endpoint should be included in the document. The object: -* contains information about the endpoint, such as the HTTP method, route, and response types +* Contains information about the endpoint, such as the HTTP method, route, and response types. * Metadata attached to the endpoint via attributes or extension methods. -The default implementation of this delegate uses the field of . The delegate is set on an endpoint using either the extension method or the attribute. `WithGroupName` or the `EndpointGroupName` attribute determines which endpoints to include in the document. Any endpoint that has not been assigned a group name is included all OpenAPI documents. +The default implementation of this delegate uses the field of . The delegate is set on an endpoint using either the extension method or the attribute. `WithGroupName` or the `EndpointGroupName` attribute determines which endpoints to include in the document. Any endpoint that hasn't been assigned a group name is included all OpenAPI documents. ```csharp - // Include endpoints without a group name or with a group name that matches the document name - ShouldInclude = (description) => description.GroupName == null || description.GroupName == DocumentName; +// Include endpoints without a group name or with a group name +// that matches the document name +ShouldInclude = (description) => description.GroupName == null || + description.GroupName == DocumentName; ``` -You can customize the delegate method to include or exclude endpoints based on any criteria you choose. +You can customize the delegate method to include or exclude endpoints based on any criteria. -## Generate OpenAPI documents at build-time +## Generate OpenAPI documents at build time -In typical web apps, OpenAPI documents are generated at run-time and served via an HTTP request to the app server. +In typical web apps, OpenAPI documents are generated at runtime and served via an HTTP request to the app server. -In some scenarios, it's helpful to generate the OpenAPI document during the app's build step. These scenarios include: +In some scenarios, it's helpful to generate the OpenAPI document during the app's build step. These scenarios include generating OpenAPI documentation that is: -* Generating OpenAPI documentation that is committed into source control. -* Generating OpenAPI documentation that is used for spec-based integration testing. -* Generating OpenAPI documentation that is served statically from the web server. +* Committed into source control. +* Used for spec-based integration testing. +* Served statically from the web server. -To add support for generating OpenAPI documents at build time, install the `Microsoft.Extensions.ApiDescription.Server` package: +To add support for generating OpenAPI documents at build time, install the [`Microsoft.Extensions.ApiDescription.Server` package](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server): -### [Visual Studio](#tab/visual-studio) +# [Visual Studio](#tab/visual-studio) Run the following command from the **Package Manager Console**: - ```powershell - Install-Package Microsoft.Extensions.ApiDescription.Server +```powershell +Install-Package Microsoft.Extensions.ApiDescription.Server ``` -### [.NET CLI](#tab/net-cli) +# [.NET CLI](#tab/net-cli) -Run the following command in the directory that contains the project file: +Run the following command in a command shell opened to the directory that contains the app's project file: ```dotnetcli dotnet add package Microsoft.Extensions.ApiDescription.Server @@ -216,7 +218,7 @@ Upon installation, this package: * Automatically generates the Open API document(s) associated with the app during build. * Populates the Open API documents in the app's output directory. -If multiple documents are registered, ***and*** document name is ***not*** `v1`, it's post-fixed with the document name. E.g., `{ProjectName}_{DocumentName}.json`. +If multiple documents are registered ***and*** the document name is ***not*** `v1`, the project name is post-fixed with the document name. Example: `{ProjectName}_{DocumentName}.json`. The `{ProjectName}` placeholder is the project name, and the `{DocumentName}` placeholder is the document name. # [Visual Studio Code](#tab/visual-studio-code) @@ -250,11 +252,11 @@ Disable the Terminal Logger and use legacy-style logs with the [`--tl` option](/ dotnet build --tl:off ``` -### Customizing build-time document generation +### Customize build-time document generation -#### Modifying the output directory of the generated Open API file +#### Modify the output directory of the generated Open API file -By default, the generated OpenAPI document will be emitted to the app's output directory. To modify the location of the emitted file, set the target path in the `OpenApiDocumentsDirectory` property. +By default, the generated OpenAPI document is emitted to the app's output directory. To modify the location of the emitted file, set the target path in the `OpenApiDocumentsDirectory` property: ```xml @@ -262,52 +264,56 @@ By default, the generated OpenAPI document will be emitted to the app's output d ``` -The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value above will emit the OpenAPI document in the same directory as the project file. +The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value, as seen in the preceding example, emits the OpenAPI document in the same directory as the project file. -#### Modifying the output file name +#### Modify the output file name -By default, the generated OpenAPI document will have the same name as the app's project file. To modify the name of the emitted file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property. +By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the emitted file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: ```xml - --file-name my-open-api + + --file-name my-open-api + ``` -#### Selecting the OpenAPI document to generate +#### Select the OpenAPI document to generate -Some apps may be configured to emit multiple OpenAPI documents. Multiple OpenAPI documents may be generated for different versions of an API or to distinguish between public and internal APIs. By default, the build-time document generator emits files for all documents that are configured in an app. To only emit for a single document name, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property. +Some apps may be configured to emit multiple OpenAPI documents. Multiple OpenAPI documents may be generated for different versions of an API or to distinguish between public and internal APIs. By default, the build-time document generator emits files for all documents that are configured in an app. To only emit for a single document name, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: ```xml - --document-name v2 + + --document-name v2 + ``` -### Customizing run-time behavior during build-time document generation +### 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 that will run when the apps entry point is being invoked from build-time document generation. These scenarios include: +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: * Not reading from certain configuration strings. * Not registering database-related services. -In order to restrict these code paths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly: +In order to restrict invoking these code paths by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly: :::code language="csharp" source="~/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.Web/Program.cs" highlight="5-8"::: -[AddServiceDefaults](https://source.dot.net/#TestingAppHost1.ServiceDefaults/Extensions.cs,0f0d863053754768,references) adds common .NET Aspire services such as service discovery, resilience, health checks, and OpenTelemetry. +[`AddServiceDefaults`](https://source.dot.net/#TestingAppHost1.ServiceDefaults/Extensions.cs,0f0d863053754768,references) adds common .NET Aspire services such as service discovery, resilience, health checks, and OpenTelemetry. ## Trimming and Native AOT -OpenAPI in ASP.NET Core supports trimming and native AOT. The following steps create and publish an OpenAPI app with trimming and native AOT: +OpenAPI in ASP.NET Core supports trimming and native AOT. The following steps create and publish an OpenAPI app with trimming and native AOT. -Create a new ASP.NET Core Web API (Native AOT) project. +Create a new ASP.NET Core Web API (Native AOT) project: ```console dotnet new webapiaot ``` -Publish the app. +Publish the app: ```console dotnet publish diff --git a/aspnetcore/migration/fx-to-core/areas/authentication.md b/aspnetcore/migration/fx-to-core/areas/authentication.md index d920e7d37eda..eb83bab513fd 100644 --- a/aspnetcore/migration/fx-to-core/areas/authentication.md +++ b/aspnetcore/migration/fx-to-core/areas/authentication.md @@ -4,7 +4,7 @@ description: ASP.NET Framework to Core Authentication Migration author: wadepickett ms.author: wpickett monikerRange: '>= aspnetcore-6.0' -ms.date: 07/17/2025 +ms.date: 09/24/2025 ms.topic: article uid: migration/fx-to-core/areas/authentication zone_pivot_groups: migration-remote-app-setup @@ -344,8 +344,8 @@ Details on how to configure sharing auth cookies between ASP.NET and ASP.NET Cor The following samples in the [System.Web adapters](https://github.com/dotnet/systemweb-adapters) GitHub repo demonstrates remote app authentication with shared cookie configuration enabling both apps to sign users in and out: -* [ASP.NET app](https://github.com/dotnet/systemweb-adapters/tree/main/samples/RemoteAuth/Identity/MvcApp) -* [ASP.NET Core app](https://github.com/dotnet/systemweb-adapters/tree/main/samples/RemoteAuth/Identity/MvcCoreApp) +* [ASP.NET app](https://github.com/dotnet/systemweb-adapters/tree/main/samples/AuthRemoteIdentity/AuthRemoteIdentityFramework) +* [ASP.NET Core app](https://github.com/dotnet/systemweb-adapters/tree/main/samples/AuthRemoteIdentity/AuthRemoteIdentityCore) ### When to choose shared cookie authentication diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/distributed-cache-tag-helper.md b/aspnetcore/mvc/views/tag-helpers/built-in/distributed-cache-tag-helper.md index 00899a2a3f2c..b78f0f9be81d 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/distributed-cache-tag-helper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/distributed-cache-tag-helper.md @@ -4,20 +4,20 @@ author: pkellner description: Learn how to use the Distributed Cache Tag Helper. ms.author: tdykstra ms.custom: mvc -ms.date: 01/24/2020 +ms.date: 09/24/2025 uid: mvc/views/tag-helpers/builtin-th/distributed-cache-tag-helper --- # Distributed Cache Tag Helper in ASP.NET Core By [Peter Kellner](https://peterkellner.net) -The Distributed Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app by caching its content to a distributed cache source. +The Distributed Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app by caching its content to a [distributed cache source](xref:performance/caching/distributed). For an overview of Tag Helpers, see . The Distributed Cache Tag Helper inherits from the same base class as the Cache Tag Helper. All of the [Cache Tag Helper](xref:mvc/views/tag-helpers/builtin-th/cache-tag-helper) attributes are available to the Distributed Tag Helper. -The Distributed Cache Tag Helper uses [constructor injection](xref:fundamentals/dependency-injection#constructor-injection-behavior). The interface is passed into the Distributed Cache Tag Helper's constructor. If no concrete implementation of `IDistributedCache` is created in `Startup.ConfigureServices` (`Startup.cs`), the Distributed Cache Tag Helper uses the same in-memory provider for storing cached data as the [Cache Tag Helper](xref:mvc/views/tag-helpers/builtin-th/cache-tag-helper). +The Distributed Cache Tag Helper uses [constructor injection](xref:fundamentals/dependency-injection#constructor-injection-behavior). The interface is passed into the Distributed Cache Tag Helper's constructor. If no concrete implementation of is created in the `Program` file or `Startup.ConfigureServices` (`Startup.cs`), the Distributed Cache Tag Helper uses the same in-memory provider for storing cached data as the [Cache Tag Helper](xref:mvc/views/tag-helpers/builtin-th/cache-tag-helper). ## Distributed Cache Tag Helper Attributes @@ -27,13 +27,15 @@ The Distributed Cache Tag Helper uses [constructor injection](xref:fundamentals/ * `expires-on` * `expires-after` * `expires-sliding` +* `vary-by` +* `vary-by-cookie` +* `vary-by-culture` * `vary-by-header` * `vary-by-query` * `vary-by-route` -* `vary-by-cookie` * `vary-by-user` -* `vary-by` -* `priority` + +The `expires-sliding` attribute value defaults to 30 seconds if `expires-after` and `expires-on` aren't set. Otherwise, the value defaults to 20 minutes with the SQL Server caching service. The Distributed Cache Tag Helper inherits from the same class as Cache Tag Helper. For descriptions of these attributes, see the [Cache Tag Helper](xref:mvc/views/tag-helpers/builtin-th/cache-tag-helper). @@ -53,16 +55,17 @@ Example: ``` -## Distributed Cache Tag Helper IDistributedCache implementations +## Distributed Cache Tag Helper `IDistributedCache` implementations + +There are two implementations of built in to ASP.NET Core. One is based on SQL Server, and the other is based on Redis. Third-party implementations are also available, such as [NCache](http://www.alachisoft.com/ncache/aspnet-core-idistributedcache-ncache.html). Both implementations involve setting an instance of in either the `Program` file or `Startup` class. -There are two implementations of built in to ASP.NET Core. One is based on SQL Server, and the other is based on Redis. Third-party implementations are also available, such as [NCache](http://www.alachisoft.com/ncache/aspnet-core-idistributedcache-ncache.html). Details of these implementations can be found at . Both implementations involve setting an instance of `IDistributedCache` in `Startup`. +There are no tag attributes specifically associated with using any implementation of . -There are no tag attributes specifically associated with using any specific implementation of `IDistributedCache`. +For more information, see . ## Additional resources * * -* * *