Skip to content

Commit 419e080

Browse files
Copilotdanroth27
Copilot
and
danroth27
committed
Add ASP.NET Core release notes for .NET 10 Preview 7
Co-authored-by: danroth27 <[email protected]>
1 parent 2a403c7 commit 419e080

File tree

1 file changed

+200
-3
lines changed

1 file changed

+200
-3
lines changed

‎release-notes/10.0/preview/preview7/aspnetcore.md

Lines changed: 200 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,211 @@
22

33
Here's a summary of what's new in ASP.NET Core in this preview release:
44

5-
- [Feature](#feature)
5+
- [Configure suppressing exception handler diagnostics](#configure-suppressing-exception-handler-diagnostics)
6+
- [Avoid cookie login redirects for known API endpoints](#avoid-cookie-login-redirects-for-known-api-endpoints)
7+
- [Passkey authentication improvements](#passkey-authentication-improvements)
8+
- [Support for the .localhost Top-Level Domain](#support-for-the-localhost-top-level-domain)
9+
- [JSON+PipeReader deserialization support](#jsonpipereader-deserialization-support)
10+
- [OpenAPI improvements](#openapi-improvements)
611

712
ASP.NET Core updates in .NET 10:
813

914
- [What's new in ASP.NET Core in .NET 10](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0) documentation.
1015
- [Breaking changes](https://docs.microsoft.com/dotnet/core/compatibility/10.0#aspnet-core)
1116
- [Roadmap](https://github.com/dotnet/aspnetcore/issues/59443)
1217

13-
## Feature
18+
## Configure suppressing exception handler diagnostics
1419

15-
Something about the feature
20+
This setting is useful when you know an exception is transient, or has been handled by the exception handler middleware, and don't want to error logs written to your observability platform.
21+
22+
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`.
23+
24+
You can revert to the previous behavior by configuring `SuppressDiagnosticsCallback`:
25+
26+
```csharp
27+
app.UseExceptionHandler(new ExceptionHandlerOptions
28+
{
29+
SuppressDiagnosticsCallback = context => false;
30+
});
31+
```
32+
33+
For more information about this breaking change, see https://github.com/aspnet/Announcements/issues/524.
34+
35+
## Avoid cookie login redirects for known API endpoints
36+
37+
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.
38+
39+
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.
40+
41+
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:
42+
43+
- `[ApiController]` endpoints
44+
- Minimal API endpoints that read JSON request bodies or write JSON responses
45+
- Endpoints using `TypedResults` return types
46+
- SignalR endpoints
47+
48+
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.
49+
50+
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` as follows:
51+
52+
```csharp
53+
builder.Services.AddAuthentication()
54+
.AddCookie(options =>
55+
{
56+
options.Events.OnRedirectToLogin = context =>
57+
{
58+
context.Response.Redirect(context.RedirectUri);
59+
return Task.CompletedTask;
60+
};
61+
62+
options.Events.OnRedirectToAccessDenied = context =>
63+
{
64+
context.Response.Redirect(context.RedirectUri);
65+
return Task.CompletedTask;
66+
};
67+
});
68+
```
69+
70+
For more information about this breaking change, see https://github.com/aspnet/Announcements/issues/525
71+
72+
## Passkey authentication improvements
73+
74+
APIs for passkey authentication in ASP.NET Core Identity have been updated and simplified, and now resemble what we expect to ship in .NET 10 GA.
75+
76+
### Getting started with passkeys
77+
78+
**For new applications:** The Blazor Web App project template now includes passkey functionality out of the box. Create a new Blazor app with passkey support using:
79+
80+
```sh
81+
dotnet new blazor -au Individual
82+
```
83+
84+
**For existing applications:** Please refer to the [official docs](https://learn.microsoft.com/aspnet/core/security/authentication/identity) for guidance on upgrading existing apps to utilize passkeys.
85+
86+
## Support for the .localhost Top-Level Domain
87+
88+
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.
89+
90+
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.
91+
92+
ASP.NET Core's built-in HTTP server, Kestrel, will now correctly treat any `*.localhost` 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.
93+
94+
*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.*
95+
96+
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.
97+
98+
*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*
99+
100+
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`:
101+
102+
```
103+
$ dotnet new web -n MyApp --localhost-tld
104+
The template "ASP.NET Core Empty" was created successfully.
105+
106+
Processing post-creation actions...
107+
Restoring D:\src\MyApp\MyApp.csproj:
108+
Restore succeeded.
109+
110+
$ cd .\MyApp\
111+
$ dotnet run --launch-profile https
112+
info: Microsoft.Hosting.Lifetime[14]
113+
Now listening on: https://myapp.dev.localhost:7099
114+
info: Microsoft.Hosting.Lifetime[14]
115+
Now listening on: https://localhost:7099/
116+
info: Microsoft.Hosting.Lifetime[14]
117+
Now listening on: http://myapp.dev.localhost:5036
118+
info: Microsoft.Hosting.Lifetime[14]
119+
Now listening on: http://localhost:5036/
120+
info: Microsoft.Hosting.Lifetime[0]
121+
Application started. Press Ctrl+C to shut down.
122+
info: Microsoft.Hosting.Lifetime[0]
123+
Hosting environment: Development
124+
info: Microsoft.Hosting.Lifetime[0]
125+
Content root path: D:\src\local\10.0.1xx\MyApp
126+
```
127+
128+
## JSON+PipeReader deserialization support
129+
130+
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.
131+
132+
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.
133+
134+
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`.
135+
136+
To fix `JsonConverter` implementations, there is the quick fix which allocates an array from the `ReadOnlySequence` and would look something like:
137+
138+
```csharp
139+
public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
140+
{
141+
var span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
142+
// previous code
143+
}
144+
```
145+
146+
Or the more complicated (but performant) fix which would involve having a separate code path for the `ReadOnlySequence` handling:
147+
148+
```csharp
149+
public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
150+
{
151+
if (reader.HasValueSequence)
152+
{
153+
reader.ValueSequence;
154+
// ReadOnlySequence optimized path
155+
}
156+
else
157+
{
158+
reader.ValueSpan;
159+
// ReadOnlySpan optimized path
160+
}
161+
}
162+
```
163+
164+
## OpenAPI improvements
165+
166+
### Upgrade Microsoft.OpenApi to 2.0.0
167+
168+
The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation has been upgraded to v2.0.0 (GA). With the update to the GA version of this package, no further breaking changes are expected in the OpenAPI document generation.
169+
170+
### Enhance validation for classes and records
171+
172+
Users can now use validation attributes on both classes and records, with consistent code generation and validation behavior. This enhances flexibility when designing models using records in ASP.NET Core applications.
173+
174+
**Community contribution: Thanks to [@marcominerva](https://github.com/marcominerva)**
175+
176+
### Fix ProducesResponseType Description for Minimal APIs
177+
178+
The Description property for the `ProducesResponseType` attribute is now correctly set in Minimal APIs even when the attribute type and the inferred return type are not an exact match.
179+
180+
**Community contribution: Thanks to [@sander1095](https://github.com/sander1095)**
181+
182+
### Correct metadata type for formdata enum parameters
183+
184+
The metadata type for formdata enum parameters in MVC controller actions has been updated to use the actual enum type instead of string.
185+
186+
**Community contribution: Thanks to [@ascott18](https://github.com/ascott18)**
187+
188+
### Unify handling of documentation IDs in OpenAPI XML comment generator
189+
190+
XML documentation comments from referenced assemblies are now correctly merged if their documentation IDs included return type suffixes. As a result, all valid XML comments are now reliably included in generated OpenAPI documentation, improving doc accuracy and completeness for APIs using referenced assemblies.
191+
192+
## Contributors
193+
194+
Thank you contributors! ❤️
195+
196+
- [ascott18](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Aascott18)
197+
- [BrennanConroy](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3ABrennanConroy)
198+
- [captainsafia](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Acaptainsafia)
199+
- [Copilot](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3ACopilot)
200+
- [DamianEdwards](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3ADamianEdwards)
201+
- [halter73](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Ahalter73)
202+
- [ilonatommy](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Ailonatommy)
203+
- [JamesNK](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3AJamesNK)
204+
- [javiercn](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Ajaviercn)
205+
- [ladeak](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Aladeak)
206+
- [MackinnonBuck](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3AMackinnonBuck)
207+
- [maraf](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Amaraf)
208+
- [marcominerva](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Amarcominerva)
209+
- [oroztocil](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Aoroztocil)
210+
- [pavelsavara](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Apavelsavara)
211+
- [sander1095](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Asander1095)
212+
- [wtgodbe](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview7+author%3Awtgodbe)

0 commit comments

Comments
 (0)