Skip to content

Commit 229dc91

Browse files
gewarrengewarren
authored
Port breaking changes from dotnet/docs repo (#36693)
1 parent 0462121 commit 229dc91

107 files changed

Lines changed: 6534 additions & 36 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎aspnetcore/breaking-changes/10/apidescription-client-deprecated.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: "Breaking change - Microsoft.Extensions.ApiDescription.Client package deprecated"
3+
description: "Learn about the breaking change in ASP.NET Core 10 where the Microsoft.Extensions.ApiDescription.Client package has been deprecated."
4+
ms.date: 08/07/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/aspnet/Announcements/issues/518
7+
---
8+
9+
# Microsoft.Extensions.ApiDescription.Client package deprecated
10+
11+
The Microsoft.Extensions.ApiDescription.Client NuGet package has been deprecated. The package supplied MSBuild targets and CLI support that generated OpenAPI-based client code during the build. Projects that reference the package now receive a warning during build.
12+
13+
## Version introduced
14+
15+
.NET 10 Preview 7
16+
17+
## Previous behavior
18+
19+
Projects could add `<PackageReference Include="Microsoft.Extensions.ApiDescription.Client" ... />` and `<OpenApiReference>` items (or run `dotnet openapi`) to generate strongly typed clients at build time.
20+
21+
```xml
22+
<Project Sdk="Microsoft.NET.Sdk">
23+
<PropertyGroup>
24+
<TargetFramework>net10.0</TargetFramework>
25+
</PropertyGroup>
26+
27+
<ItemGroup>
28+
<PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="8.0.0" />
29+
</ItemGroup>
30+
31+
<ItemGroup>
32+
<OpenApiReference Include="swagger.json" />
33+
</ItemGroup>
34+
</Project>
35+
```
36+
37+
## New behavior
38+
39+
The package is now deprecated and projects that reference it receive build warnings. The MSBuild targets and CLI commands are no longer supported.
40+
41+
## Type of breaking change
42+
43+
This change can affect [source compatibility](/dotnet/core/compatibility/categories#source-compatibility).
44+
45+
## Reason for change
46+
47+
- The package has seen minimal updates and maintenance since its introduction.
48+
- Its abstractions were tightly coupled to certain generators and did not scale well to others. Each generator now ships its own CLI/configuration experience, making the MSBuild middle-layer redundant.
49+
- Removing the package reduces maintenance burden and clarifies the recommended workflow for client generation.
50+
51+
## Recommended action
52+
53+
- Remove any `<PackageReference Include="Microsoft.Extensions.ApiDescription.Client" … />` from your project.
54+
- Replace `<OpenApiReference>` items or `dotnet openapi` commands with generator-specific tooling:
55+
- NSwag – Use `npx nswag` or `dotnet tool run nswag` with an `.nswag` config file.
56+
- Kiota – Install with `dotnet tool install -g Microsoft.OpenApi.Kiota` and run `kiota generate`.
57+
- OpenAPI generator – Invoke `openapi-generator-cli` via JAR or Docker.
58+
- Commit the generated client code or run generation in a custom pre-build step that doesn't rely on the removed package.
59+
60+
## Affected APIs
61+
62+
- MSBuild item `OpenApiReference` (all instances).
63+
- MSBuild property `OpenApiProjectReference`.
64+
- CLI command [`dotnet openapi`](/aspnet/core/fundamentals/openapi/openapi-tools).

‎aspnetcore/breaking-changes/10/cookie-authentication-api-endpoints.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "Cookie login redirects are disabled for known API endpoints"
3+
description: "Learn about the breaking change in ASP.NET Core 10 where cookie authentication no longer redirects to login or access denied URIs for known API endpoints."
4+
ms.date: 08/08/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/aspnet/Announcements/issues/525
7+
---
8+
9+
# Cookie login redirects are disabled for known API endpoints
10+
11+
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.
12+
13+
Known API [endpoints](/aspnet/core/fundamentals/routing) are identified using the new `IApiEndpointMetadata` <!--xref:Microsoft.AspNetCore.Http.Metadata.IApiEndpointMetadata--> interface, and metadata implementing the new interface has been added automatically to the following:
14+
15+
- [`[ApiController]`](xref:Microsoft.AspNetCore.Mvc.ApiControllerAttribute) endpoints.
16+
- Minimal API endpoints that read JSON request bodies or write JSON responses.
17+
- Endpoints using <xref:Microsoft.AspNetCore.Http.TypedResults> return types.
18+
- SignalR endpoints.
19+
20+
## Version introduced
21+
22+
.NET 10 Preview 7
23+
24+
## Previous behavior
25+
26+
Previously, the cookie authentication handler redirected unauthenticated and unauthorized requests to a login or access-denied URI by default for all requests other than [XMLHttpRequests (XHRs)](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest).
27+
28+
## New behavior
29+
30+
Starting in .NET 10, unauthenticated and unauthorized requests made to known API endpoints result in 401 and 403 responses rather than redirecting to a login or access-denied URI. XHRs continue to result in 401 and 403 responses regardless of the target endpoint.
31+
32+
## Type of breaking change
33+
34+
This change is a [behavioral change](/dotnet/core/compatibility/categories#behavioral-change).
35+
36+
## Reason for change
37+
38+
This change was highly requested. 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.
39+
40+
## Recommended action
41+
42+
If you want to always redirect to the login and access-denied URIs for unauthenticated or unauthorized requests regardless of the target endpoint or whether the source of the request is an XHR, you can override <xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationEvents.RedirectToLogin*> and <xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationEvents.RedirectToAccessDenied*> as follows:
43+
44+
```csharp
45+
builder.Services.AddAuthentication()
46+
.AddCookie(options =>
47+
{
48+
options.Events.OnRedirectToLogin = context =>
49+
{
50+
context.Response.Redirect(context.RedirectUri);
51+
return Task.CompletedTask;
52+
};
53+
54+
options.Events.OnRedirectToAccessDenied = context =>
55+
{
56+
context.Response.Redirect(context.RedirectUri);
57+
return Task.CompletedTask;
58+
};
59+
});
60+
```
61+
62+
If you want to revert to the exact previous behavior that avoids redirecting for only XHRs, you can override the events with this slightly more complicated logic:
63+
64+
```csharp
65+
builder.Services.AddAuthentication()
66+
.AddCookie(options =>
67+
{
68+
bool IsXhr(HttpRequest request)
69+
{
70+
return string.Equals(request.Query[HeaderNames.XRequestedWith], "XMLHttpRequest", StringComparison.Ordinal) ||
71+
string.Equals(request.Headers.XRequestedWith, "XMLHttpRequest", StringComparison.Ordinal);
72+
}
73+
74+
options.Events.OnRedirectToLogin = context =>
75+
{
76+
if (IsXhr(context.Request))
77+
{
78+
context.Response.Headers.Location = context.RedirectUri;
79+
context.Response.StatusCode = 401;
80+
}
81+
else
82+
{
83+
context.Response.Redirect(context.RedirectUri);
84+
}
85+
86+
return Task.CompletedTask;
87+
};
88+
89+
options.Events.OnRedirectToAccessDenied = context =>
90+
{
91+
if (IsXhr(context.Request))
92+
{
93+
context.Response.Headers.Location = context.RedirectUri;
94+
context.Response.StatusCode = 403;
95+
}
96+
else
97+
{
98+
context.Response.Redirect(context.RedirectUri);
99+
}
100+
101+
return Task.CompletedTask;
102+
};
103+
});
104+
```
105+
106+
## Affected APIs
107+
108+
- `Microsoft.AspNetCore.Http.Metadata.IApiEndpointMetadata` <!--xref:Microsoft.AspNetCore.Http.Metadata.IApiEndpointMetadata?displayProperty=fullName-->
109+
- <xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationEvents.RedirectToLogin*?displayProperty=fullName>
110+
- <xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationEvents.RedirectToAccessDenied*?displayProperty=fullName>

‎aspnetcore/breaking-changes/10/exception-handler-diagnostics-suppressed.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: "Breaking change: Exception diagnostics are suppressed when IExceptionHandler.TryHandleAsync returns true"
3+
description: Learn about the breaking change in ASP.NET Core 10 where exception diagnostics are no longer recorded when IExceptionHandler.TryHandleAsync returns true.
4+
ms.date: 08/08/2025
5+
ms.custom: https://github.com/aspnet/Announcements/issues/524
6+
---
7+
8+
# Exception diagnostics are suppressed when IExceptionHandler.TryHandleAsync returns true
9+
10+
The ASP.NET Core exception handler middleware no longer records diagnostics for exceptions handled by <xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler> by default.
11+
12+
## Version introduced
13+
14+
.NET 10 Preview 7
15+
16+
## Previous behavior
17+
18+
Previously, the exception handler middleware recorded diagnostics about exceptions handled by <xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler>.
19+
20+
The exception diagnostics are:
21+
22+
- Logging `UnhandledException` to <xref:Microsoft.Extensions.Logging.ILogger>.
23+
- Writing the `Microsoft.AspNetCore.Diagnostics.HandledException` event to <xref:Microsoft.Extensions.Logging.EventSource>.
24+
- Adding the `error.type` tag to the `http.server.request.duration` metric.
25+
26+
## New behavior
27+
28+
Starting in .NET 10, if <xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler.TryHandleAsync%2A?displayProperty=nameWithType> returns `true`, then exception diagnostics are no longer recorded by default.
29+
30+
## Type of breaking change
31+
32+
This change is a [behavioral change](/dotnet/core/compatibility/categories#behavioral-change).
33+
34+
## Reason for change
35+
36+
ASP.NET Core users have given feedback that the previous behavior was undesirable. Their <xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler> implementation reported that the exception was handled, but the error handling middleware still recorded the error in the app's telemetry.
37+
38+
ASP.NET Core now follows the behavior expected by users by suppressing diagnostics when <xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler> handles the exception. Configuration options are also available to customize exception diagnostics behavior if needed.
39+
40+
## Recommended action
41+
42+
If you want handled exceptions to continue to record telemetry, you can use the new `ExceptionHandlerOptions.SuppressDiagnosticsCallback` option:
43+
44+
```csharp
45+
app.UseExceptionHandler(new ExceptionHandlerOptions
46+
{
47+
SuppressDiagnosticsCallback = context => false;
48+
});
49+
```
50+
51+
The `context` passed to the callback includes information about the exception, the request, and whether the exception was handled. The callback returns `false` to indicate that diagnostics shouldn't be suppressed, thus restoring the previous behavior.
52+
53+
## Affected APIs
54+
55+
- <xref:Microsoft.AspNetCore.Builder.ExceptionHandlerExtensions.UseExceptionHandler%2A?displayProperty=fullName>
56+
- <xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler?displayProperty=fullName>

‎aspnetcore/breaking-changes/10/iactioncontextaccessor-obsolete.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: "IActionContextAccessor and ActionContextAccessor are obsolete"
3+
description: "Learn about the breaking change in ASP.NET Core 10 where IActionContextAccessor and ActionContextAccessor are marked as obsolete."
4+
ms.date: 08/07/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/aspnet/Announcements/issues/520
7+
---
8+
9+
# IActionContextAccessor and ActionContextAccessor are obsolete
10+
11+
<xref:Microsoft.AspNetCore.Mvc.Infrastructure.IActionContextAccessor> and <xref:Microsoft.AspNetCore.Mvc.Infrastructure.ActionContextAccessor> have been marked as obsolete with diagnostic ID `ASPDEPR006`. With the introduction of endpoint routing, `IActionContextAccessor` is no longer necessary as developers can access action descriptor and metadata information directly through `HttpContext.GetEndpoint()`.
12+
13+
## Version introduced
14+
15+
.NET 10 Preview 7
16+
17+
## Previous behavior
18+
19+
Previously, you could use `IActionContextAccessor` to access the current <xref:Microsoft.AspNetCore.Mvc.ActionContext>:
20+
21+
```csharp
22+
public class MyService
23+
{
24+
private readonly IActionContextAccessor _actionContextAccessor;
25+
26+
public MyService(IActionContextAccessor actionContextAccessor)
27+
{
28+
_actionContextAccessor = actionContextAccessor;
29+
}
30+
31+
public void DoSomething()
32+
{
33+
var actionContext = _actionContextAccessor.ActionContext;
34+
var actionDescriptor = actionContext?.ActionDescriptor;
35+
// Use action descriptor metadata.
36+
}
37+
}
38+
```
39+
40+
## New behavior
41+
42+
Starting in .NET 10, using `IActionContextAccessor` and `ActionContextAccessor` produces a compiler warning with diagnostic ID `ASPDEPR006`:
43+
44+
> warning ASPDEPR006: ActionContextAccessor is obsolete and will be removed in a future version. For more information, visit <https://aka.ms/aspnet/deprecate/006>.
45+
46+
## Type of breaking change
47+
48+
This change can affect [source compatibility](/dotnet/core/compatibility/categories#source-compatibility).
49+
50+
## Reason for change
51+
52+
With the introduction of endpoint routing in ASP.NET Core, `IActionContextAccessor` is no longer necessary. The endpoint routing infrastructure provides a cleaner, more direct way to access endpoint metadata through `HttpContext.GetEndpoint()`, aligning with ASP.NET Core's architectural evolution toward endpoint routing.
53+
54+
## Recommended action
55+
56+
Migrate from `IActionContextAccessor` to <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> and use `HttpContext.GetEndpoint()`:
57+
58+
Before:
59+
60+
```csharp
61+
public class MyService
62+
{
63+
private readonly IActionContextAccessor _actionContextAccessor;
64+
65+
public MyService(IActionContextAccessor actionContextAccessor)
66+
{
67+
_actionContextAccessor = actionContextAccessor;
68+
}
69+
70+
public void DoSomething()
71+
{
72+
var actionContext = _actionContextAccessor.ActionContext;
73+
var actionDescriptor = actionContext?.ActionDescriptor;
74+
// Use action descriptor metadata
75+
}
76+
}
77+
```
78+
79+
After:
80+
81+
```csharp
82+
public class MyService
83+
{
84+
private readonly IHttpContextAccessor _httpContextAccessor;
85+
86+
public MyService(IHttpContextAccessor httpContextAccessor)
87+
{
88+
_httpContextAccessor = httpContextAccessor;
89+
}
90+
91+
public void DoSomething()
92+
{
93+
var httpContext = _httpContextAccessor.HttpContext;
94+
var endpoint = httpContext?.GetEndpoint();
95+
var actionDescriptor = endpoint?.Metadata.GetMetadata<ActionDescriptor>();
96+
// Use action descriptor metadata.
97+
}
98+
}
99+
```
100+
101+
## Affected APIs
102+
103+
- <xref:Microsoft.AspNetCore.Mvc.Infrastructure.IActionContextAccessor?displayProperty=fullName>
104+
- <xref:Microsoft.AspNetCore.Mvc.Infrastructure.ActionContextAccessor?displayProperty=fullName>

‎aspnetcore/breaking-changes/10/ipnetwork-knownnetworks-obsolete.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: "Breaking change: IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete"
3+
description: Learn about the breaking change in ASP.NET Core 10.0 where IPNetwork and ForwardedHeadersOptions.KnownNetworks have been obsoleted in favor of System.Net.IPNetwork and KnownIPNetworks.
4+
ms.date: 08/08/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/aspnet/Announcements/issues/523
7+
---
8+
# IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete
9+
10+
<xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName> and <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks> have been marked as obsolete in favor of using <xref:System.Net.IPNetwork?displayProperty=fullName> and `KnownIPNetworks`.
11+
12+
## Version introduced
13+
14+
.NET 10 Preview 7
15+
16+
## Previous behavior
17+
18+
Previously, you could use <xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName> and <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks> to configure known networks for the forwarded headers middleware:
19+
20+
```csharp
21+
app.UseForwardedHeaders(new ForwardedHeadersOptions
22+
{
23+
KnownNetworks.Add(new(IPAddress.Loopback, 8))
24+
});
25+
```
26+
27+
## New behavior
28+
29+
Starting in .NET 10, if you use [the obsolete APIs](#affected-apis) in your code, you'll get warning `ASPDEPR005` at compile time:
30+
31+
> warning ASPDEPR005: Please use KnownIPNetworks instead. For more information, visit <https://aka.ms/aspnet/deprecate/005>.
32+
33+
Use the <xref:System.Net.IPNetwork?displayProperty=fullName> type and `KnownIPNetworks` property instead.
34+
35+
## Type of breaking change
36+
37+
This change can affect [source compatibility](/dotnet/core/compatibility/categories#source-compatibility).
38+
39+
## Reason for change
40+
41+
<xref:System.Net.IPNetwork?displayProperty=fullName> has replaced the <xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName> type that was implemented for <xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersMiddleware>.
42+
43+
## Recommended action
44+
45+
Change to using <xref:System.Net.IPNetwork?displayProperty=fullName> and `KnownIPNetworks`.
46+
47+
## Affected APIs
48+
49+
- <xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName>
50+
- <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks?displayProperty=fullName>

0 commit comments

Comments
 (0)