dotnet / dotnet/runtime

[API Proposal]: Add Obsolete as info diagnostic

Open
#128,861 108 comments 3 reactions 0 assignees View on GitHub
api-suggestion area-System.Runtime
Dominant language
C#
Stars
18.3k
Forks
5.6k
PR merge metrics
PR metrics pending

Description

### Background and motivation

APIs are sometimes "soft-obsoleted", meaning we don't want users to use them in new code, but an Obsolete warning is too much of a heavy tool as there is nothing wrong with the old API - it will still work, though we'd still ideally like consumers to know that a newer API exists as an alternative. For example, the old API won't be expanded upon anymore. In these cases currently, sometimes we do nothing, sometimes we create a custom analyzer, and sometimes we do use the heavy Obsolete tool as a warning, even if it's not justified.

My proposal is that we'd be able to mark APIs as obsolete only as an information/suggestion in the IDE, so that when people are writing new code, they would be alerted to the fact that a newer alternative exists, but with no warning. This would help in not having to create custom analyzers for such cases, as is currently often done.

~~For example, I would put this on Math, as moving on, the methods will be on the primitive types themselves~~

This would require coordination with [@dotnet/roslyn](https://github.com/dotnet/roslyn).

### API Proposal

```c#
namespace System
{
public sealed partial class ObsoleteAttribute
{
public ObsoleteAttribute(string? message, DiagnosticLevel level);

public DiagnosticLevel DiagnosticLevel { get; }
}
}

namespace System.Diagnostics.CodeAnalysis
{
public enum DiagnosticLevel // or DiagnosticSeverity
{
Info,
Warning,
Error,
}
}
```

### API Usage

```c#
[Obsolete("A newer alternative exists at... This API won't be evolved any longer.", DiagnosticLevel.Info)]
class C()
{
}
```

If this were to be accepted, we'd be able to remove a number of analyzers.

### Alternative Designs

An alternative to DiagnosticLevel would be DiagnosticSeverity.

### Risks

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.