News

Roslyn Analyzer IDs Problem .NET Core, .NET Standard APIs

• By David Ramel
• 11/07/2017

Microsoft launched a Roslyn-based analyzer that works in Visual Studio to flag problematic .NET Core and .NET Standard APIs that might be deprecated or incompatible with certain platforms.

After referencing the NuGet package for the new API Analyzer, developers working in Visual Studio are notified when they code in a call to an API that might cause problems.

Upon detecting a call to an API that has been deprecated, for example, the tool will "squiggle" the reference and present the familiar lightbulb helper that can be clicked to see more detailed information about the problematic API and possible alternative APIs that should be used instead. Programmers can click on the API error ID to go to a Web page that details why it was deprecated and the use of alternative APIs.

Microsoft indicated this is a crucial capability in the vast and evolving .NET ecosystem where APIs are subsumed with newer variants that developers might not know about. As an example, Microsoft pointed out the .NET Framework networking stack has evolved from HttpWebRequest to WebClient to the newer HttpClient.

However, a coder who has been working with WebClient might not even be aware that HttpClient API is now the recommended option. Another example is the ArrayList class, which has been deprecated in favor of List <T>. A developer might have consulted documentation that uses ArrayList without paying attention to the date of the guidance or any notes that it has been replaced by newer documentation.

Although Microsoft has imposed more order on the wide-ranging family of .NET APIs with the new .NET Standard 2.0 (which details all the APIs that .NET implementations must adhere to for consistent API compatibility and usage) and .NET Core 2.0 (the latest cross-platform, open source .NET implementation), developers can still get into problems that the API Analyzer can get them out of.

For example, in addition to flagging deprecated APIs, the tool can also alert to compatibility problems such as an API that might work on one platform but not another, despite Microsoft's efforts to provide cross-platform APIs.

"A good example is Console.WindowWidth, which works on Windows but not on Linux and macOS," said Microsoft's Olia Gavrysh in a blog post last week. "If your app were to run on Linux or maxOS, a call to Console.WindowWidth would throw a PlatformNotSupportedException. API Analyzer will notify you that the API is not supported, which will help you to address the problem right away while you're still editing the code.

"Even if you are targeting only one platform at this moment, your business goals might change in the future and you will have to spend a lot of time going through your code figuring out if there are any cross-platform problems. In contrast, API Analyzer will highlight all the problematic parts right away."

In some cases, a developer might want to go ahead and use a flagged API for some reason, so the tool is configurable, letting coders specify which warnings to suppress. In the case of incompatible APIs, the developer can configure the tool to suppress warnings on specific platforms.

The API Analyzer is based on the analysis capabilities of the .NET Compiler Platform (commonly called Roslyn), which opened up the internals of Microsoft's C# and VB.NET compilers for programmatic use cases just like this. That means F# code isn't supported.

The list of supported diagnostics right now (work continues on the tool, which is still in preview) and their associated codes is:

• Usage of a .NET Standard API that will throw PlatformNoSupportedException (PC001)
• Usage of a .NET Standard API that isn't available on the .NET Framework 4.6.1 (PC002)
• Usage of a native API that doesn't exist in UWP (PC003)
• Usage of an API that is marked as deprecated (DEXXXX)

When one reader of last week's post wondered why the tool was provided as a NuGet package rather than as part of the .NET SDK, Microsoft's Immo Landwerth explained it was to collect feedback immediately and quickly ship updates. "Requiring an SDK update/VS update makes it significantly harder to get people to use on their real world projects right away," he said.

"We could have made it a VSIX [extension] but that has two problems: they don't participate in command line builds, they don't travel to the CI system, and the analyzer wouldn't be able to get access to the build environment (target framework) without making it a system wide install (MSI)."

The API Analyzer's NuGet listing shows 450 downloads, averaging 37 per day. The tool's source code is available on GitHub, where the project's repository has garnered 77 stars and shows two contributors: Landwerth and Paulo Janotti.