Obsolete API warning docs for .NET 10+ on aspnetcore.docs

Abierto
  • ¿Algo no está bien?
#36,299 1 comentario 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@tdykstra ya está trabajando en esto.

Desde el 1/4/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

10.0 Pri1 seQUESTered

Obsolete API warnings for ASP.NET Core need to be created in the aspnetcore.docs repo starting with .NET 10 and on.

Currently documentation on diagnostics warning for ASP.NET Core are located here, which also seems like a good location for adding the Obsolete API warnings:
:
https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/diagnostics

The existing documentation on diagnostics warning for ASP.NET Core uses 3 prefixes, (although a bit cryptic):
They are: asp, bl and mvc
Examples:
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/diagnostics/asp0028.md
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/diagnostics/bl0001.md
https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/diagnostics/mvc1000.md

The new one would use the warning ID as the name of the file:
So for warning ID:
ASPDEPR008.md
The file name would be the following which should be lower case:
aspdepr008.md

The TOC lists these under Code Analysis, but we might consider changing that to Compiler Diagnostics instead to fit them all under one description that makes sense.

What exists now:

No prior documents on obsolete API's for the ASP.NET core API's exist at all as their own topics.  They exist in the breaking change documentation and the breaking change issues filed on the source, but it is not available in separate topics which would be much more accessible, folks are directed right the individual warning and what to do for it, rather than a larger breaking changes doc that includes possibly multiple listed obsolete API's.

For this issue, document custom obsoletion ID warnings with the obsolete API (sometimes groups) that use them in the current ASP.NET Core for .NET 10 branch, and then I am done.

The process will be (as verified with gewarren):

How to find the ASP.NET Core obsolete API for .NET 10 that need to be documented

A. Search for the string "REMOVED" in all "*.unshipped.txt" files in the 10.0 branch.
or
B. Search across the source code for use of ObsoleteAttribute to get a list of everything to document and either compare that to what has been documented so far (which has been up to .NET 9 on the donet docs repo) or cross check against when the attribute was added.

Example:
[Obsolete("IWebHost is obsolete. Use IHost instead. For more information, visit https://aka.ms/aspnet/deprecate/008.", DiagnosticId = "ASPDEPR008", UrlFormat = Obsoletions.AspNetCoreDeprecate008Url)]

After you find obsoletion ID in the .NET 10 branch of the ASP.NET Core source.
  1. Identify what obsolete API share that ID and create one article for one ID that covers all the obsoleted API related.
  2. The contents of what should go in that article can be derived from a breaking changes issue the product team created (if available) which usually includes information such as work arounds or API to use instead of the obsolete API.
    -- Also follow the blame to the PR (or its issue) where the ID was added and find the reasoning there.
  3. The contents should model pretty much the Syslibxxxx examples you showed us as the closest model we can point to as an example of what these articles would look like.
  4. Repeat until every ID in the ASP.NET Core source code for the .NET 10 branch (so I have the latest), has been documented with an API obsolete warning page.
    Only center on for ID's for obsolete API, nothing else for this issue.

Associated WorkItem - 544742

Lenguaje dominante
C#
Estrellas
13.1k
Forks
24.5k
Merge medio
3 d 6 h
PR fusionados (30 d)
210

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de dotnet/AspNetCore.Docs

Todos los issues de dotnet/AspNetCore.Docs

Issues similares

Más issues de C#

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.