Build and Analysis for C# Projects [Windows only]

• How The Build Works
• Command Line Build
• Managed, Safe Code Only
• C# Build Options
• Example Command Lines
• IDE Integrations and Windows Build Wizard
• Troubleshooting

How The C# Build Works

The following diagram shows the CodeSonar build and analysis process for C# projects.

The steps of the build and analysis process are described in Building: Overview. For projects based on C# code, the steps manifest as follows.

Once it has finished building the project, CodeSonar can run the analysis. If you use the analyze command, the analysis will run (and send its results to the hub) after the build has finished.

The degree of parallelism in the analysis will depend on the setting of ANALYSIS_SLAVES. Additional parallelism can be achieved by executing multiple cs-dotnet-scan commands in parallel for various smaller pieces of a project.

Managed, Safe Code Only

The CodeSonar C# build/analysis can only be applied to code that is both managed and safe. It will not understand native code, including "unsafe" C# code, or account for its effects.

When you invoke cs-dotnet-scan, do not include any artifacts with native or unmanaged code. In some cases you may need to use a combination of include options and exclude options to accomplish this. Example 13, below, illustrates one such case.

If your C# analysis includes one or more components (for example, classes) written in native or unmanaged code, the analysis will issue a Native Component alert.
See the troubleshooting notes below for more information.

Command Line Build

As described in Command Line Build/Analysis: Command, the general form of the usual CodeSonar build/analysis command is

The command element is described below; the other parts of the command line are discussed in Command Line Build/Analysis: Elements.

command

To build a C# project, CodeSonar observes the execution of a command of one of the following forms.

There are therefore three general forms of the CodeSonar build/analysis command for C# projects:

where remaining-options is any combination of include options, exclude options, and other options.

Patterns

Wildcard patterns follow the rules of the Glob library. In particular:

• ? matches one character. It does not match directory separator characters.
• * matches zero or more characters. It does not match directory separator characters.
• ** matches zero or more directories in a path.
• Patterns including any wildcards (?, *, or **) must be quoted.

A pattern that matches a directory is considered to match all files with appropriate suffixes that are located in that directory or any of its (recursive) subdirectories. Suffixes are as follows.

• .sln for -msbuild-solution
• .cs for -include-sources and -exclude-sources
• .exe, .dll, .properties, .sarl, and .xml for all other include options and exclude options.

C# Build Options

This section describes the available options for cs-dotnet-scan, all of which can be added using configuration file settings.

• Specifying C# Build Options
• Options
• Categories

As described above, there are three general forms of the CodeSonar build/analysis command for C# projects.

Where remaining-options is any combination of include options, exclude options, and other options.

The relative ordering of include and exclude options is important:

• Files specified for inclusion in the project with an include option will be removed if they match a subsequent occurrence of the corresponding exclude option.
• Files removed by an exclude option will be included again if they match a subsequent occurrence of the corresponding include option.

Specifying C# Build Options

You can specify C# build options using the following configuration file parameters as an alternative to specifying them directly in the command line.

Specifying Files for Analysis

There are two mechanisms for specifying inputs to the analysis in a cs-dotnet-scan command:

• Specify an MSBuild solution file, which CodeSonar will use to determine the artifacts, source files, and signatures to be analyzed.
  
  or
• Use a combination of include and exclude options to explicitly specify the artifacts, source files, libraries, and signatures to be included in the project.

In most cases, each cs-dotnet-scan command will only use one or the other of these mechanisms. However, it is possible to use both. The following diagram illustrates the handling for the various specified inputs in each case. For more information on individual command line options, see Options, below.

Options

The following table lists all options understood by cs-dotnet-scan.

Artifact Categories

Artifacts are files with the following extensions: .exe, .dll.

Each artifact included in a particular CodeSonar analysis belongs to one of four categories: ordinary artifacts, sourceless artifacts, libraries, and signatures. The artifact's category determines how the analysis will handle the artifact, as described in the table below.

• If you are analyzing a solution file specifed with -msbuild-solution, all the artifacts that CodeSonar identifies by parsing the solution file are treated as ordinary artifacts.
• Otherwise:
  • Inclusion and exclusion are handled separately for each artifact category. For example, an occurrence of -exclude-sourceless-artifacts will have no effect on the inclusion of artifacts specified with earlier occurrences of -include-artifacts, -include-libraries, or -include-signatures.
  • If an artifact is specified as a member of multiple categories (for example, because it matches both an -include-artifacts pattern and an -include-libraries pattern specified in the project build command), it will be treated as a member of the most important of those categories.

Every artifact (of every category) must have a corresponding PDB file located in the same directory. If there is no such PDB file, the analysis will issue an alert.
For example, if /myfiles/project/X.dll is specified, /myfiles/project/X.pdb must also be present.

The following table describes the artifact categories in order of importance.

Example Command Lines

Some example CodeSonar command lines for building and analyzing C# projects.

Note: Depending on the hub configuration, you may be prompted for hub user account credentials to authenticate and authorize codesonar build and codesonar analyze commands. See Hub Authentication: Authenticated codesonar Subcommands for more information.

The first four examples below are for projects with simple structure.

Example 1

Build a CodeSonar project based on the classes contained in Example.dll, located in the current working directory.

• Analyze all classes contained in Example.dll.
• Expect to also find file Example.pdb in the current directory.
  • Use the information in Example.pdb to identify the source files corresponding to Example.dll.
    If the identified source files cannot be loaded, CodeSonar will not be able to issue warnings for Example.dll.
  • If Example.pdb is not present, issue an alert.
• Output warnings relevant to the identified source files.

Example 2

Build and analyze a CodeSonar project based on the source files in /path/to/sources and the artifacts in /path/to/binaries.

• The sources will be all .cs files in the tree below /path/to/sources.
• The artifacts will be all .exe and .dll files in the tree below /path/to/binaries.
• Each artifact must have a corresponding PDB file in the same directory.

Example 3

Build and analyze a CodeSonar project based on the source files in /path/to/sources and the artifacts in /path/to/classes.

• The artifacts will be all .dll files in the tree below /path/to/binaries.
• Each artifact must have a corresponding PDB file in the same directory. The analysis will use the information in these files to identify the source files for each artifact.
  If the identified source files for a particular artifact cannot be loaded, CodeSonar will not be able to issue warnings for that artifact.
• /path/to/binaries/**/*.dll is called a wildcard pattern, where ** corresponds to zero or more directories, and *.dll corresponds to any file name with suffix .dll. All files with the suffix .dll will be found, an arbitrary number of directories deep.

Example 4

Build and analyze a CodeSonar project based on the source files in /path/to/sources and the .exe file /path/to/Project.exe.

• The sources will be all .cs files in the tree below /path/to/sources.
• The contents of /path/to/Project.exe will be analyzed.
• PDB file/path/to/Project.pdb must also be present.

The following examples illustrate more fine-grained control of the analysis.

Example 5

Build and analyze a CodeSonar project based on the artifacts in /path/to/binaries, except for the artifacts in /path/to/binaries/A.

• The artifacts will be all .dll files in the tree below /path/to/binaries, except for the ones below /path/to/binaries/A .
• The order of -include-artifacts and -exclude-artifacts is critical. In this case, if they were reversed, no class files would be excluded.
• Each .dll file must have a corresponding PDB file in the same directory. The analysis will use the information in these files to identify the source files for each artifact.
  If the identified source files for a particular artifact cannot be loaded, CodeSonar will not be able to issue warnings for that artifact.
• Note that options including wildcard patterns must be quoted.

Example 6

Build and analyze a CodeSonar project based on the .exe files in the tree below /path/to/binaries, except for those that are in /path/to/binaries/A but not in /path/to/binaries/A/B.

• Each .exe file must have a corresponding PDB file in the same directory. The analysis will use the information in these files to identify the source files for each artifact.
  If the identified source files for a particular artifact cannot be loaded, CodeSonar will not be able to issue warnings for that artifact.
• Once again, the order of -include-artifacts and -exclude-artifacts is critical to ensure expected results.
• Note that options including wildcard patterns must be quoted.

Example 7

Build and analyze a CodeSonar project based on .exe file /path/to/Project.exe, using the type signatures of the classes found inside /path/to/External.dll.

• The contents of /path/to/Project.exe will be analyzed.
• The contents of /path/to/External.dll will be used to provide type signatures to the analysis engine.
• PDB files /path/to/Project.pdb and /path/to/External.pdb must also be present.
• The analysis will use the information in /path/to/Project.pdb to identify the source files for /path/to/Project.dll.
  If the identified source files cannot be loaded, CodeSonar will not be able to issue warnings.

Example 8

Build and analyze a CodeSonar project based on the full contents of the current directory and all its (recursive) subdirectories.

Example 9

Build and analyze a CodeSonar project based on the full contents of the current directory and all its (recursive) subdirectories, excluding .dll files whose name or directory path contains "Test".

Example 10

cat <<EOF > buildscan.sh
#!/bin/sh
ant
cs-dotnet-scan -include-artifacts foo -include-sources foo &
cs-dotnet-scan -include-artifacts bar -include-sources bar &
wait
EOF
chmod +x buildscan.sh
codesonar analyze foo ./buildscan.sh

Executing this shell script will build the project with ant, then run two instances of cs-dotnet-scan in parallel on different parts of the project.

Example 11

Build and analyze a CodeSonar project based on path\to\SolutionX.sln (an MSBuild solution file).

• CodeSonar will parse SolutionX.sln using the MSBuild installation at C:\Program Files\Microsoft Visual Studio\2022\Professional.
  • If ProjectX.sln has one or more multiple target framework projects, CodeSonar will attempt to select an appropriate target framework for each project in the solution and record this selection in the build log.
• Each artifact identified is added to the CodeSonar project as an ordinary artifact.
• The source files associated with the identified ordinary artifacts must also be in the solution.
• The corresponding PDB file for each artifact must also be present.

Example 12

Build and analyze a CodeSonar project based on MSBuild project projpath\to\ProjX5.csproj, which is part of MSBuild solution solpath\to\SolutionX.sln.

• CodeSonar will parse SolutionX.sln using the MSBuild installation at C:\Program Files\Microsoft Visual Studio\2022\Professional.
  It will consider only one of the projects contained in SolutionX.sln: the one whose path is projpath\to\ProjX5.csproj.
  • If there is no such project, the build/analysis will fail.
  • If ProjX5.csproj has multiple target frameworks, CodeSonar attempt to select an appropriate target framework and record this selection in the build log.
• Each artifact identified as part of ProjX5.csproj is added to the CodeSonar project as an ordinary artifact.
• The source files associated with the identified ordinary artifacts must also be in the solution.
• The corresponding PDB file for each artifact must also be present.

Example 13

Suppose your project has a number of DLL files in directory bin\Debug\. The main artifact is called CashGrabber.dll and has associated source code; the remaining DLLs are libraries and do not have source code. Furthermore, library crypto.dll contains unmanaged code and so must be excluded from the CodeSonar C# analysis.

• bin\Debug\CashGrabber.dll is added to the CodeSonar project as an ordinary artifact.
• The remaining .exe and .dll files in the tree below \bin\Debug, with the exception of bin\Debug\crypto.dll, are added to the CodeSonar project as libraries.
• CodeSonar uses the information in bin\Debug\CashGrabber.pdb to identify the source files corresponding to CashGrabber.dll.
  If the identified source files cannot be loaded, CodeSonar will not be able to issue warnings for CashGrabber.dll.
  • If CashGrabber.pdb is not present, issue an alert.

IDE Integrations and Windows Build Wizard

In general, we recommend using the command line CodeSonar build/analysis for C# projects.

Troubleshooting

• Resolving Alerts
• "Too many potential candidates" parse errors

Resolving Alerts

The most typical alerts related to the C# build/analysis are listed below. For descriptions of all CodeSonar alerts, see Alerts.

"Too many potential candidates" parse errors

In some cases, you may see a parse error that looks something like the following.

For each analyzed ordinary artifact and sourceless artifact, CodeSonar attempts to identify the corresponding source file. To do this, CodeSonar iterates over those files specified with -include-sources and -exclude-sources whose basenames correspond to that of the artifact, checking each in turn to see if it is the correct match. Iteration finishes either when a match is found, or when the number of source files checked for a particular artifact exceeds the limit specified in environment variable CS_DOTNETFE_INCLUDESOURCE_LIMIT. The default value for this limit is 100.

If CodeSonar does not find the correct matching source file before reaching the iteration limit, then:

• The artifact is treated as having a missing source file.
  • No analysis results will be produced for this artifact.
  • A Missing Source File alert will be produced.
  • If it is an ordinary artifacts, the analysis may fail: see the discussion of ordinary artifacts above for details.
• You will see a parse error message like the one above.

There are two options for resolving this problem.

• Option 1: Use -include-sources and -exclude-sources to specify a more precise set of source files.

  This option is generally preferable if some of the source files with duplicate basenames are not relevant to your analysis. A more precise set of candidate source files will generally reduce the time spent on matching, and so reduce overall analysis time.

• Option 2 : Increase the setting of environment variable CS_DOTNETFE_INCLUDESOURCE_LIMIT to your preferred value.

  If you have a large number of artifacts with the same basename, there will necessarily be a large number of corresponding source files to iterate through for matching. In this case, you will need to increase the CS_DOTNETFE_INCLUDESOURCE_LIMIT to a value that allows all your source files to be considered.

  This approach imposes additional time costs. Firstly, a higher limit means that more time can be spent on matching and so the overall analysis time is generally increased. Secondly, you will need to spend time investigating or experimenting to determine a suitable CS_DOTNETFE_INCLUDESOURCE_LIMIT setting. We recommend the following approach.

  1. Identify the highly-duplicated basenames by reading them from parse error mesages like the example above.
  2. For each of these basenames, count the number of file instances in your source directory or directories.
  3. Set CS_DOTNETFE_INCLUDESOURCE_LIMIT to a value slightly higher than the highest of these counts.

In some cases, the most convenient solution might be to split your build/analysis across two or more cs-dotnet-scan invocations, each of which covers a smaller set of artifacts and specifies a more precise set of source files. This approach may still require you to increase the CS_DOTNETFE_INCLUDESOURCE_LIMIT, but typically not to the same extent.

Related Sections

• Command Line Build Instructions
• The Build/Analyze Commands (detailed documentation)