Merge to Live

README.md

@@ -1,6 +1,6 @@
 # ASP.NET Core Docs
 
-This repository contains the ASP.NET Core documentation. See the [Contributing Guide](CONTRIBUTING.md) and the [issues list](https://github.com/dotnet/AspNetCore.Docs/issues) if you would like to help.
+This repository contains the [ASP.NET Core documentation](https://learn.microsoft.com/aspnet/core/introduction-to-aspnet-core). See the [Contributing Guide](CONTRIBUTING.md) and the [issues list](https://github.com/dotnet/AspNetCore.Docs/issues) if you would like to help.
 
 To provide comments and suggestions on [learn.microsoft.com](https://learn.microsoft.com) site functionality, open an issue in the [`MicrosoftDocs/feedback` GitHub repository](https://github.com/MicrosoftDocs/feedback).
 

aspnetcore/blazor/components/prerender.md

@@ -114,8 +114,6 @@ When the component executes, `currentCount` is only set once during prerendering
 
 By initializing components with the same state used during prerendering, any expensive initialization steps are only executed once. The rendered UI also matches the prerendered UI, so no flicker occurs in the browser.
 
-The prerendered data sent to the client by the <xref:Microsoft.AspNetCore.Components.PersistentComponentState> service is protected by [ASP.NET Core Data Protection](xref:security/data-protection/introduction), so the state can't be read by a malicious user.
-
 ## Components embedded into pages and views (Razor Pages/MVC)
 
 For components embedded into a page or view of a Razor Pages or MVC app, you must add the [Persist Component State Tag Helper](xref:mvc/views/tag-helpers/builtin-th/persist-component-state-tag-helper) with the `<persist-component-state />` HTML tag inside the closing `</body>` tag of the app's layout. **This is only required for Razor Pages and MVC apps.** For more information, see <xref:mvc/views/tag-helpers/builtin-th/persist-component-state-tag-helper>.

aspnetcore/blazor/components/prerendering-and-integration.md

@@ -920,8 +920,6 @@ else
 
 By initializing components with the same state used during prerendering, any expensive initialization steps are only executed once. The rendered UI also matches the prerendered UI, so no flicker occurs in the browser.
 
-The prerendered data sent to the client by the <xref:Microsoft.AspNetCore.Components.PersistentComponentState> service is protected by [ASP.NET Core Data Protection](xref:security/data-protection/introduction), so the state can't be read by a malicious user.
-
 :::zone pivot="webassembly"
 
 ## Additional Blazor WebAssembly resources

aspnetcore/fundamentals/configuration/index.md

@@ -181,7 +181,7 @@ Using the [default](#default) configuration, the <xref:Microsoft.Extensions.Conf
 
 [!INCLUDE[](~/includes/environmentVarableColon.md)]
 
-The following `set` commands:
+The following commands:
 
 * Set the environment keys and values of the [preceding example](#appsettingsjson) on Windows.
 * Test the settings when using the [sample download](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/fundamentals/configuration/index/samples/3.x/ConfigSample). The `dotnet run` command must be run in the project directory.

aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

@@ -279,21 +279,43 @@ When no explicit annotation is provided, the framework attempts to determine the
 
 #### Describe response types
 
-<!-- TODO: Restructure this section to cover both controller-based and minimal API apps -->
+OpenAPI supports providing a description of the responses returned from an API. ASP.NET Core provides several strategies for setting the response metadata of an endpoint. Response metadata that can be set includes the status code, the type of the response body, and content type(s) of a response. Responses in OpenAPI may have additional metadata, such as description, headers, links, and examples. This additional metadata can be set with a [document transformer](#use-document-transformers) or [operation transformer](#use-operation-transformers).
+
+The specific mechanisms for setting response metadata depend on the type of app being developed.
+
+##### [Minimal APIs](#tab/minimal-apis)
 
-OpenAPI supports providing a description of the responses returned from an API. Minimal APIs support three strategies for setting the response type of an endpoint:
+In Minimal API apps, ASP.NET Core can extract the response metadata added by extension methods on the endpoint, attributes on the route handler, and the return type of the route handler.
 
-* Via the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method on the endpoint.
-* Via the [`ProducesResponseType`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute) attribute on the route handler.
-* By returning<xref:Microsoft.AspNetCore.Http.TypedResults> from the route handler.
+* The <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method can be used on the endpoint to specify the status code, the type of the response body, and content type(s) of a response from an endpoint.
+* The <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> or <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute%601> attribute can be used to specify the type of the response body.
+* A route handler can be used to return a type that implements <xref:Microsoft.AspNetCore.Http.Metadata.IEndpointMetadataProvider> to specify the type and content-type(s) of the response body.
+* The <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.ProducesProblem%2A> extension method on the endpoint can be used to specify the status code and content-type(s) of an error response.
 
-The `Produces` extension method can be used to add `Produces` metadata to an endpoint. When no parameters are provided, the extension method populates metadata for the targeted type under a `200` status code and an `application/json` content type.
+Note that the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A>  and <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.ProducesProblem%2A> extension methods are supported on both <xref:Microsoft.AspNetCore.Builder.RouteHandlerBuilder> and on <xref:Microsoft.AspNetCore.Routing.RouteGroupBuilder>. This allows, for example, a common set of error responses to be defined for all operations in a group.
+
+When not specified by one of the preceding strategies, the:
+* Status code for the response defaults to 200.
+* Schema for the response body can be inferred from the implicit or explicit return type of the endpoint method, for example, from `T` in <xref:System.Threading.Tasks.Task%601>; otherwise, it's considered to be unspecified.
+* Content-type for the specified or inferred response body is "application/json".
+
+In Minimal APIs, the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method and the <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute only set the response metadata for the endpoint. They do not modify or constrain the behavior of the endpoint, which may return a different status code or response body type than specified by the metadata, and the content-type is determined by the return type of the route handler method, irrespective of any content-type specified in attributes or extension methods.
+
+The <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.Produces%2A> extension method can specify an endpoint's response type, with a default status code of 200 and a default content type of `application/json`. The following example illustrates this:
 
 ```csharp
 app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
   .Produces<IList<Todo>>();
 ```
 
+The <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> can be used to add response metadata to an endpoint. Note that the attribute is applied to the route handler method, not the method invocation to create the route, as shown in the following example:
+
+```csharp
+app.MapGet("/todos",
+    [ProducesResponseType<List<Todo>>(200)]
+    async (TodoDb db) => await db.Todos.ToListAsync());
+```
+
 Using <xref:Microsoft.AspNetCore.Http.TypedResults> in the implementation of an endpoint's route handler automatically includes the response type metadata for the endpoint. For example, the following code automatically annotates the endpoint with a response under the `200` status code with an `application/json` content type.
 
 ```csharp
@@ -304,13 +326,37 @@ app.MapGet("/todos", async (TodoDb db) =>
 });
 ```
 
-##### Set responses for `ProblemDetails`
+Only return types that implement <xref:Microsoft.AspNetCore.Http.Metadata.IEndpointMetadataProvider> create a `responses` entry in the OpenAPI document. The following is a partial list  of some of the <xref:Microsoft.AspNetCore.Http.TypedResults> helper methods that produce a `responses` entry:
+
+| TypedResults helper method | status code |
+| -------------------------- | ----------- |
+| Ok()                       | 200         |
+| Created()                  | 201         |
+| CreatedAtRoute()           | 201         |
+| Accepted()                 | 202         |
+| AcceptedAtRoute()          | 202         |
+| NoContent()                | 204         |
+| BadRequest()               | 400         |
+| ValidationProblem()        | 400         |
+| NotFound()                 | 404         |
+| Conflict()                 | 409         |
+| UnprocessableEntity()      | 422         |
+
+All of these methods except `NoContent` have a generic overload that specifies the type of the response body.
+
+A class can be implemented to set the endpoint metadata and return it from the route handler.
+
+###### Set responses for `ProblemDetails`
+
+When setting the response type for endpoints that may return a ProblemDetails response, the following can be used to add the appropriate response metadata for the endpoint:
 
-When setting the response type for endpoints that may return a ProblemDetails response, the <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.ProducesProblem%2A> or <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.ProducesValidationProblem%2A> extension method or <xref:Microsoft.AspNetCore.Http.TypedResults.Problem%2A?displayProperty=nameWithType> can be used to add the appropriate annotation to the endpoint's metadata.
+* <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.ProducesProblem%2A>
+* <xref:Microsoft.AspNetCore.Http.OpenApiRouteHandlerBuilderExtensions.ProducesValidationProblem%2A> extension method.
+* <xref:Microsoft.AspNetCore.Http.TypedResults> with a status code in the (400-499) range.
 
-When there are no explicit annotations provided by one of these strategies, the framework attempts to determine a default response type by examining the signature of the response. This default response is populated under the `200` status code in the OpenAPI definition.
+For more information on how to configure a Minimal API app to return ProblemDetails responses, see <xref:fundamentals/minimal-apis/handle-errors>.
 
-##### Multiple response types
+###### Multiple response types
 
 If an endpoint can return different response types in different scenarios, you can provide metadata in the following ways:
 
@@ -326,6 +372,43 @@ If an endpoint can return different response types in different scenarios, you c
 
   The union types implement implicit cast operators. These operators enable the compiler to automatically convert the types specified in the generic arguments to an instance of the union type. This capability has the added benefit of providing compile-time checking that a route handler only returns the results that it declares it does. Attempting to return a type that isn't declared as one of the generic arguments to `Results<TResult1,TResult2,TResultN>` results in a compilation error.
 
+##### [Controllers](#tab/controllers)
+
+In controller-based apps, ASP.NET Core can extract the response metadata from the action method signature, attributes, and conventions. 
+
+* You can use the <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> or <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute%601> attribute to specify the status code, the type of the response body, and content type(s) of a response from an action method.
+* You can use the <xref:Microsoft.AspNetCore.Mvc.ProducesAttribute> or <xref:Microsoft.AspNetCore.Mvc.ProducesAttribute%601> attribute to specify the type of the response body.
+* You can use the <xref:Microsoft.AspNetCore.Mvc.ProducesDefaultResponseTypeAttribute> attribute to specify the response body type for the "default" response.
+* You can use the <xref:Microsoft.AspNetCore.Mvc.ProducesErrorResponseTypeAttribute> attribute to specify the response body type for an error response. However, be aware that this is only complements the status code and content type(s) specified by an <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute with a 4XX status code.
+
+Only one <xref:Microsoft.AspNetCore.Mvc.ProducesAttribute> or <xref:Microsoft.AspNetCore.Mvc.ProducesAttribute%601> attributes may be applied to an action method, but multiple <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> or <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute%601> attributes with different status codes may be applied to a single action method.
+
+All of the above attributes can be applied to individual action methods or to the controller class where it applies to all action methods in the controller.
+
+When not specified by an attribute:
+* the status code for the response defaults to 200,
+* the schema for the response body of 2xx responses may be inferred from the return type of the action method, e.g. from `T` in <xref:Microsoft.AspNetCore.Mvc.ActionResult%601>, but otherwise is considered to be not specified,
+* the schema for the response body of 4xx responses is inferred to be a problem details object,
+* the schema for the response body of 3xx and 5xx responses is considered to be not specified,
+* the content-type for the response body can be inferred from the return type of the action method and the set of output formatters.
+
+Note that there are no compile-time checks to ensure that the response metadata specified with a <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute is consistent with the actual behavior of the action method,
+which may return a different status code or response body type than specified by the metadata.
+
+In controller-based apps, ASP.NET responds with a ProblemDetails response type when model validation fails or when the action method returns a result with a 4xx or 5xx HTTP status code. Validation errors typically use the 400 status code, so you can use the <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute> attribute to specify the error response for an action, as shown in the following example:
+
+```csharp
+[HttpPut("/todos/{id}")]
+[ProducesResponseType<Todo>(StatusCodes.Status200OK, "application/json")]
+[ProducesResponseType<Todo>(StatusCodes.Status201Created, "application/json")]
+[ProducesResponseType<ProblemDetails>(StatusCodes.Status400BadRequest, "application/problem+json")]
+public async Task<ActionResult<Todo>> CreateOrReplaceTodo(string id, Todo todo)
+```
+
+This example also illustrates how to define multiple response types for an action method, including the content type of the response body.
+
+---
+
 #### Excluding endpoints from the generated document
 
 By default, all endpoints that are defined in an app are documented in the generated OpenAPI file, but endpoints can be excluded from the document using attributes or extension methods.