Your New Virtual API Review Assistant

This post has been republished via RSS; it originally appeared at: Channel 9.

So there you are, writing a cross platform .NET Core app. You've found this great API that solves a big problem for you.

You deploy and your project gacks!

What, that great API isn't available on that other platform? Doh!

Grrrr.... There's got to be some way that Visual Studio can help you with this kind of thing? Can't it, or an extension of some kind, identify API's that are not available on the other platforms? Maybe also help with depreciated API's too?

How about something that can do this?

The .NET Team thought the same thing!

Introducing API Analyzer

Have you ever wondered which APIs are deprecated and which should you use instead? Or have you ever used an API and then found out it didn’t work on Mac or Linux? Have that ever happened to you too late when a major part of your code is already implemented and refactoring is way too hard? Both of these problems can be avoided with the new API Analyzer, which allows you to get live feedback on API usage and warns about potential compatibility issues and calls to deprecated APIs.

TL;DR You can now have a virtual API expert!

API Analyzer is a Roslyn analyzer that comes as NuGet package. After referencing it in your project, it automatically starts monitoring your code and squiggles problematic API usage. You can get suggestions on possible fixes by clicking on the light bulb, which also includes the ability to suppress the warnings. Think of the API Analyzer as an expert that is looking over your shoulder and gives you feedback as you code.

...

Discovering deprecated APIs

The .NET Framework is a large product that is getting constantly upgraded to better serve customer needs, implement innovative approaches, and fix issues. So it’s natural to deprecate some APIs and replace them with new ones. For example, we have build three versions of the .NET Framework networking stack. The latest version, HttpClient, is intended to replace WebClient and HttpWebRequest. As a developer, how do I know that I should use HttpClient instead of WebClient? There is  documentation, but we usually look in documentation only after we face some problems, when code is already implemented with an old API and refactoring is annoying. So it is very beneficial to be prompted that you’re using a deprecated API at its first appearance in your code.

...

 

Discovering cross-platform issues

While .NET is a cross platform stack, some of its APIs aren’t available on all platforms. There are also types that are present on all platforms, but some members are not supported by each platform. A good example is Console.WindowWidth, which works on Windows but not on Linux and macOS. 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.

The experience of analyzer handling cross-platform issues is very similar to deprecated APIs: you’ll see a squiggle and a diagnostic ID in Error List window, and you will be able to suppress warning by right clicking and selecting Quick Actions and Refactorings. You have the same suppression options as with deprecated APIs but you also have the option to suppress warnings for specific platforms. This is useful if you’re only planning to support your code on a specific subset of platforms (e.g. only Windows and Linux, but not macOS). To do so, you just need to edit your project file and add a property PlatformCompatIgnore that lists all platforms to be ignored:

...

Supported diagnostics

Right now the analyzer handles the following cases:

• 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)

...

Command Line & Continuous Integration (CI)

All these diagnostics are not only available in the IDE, but also when you build on the command line, which includes the CI server. This allows you to enforce whichever policy you set for the individual diagnostics across the entire team.

Summary

API Analyzer helps developers to be informed right away if they are about to use a deprecated API or when depend on non cross-platform functionality. Being notified immediately eliminates a need of refactoring the code in the future and results in  higher quality applications and libraries.

[Click through to read the entire post]

And of course, it's open source!

https://github.com/dotnet/platform-compat

Follow @CH9
Follow @coding4fun
Follow @gduncan411