Our website uses cookies to enhance your browsing experience.
Accept
to the top
close form

Fill out the form in 2 simple steps below:

Your contact information:

Step 1
Congratulations! This is your promo code!

Desired license type:

Step 2
Team license
Enterprise license
** By clicking this button you agree to our Privacy Policy statement
close form
Request our prices
New License
License Renewal
--Select currency--
USD
EUR
* By clicking this button you agree to our Privacy Policy statement

close form
Free PVS‑Studio license for Microsoft MVP specialists
* By clicking this button you agree to our Privacy Policy statement

close form
To get the licence for your open-source project, please fill out this form
* By clicking this button you agree to our Privacy Policy statement

close form
I am interested to try it on the platforms:
* By clicking this button you agree to our Privacy Policy statement

close form
check circle
Message submitted.

Your message has been sent. We will email you at


If you haven't received our response, please do the following:
check your Spam/Junk folder and click the "Not Spam" button for our message.
This way, you won't miss messages from our team in the future.

>
>
Analyzing Visual Studio / MSBuild / .NE…
menu mobile close menu
Analyzer diagnostics
General Analysis (C++)
General Analysis (C#)
General Analysis (Java)
Micro-Optimizations (C++)
Diagnosis of 64-bit errors (Viva64, C++)
Customer specific requests (C++)
MISRA errors
AUTOSAR errors
OWASP errors (C#)
Problems related to code analyzer
Additional information
toggle menu Contents

Analyzing Visual Studio / MSBuild / .NET projects from the command line using PVS-Studio

Dec 12 2023

This document covers the usage of command-line utilities for the analysis of MSBuild projects (.vcxproj / .csproj) and Visual Studio solutions.

This document covers the usage of command line utilities. Usage of plugins for Visual Studio and JetBrains Rider is described in the following documentation sections: "Getting acquainted with the PVS-Studio static code analyzer on Windows", "Using PVS-Studio with JetBrains Rider".

The command-line analyzer of MSBuild projects has various names on different platforms supported by the analyzer:

  • PVS-Studio_Cmd (analysis of solutions, C#, C++ projects on Windows);
  • pvs-studio-dotnet (analysis of solutions, C# projects on Linux / macOS);

The features described below are relevant for both utilities. Examples with PVS-Studio_Cmd / pvs-studio-dotnet are interchangeable unless explicitly stated otherwise.

Note. To analyze C++ projects that don't use the MSBuild build system, on Windows use the compilation monitoring system or direct integration of the analyzer into the build system. Analysis of C++ projects on Linux / macOS is described in detail in this section of the documentation.

Running analysis of sln and csproj/vcxproj files

Command line utilities are unpacked to the following directories by default:

  • PVS-Studio_Cmd.exe
    • Windows: "C:\Program Files (x86)\PVS-Studio\";
  • pvs-studio-dotnet
    • Linux: "/usr/share/pvs-studio-dotnet/";
    • macOS: "/usr/local/share/pvs-studio-dotnet".

The '--help' command displays all available arguments of the analyzer:

PVS-Studio_Cmd.exe --help

Here is an example of how to check 'mysolution.sln':

PVS-Studio_Cmd.exe -t "mysolution.sln" -o "mylog.plog"

Let's look at the main arguments of the analyzer:

  • --target (-t): required parameter. Allows you to specify the object to be tested (sln or csproj/vcxproj file);
  • --output (-o): path to the file, where the analysis results will be written. If this parameter is omitted, the analyzer report file will be created next to the file specified using the '--target' flag. The analyzer report can be saved in 2 formats: .json and. plog. The format type is determined by the specified extension. By default, without specifying this flag, the report will be generated in the .plog format on Windows, and in the .json format on Linux and macOS;
  • --platform (-p) and --configuration (-c): the check will be run for the specified platform and configuration. If these parameters are not specified, the first available "platform|configuration" (when checking the sln file) pair will be selected or "Debug|AnyCPU" (when checking a separate csproj project) or "Debug|Win32" (when checking a separate vcxproj project);
  • --sourceFiles (-f): path to the text file containing a list of paths to source files for the analysis (each must be on a separate line). The argument cannot be used with the '-- regenerateDependencyCacheWithoutAnalysis '(-W) flag in the same command. Relative and absolute paths are supported. In this mode, when analyzing C and C++ files, a cache file of compilation unit dependencies on header files is created (and used). You can control its location using the '--dependencyRoot' (-D) flag. Note: when this argument is used with the '--selectProjects' (-S) and/or '--excludeProjects' (-E) arguments, the project filtering is applied first, and then the files from '--sourceFiles' (-f) are searched and analyzed among the remaining project files;
  • --regenerateDependencyCache (-G): generates or updates compilation dependency cache for all project source files that is used together with the '--sourceFiles' (-f) flag and starts analysis for all project source files. You can use the '--selectProjects' (-S) and the '--excludeProjects' (-E) flags to filter out projects. Passing the '--sourceFiles' (-f) flag along with this flag causes a complete regeneration of the dependency caches for all project source files, and the analysis is done only for the list of files passed in '--sourceFiles' (-f);
  • --regenerateDependencyCacheWithoutAnalysis (-W): generates or updates the compilation dependency cache for all project source files that is used together with the '--sourceFiles' flag (-f), without running analysis. You can use the '--selectProjects' (-S) and '--excludeProjects' (-E) flags to filter out projects. The argument cannot be used with the '--sourceFiles' (-f) flag;
  • --dependencyRoot (-D): an optional path to the directory where the source file dependency caches are located. Works in addition to the '--sourceFiles' (-f) and '--regenerateDependencyCache' (-G) flags;
  • --dependencyCacheSourcesRoot (-R): an optional path to specify the root directory of relative source file paths in dependency caches generated with '--sourceFiles' (-f) and '--regenerateDependencyCache' (-G) flags;
  • --settings (-s): path to the PVS-Studio configuration file. If this parameter is omitted, the Settings.xml file will be used, located in the directory "%AppData%\PVS-Studio\" on Windows or "~/.config/PVS-Studio/" on Linux / macOS. These same settings files are used by plugins (Visual Studio, Rider), which makes it possible to edit them using the PVS-Studio plugin interface in these IDEs. Please note that for the analyzer to work under Windows, the settings file must contain registration information. Various ways to enter a license are described here. Depending on the settings file used, the following rules apply:
    • when using the default settings file, it must contain registration information;
    • if you explicitly specify the path to the settings file, the registration information must be written either in the specified settings file or in the default settings file;
  • --licFile (-l): path to the PVS-Studio license file. This flag is available only in pvs-studio-dotnet. If the parameter is omitted, the PVS-Studio.lic license file will be used, which is located in the "~/.config/PVS-Studio/ " directory.
  • --suppressAll (-a): add unsuppressed warnings in suppress files of corresponding projects (disabled by default). If this flag is present, all messages will be added to the suppress warnings base after saving the check result. The flag supports 5 operating modes.
    • SuppressOnly adds messages from the passed analyzer report to the suppress files without running the analysis;
    • AnalyzeAndSuppress runs the analysis, saves the analyzer report, and only after this suppresses the messages found in it. This mode allows you to get a report from the analyzer on regular runs, which contains only new messages for the changed \ written code, i.e. new messages get into the new log and get immediately suppressed - they won't be issued during the subsequent check. However, if you still need to view the old messages (without rechecking), a file with the full check report (only for .plog analyzer reports) will be saved next to the analyzer report containing new messages. Read more about message suppression mode in this section of the documentation;
  • --sourceTreeRoot (-e): the root part of the path that PVS-Studio will use when generating relative paths in diagnostic messages. Setting this parameter overrides the 'SourceTreeRoot' value in the PVS-Studio settings;
  • --incremental (-i): incremental analysis mode. For more information about incremental analysis in PVS-Studio, see the section "PVS-Studio incremental analysis mode". Note, that this mode is available only under PVS-Studio Enterprise license. There are following modes of incremental analysis available:
    • Scan - analyze all dependencies to determine, which files will be analyzed incrementally. The analysis itself won't be performed. Changes made since the last build will be taken into account, and the previous history of changes will be deleted.
    • AppendScan - analyze all dependencies to determine, which files will be analyzed incrementally. The analysis itself won't be performed. Changes made since the last build, as well as all previous changes, will be taken into account.
    • Analyze - perform incremental analysis. This step should be done after Scan or AppendScan and can be performed both before and after the build of a solution or project. Static analysis will only be performed for files from the list obtained by executing the Scan or AppendScan commands.
    • ScanAndAnalyze - analyze all the dependencies to determine which files should be analyzed incrementally and perform incremental analysis of the edited files with the source code. Changes made since the last build will be taken into account.
  • --msBuildProperties (-m): allows you to set or redefine project level properties. To set or redefine multiple project level properties, use the "|" symbol, for example: --msBuildProperties "WarningLevel=2|OutDir=bin\OUT32\"
  • --excludeDefines (-x): a list of symbols that will be excluded from the current set when analyzing the project. If you need to list several symbols, use ';' as the delimiter. Example: --excludeDefines "DEF1;DEF2". This option is only taken into account when analyzing C# projects.
  • --appendDefines (-d): a list of symbols that will be added to the current set when analyzing the project. If you need to list several symbols, use ';' as the delimiter. Example: --appendDefines "DEF1;DEF2". This option is only taken into account when analyzing C# projects.
  • --selectProjects (-S): a list of analyzed solution's projects (sln) to be analyzed. Other projects will be excluded from the analysis. It supports listing projects using the name of the project file (with or without an extension), using an absolute or relative path. If you need to list multiple projects, use ';' as the delimiter. Example: --selectProjects Project1;"Project 2.vcxproj";".\Project3\Project3.csproj".
  • --excludeProjects (-E): a list of projects in the analyzed solution (sln) that will be excluded from the analysis. It supports listing projects using the name of the project file (with or without an extension), using an absolute or relative path. If you need to list multiple projects, use ';' as the delimiter. Example: --excludeProjects Project1;"Project 2.vcxproj";".\Project3\Project3.csproj".
  • --rulesConfig (-C): path to the .pvsconfig diagnostics configuration file. It can be used together with configuration files from projects / solutions and configuration files from directories:
    • Windows: "%AppData%\PVS-Studio\";
    • Linux / macOS: "~/.config/PVS-Studio/".
  • --useSuppressFile (-u): path to the suppress files. You can specify several suppress files via this parameter. Use the ';' character to separate paths to suppress files. For example: -u "path\to\test.suppress;path\to\test.suppress.json". Read more about message suppression mode in this section of the documentation.
  • --disableLicenseExpirationCheck (-h): resets return code and disables license expiration warning when the license is about to expire.
  • --intermodular (-I): enables the intermodular analysis mode for C and C++ projects. In this mode, the analyzer performs a deeper code analysis by increasing the analysis time. The C# analyzer provides the intermodular analysis by default.

The console utility also has additional modes of operation:

  • credentials – intended to activate the license;
  • suppression – is intended for specific actions on the suppress files (to create empty suppress files, to suppress/unsuppress individual warnings, to get statistics on the suppress files).

The "suppression" mode has additional flags that are not present in the main mode (or the flags have a different name):

  • --mode (-m): using this flag you can specify the submode for working with suppress files:
  • CreateEmptySuppressFiles creates empty suppress files next to project files (.csproj/.vcxproj) by the specified pattern of the file name (--suppressFilePattern flag). If the flag of the pattern is omitted, empty suppress files are created with the project name. This mode takes into account the flag marking suppress files with the primary tag (--markAsPrimary). Primary suppress files are used to suppress several warnings selected in the PVS-Studio Output Window for Visual Studio;
  • Suppress allows suppression of individual warnings from the analyzer's report file (--analyzerReport). The suppressed warnings from the analyzer report are selected using filters: groups (--groups), diagnostic codes (--errorCodes), paths (--files). This mode takes into account the --markAsPrimary flag;
  • UnSuppress mode unsuppresses warnings from the passed analyzer report. UnSuppress is similar to Suppress mode in terms of the flags used, except for the --markAsPrimary flag. It is not used in this mode;
  • FilterFromSuppress filters the messages in the existing report file (.plog, .json, or unparsed output of the C++ core) without running the analysis. This mode filters the messages using suppress files located next to project/solution files. Another option: pass the path to the suppress files using the –useSuppressFile (-u) flag. The file with results is saved next to the report file passed. The file is named with postfix '_filtered'.
  • CountSuppressedMessages calculates the number of suppressed warnings in all suppress files. This mode can also calculate the number of relevant warnings in suppress files. If you pass the full report file (via the -o flag), you can see how many warnings in the suppress base are still relevant. You can also learn statistics for each suppress file if you run this mode with the '-r' flag.
  • UpdateSuppressFiles updates suppress files and deletes the warnings that are not included in the report file passed. Please note that this mode requires a full report containing suppressed warnings. A full report is created each time the analysis is started if there are suppressed warnings. The full report file is named "*_WithSuppressedMessages.*" and is located next to the main report file. If you run this mode with a report file that doesn't contain suppressed warnings, all suppress files will be cleared.
  • --analyzerReport (-R): the path to the analyzer report whose warnings are to be used in processing. Similar to -o flag from the main mode;
  • --msBuildProperties (-b): key-value pairs. It is similar to -msBuildProperties (-m) flag from the main mode of PVS-Studio-Cmd.exe;
  • --markAsPrimary (-M): marks suppress files as primary suppress files;
  • --suppressFilePattern (-P): the name pattern for creating/using suppress files;
  • --logModifiedFiles (-l): paths to all modified project and suppress files are written to the file passed in this flag. Both absolute and relative file paths can be used. A file will be created or overwritten if at least one project or suppress file has been modified. The same information is output to the console if the --progress (-r) flag is specified;
  • --groups (-g): the filter of warnings from the analyzer report (-R) by diagnostic groups with warning certainty level. Example: GA:1,2,3|OWASP|64:2;
  • --errorCodes (-E): the filter of warnings from the analyzer report (-R) by the analyzer diagnostic codes. Example: V501,V1001,V3001;
  • --files (-f): the filter of warnings from the analyzer report (-R) by paths. Example: --files absolute/path/directory*3,8,11|relative/path/file*1|fileName

PVS-Studio command-line version supports all settings on filtering/disabling messages available in the IDE plugin for Visual Studio. You can either set them manually in the xml file, passed through the '--settings' argument, or use the settings specified through the UI plugin, without passing this argument. Note that the PVS-Studio IDE plugin uses an individual set of settings for each user in the system.

Only relevant for PVS-Studio_Cmd. If you have installed multiple instances of PVS-Studio of different versions for the current system user, all instances of the program will use the installation directory specified during the last installation. To avoid conflicts in the analyzer's operation, in the settings passed with the --settings (-s) argument, the path to the installation directory (the value of the <InstallDir> element) must be specified.

Specification of individual files for analysis

PVS-Studio_Cmd allows you to selectively check individual files (for example, only files that have been modified) specified in the list passed using the '--sourceFiles' (-f) flag. This significantly reduces the time required for analysis and also enables you to get the analyzer report only for specific changes in the source code.

The file list is a simple text file that contains line-by-line paths to the files being checked. Relative file paths will be expanded relative to the current working directory. You can specify both compiled source files (c/cpp for C++ and cs for C#), and header files (h/hpp for C++).

To get a list of changed files for the '--sourceFiles' (-f) flag, you can use version control systems (SVN, Git, etc.). They provide the analyzer with up-to-date information about changes in the code.

When you use the mode to analyze C and C++ files, a compilation dependency cache is generated, which will be used for subsequent analysis runs. By default, dependency caches are saved in a special '.pvs-studio' subdirectory where project files (.vcxproj) are located. If necessary, you can change their storage location using the '--dependencyRoot' (-D) flag. . You can also use the --dependencyCacheSourcesRoot (-R) flag to generate dependency cache files with relative paths, allowing the same dependency cache file to be used on different systems.

When you run the analysis for the first time using the '--sourceFiles' flag (-f), the analyzer preprocesses all C and C++ files from the projects submitted for analysis. The information on dependencies is stored in a separate dependency cache file for each project.

On future analyzer runs with the '--sourceFiles' flag (-f), the information will be added/updated to the dependency cache for:

  • Files listed from the '--sourceFiles' flag (-f).
  • Files that do not yet have an entry in the dependency cache file. For example, new files added to the project.
  • Files that previously depended on the files listed from the '--sourceFiles' flag (-f). The information on dependencies is taken from the dependency cache file that was generated/updated during the last run of the analysis with the '--sourceFiles' (-f) flag.

After updating the information on dependencies, all files specified in '--sourceFiles' (-f) are analyzed, as well as the files that depend on these files (the information on dependencies from the previous step is used).

Before each analysis run, the compilation dependency cache is updated for all files passed in '--sourceFiles' (-f) and for the files whose dependencies include files passed in the list. If there are changes in file dependencies relative to cached dependencies, these changes will be considered in the current analysis run and the cache will be updated for future runs.

To keep the dependency cache up to date, run the analysis with the '--sourceFiles' (-f) flag each time when the source files are changed, or simultaneously for all changed files from multiple commits.

Skipping the analysis of changes to source files, or separately analyzing modified files in an order other than the order in which they were modified, may cause the analysis to be skipped in the future due to changes in the dependency structure of the project. For example, if a dependency on an .h file has been added to a .cpp file, that .cpp file should be added to the list of files to be checked to update the dependency cache. Otherwise, when a newly added .h file is included in the list of files to be analyzed, the analyzer will not be able to find the translation unit for which preprocessing should be performed.

If you cannot provide a guaranteed transfer of all changing project files in the '--sourceFiles' (-f) mode, use the '--sourceFiles' (-f) mode together with the '--regenerateDependencyCache' (-G) mode. In such a case, the analyzer operation time will slightly increase (for cache regeneration, all project translation units should be preprocessed). However, it will still be much less than the time of full analysis (because only preprocessing of all project source files is performed, not the analysis itself). Cache relevance is guaranteed on every analysis run and is not dependent on the possible omission of changed files or the order in which the files were submitted for analysis.

Wildcard filtration of the analyzed

To specify the list of analyzed files with path patterns, you need to pass a specially formatted XML file to the '--sourceFiles' (-f) flag. It accepts the list of absolute and relative paths and/or wildcards to analyzed files.

<SourceFilesFilters>
  <SourceFiles>
    <Path>C:\Projects\Project1\source1.cpp</Path>
    <Path>\Project2\*</Path>
    <Path>source_*.cpp</Path>
  </SourceFiles>
  <SourcesRoot>C:\Projects\</SourcesRoot>
</SourceFilesFilters>

Intermodular analysis mode

Enabling this mode allows the analyzer to consider information not only from the analyzed file, but also from files that relate to the analyzed file. This allows for deeper and more qualitative analysis. However, it takes extra time to collect the necessary information, which will affect the time you analyze your project.

This mode is relevant to C and C++ projects. C# projects provide cross-modular analysis by default.

To start the intermodular analysis, pass the --intermodular flag to the command-line utility.

Command-line tools exit codes

The PVS-Studio_Cmd / pvs-studio-dotnet utilities have several non-zero exit codes that don't indicate a problem with the utility itself, i.e. even if the utility returned not '0', it doesn't mean that it crashed. The exit code is a bit mask that masks all possible states that occurred during the operation of the utility. For example, the utility will return a non-zero code if the analyzer finds potential errors in the code being checked. This allows you to handle this situation separately, for example, on the build server, when the analyzer usage policy doesn't imply the presence of warnings in the code uploaded in the version control system.

PVS-Studio_Cmd exit codes (Windows)

Let's look at all possible utility state codes that form the bit mask of the return code.

  • '0' - the analysis was completed successfully, no errors were found in the code being checked;
  • '1' - an error (crash) of the analyzer when checking one of the files;
  • '2' - a general (non-specific) error during the analyzer operation, intercepted exception during operation. This usually signals the presence of an error in the analyzer code itself and is followed by this error's stack trace in stderr. If you stumbled upon such an error, please, help us make the analyzer better and send this stack trace to us;
  • '4' - some of the passed command-line arguments are incorrect;
  • '8' - the specified project, solution, or analyzer settings file wasn't found;
  • '16' - the specified configuration and / or platform weren't found in the solution file;
  • '32' - the solution or project file isn't supported or contains errors;
  • '64' - invalid extension of the solution or project being checked;
  • '128' - invalid or expired analyzer license;
  • '256' - potential errors were found in the code being checked;
  • '512' - an error occurred while performing message suppression
  • '1024' - indicates that the analyzer license will expire within a month;

Here is an example of a Windows batch script for decrypting the return code of the PVS-Studio_Cmd utility:

@echo off

"C:\Program Files (x86)\PVS-Studio\PVS-Studio_Cmd.exe"
-t "YourSolution.sln" -o "YourSolution.plog"

set /A FilesFail = "(%errorlevel% & 1) / 1"
set /A GeneralExeption = "(%errorlevel% & 2) / 2"
set /A IncorrectArguments = "(%errorlevel% & 4) / 4"
set /A FileNotFound = "(%errorlevel% & 8) / 8"
set /A IncorrectCfg = "(%errorlevel% & 16) / 16"
set /A InvalidSolution = "(%errorlevel% & 32) / 32"
set /A IncorrectExtension = "(%errorlevel% & 64) / 64"
set /A IncorrectLicense = "(%errorlevel% & 128) / 128"
set /A AnalysisDiff = "(%errorlevel% & 256) / 256"
set /A SuppressFail = "(%errorlevel% & 512) / 512"
set /A LicenseRenewal = "(%errorlevel% & 1024) / 1024"

if %FilesFail% == 1 echo FilesFail
if %GeneralExeption% == 1 echo GeneralExeption
if %IncorrectArguments% == 1 echo IncorrectArguments
if %FileNotFound% == 1 echo FileNotFound
if %IncorrectCfg% == 1 echo IncorrectConfiguration
if %InvalidSolution% == 1 echo IncorrectCfg
if %IncorrectExtension% == 1 echo IncorrectExtension
if %IncorrectLicense% == 1 echo IncorrectLicense
if %AnalysisDiff% == 1 echo AnalysisDiff
if %SuppressFail% == 1 echo SuppressFail
if %LicenseRenewal% == 1 echo LicenseRenewal

pvs-studio-dotnet exit codes (Linux / macOS)

Note. Since the maximum value of the exit code under Unix is limited by 255, exit codes of the PVS-Studio_Cmd (where the exit code may exceed 255) and pvs-studio-dotnet utilities are different.

Let's look at all possible utility state codes that form the bit mask of the return code.

  • '0' - analysis was successfully completed, no issues were found in the source code;
  • '1' - incorrect or out-of-date analyzer license;
  • '2' - general error in the analyzer's operation. This includes missed command-line arguments, invalid solution or project specified for analysis, an error inside the analyzer, etc. If an error message is followed by a stack trace, please help us improve the analyzer by sending it to us;
  • '4' - indicates that the analyzer license will expire within a month;
  • '8' - some issues were found in the source code;

Analysis run from the command line for C/C++ projects that don't use the Visual Studio build system

Note. This section is relevant for Windows. Analysis of C++ projects on Linux / macOS is described in the corresponding section of the documentation.

If your C/C++ project doesn't use standard Visual Studio build systems (VCBuild/MSBuild) or even uses your own build system / make files via NMAKE Visual Studio projects, you will not be able to check such a project using PVS-Studio_Cmd.

In this case, you can use the compiler monitoring system, which allows you to analyze projects regardless of their build system, "intercepting" the start of compilation processes. The compilation monitoring system can be used either from the command line or through the user interface of the C and C++ Compiler Monitoring UI application.

You can also directly embed the command line launch of the analyzer core right into your build system. Mind you, this will require writing a call to the PVS-Studio analyzer.exe core for each compiled file, similar to the the way how the C++ compiler is called.

Effect of PVS-Studio settings on command line run; filtering and converting analysis results (plog\json file)

When you run code analysis from the command line, the default settings are the same as when you run analysis from the IDE (Visual Studio / Rider). You can also specify which settings file to use via the --settings argument, as described above.

For example, as for the filter system (Keyword Message Filtering and Detectable Errors), it is NOT used when analyzing from the command line. Which means that the report file will contain all error messages regardless of the parameters you set. However, when you upload the results file to the IDE, the filters will already be applied. This is because filters are applied dynamically to results. The same occurs when running from the IDE as well. This is very convenient, because when you get a list of messages, you may want to disable some of them (for example, V201). Just disable them in the settings and the corresponding messages will disappear from the list WITHOUT restarting the analysis.

The analyzer report format isn't intended for direct display or human reading. However, if you need to filter the analysis results in some way and convert them to a "readable" view, you can use the PlogConverter utility distributed with PVS-Studio.

To work with reports in different formats, you need to use different utilities:

  • .plog – PlogConverter.exe (available only on Windows);
  • .json – plog-converter (Linux, macOS).

The source code of both utilities is open and available for download: PlogConverter; plog-converter, which allows you to simply add support for new formats based on existing algorithms.

These utilities are described in more detail in the corresponding sections of the documentation: