Roslyn-analyzers: Are the FlowAnalysis.Utilities / AnalyzerUtilities APIs ready to be consumed by 3rd party analyzers?

[andrei-epure-sonarsource]

Analyzer package
Microsoft.CodeAnalysis.FlowAnalysis.Utilities / Microsoft.CodeAnalysis.AnalyzerUtilities

We are considering the option to use the data flow analysis engine from Microsoft.CodeAnalysis.FlowAnalysis.Utilities/ Microsoft.CodeAnalysis.AnalyzerUtilities and we have a few questions:

1. Is the package meant to be used as a library by 3rd party analyzers? Is the API stable enough for this? I've noticed that there is a PublicAPI.Shipped.txt empty file and a PublicAPI.Unshipped.txt file with all APIs, but I don't know how these are used and whether before each release you move the APIs from Unshipped to Shipped?
2. We've seen that the package doesn't declare explicit dependencies, however we were wondering what dependencies there are between the package and the Roslyn lifecycle?
3. Do you have more documentation about the APIs (more than the one on Writing dataflow analysis based analyzers)?

Note: we've also asked this on discord, and were guided to post the question here. Please let me know if we need to use a different channel to ask this sort of questions.

Thank you.

[Evangelink]

Tagging @mavasani

[mavasani]

Is the package meant to be used as a library by 3rd party analyzers?

Yes, it is in fact used by few 3rd party analyzers.

Is the API stable enough for this? I've noticed that there is a PublicAPI.Shipped.txt empty file and a PublicAPI.Unshipped.txt file with all APIs, but I don't know how these are used and whether before each release you move the APIs from Unshipped to Shipped?

Yes and No. The API ships with a weak contract - we try to avoid breaking changes as much as possible, but the API is still not ready for a fully non-breaking support. Given that this package would be an analyzer dependency, you will never be broken unless you explicitly decide to upgrade to a newer package.

We've seen that the package doesn't declare explicit dependencies, however we were wondering what dependencies there are between the package and the Roslyn lifecycle?

This package only depends on the core Microsoft.CodeAnalysis NuGet package and the version of the package will always match the version of Microsoft.CodeAnalysis NuGet package that it is built against, and it will work fine on whichever VS/compiler versions that the corresponding Microsoft.CodeAnalysis NuGet package works on.

Do you have more documentation about the APIs

Not really, feel free to ping here if you need more info about specific APIs.

One suggestion is to try and mimic the approach used by PlatformCompatilibity analyzer and use the newly added GlobalFlowStateAnalysis, which allows tracking a single data value at each operation in the entire flow graph. Though more restricted compared to other flow analyses (which allow tracking multiple entities), it's implementation is way more simpler for writing new custom dataflow analyses. For example, the PlatformCompatilibity analyzer just had to implement the following 2 files to get a completely new custom data flow analysis implementation:

1. OperationVisitor: https://github.com/dotnet/roslyn-analyzers/blob/master/src/NetAnalyzers/Core/Microsoft.NetCore.Analyzers/InteropServices/PlatformCompatibilityAnalyzer.OperationVisitor.cs
2. Abstract value: https://github.com/dotnet/roslyn-analyzers/blob/master/src/NetAnalyzers/Core/Microsoft.NetCore.Analyzers/InteropServices/PlatformCompatibilityAnalyzer.Value.cs

[andrei-epure-sonarsource]

Thank you, @mavasani . I have some additional questions, mainly from the context of backwards compatibility. To give some context, our analyzers are currently compatible with VS 2015 Update 3 and higher, and historically we have tried to keep backwards compatibility with what VS versions are still supported by Microsoft.

By checking the sources we have noticed that Microsoft.CodeAnalysis.FlowAnalysis.Utilities implicitly relies on Roslyn 2.9.0 (Microsoft.CodeAnalysis) and that Microsoft.CodeAnalysis.AnalyzerUtilities relies on Roslyn 3.3.0.

1. Does this mean that by using the latest version of AnalyzerUtilities we will only be able to offer support for Visual Studio 2019 version 16.3, and newer?
2. Are there plans in the future to have a Roslyn minimum supported version? Or can we expect drops of compatibility between versions?

This package only depends on the core Microsoft.CodeAnalysis NuGet package and the version of the package will always match the version of Microsoft.CodeAnalysis NuGet package that it is built against, and it will work fine on whichever VS/compiler versions that the corresponding Microsoft.CodeAnalysis NuGet package works on.

Regarding forward-compatibility, is there a possibility that the Microsoft.CodeAnalysis.AnalyzerUtilities may rely on Roslyn CFG API functionalities that may change in future versions of Roslyn (does the Roslyn CFG API design consider backwards compatibility with older versions)?

Thank you.

[Evangelink]

ping @mavasani

[mavasani]

Does this mean that by using the latest version of AnalyzerUtilities we will only be able to offer support for Visual Studio 2019 version 16.3, and newer?

Yes, that is correct. Microsoft.CodeAnalysis.AnalyzerUtilities needs Visual Studio 2019 version 16.3 (16.8 recommended) and Microsoft.CodeAnalysis.FlowAnalysis.Utilities needs Visual Studio 2019 version 15.9

Are there plans in the future to have a Roslyn minimum supported version? Or can we expect drops of compatibility between versions?

There are no plans as of now to publish a fully supported package with guaranteed no API breaks in future. This package is mainly a helper package which will likely have APIs breaks as you move forward.

[mavasani]

does the Roslyn CFG API design consider backwards compatibility with older versions

I believe that is the case, the CFG will not have any breaking API changes, though the underlying CFG operations and basic block structure can change between Roslyn versions. Feel free to file a new issue on Roslyn repo if you have more questions about CFG API or structure itself.

[Evangelink]

@andrei-epure-sonarsource I will let you close this ticket if you think all your questions have been answered.