diff --git a/aspnetcore/breaking-changes/10/withopenapi-deprecated.md b/aspnetcore/breaking-changes/10/withopenapi-deprecated.md index f97fe2482d94..f1966dd6eaf3 100644 --- a/aspnetcore/breaking-changes/10/withopenapi-deprecated.md +++ b/aspnetcore/breaking-changes/10/withopenapi-deprecated.md @@ -8,7 +8,7 @@ ms.custom: https://github.com/aspnet/Announcements/issues/519 # Deprecation of WithOpenApi extension method -The methods have been deprecated in .NET 10. Invoking these methods now produces the compile-time diagnostic `ASPDEPR002` and a standard `Obsolete` warning that states: +The methods have been deprecated in .NET 10. Invoking these methods now produces the compile-time diagnostic [`ASPDEPR002`](xref:diagnostics/aspdepr002) and a standard `Obsolete` warning that states: > WithOpenApi is deprecated and will be removed in a future release. For more information, visit . diff --git a/aspnetcore/diagnostics/aspdepr-ids.md b/aspnetcore/diagnostics/aspdepr-ids.md new file mode 100644 index 000000000000..339f296c4250 --- /dev/null +++ b/aspnetcore/diagnostics/aspdepr-ids.md @@ -0,0 +1,26 @@ +--- +title: ASPDEPR diagnostics overview +ai-usage: ai-assisted +author: tdykstra +description: Overview of ASPDEPR deprecation diagnostics in ASP.NET Core. +monikerRange: '>= aspnetcore-10.0' +ms.author: tdykstra +ms.date: 03/03/2026 +uid: diagnostics/aspdepr-ids +--- +# ASPDEPR diagnostics overview + +ASPDEPR diagnostics are compile-time warnings issued by the .NET compiler when your code uses ASP.NET Core APIs that have been deprecated. Deprecated APIs are still functional but are scheduled for removal in a future release. Addressing these warnings helps keep your code up to date and ensures a smoother upgrade path. + +ASPDEPR diagnostics are similar to the [`SYSLIB` obsoletions](/dotnet/fundamentals/syslib-diagnostics/obsoletions-overview) in .NET, but are specific to ASP.NET Core. + +> [!NOTE] +> This article is a work-in-progress. It's not a complete list of deprecation diagnostics. + +## ASPDEPR diagnostics + +The following table lists the `ASPDEPR` deprecation diagnostics for ASP.NET Core: + +| Diagnostic ID | Description | +|-------------------------------------------|-----------------------------| +| [ASPDEPR002](xref:diagnostics/aspdepr002) | `WithOpenApi` is deprecated | diff --git a/aspnetcore/diagnostics/aspdepr002.md b/aspnetcore/diagnostics/aspdepr002.md new file mode 100644 index 000000000000..d8f8dea82d13 --- /dev/null +++ b/aspnetcore/diagnostics/aspdepr002.md @@ -0,0 +1,96 @@ +--- +title: ASPDEPR002 warning +description: Learn about the obsoletions that generate compile-time warning ASPDEPR002. +ai-usage: ai-assisted +monikerRange: '>= aspnetcore-10.0' +ms.date: 03/03/2026 +uid: diagnostics/aspdepr002 +ms.author: tdykstra +author: tdykstra +f1_keywords: + - aspdepr002 +--- +# ASPDEPR002: `WithOpenApi` is deprecated + +The extension methods are deprecated starting in .NET 10. Using these methods produces the `ASPDEPR002` diagnostic at compile time. The functionality they provided is now available through the built-in OpenAPI document generation pipeline. + +## Workarounds + +Remove `.WithOpenApi()` calls from your code. + +- If you used `Microsoft.AspNetCore.OpenApi` for document generation, use the `AddOpenApiOperationTransformer` extension method instead. + + Before: + + ```csharp + using Microsoft.AspNetCore.OpenApi; + + var builder = WebApplication.CreateBuilder(); + var app = builder.Build(); + + app.MapGet("/weather", () => ...) + .WithOpenApi(operation => + { + // Per-endpoint tweaks + operation.Summary = "Gets the current weather report."; + operation.Description = "Returns a short description and emoji."; + return operation; + }); + + app.Run(); + ``` + + After: + + ```csharp + using Microsoft.AspNetCore.OpenApi; + + var builder = WebApplication.CreateBuilder(); + var app = builder.Build(); + + app.MapGet("/weather", () => ...) + .AddOpenApiOperationTransformer((operation, context, ct) => + { + // Per-endpoint tweaks + operation.Summary = "Gets the current weather report."; + operation.Description = "Returns a short description and emoji."; + return Task.CompletedTask; + }); + + app.Run(); + ``` + +- If you used `Swashbuckle` for document generation, use the `IOperationFilter` API. +- If you used `NSwag` for document generation, use the `IOperationProcessor` API. + +## Suppress a warning + +If you must use the deprecated APIs, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable ASPDEPR002 + +// Code that uses deprecated API. +// ... + +// Re-enable the warning. +#pragma warning restore ASPDEPR002 +``` + +To suppress all the `ASPDEPR002` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);ASPDEPR002 + + +``` + +## See also + +- [Deprecation of WithOpenApi extension method](../breaking-changes/10/withopenapi-deprecated.md) diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 237c2c6c2db6..77ac3e4bdd5c 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -1652,8 +1652,10 @@ items: - name: Azure and IIS errors reference uid: host-and-deploy/azure-iis-errors-reference - name: Code analysis - uid: diagnostics/code-analysis items: + - name: Overview + displayName: code analysis + uid: diagnostics/code-analysis - name: ASP0000 uid: diagnostics/asp0000 - name: ASP0001 @@ -1740,8 +1742,10 @@ items: uid: diagnostics/mvc1005 - name: MVC1006 uid: diagnostics/mvc1006 - - name: RDG diagnostics - displayName: aot, RDG diagnostics + - name: RDG diagnostics + items: + - name: Overview + displayName: aot, rdg diagnostics uid: fundamentals/aot/request-delegate-generator/rdg-ids - name: RDG002 uid: fundamentals/aot/request-delegate-generator/diagnostics/rdg002 @@ -1765,6 +1769,13 @@ items: uid: fundamentals/aot/request-delegate-generator/diagnostics/rdg012 - name: RDG013 uid: fundamentals/aot/request-delegate-generator/diagnostics/rdg013 + - name: ASPDEPR diagnostics + items: + - name: Overview + displayName: aspdepr diagnostics + uid: diagnostics/aspdepr-ids + - name: ASPDEPR002 + uid: diagnostics/aspdepr002 - name: Data access items: - name: Tutorials