While working with the .NET framework, it is common to come across [Obsolete(“message”)] attribute used in .NET APIs. This would signify an API which is no longer supported or more likely to be deprecated in the near future. With the continuous evolution of .NET, it is very common to deprecate APIs which can be replaced by better substitutes. However, there are some shortcomings of this approach.
[Obsolete("This type previously indicated an unspecified fatal error in the runtime. The runtime no longer raises this exception so this type is obsolete.")]
public sealed class ExecutionEngineException : SystemException
The above code decorated with the [Obsolete(“message”)] attribute returns only one warning code saying the class is obsolete.
- We end up getting only a warning message without any additional scope for further documentation, if required. For obsolete APIs, it is always the code – CS0618.
- If we have already referenced an assembly in our project and it is updated with the Obsolete attribute, the consuming project needs to be updated with the new updated version of the assembly.
Since .NET framework has always been in continuous development, the above 2 points can be major detriments when you would have to update your assemblies each time there is a new deprecated API.
Dealing With Deprecated APIs Using Microsoft.DotNet.Analyzers.Compatibility package :
There is a better option though. You can use the Microsoft.DotNet.Analyzers.Compatibility to target DE ( deprecated ) error codes. This is shipped as a Nuget package. The below screenshot shows how you can add it to your project.
- In your project, right click “References” and select “Manage Nuget Packages” option.
- Go to Browse.
- Add “Microsoft.DotNet.Analyzers.Compatibility” package to your project.
- You can then select the “Add analyzer” option under “References” and select the 2 DLLs from this package.
- Add the “Microsoft.DotNet.Analyzers.Compatibility.dll” and “Microsoft.DotNet.Csv.dll” to the analyzer.
Once this is done, you will see the following under analyzers. Look at the “DE” error codes.
Let us now see how we can use this Nuget package during development. Add the System.Net.HttpWebRequest class to your code. You will immediately see the squiggly lines below the class with the warning description and documentation URL as shown in the below snapshot :
You can click the warning code and visit the documentation page on GitHub.
Targeting Cross-Platform Issues :
Similarly, a .NET framework API might not be supported on other platforms like iOS or Linux and the following category of warnings provides documentation on this.
PC001: API not supported on all platforms
Note : This is a pre-release version and at version – v0.2.12-alpha at the time of writing this post.
Important Reference Links :
Source Code for the Nuget package
Microsoft documentation on this topic
.NET CORE 3.0 and C# 8.0
