Hosting StyleCop in a Custom Environment

This article explains how to create a custom wrapper which loads and runs the StyleCop toolset, allowing StyleCop to be integrated into a custom build environment. To learn how to integrate StyleCop into an MSBuild-based build environment, see the Integrating StyleCop into MSBuild topic.

Creating a Custom StyleCop Wrapper

1. The first step in creating custom wrapper code for StyleCop is to create an instance of the StyleCopConsole class. The StyleCopConsole instance provides functionality for running StyleCop in a command-line based application, suitable for a custom build environment.

   Code
   StyleCopConsole console = new StyleCopConsole(null, true, null, null, true);

   The code example above will create an instance of the StyleCopConsole class with the default settings. It is possible to control the input and output of StyleCop by passing values into the StyleCopConsole constructor. For example, it is possible to provide the path to a StyleCop settings file containing the settings to be used during the analysis, rather than the default settings files. It is also possible to provide an alternate path for the output file containing the analysis results. Finally, it is possible to provide a collection of paths where StyleCop should search for assemblies containing StyleCop rules analyzers. Furthermore, it is possible to instruct StyleCop to skip loading rules analyzers from the default location.

   The next step in creating a custom StyleCop wrapper is to create an instance of the Configuration class. This object will specify the collection of preprocessor flags that should be set while performing the style analysis. For example, it is common for code to include #if DEBUG statements. By creating a Configuration class which defines the DEBUG flag, StyleCop will include code within #if DEBUG regions during the analysis.

   Code
   Configuration configuration = new Configuration(new string[] { "DEBUG" });

   Next, create one or more CodeProject objects and add the collection of source code files to analyze within each project. A CodeProject class represents a collection of code files located beneath a common root path.

   Code

   List<CodeProject> projects = new List<CodeProject>(); foreach (string myProject in this.myProjects) { CodeProject project = new CodeProject(myProject.Path.GetHashCode(), myProject.Path, configuration); // Add each source file to this project. foreach (string sourceFilePath in myProject.FilesToAnalyze) { console.Core.Environment.AddSourceCode(project, sourceFilePath, null); } projects.Add(project); }

   After submitting each of the source code files to analyze, the next step is to register for StyleCop output events. These events will be called whenever output is generated from StyleCop during the style analysis.

   Code
   console.OutputGenerated += this.OnOutputGenerated; console.ViolationEncountered += this.OnViolationEncountered;

   The OutputGenerated event is called whenever textual output is generated during an analysis. This output should typically be written into a log file. The ViolationEncountered event is fired whenever a rules violation is discovered in one of the source code files being analyzed. Register to this event to publish StyleCop rules violations to your build system.

   The final step in creating the StyleCop wrapper is to start the analysis. This is done by executing the Start(IList<(Of <(CodeProject>)>), Boolean) method.

   Code
   console.Start(projects, false);

   Finally, clean up after running the tool by unregistering for events and disposing the console object.

   Code
   console.OutputGenerated -= this.OnOutputGenerated; console.ViolationEncountered -= this.OnViolationEncountered; console.Dispose();