Skip to content

Commit 7783168

Browse files
CopilotCopilot
authored
Add ASP.NET Core release notes for .NET 10 Preview 5 (#9925)
1 parent 4ffc4e7 commit 7783168

File tree

1 file changed

+170
-0
lines changed

1 file changed

+170
-0
lines changed

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

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# ASP.NET Core in .NET 10 Preview 5 - Release Notes
2+
3+
Here's a summary of what's new in ASP.NET Core in this preview release:
4+
5+
- [Configure custom security descriptors for HTTP.sys request queues](#configure-custom-security-descriptors-for-httpsys-request-queues)
6+
- [Validation resolver APIs marked as experimental](#validation-resolver-apis-marked-as-experimental)
7+
- [Support for generating OpenAPI 3.1](#support-for-generating-openapi-31)
8+
- [OpenAPI metadata from XML doc comments](#openapi-metadata-from-xml-doc-comments)
9+
- [Add a Not Found page using the Blazor Router](#add-a-not-found-page-using-the-blazor-router)
10+
- [Blazor metrics and tracing](#blazor-metrics-and-tracing)
11+
12+
ASP.NET Core updates in .NET 10:
13+
14+
- [What's new in ASP.NET Core in .NET 10](https://learn.microsoft.com/aspnet/core/release-notes/aspnetcore-10.0) documentation.
15+
- [Breaking changes](https://learn.microsoft.com/dotnet/core/compatibility/10.0#aspnet-core)
16+
- [Roadmap](https://github.com/dotnet/aspnetcore/issues/59443)
17+
18+
## Configure custom security descriptors for HTTP.sys request queues
19+
20+
You can now specify a custom security descriptor for HTTP.sys request queues using the new `RequestQueueSecurityDescriptor` property on `HttpSysOptions`. This feature enables more granular control over access rights for the request queue, allowing you to tailor security to your application's needs.
21+
22+
By customizing the security descriptor, you can allow or deny specific users or groups access to the request queue. This is particularly useful in scenarios where you want to restrict or delegate HTTP.sys request handling at the operating system level.
23+
24+
To use this feature, set the `RequestQueueSecurityDescriptor` property to a `GenericSecurityDescriptor` instance when configuring your HTTP.sys server. For example, to allow all users but deny guest accounts:
25+
26+
```csharp
27+
using System.Security.AccessControl;
28+
using System.Security.Principal;
29+
using Microsoft.AspNetCore.Server.HttpSys;
30+
31+
// Create a new security descriptor
32+
var securityDescriptor = new CommonSecurityDescriptor(isContainer: false, isDS: false, sddlForm: string.Empty);
33+
34+
// Create a discretionary access control list (DACL)
35+
var dacl = new DiscretionaryAcl(isContainer: false, isDS: false, capacity: 2);
36+
dacl.AddAccess(
37+
AccessControlType.Allow,
38+
new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null),
39+
-1,
40+
InheritanceFlags.None,
41+
PropagationFlags.None
42+
);
43+
dacl.AddAccess(
44+
AccessControlType.Deny,
45+
new SecurityIdentifier(WellKnownSidType.BuiltinGuestsSid, null),
46+
-1,
47+
InheritanceFlags.None,
48+
PropagationFlags.None
49+
);
50+
51+
// Assign the DACL to the security descriptor
52+
securityDescriptor.DiscretionaryAcl = dacl;
53+
54+
// Configure HTTP.sys options
55+
var builder = WebApplication.CreateBuilder();
56+
builder.WebHost.UseHttpSys(options =>
57+
{
58+
options.RequestQueueSecurityDescriptor = securityDescriptor;
59+
});
60+
```
61+
62+
### Additional notes
63+
64+
- The `RequestQueueSecurityDescriptor` applies only when creating a new request queue.
65+
- This property does not affect existing request queues.
66+
- See the official documentation for more information about Windows security descriptors and their usage.
67+
68+
## Validation resolver APIs marked as experimental
69+
70+
To allow for future adjustments to the new validation APIs, the underlying validation resolver APIs used to support minimal API validation have been marked as experimental. However, the top-level `AddValidation` APIs and the built-in validation filter for Minimal APIs remain non-experimental.
71+
72+
## Support for generating OpenAPI 3.1
73+
74+
The OpenAPI.NET library used in ASP.NET Core OpenAPI document generation has been upgraded to [v2.0.0-preview18](https://github.com/microsoft/OpenAPI.NET/releases/tag/v2.0.0-preview.18).
75+
76+
## OpenAPI metadata from XML doc comments
77+
78+
Support for generating OpenAPI metadata from XML doc comments has been extended to extract metadata for operation responses from `<returns>` and `<response>` XML tags on handler methods.
79+
80+
## Add a Not Found page using the Blazor Router
81+
82+
Blazor now provides an improved way to display a "Not Found" page when navigating to a non-existent page. You can specify a page to render when `NavigationManager.NotFound()` is called by passing a page type to the `Router` component using the `NotFoundPage` parameter. This approach is recommended over the previous `NotFound` fragment, as it supports routing, works across code re-execution middleware, and is compatible even with non-Blazor scenarios. If both `NotFound` fragment and `NotFoundPage` are defined, the page specified by `NotFoundPage` takes priority.
83+
84+
```html
85+
<Router AppAssembly="@typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
86+
<Found Context="routeData">
87+
<RouteView RouteData="@routeData" />
88+
<FocusOnNavigate RouteData="@routeData" Selector="h1" />
89+
</Found>
90+
<NotFound>This content will be ignored because we have NotFoundPage defined.</NotFound>
91+
</Router>
92+
```
93+
94+
The Blazor project template now includes a `NotFound.razor` page by default. This page will automatically render whenever `NavigationManager.NotFound()` is called in your application, making it easier to handle missing routes with a consistent user experience.
95+
96+
## Blazor metrics and tracing
97+
98+
.NET 10 Preview 5 introduces comprehensive metrics and tracing capabilities for Blazor applications, providing detailed observability into component lifecycle, navigation, event handling, and circuit management.
99+
100+
### Blazor metrics
101+
102+
The new metrics feature includes several meters that track different aspects of Blazor application performance:
103+
104+
**Microsoft.AspNetCore.Components meter:**
105+
106+
- **`aspnetcore.components.navigation`** - Tracks the total number of route changes in your Blazor application
107+
- **`aspnetcore.components.event_handler`** - Measures the duration of processing browser events, including your business logic
108+
109+
**Microsoft.AspNetCore.Components.Lifecycle meter:**
110+
111+
- **`aspnetcore.components.update_parameters`** - Measures the duration of processing component parameters, including your business logic
112+
- **`aspnetcore.components.render_diff`** - Tracks the duration of rendering batches
113+
114+
**Microsoft.AspNetCore.Components.Server.Circuits meter:**
115+
116+
For Blazor Server applications, additional circuit-specific metrics are available:
117+
118+
- **`aspnetcore.components.circuit.active`** - Shows the number of active circuits currently in memory
119+
- **`aspnetcore.components.circuit.connected`** - Tracks the number of circuits connected to clients
120+
- **`aspnetcore.components.circuit.duration`** - Measures circuit lifetime duration and provides total count
121+
122+
### Blazor tracing
123+
124+
The new activity tracing capabilities use the `Microsoft.AspNetCore.Components` activity source and provide three main types of activities:
125+
126+
**Circuit lifecycle tracing:**
127+
128+
- **`Microsoft.AspNetCore.Components.CircuitStart`** - Traces circuit initialization with format `Circuit {circuitId}`
129+
- Tags: `aspnetcore.components.circuit.id`
130+
- Links: HTTP activity
131+
132+
**Navigation tracing:**
133+
134+
- **`Microsoft.AspNetCore.Components.RouteChange`** - Tracks route changes with format `Route {route} -> {componentType}`
135+
- Tags: `aspnetcore.components.circuit.id`, `aspnetcore.components.type`, `aspnetcore.components.route`
136+
- Links: HTTP trace, circuit trace
137+
138+
**Event handling tracing:**
139+
140+
- **`Microsoft.AspNetCore.Components.HandleEvent`** - Traces event handling with format `Event {attributeName} -> {componentType}.{methodName}`
141+
- Tags: `aspnetcore.components.circuit.id`, `aspnetcore.components.type`, `aspnetcore.components.method`, `aspnetcore.components.attribute.name`, `error.type`
142+
- Links: HTTP trace, circuit trace, router trace
143+
144+
To enable Blazor metrics and tracing in your application, configure OpenTelemetry with the following meters and activity sources:
145+
146+
```csharp
147+
builder.Services.ConfigureOpenTelemetryMeterProvider(meterProvider =>
148+
{
149+
meterProvider.AddMeter("Microsoft.AspNetCore.Components");
150+
meterProvider.AddMeter("Microsoft.AspNetCore.Components.Lifecycle");
151+
meterProvider.AddMeter("Microsoft.AspNetCore.Components.Server.Circuits");
152+
});
153+
154+
builder.Services.ConfigureOpenTelemetryTracerProvider(tracerProvider =>
155+
{
156+
tracerProvider.AddSource("Microsoft.AspNetCore.Components");
157+
});
158+
```
159+
160+
These new observability features help you monitor and diagnose Blazor application performance, track user interactions, and understand component behavior in production environments.
161+
162+
## Contributors
163+
164+
Thank you contributors! ❤️
165+
166+
- [@am11](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview5+author%3Aam11)
167+
- [@Dona278](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview5+author%3ADona278)
168+
- [@feiyun0112](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview5+author%3Afeiyun0112)
169+
- [@MohabASHRAF-byte](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview5+author%3AMohabASHRAF-byte)
170+
- [@profet23](https://github.com/dotnet/aspnetcore/pulls?q=is%3Apr+is%3Amerged+milestone%3A10.0-preview5+author%3Aprofet23)

0 commit comments

Comments
 (0)