CoreCompatibilyzer

Welcome to CoreCompatibilyzer, a static .Net code analyzer that checks .Net Framework code for compatibility with .Net Core 2.2. To run the analysis, you can either install the CoreCompatibilyzer VSIX extension or use the console runner. For more information, see the CoreCompatibilyzer Release Notes.

Analysis

The analysis itself is not very complex. All API uses are checked against a list of the APIs that are incompatible with .Net Core 2.2. An API is marked as incompatible if any of the following are in the list of incompatible (also called banned) APIs: the API, its containing types, or the containing namespace. The list of incompatible APIs is stored in the tool's .\ApiData\Data subfolder in the BannedApis.txt file. The list of allowed APIs is located in the WhiteList.txt file in the same folder. The allowed APIs are not reported by the analyzer even if they are recognized as incompatible. Sometimes code may contain types declared in system namespaces, such as System.Web.Compilation.CustomBuildManager, and we don't want to report these types. The open list of APIs loaded by the application at runtime provides an effortless way to configure the analysis.

You can forbid the use of some API by adding it to the list of banned APIs or allow an API that is currently banned by adding it to the list of allowed APIs. The format of API records is described in the next section.

For the full list of diagnostics, see Summary.

API Format

The API records in both files have the same API format, which is based on the DocID format: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#id-strings. This format is chosen due to its convenience: It is widely used by .Net technology, and Roslyn already has built-in functionality to generate DocID for APIs. However, the Doc ID format was slightly modified as follows to store more information about the API:

• In the full API name, the namespace is separated from the containing type names with a special hyphen (-) separator. This allows us to parse API name parts and calculate which part is the namespace name which is impossible to do in all cases for the standard DocID format. Here is an example.

  T:System.Data-UpdateException

• If the API name includes nested types, then their names are separated by the plus sign (+) to simplify the parsing of the API name into parts, as shown below.

  T:Microsoft.AspNet.Mvc.ModelBinding-ModelStateDictionary+PrefixEnumerable

• There are two kinds of incompatible APIs: an API that is missing in the .Net Core 2.2, and an API that is obsolete in the .Net Core 2.2. The latter kind won't cause compilation errors after migration to .Net Core 2.2, but they throw exceptions when they are called at runtime. These APIs are marked with a special character, O, at the end, marking it as obsolete (as shown in the following example).

M:System-Uri.EscapeUriString(System.String) O

CoreCompatibilyzer Console Runner

The console runner provides several command-line arguments that configure the static code analysis and the format of the report generated by the console runner. You can run --help to see the description of all arguments in the console window. Below is the list of command-line arguments.

Argument	Description
codeSource (position 0)	Required. A path to the code source that will be validated. The term code source is a general term describing components and services that can provide source code to the tool. Currently, the supported code sources are C# projects and C# solutions.
-v, ‑‑verbosity	By using this optional parameter, you can explicitly specify logger verbosity. The allowed values are taken from the "Serilog.Events.LogEventLevel enum. The allowed values are Verbose, Debug, Information, Warning, Error, and Fatal. By default, the logger will use the Information verbosity.
‑‑noSuppression	When this optional flag is specified, the code analysis will not take into consideration suppression comments that are present in the code and will report suppressed diagnostics.
‑‑msBuildPath	By using this optional parameter, you can explicitly provide a path to the MSBuild tool that will be used for analysis. By default, MSBuild installations will be searched automatically on the current machine and the latest found version will be used.
‑‑withUsages	By default, the report output includes only a shortened list of the used banned APIs. Set this flag to include the locations of the used banned API calls in the report.
‑‑withDistinctApis	If this flag is set, the report will start with a list of all distinct APIs used by the code source.
‑‑showMembersOfUsedType	When the report is displayed in a shortened form without the locations of the banned API calls, it can be shortened even more. By default, the report will not display banned type member APIs that have been used if their containing type is also banned and used by the code being analyzed. Set this flag to include the banned type member APIs in the report along with their containing type. This flag does not affect the report when the --withUsages argument is specified.
-g, ‑‑grouping	By using this parameter, you can specify the grouping of API calls. By default, there is no grouping. You can specify the grouping of the reported API calls by namespaces, types, APIs, or any combination of them as follows:
	- Add f or F to group the API uses by source files.
	- Add n or N to group the API uses by namespaces.
	- Add t or T to group the API uses by types.
	- Add a or A to group the API uses by APIs.
-f, ‑‑file	The name of the output file. If the name is not specified, the report will be generated to the console window.
‑‑outputAbsolutePaths	When the report is set to generate the detailed list of banned APIs with their uses, this flag regulates how the locations of API uses will be generated. By default, file paths in locations are relative to the containing project directory. However, if this flag is set, the absolute file paths will be used. This flag does not affect the report when the --withUsages argument is not specified.
‑‑format	The report output format, which can be one of the following:
	- text to generate the report in plain text. This is the default output mode.
	- json to generate the report in JSON format.
‑‑help	Displays the description of arguments.
‑‑version	Displays the version information.