Merge pull request #35924 from dotnet/main

Merge to Live

Author: wadepickett

aspnetcore/blazor/performance/index.md

@@ -56,13 +56,14 @@ For more information on the following performance meters, see <xref:log-mon/metr
 
 `Microsoft.AspNetCore.Components` meter:
 
-* `aspnetcore.components.navigation`: Tracks the total number of route changes in the app.
-* `aspnetcore.components.event_handler`: Measures the duration of processing browser events, including business logic.
+* `aspnetcore.components.navigate`: Tracks the total number of route changes in the app.
+* `aspnetcore.components.handle_event.duration`: Measures the duration of processing browser events, including business logic.
 
 `Microsoft.AspNetCore.Components.Lifecycle` meter:
 
-* `aspnetcore.components.update_parameters`: Measures the duration of processing component parameters, including business logic.
-* `aspnetcore.components.render_diff`: Tracks the duration of rendering batches.
+* `aspnetcore.components.update_parameters.duration`: Measures the duration of processing component parameters, including business logic.
+* `aspnetcore.components.render_diff.duration`: Tracks the duration of rendering batches.
+* `aspnetcore.components.render_diff.size`: Tracks the size of rendering batches.
 
 `Microsoft.AspNetCore.Components.Server.Circuits` meter:
 
@@ -80,7 +81,7 @@ The new activity tracing capabilities use the `Microsoft.AspNetCore.Components`
 
 Circuit lifecycle tracing:
 
-`Microsoft.AspNetCore.Components.CircuitStart`: Traces circuit initialization with the format `Circuit {circuitId}`.
+`Microsoft.AspNetCore.Components.StartCircuit`: Traces circuit initialization with the format `Circuit {circuitId}`.
 
 Tags:
 
@@ -96,7 +97,7 @@ Usage: Links other Blazor traces of the same session/circuit to HTTP and SignalR
 
 Navigation tracing:
 
-`Microsoft.AspNetCore.Components.RouteChange`: Tracks route changes with the format `Route {route} -> {componentType}`.
+`Microsoft.AspNetCore.Components.Navigate`: Tracks route changes with the format `Route {route} -> {componentType}`.
 
 Tags:
 
@@ -119,14 +120,12 @@ Event handling tracing:
 Tags:
 
 * `aspnetcore.components.attribute.name`: Name of the HTML attribute that triggers the event (example: `onClick`).
-* `aspnetcore.components.method`: C# method name of the handler.
+* `code.function.name`: C# method name of the handler.
 * `aspnetcore.components.type`: Full name of target C# component that receives the event.
 * `error.type`: Exception type full name (optional).
 
 Links:
 
-* HTTP trace
-* SignalR trace
 * Circuit trace
 * Route trace
 

aspnetcore/release-notes/aspnetcore-10.0.md

@@ -45,6 +45,8 @@ This section describes new features for minimal APIs.
 
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/validation-package-move.md)]
 
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md)]
+
 ## OpenAPI
 
 This section describes new features for OpenAPI.
@@ -61,11 +63,15 @@ This section describes new features for OpenAPI.
 
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/xml-comment-generator.md)]
 
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/formdata-enum-parameters.md)]
+
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiSchemasInTransformers.md)]
 
-[!INCLUDE[](~/release-notes/aspnetcore-10/includes/OpenApiNetUpdatePrev.md)]
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md)]
 
-## Authentication and authorization metrics
+## Authentication and authorization
+
+### Authentication and authorization metrics
 
 Metrics have been added for certain authentication and authorization events in ASP.NET Core. With this change, you can now obtain metrics for the following events:
 
@@ -84,10 +90,18 @@ The following image shows an example of the Authenticated request duration metri
 
 For more information, see <xref:log-mon/metrics/built-in#microsoftaspnetcoreauthorization>.
 
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/avoid-cookie-login-redirects.md)]
+
 ## Miscellaneous
 
 This section describes miscellaneous new features in .NET 10.
 
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/exception-handler.md)]
+
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/top-level-domain.md)]
+
+[!INCLUDE[](~/release-notes/aspnetcore-10/includes/pipe-reader.md)]
+
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/memory-eviction.md)]
 
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/httpsys.md)]

aspnetcore/release-notes/aspnetcore-10/includes/avoid-cookie-login-redirects.md

@@ -0,0 +1,36 @@
+### Avoid cookie login redirects for known API endpoints
+
+By default, unauthenticated and unauthorized requests made to known API endpoints protected by cookie authentication now result in 401 and 403 responses rather than redirecting to a login or access denied URI.
+
+This change was [highly requested](https://github.com/dotnet/aspnetcore/issues/9039), because redirecting unauthenticated requests to a login page doesn't usually make sense for API endpoints which typically rely on 401 and 403 status codes rather than HTML redirects to communicate auth failures.
+
+Known API [Endpoints](https://learn.microsoft.com/aspnet/core/fundamentals/routing) are identified using the new `IApiEndpointMetadata` interface, and metadata implementing the new interface has been added automatically to the following:
+
+- `[ApiController]` endpoints
+- Minimal API endpoints that read JSON request bodies or write JSON responses
+- Endpoints using `TypedResults` return types
+- SignalR endpoints
+
+When `IApiEndpointMetadata` is present, the cookie authentication handler now returns appropriate HTTP status codes (401 for unauthenticated requests, 403 for forbidden requests) instead of redirecting.
+
+If you want to prevent this new behavior, and always redirect to the login and access denied URIs for unauthenticated or unauthorized requests regardless of the target endpoint, you can override the `RedirectToLogin` and `RedirectToAccessDenied` events as follows:
+
+```csharp
+builder.Services.AddAuthentication()
+    .AddCookie(options =>
+    {
+        options.Events.OnRedirectToLogin = context =>
+        {
+            context.Response.Redirect(context.RedirectUri);
+            return Task.CompletedTask;
+        };
+
+        options.Events.OnRedirectToAccessDenied = context =>
+        {
+            context.Response.Redirect(context.RedirectUri);
+            return Task.CompletedTask;
+        };
+    });
+```
+
+For more information about this breaking change, see [ASP.NET Core breaking changes announcement](https://github.com/aspnet/Announcements/issues/525).

aspnetcore/release-notes/aspnetcore-10/includes/enhance-validation-classes-records.md

@@ -0,0 +1,5 @@
+### Enhanced validation for classes and records
+
+Validation attributes can now be applied to both classes and records with consistent code generation and validation behavior. This enhancement improves flexibility when designing models using records in ASP.NET Core apps.
+
+Community contribution: Thanks to [@marcominerva](https://github.com/marcominerva)!

aspnetcore/release-notes/aspnetcore-10/includes/exception-handler.md

@@ -0,0 +1,18 @@
+### Configure suppressing exception handler diagnostics
+
+A new configuration option has been added to the [ASP.NET Core exception handler middleware](https://learn.microsoft.com/aspnet/core/fundamentals/error-handling#exception-handler-page)  to control diagnostic output: `ExceptionHandlerOptions.SuppressDiagnosticsCallback`. This callback is passed context about the request and exception, allowing you to add logic that determines whether the middleware should write exception logs and other telemetry.
+
+This setting is useful when you know an exception is transient or has been handled by the exception handler middleware, and don't want error logs written to your observability platform.
+
+Additionally, the middleware's default behavior has changed: it no longer writes exception diagnostics for exceptions handled by `IExceptionHandler`. Based on user feedback, logging handled exceptions at the error level was often undesirable when `IExceptionHandler.TryHandleAsync` returned `true`.
+
+You can revert to the previous behavior by configuring `SuppressDiagnosticsCallback`:
+
+```csharp
+app.UseExceptionHandler(new ExceptionHandlerOptions
+{
+    SuppressDiagnosticsCallback = context => false;
+});
+```
+
+For more information about this breaking change, see https://github.com/aspnet/Announcements/issues/524.

aspnetcore/release-notes/aspnetcore-10/includes/formdata-enum-parameters.md

@@ -0,0 +1,5 @@
+### Form data enum parameters use actual enum type in OpenAPI
+
+Form data parameters in MVC controller actions now generate OpenAPI metadata using the actual enum type instead of defaulting to string.
+
+Community contribution: Thanks to [@ascott18](https://github.com/ascott18)!

aspnetcore/release-notes/aspnetcore-10/includes/pipe-reader.md

@@ -0,0 +1,37 @@
+### Json+PipeReader deserialization support in MVC and Minimal
+
+PR: https://github.com/dotnet/aspnetcore/pull/62895
+
+See https://github.com/dotnet/core/blob/dotnet10-p7-libraries/release-notes/10.0/preview/preview7/libraries.md#pipereader-support-for-json-serializer
+
+MVC, Minimal APIs, and the `HttpRequestJsonExtensions.ReadFromJsonAsync` methods have all been updated to use the new Json+PipeReader support without requiring any code changes from applications.
+
+For the majority of applications this should have no impact on behavior. However, if the application is using a custom `JsonConverter`, there is a chance that the converter doesn't handle [Utf8JsonReader.HasValueSequence](https://learn.microsoft.com/dotnet/api/system.text.json.utf8jsonreader.hasvaluesequence) correctly. This can result in missing data and errors like `ArgumentOutOfRangeException` when deserializing.
+
+The quick workaround (especially if you don't own the custom `JsonConverter` being used) is to set the `"Microsoft.AspNetCore.UseStreamBasedJsonParsing"` [AppContext](https://learn.microsoft.com/dotnet/api/system.appcontext?view=net-9.0) switch to `"true"`. This should be a temporary workaround and the `JsonConverter`(s) should be updated to support `HasValueSequence`.
+
+To fix `JsonConverter` implementations, there is the quick fix which allocates an array from the `ReadOnlySequence` and would look something like:
+```csharp
+public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+{
+    var span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
+    // previous code
+}
+```
+
+Or the more complicated (but performant) fix which would involve having a separate code path for the `ReadOnlySequence` handling:
+```csharp
+public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+{
+    if (reader.HasValueSequence)
+    {
+        reader.ValueSequence;
+        // ReadOnlySequence optimized path
+    }
+    else
+    {
+        reader.ValueSpan;
+        // ReadOnlySpan optimized path
+    }
+}
+```

aspnetcore/release-notes/aspnetcore-10/includes/responseDescProducesResponseType.md

@@ -1,23 +1,24 @@
-### Response description on ProducesResponseType for API controllers
+### Response description on `ProducesResponseType` for API controllers
 
-The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute) attributes now accept an optional string parameter, `Description`, that will set the description of the response. Here's an example:
+The <xref:Microsoft.AspNetCore.Mvc.ProducesAttribute>, <xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute>, and <xref:Microsoft.AspNetCore.Mvc.ProducesDefaultResponseTypeAttribute> now accept an optional string parameter, `Description`, that sets the description of the response:
 
 ```csharp
 [HttpGet(Name = "GetWeatherForecast")]
 [ProducesResponseType<IEnumerable<WeatherForecast>>(StatusCodes.Status200OK,
-                   Description = "The weather forecast for the next 5 days.")]
+    Description = "The weather forecast for the next 5 days.")]
 public IEnumerable<WeatherForecast> Get()
 {
 ```
 
-And the generated OpenAPI:
+Generated OpenAPI data:
 
 ```json
-        "responses": {
-          "200": {
-            "description": "The weather forecast for the next 5 days.",
-            "content": {
+"responses": {
+  "200": {
+    "description": "The weather forecast for the next 5 days.",
+    "content": {
 ```
-[Minimal APIs](https://github.com/dotnet/aspnetcore/issues/58724) currently don't support `ProducesResponseType`.
 
-[Community contribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏
+This functionality is supported in both [API controllers](xref:web-api/index#apicontroller-attribute) and [Minimal APIs](xref:fundamentals/minimal-apis/overview). For Minimal APIs, the `Description` property is correctly set even when the attribute's type and the inferred return type aren't an exact match.
+
+[Community contribution (`dotnet/aspnetcore` #58193)](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095).

aspnetcore/release-notes/aspnetcore-10/includes/top-level-domain.md

@@ -0,0 +1,41 @@
+### Support for the .localhost Top-Level Domain
+
+The `.localhost` top-level domain (TLD) is defined in [RFC2606](https://www.rfc-editor.org/rfc/rfc2606) and [RFC6761](https://www.rfc-editor.org/rfc/rfc6761) as being reserved for testing purposes and available for users to use locally as they would any other domain name. This means using a name like `myapp.localhost` locally that resolves to the IP loopback address is allowed and expected according to these RFCs. Additionally, modern evergreen browsers already automatically resolve any `*.localhost` name to the IP loopback address (`127.0.0.1`/`::1`), effectively making them an alias for any service already being hosted at `localhost` on the local machine, i.e. any service responding to `http://localhost:6789` will also respond to `http://anything-here.localhost:6789`, assuming no further specific hostname verification or enforcement is being performed by the service.
+
+ASP.NET Core has been updated in .NET 10 preview 7 to better support the `.localhost` TLD, such that it can now be easily used when creating and running ASP.NET Core applications in your local development environment. Having different apps running locally be resolvable via different names allows for better separation of some domain-name-associated website assets, e.g. cookies, and makes it easier to identify which app you're browsing via the name displayed in the browser address bar.
+
+ASP.NET Core's built-in HTTP server, Kestrel, will now correctly treat any `*.locahost` name set via [supported endpoint configuration mechanisms](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints#configure-endpoints) as the local loopback address and thus bind to it rather than all external address (i.e. bind to `127.0.0.1`/`::1` rather than `0.0.0.0`/`::`). This includes the `"applicationUrl"` property in [launch profiles configured in a *launchSettings.json* file](https://learn.microsoft.com/aspnet/core/fundamentals/environments#development-and-launchsettingsjson), and the `ASPNETCORE_URLS` environment variable. When configured to listen on a `.localhost` address, Kestrel will log an information message for both the `.localhost` **and** `localhost` addresses, to make it clear that both names can be used.
+
+*Note that while web browsers will automatically resolve `*.localhost` names to the local loopback address, other applications may treat `*.localhost` names as a regular domain names and attempt to resolve them via their corresponding DNS stack. If your DNS configuration does not resolve `*.localhost` names to an address then they will fail to connect. You can continue to use the regular `localhost` name to address your applications when not in a web browser.*
+
+The [ASP.NET Core HTTPS development certificate](https://learn.microsoft.com/aspnet/core/security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate) (including the `dotnet dev-certs https` command) have been updated to ensure the certificate is valid for use with the `*.dev.localhost` domain name. After installing .NET 10 SDK preview 7, trust the new developer certificate by running `dotnet dev-certs https --trust` at the command line to ensure your system is configured to trust the new certificate.
+
+*Note that the certificate lists the `*.dev.localhost` name as a Subject Alternative Name (SAN) rather than `*.localhost` as it's invalid to have wildcard certificates for top-level domain names*
+
+The project templates for *ASP.NET Core Empty* (`web`) and *Blazor Web App* (`blazor`) have been updated with a new option that when specified configures the created project to use the `.dev.localhost` domain name suffix, combining it with the project name to allow the app to be browsed to at an address like `https://myapp.dev.localhost:5036`:
+
+```
+$ dotnet new web -n MyApp --localhost-tld
+The template "ASP.NET Core Empty" was created successfully.
+
+Processing post-creation actions...
+Restoring D:\src\MyApp\MyApp.csproj:
+Restore succeeded.
+
+$ cd .\MyApp\
+$ dotnet run --launch-profile https
+info: Microsoft.Hosting.Lifetime[14]
+      Now listening on: https://myapp.dev.localhost:7099
+info: Microsoft.Hosting.Lifetime[14]
+      Now listening on: https://localhost:7099/
+info: Microsoft.Hosting.Lifetime[14]
+      Now listening on: http://myapp.dev.localhost:5036
+info: Microsoft.Hosting.Lifetime[14]
+      Now listening on: http://localhost:5036/
+info: Microsoft.Hosting.Lifetime[0]
+      Application started. Press Ctrl+C to shut down.
+info: Microsoft.Hosting.Lifetime[0]
+      Hosting environment: Development
+info: Microsoft.Hosting.Lifetime[0]
+      Content root path: D:\src\local\10.0.1xx\MyApp
+```

aspnetcore/release-notes/aspnetcore-10/includes/upgrade-microsoft-openapi-2.md

@@ -0,0 +1,4 @@
+### Upgrade Microsoft.OpenApi to 2.0.0
+
+The [`Microsoft.OpenApi`](https://www.nuget.org/packages/Microsoft.OpenApi/) library used for OpenAPI document generation in ASP.NET Core has been upgraded to version 2.0.0 (GA).  
+With this update to the GA version, no further breaking changes are expected in OpenAPI document generation.