Page 68 - MSDN Magazine, December 15, 2017

Figure 8 Suppressing Warnings for Use of Non-Portable APIs
Tooling warns when non-portable APIs are used. We provide an API Analyzer (bit.ly/2iV9n7o) that detects usage of non- portable APIs and warns you as you’re developing your code.
Let’s see how API Analyzer would work in the context of Fabrikam’s shared library. The analyzer is provided in the NuGet package Microsoft.DotNet.Analyzers.Compatibility. After it’s installed, the error list shows warnings in the GetLoggingPath method, as shown in Figure 7.
It informs you that both OpenSubKey and GetValue aren’t avail- able and will throw PlatformNotSupportedException on Linux and macOS. It’s worth pointing out that this analyzer is powered by Roslyn, which means it provides immediate feedback and doesn’t require you to compile. This is very powerful as you’re getting information as you’re developing your code, so you can focus on the task at hand without having to remember to run a tool after the fact.
To address the warning, you’ll need to add the platform guard and then suppress the warning, as shown in Figure 8.
My preference is to use the global suppression file (which will suppress this warning for the method you’re currently in but records that suppression in a secondary file) as opposed to using the in-source option (which will put a #pragma suppression around the current statement), but the choice is yours. While the analyzer provides a great interactive experience in Visual Studio,
Figure 9 Configuring the Severity Level for Non-Portable APIs 64 msdn magazine
it’s by no means tied to Visual Studio or to the concept of an IDE. Analyzers are run by the compiler. If you checked in the code and submitted it to your Linux CI server or just compiled it from the command line, you’d get the same warnings:
$ dotnet build
Logger.cs(17,43): warning PC001: RegistryKey.OpenSubKey(string) isn't supported on Linux, MacOSX
Logger.cs(19,18): warning PC001: RegistryKey.GetValue(string) isn't supported on Linux, MacOSX
Fabrikam.Shared -> /home/immol/Fabrikam.Shared/bin/Debug/netstandard2.0/ Fabrikam.Shared.dll
Build succeeded.
The analyzer is also configurable as to whether these are mere suggestions, warnings or even errors. The default is warnings, but, as Figure 9 shows, you can configure them to be errors, too.
Wrapping Up
Each migration is different. Before porting to .NET Core, you should understand your goals and what you want the migration to accomplish. Use the API Port tool to assess how portable your existing code is.
Plan your migration not as a single monolithic operation but rather as a series of steps along the migration path. Don’t assume you can port an existing application all at once. This allows you to realize value as you go and learn more about potential issues and how your architecture needs to change to become cross-platform.
Take advantage of the Windows Compatibility Pack, which provides access to about 40 .NET Framework components and can be referenced from both .NET Core and .NET Standard proj- ects. However, definitely keep in mind that this package includes Windows-only components. If you plan to go cross-platform, use the API Analyzer, which will inform you whenever you’re using non-portable APIs. Guard the calls to these APIs accordingly and provide sensible fallback logic, then suppress the warning.
And, last, keep in mind that not porting is also an option. The .NET Framework is still the best choice for certain kinds of apps, particularly desktop applications. n
Immo Landwerth is a program manager working on the .NET platform team at Microsoft. He specializes in the base class library, API design and .NET Standard.
thanks to the following Microsoft technical experts who reviewed this article: Wes Haggard and Dan Moseley
.NET