BuildCop Wiki & Documentation Rss Feed

UPDATED WIKI: Home

jelled — Tue, 05 Feb 2008 21:18:39 GMT

Introduction

BuildCop is a tool that analyzes MSBuild project files (interactively or during e.g. a daily build) according to a customizable set of rules and generates reports - e.g. is strong naming enabled, are certain project properties set correctly, is XML documentation being generated, are assembly references correct, are naming conventions respected, ...

Getting Started

BuildCop consists of a command-line tool and an XML configuration file. When the application is run, it will read the configuration file to figure out which files to analyze, which rules to run, and which reports to generate.

Basic usage looks as follows:

Define the configuration file: this XML file determines the actions that BuildCop takes; see below for the details of the configuration file.
Run the tool: this can be done interactively on the command-line or in an automated way, e.g. during a daily build.
Open the report(s): the generated reports contain the results of the analysis and allow you to take appropriate actions to correct issues in MSBuild files; various reporting options (to the console, or to a XML, HTML or CSV file) are provided out of the box.
Create additional rules and/or formatters: BuildCop is created with extensibility in mind, so if you would like to extend BuildCop to run additional rules or provide additional reporting formats, it's quite easy to provide custom rules and formatters.

In the future, an additional GUI application could be foreseen to run the rules interactively in a rich Windows application, and to edit configuration files, but those are currently not implemented yet. Of course, feel free to contact me if you want to contribute to the project!

Documentation

Configuration: Provides details on how to configure the application.
Built-In Rules: Lists the built-in rules and explains how to configure them.
Built-In Formatters: Lists the built-in formatters and explains how to configure them.
Customization: Provides details on how to add custom rules and formatters.

A slightly better version of the documentation is also included in the released download package, where everything is bundled in one compiled help (chm) file.

UPDATED WIKI: Home

jelled — Tue, 05 Feb 2008 21:18:14 GMT

Introduction

Getting Started

Define the configuration file: this XML file determines the actions that BuildCop takes; see below for the details of the configuration file.
Run the tool: this can be done interactively on the command-line or in an automated way, e.g. during a daily build.
Open the report(s): the generated reports contain the results of the analysis and allow you to take appropriate actions to correct issues in MSBuild files; various reporting options (to the console, or to a XML, HTML or CSV file) are provided out of the box.
Create additional rules and/or formatters: BuildCop is created with extensibility in mind, so if you would like to extend BuildCop to run additional rules or provide additional reporting formats, it's quite easy to provide custom rules and formatters.

Documentation

Configuration: Provides details on how to configure the application.
Built-In Rules: Lists the built-in rules and explains how to configure them.
Built-In Formatters: Lists the built-in formatters and explains how to configure them.
Customization: Provides details on how to add custom rules and formatters.

A slightly better version of the documentation is also included in the released download package, where everything is bundled in one compiled help (chm) file.

UPDATED WIKI: Customization

jelled — Tue, 05 Feb 2008 21:11:40 GMT

Customization

Overview

BuildCop is designed with extensibility in mind: its use would be very restricted if it weren't possible to write custom rules or formatters. Luckily, customization is quite straight-forward if you are a .NET developer, so feel free to extend the tool and send me any custom classes you have created!

If the documentation would not suffice, you can always look at the source code for the existing rules (they have no special tricks or privileges) to get more insight in the way it works. If you would still get stuck in any way, though, please let me know and I'll clear up whatever isn't obvious right now.

As for the technical details: BuildCop is written on .NET 2.0 so all you need is a compiler and a reference to the JelleDruyts.BuildCop.dll assembly, which contains all the required classes needed for customization.

Writing Custom Rules

Overview

Create a class that derives from JelleDruyts.BuildCop.Rules.BaseRule.

Re-implement the base class constructor (simply pass through to the base class constructor).
Override the Check method to analyze an MSBuild project file and return log entries.
If your rule has configuration information, retrieve the strongly typed configuration instance using the generic GetTypedConfiguration method.
When creating log entries, you should pass the Name property of your rule as the rule argument for the log entry's constructor.

If your rule requires configuration:

Create a root configuration element that inherits from JelleDruyts.BuildCop.Configuration.RuleConfigurationElement.
Re-implement the two base class constructors (simply pass through to the base class constructors).
Inside the class, use the standard .NET 2.0 Configuration infrastructure (i.e. ConfigurationElement and ConfigurationElementCollection classes) to define the actual configuration information.
Decorate your custom rule class with [BuildCopRule(ConfigurationType = typeof(your configuration root type))] to associate the rule with the configuration type.

Copy the assembly containing your rule to the BuildCop directory.
Register your rule in the configuration file using its fully qualified name, and provide the necessary configuration information.

Example

Below is a sample implementation of a custom rule that raises errors if the project's assembly name contains forbidden words:

[BuildCopRule(ConfigurationType = typeof(ForbiddenWordsRuleElement))]
public class ForbiddenWordsRule : BaseRule
{
    public ForbiddenWordsRule(RuleConfigurationElement configuration) : base(configuration)
    {
    }
 
    public override IList<LogEntry> Check(BuildFile project)
    {
        ForbiddenWordsRuleElement config = this.GetTypedConfiguration<ForbiddenWordsRuleElement>();
        List<LogEntry> entries = new List<LogEntry>();
 
        foreach (string forbiddenWord in config.Words.ForbiddenWords.Split(';'))
        {
            if (project.AssemblyName.IndexOf(forbiddenWord, StringComparison.OrdinalIgnoreCase) >= 0)
            {
                string message = "The assembly name contains a forbidden word.";
                string detail = string.Format("The assembly name \"{0}\" contains the forbidden word \"{1}\".",
                    project.AssemblyName, forbiddenWord);
                entries.Add(new LogEntry(this.Name, "ForbiddenWord", LogLevel.Error, message, detail));
            }
        }
 
        return entries;
    }
}

The configuration classes for this rule would be defined as follows:

public class ForbiddenWordsRuleElement : RuleConfigurationElement
{
    public ForbiddenWordsRuleElement()
    {
    }
 
    public ForbiddenWordsRuleElement(XmlReader reader) : base(reader)
    {
    }
 
    [ConfigurationProperty("words", IsRequired = true)]
    public WordsElement Words
    {
        get { return (WordsElement)base["words"]; }
    }
}
 
public class WordsElement : ConfigurationElement
{
    [ConfigurationProperty("forbidden", IsRequired = true)]
    public string ForbiddenWords
    {
        get { return (string)base["forbidden"]; }
        set { base["forbidden"] = value; }
    }
}

The configuration file would then contain a rule definition such as the following:

<rule name="ForbiddenWordsRule" type="CustomRules.ForbiddenWordsRule, CustomRules">
  <words forbidden="hack;crack;dummy" />
</rule>

Writing Custom Formatters

Overview

Create a class that derives from JelleDruyts.BuildCop.Formatters.BaseFormatter.

Re-implement the base class constructor (simply pass through to the base class constructor).
Override the WriteReport method to write the given report in whatever way you want.
If your formatter has configuration information, retrieve the strongly typed configuration instance using the generic GetTypedConfiguration method.
To retrieve the log entries to write (taking the minimum log level into account), call the FindLogEntries method of the given BuildCopReport instance.

If your formatter requires configuration:

Create a root configuration element that inherits from JelleDruyts.BuildCop.Configuration.FormatterConfigurationElement.
Re-implement the two base class constructors (simply pass through to the base class constructors).
Inside the class, use the standard .NET 2.0 Configuration infrastructure (i.e. ConfigurationElement and ConfigurationElementCollection classes) to define the actual configuration information.
Decorate your custom formatter class with [BuildCopFormatter(ConfigurationType = typeof(your configuration root type))] to associate the rule with the configuration type.

Copy the assembly containing your formatter to the BuildCop directory.
Register your formatter in the configuration file using its fully qualified name, and provide the necessary configuration information.

Note that you can build formatter and configuration classes from scratch as shown above, but in the very common case that you want to write to a file, it is also possible to use the existing FilebasedFormatter base class with its associated FilebasedFormatterElement configuration base class, which already provide you with a file name and the code that launches the file after the report has been written (if so desired by the user). In that case, you only have to worry about writing the actual file as in the example below. Likewise, if you require file-based output that involves an XSLT, you can use the XsltFilebasedFormatter and XsltFilebasedFormatterElement base classes, which adds a stylesheet attribute to the configuration. In both cases, you must now override the WriteReportCore method instead of WriteReport (to allow the base class to launch the file after it is written).

Example

Below is a sample implementation of a custom formatter that writes to a text file.

[BuildCopFormatter(ConfigurationType = typeof(FilebasedFormatterElement))]
public class TextFileFormatter : FilebasedFormatter
{
    public TextFileFormatter(FormatterConfigurationElement configuration)
        : base(configuration)
    {
    }
 
    protected override void WriteReportCore(BuildCopReport report, LogLevel minimumLogLevel)
    {
        FilebasedFormatterElement configuration = this.GetTypedConfiguration<FilebasedFormatterElement>();
        string fileName = configuration.Output.FileName;
 
        using (FileStream outputStream = new FileStream(fileName, FileMode.Create, FileAccess.Write, FileShare.Read))
        using (StreamWriter writer = new StreamWriter(outputStream))
        {
            foreach (BuildGroupReport groupReport in report.BuildGroupReports)
            {
                foreach (BuildFileReport fileReport in groupReport.BuildFileReports)
                {
                    foreach (LogEntry entry in fileReport.FindLogEntries(minimumLogLevel))
                    {
                        writer.WriteLine("{0} - {1} - {2} - {3} - {4} - {5} - {6}",
                            groupReport.BuildGroupName, fileReport.FileName,
                            entry.Level.ToString(), entry.Rule, entry.Code,
                            entry.Message, entry.Detail);
                    }
                }
            }
        }
    }
}

The configuration file would then contain a formatter definition such as the following:

<formatter name="Text" type="CustomFormatters.TextFormatter, CustomFormatters">
  <output fileName="out.txt" launch="true" />
</formatter>

UPDATED WIKI: Built-In Formatters

jelled — Tue, 05 Feb 2008 21:07:53 GMT

Built-In Formatters

Console

Writes the log entries to the console.

<formatter name="Console" type="JelleDruyts.BuildCop.Formatters.Console.ConsoleFormatter" minimumLogLevel="[...]" />

This formatter has no formatter-specific configuration.

CSV

Writes the log entries to a comma-separated values (CSV) file.

<formatter name="Csv" type="JelleDruyts.BuildCop.Formatters.Csv.CsvFormatter" minimumLogLevel="[...]">
  <output fileName="[...]" launch="[true|false]" />
</formatter>

output: defines the output settings for this formatter.

fileName: the relative path and file name of the file to write.
launch (optional): a value of "true" or "false" that determines if the file should be launched when the report has been written.

HTML

Writes the log entries to an HTML file.

<formatter name="Html" type="JelleDruyts.BuildCop.Formatters.Html.HtmlFormatter" minimumLogLevel="[...]">
  <output fileName="[...]" launch="[true|false]" stylesheet="[...]" />
</formatter>

output: defines the output settings for this formatter.

fileName: the relative path and file name of the file to write.
launch (optional): a value of "true" or "false" that determines if the file should be launched when the report has been written.
stylesheet (optional): the relative path to the XSLT stylesheet to use. The HTML formatter reuses the XML formatter to produce an XML document and then transforms this into an HTML document using an XSLT stylesheet. By default, the "BuildCopReport.xslt" file provided with the application is used, but you can provide an alternative XSLT file here.

XML

Writes the log entries to an XML file.

<formatter name="Xml" type="JelleDruyts.BuildCop.Formatters.Xml.XmlFormatter" minimumLogLevel="[...]">
  <output fileName="[...]" launch="[true|false]" stylesheet="[...]" />
</formatter>

output: defines the output settings for this formatter.

fileName: the relative path and file name of the file to write.
launch (optional): a value of "true" or "false" that determines if the file should be launched when the report has been written.
stylesheet (optional): the path to the XSLT stylesheet to reference as a processing instruction inside the XML file. You can use the "BuildCopReport.xslt" file provided with the application (or an alternative XSLT file), so that a web browser displays the XML file in a human-readable way.

UPDATED WIKI: Built-In Rules

jelled — Tue, 05 Feb 2008 21:05:49 GMT

Built-In Rules

Assembly References

Definition

Verifies that assembly references are correct. This rule can be used to make sure all projects use consistent assembly references (e.g. to correct versions of common components).

<rule name="AssemblyReferenceRule" type="JelleDruyts.BuildCop.Rules.AssemblyReferences.AssemblyReferenceRule">
  <assemblyLocations>
    <assemblyLocation assemblyName="[...]"
                      assemblyPath="[...]" />
  </assemblyLocations>
</rule>

assemblyLocations: contains 0 or more assemblyLocation nodes.
assemblyLocation: defines an expected assembly location.

assemblyName: the fully qualified assembly name to verify (or at least the start of it).
assemblyPath: the expected location of the assembly (or at least the start of it).

Example

The following example verifies that any assembly whose fully qualified name starts with "EnvDTE, Version=8.0.0.0" is referenced from a path that starts with "R:\References\VisualStudio\8.0" (in other words, that "EnvDTE.dll" is referenced from somewhere under "R:\References\VisualStudio\8.0"):

<rule name="AssemblyReferenceRule" type="JelleDruyts.BuildCop.Rules.AssemblyReferences.AssemblyReferenceRule">
  <assemblyLocations>
    <assemblyLocation assemblyName="EnvDTE, Version=8.0.0.0" assemblyPath="R:\References\VisualStudio\8.0" />
  </assemblyLocations>
</rule>

Build Properties

Definition

Verifies that build properties in a project file are correct. This rule can be used to generically check all MSBuild properties, including (but not limited to) the build properties that are defined inside the project's properties in Visual Studio.

<rule name="BuildPropertiesRule" type="JelleDruyts.BuildCop.Rules.BuildProperties.BuildPropertiesRule">
  <buildProperties>
    <buildProperty name="[...]"
                   value="[...]"
                   condition="[...]"
                   compareOption="[EqualTo|NotEqualTo|Exists|DoesNotExist|In|NotIn]"
                   stringCompareOption="[CurrentCulture|CurrentCultureIgnoreCase|InvariantCulture|InvariantCultureIgnoreCase|Ordinal|OrdinalIgnoreCase]" />
  </buildProperties>
</rule>

buildProperties: contains 0 or more buildProperty nodes.
buildProperty: defines an expected build property.

name: the name of the build property.
value (optional): the expected value of the build property.
condition (optional): the condition (or a part of it) that should be present in the build property's condition; typically used to differentiate between "Debug" and "Release" solution configurations, which are represented as MSBuild conditions.
compareOption (optional): the comparison option to use when checking build property values.

EqualTo: the build property's value must be exactly equal to the given value.
NotEqualTo: the build property's value may not be exactly equal to the given value.
Exists: the build property must exist (and can have any value).
DoesNotExist: the build property may not exist.
In: the build property's value must appear anywhere in the given value.
NotIn: the build property's value may not appear anywhere in the given value. The default value is "EqualTo".

stringCompareOption (optional): the comparison option to use when comparing strings; typically used to make the comparison case insensitive. The default value is "Ordinal".

Example

The following example verifies that warnings are always treated as errors, that the output path is correctly set for both the Debug as the Release solution configuration (i.e. condition), and that the DocumentationFile property exists:

<rule name="Build Properties" type="JelleDruyts.BuildCop.Rules.BuildProperties.BuildPropertiesRule">
  <buildProperties>
    <buildProperty name="TreatWarningsAsErrors" value="true" />
    <buildProperty name="OutputPath" value="bin\Debug\" condition="Debug" stringCompareOption="OrdinalIgnoreCase" />
    <buildProperty name="OutputPath" value="bin\Release\" condition="Release" stringCompareOption="OrdinalIgnoreCase" />
    <buildProperty name="DocumentationFile" compareOption="Exists" />
  </buildProperties>
</rule>

Documentation File

Definition

Verifies that an XML documentation file is generated as part of the build, with the correct name (i.e. the name of the assembly with the .xml file extension).

This rule has no rule-specific configuration.

Example

The following example verifies that an XML documentation file is generated as part of the build.

<rule name="DocumentationFileRule" type="JelleDruyts.BuildCop.Rules.DocumentationFile.DocumentationFileRule" />

Naming Conventions

Definition

Verifies that certain naming conventions are respected.

<rule name="NamingConventionsRule" type="JelleDruyts.BuildCop.Rules.NamingConventions.NamingConventionsRule">
  <prefixes namespacePrefix="[...]"
            assemblyNamePrefix="[...]"
            assemblyNameShouldMatchRootNamespace="[true|false]" />
</rule>

prefixes: defines naming conventions for certain prefixes.

namespacePrefix (optional): the expected root namespace of the project (or at least the start of it).
assemblyNamePrefix (optional): the expected assembly name of the project (or at least the start of it).
assemblyNameShouldMatchRootNamespace (optional): a value of "true" or "false" that determines if the assembly name must be the same as the root namespace.

Example

The following example verifies that the root namespace and assembly name start with "JelleDruyts" and are exactly the same.

<rule name="Naming Conventions" type="JelleDruyts.BuildCop.Rules.NamingConventions.NamingConventionsRule">
  <prefixes namespacePrefix="JelleDruyts"
            assemblyNamePrefix="JelleDruyts" 
            assemblyNameShouldMatchRootNamespace="true" />
</rule>

Orphaned Projects

Definition

Verifies that the MSBuild project files being analyzed are part of at least one Visual Studio solution (.sln) file.

<rule name="OrphanedProjects" type="JelleDruyts.BuildCop.Rules.OrphanedProjects.OrphanedProjectsRule">
  <solutions searchPath="[...]" />
</rule>

solutions: defines where to look for Visual Studio solution (.sln) files.

searchPath: the root path in which to recursively look for solution files.

Example

The following example verifies that all MSBuild project files are part of solution files somewhere in the "D:\Projects\Source" path.

<rule name="OrphanedProjects" type="JelleDruyts.BuildCop.Rules.OrphanedProjects.OrphanedProjectsRule">
  <solutions searchPath="D:\Projects\Source" />
</rule>

Strong Naming

Definition

Verifies the strong naming (key signing) settings of a project file.

<rule name="StrongNamingRule" type="JelleDruyts.BuildCop.Rules.StrongNaming.StrongNamingRule">
  <strongNaming strongNameRequired="[true|false]"
                keyPath="[...]"
                ignoreUnsignedProjects="[true|false]" />
</rule>

strongNaming: defines the expected settings for strong naming assemblies.

strongNameRequired: a value of "true" or "false" that determines if strong naming should be enabled.
keyPath (optional): if a strong name is required, determines the path to the key file that should be used to sign the assembly.
ignoreUnsignedProjects (optional): a value of "true" or "false" that determines if projects that don't have strong naming enabled should be ignored; this can be used to check only that the key being used is valid for projects that do have strong naming enabled.

Example

The following example verifies that all project files have strong naming enabled and that they all use the key file "D:\Projects\Source\JelleDruyts.snk".

<rule name="StrongNamingRule" type="JelleDruyts.BuildCop.Rules.StrongNaming.StrongNamingRule">
  <strongNaming strongNameRequired="true" keyPath="D:\Projects\Source\JelleDruyts.snk" ignoreUnsignedProjects="false" />
</rule>

UPDATED WIKI: Configuration

jelled — Tue, 05 Feb 2008 21:01:14 GMT

Configuration

Overview

The BuildCop configuration file must always be named JelleDruyts.BuildCop.Console.exe.config and be located in the same directory as the executable.

To assist you in defining the configuration file, an XML Schema Definition (XSD) file is provided that documents the available XML nodes and attributes for most of the file's contents. When using Visual Studio to edit the configuration file, this XSD file is used to provide IntelliSense, so defining the configuration becomes quite easy.

The configuration file has the following structure:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="buildCopConfiguration" type="JelleDruyts.BuildCop.Configuration.BuildCopConfiguration, JelleDruyts.BuildCop"/>
  </configSections>
  <buildCopConfiguration xmlns="http://schemas.jelle.druyts.net/BuildCop">
    <buildGroups>[...]</buildGroups>
    <sharedRules>[...]</sharedRules>
    <formatters>[...]</formatters>
    <outputTypeMappings>[...]</outputTypeMappings>
  </buildCopConfiguration>
</configuration>

As you can see, the XML configuration file starts with the declaration of the BuildCop configuration section and then proceeds with the actual configuration inside the <buildCopConfiguration xmlns="http://schemas.jelle.druyts.net/BuildCop"> node.

Within this buildCopConfiguration root tag, there are four main configuration nodes:

buildGroups: defines the groups of MSBuild project files that are analyzed according to the same rules; this allows you to create multiple groups with different settings.
sharedRules (optional): defines BuildCop rules that can be shared between build groups; this allows you to reuse certain rule definitions across build groups that have overlapping rules.
formatters: defines the formatters that will be used to generate the reports; this allows you to define multiple outputs for various purposes (e.g. an HTML output file to publish to a website and an XML output file to access through another tool).
outputTypeMappings (advanced, optional): defines additional mappings of Visual Studio project type GUIDs to friendly names; this allows you to exclude project types from BuildCop rules using "friendly" project type names.

Build Groups

Definition

The buildGroups configuration node has the following structure:

<buildGroups>
  <buildGroup name="Default" enabled="[true|false]">
    <buildFiles excludedFiles="[...]">
      <paths>
        <path rootPath="[...]" searchPattern="[...]" excludedFiles="[...]" />
      </paths>
    </buildFiles>
    <rules>
      <rule name="[...]" type="[...]" enabled="[true|false]" excludedFiles="[...]" excludedOutputTypes="[Win|WinExe|Library|Web|...]">
        [...]
      </rule>
      <rule name="[...] />
    </rules>
  </buildGroup>
  <buildGroup name="Exceptions">
    <buildFiles>[...]</buildFiles>
    <rules>[...]</rules>
  </buildGroup>
</buildGroups>

buildGroups: contains 1 or more buildGroup nodes.
buildGroup: defines a build group.

name: the name of the build group; must be unique.
enabled (optional): a value of "true" or "false" that determines if the build group is enabled; this allows you to disable build groups without deleting the configuration from the file.

buildFiles: defines the MSBuild project files in the build group.

excludedFiles (optional): a semicolon-separated list of strings to find in the names of files to exclude in any of the paths defined below; this allows you to exclude certain files based on (part of) their full path and file name. For example: excludedFiles="TestResults;.Test.csproj" would exclude all files with "TestResults" or ".Test.csproj" as part of their path.

paths: contains 1 or more path nodes that together form the collection of MSBuild project files to analyze.
path: defines a path in which to look for MSBuild project files.

rootPath: the root path in which to recursively look for build files.
searchPattern (optional): the search string to match against the names of files to include in the given root path. For example: searchPattern="*.csproj" would only look for files with the "csproj" extension, meaning that only C# project files are analyzed. By default, the search pattern is "*.*proj" to find all files that end in "proj", with the following file extensions excluded because they are not MSBuild project files: .proj, .vddproj, .vdproj, .csdproj.
excludedFiles (optional): see above; when defined here, only applies to this path.

rules: defines 1 or more rules to run on the MSBuild project files in this build group.
rule: defines a rule to run on the MSBuild project files in this build group.

name: the name of the rule; must be unique.
type: the fully qualified type name of the rule class to use. The rules that are available out of the box and their configuration details are described below. For example: type="JelleDruyts.BuildCop.Rules.BuildProperties.BuildPropertiesRule, JelleDruyts.BuildCop" would load the built-in "Build Properties" rule. If the type is omitted, no other configuration may be defined here but instead the shared rule with the given name is used from the sharedRules configuration node.
enabled (optional): a value of "true" or "false" that determines if the rule is enabled; this allows you to disable rules without deleting the configuration from the file.
excludedFiles (optional): see above; when defined here, only applies to this rule.
excludedOutputTypes (optional): a semicolon-separated list of output types for MSBuild project files to exclude from this rule; this allows you to exclude certain files based on their output type. The available output types are "Win" (for Console applications), "WinExe" (for Windows applications), "Library" (for dll's) and "Web" (for Web applications). For example: excludedOutputTypes="Exe;WinExe;Web" would exclude the rule for Console applications, Windows applications and Web applications - basically only running the rule for Library projects (dll's). Additional output type mappings based on project type GUIDs can be defined in the outputTypeMappings configuration node.

Rule-specific configuration: inside the rule-node, a rule-specific XML node is often needed to define the configuration required for that particular rule. The rules that are available out of the box and their configuration details are described below. Unfortunately, since these configuration nodes depend on the specific rule type, no XSD or IntelliSense information is available for them.

Example

The following example analyzes all MSBuild project files and verifies that certain build properties are always set (e.g. for debugging and error levels), that the output path is properly set for non-Web projects (note the excludedOutputTypes), and that all Library-type projects (dll's) have enabled an XML documentation file to be generated:

<buildGroup name="Default">
  <buildFiles>
    <paths>
      <path rootPath="D:\Projects\Source" />
    </paths>
  </buildFiles>
  <rules>
    <rule name="Build Properties" type="JelleDruyts.BuildCop.Rules.BuildProperties.BuildPropertiesRule">
      <buildProperties>
        <buildProperty name="DebugSymbols" value="true" condition="Debug" />
        <buildProperty name="DebugType" value="full" condition="Debug" />
        <buildProperty name="Optimize" value="false" condition="Debug" />
        <buildProperty name="DefineConstants" value="DEBUG;TRACE" condition="Debug" />
        <buildProperty name="DebugType" value="pdbonly" condition="Release" />
        <buildProperty name="Optimize" value="true" condition="Release" />
        <buildProperty name="DefineConstants" value="TRACE" condition="Release" />
        <buildProperty name="ErrorReport" value="prompt" />
        <buildProperty name="TreatWarningsAsErrors" value="true" />
        <buildProperty name="WarningLevel" value="4" />
      </buildProperties>
    </rule>
    <rule name="Build Properties (Non-Web)" type="JelleDruyts.BuildCop.Rules.BuildProperties.BuildPropertiesRule"
          excludedOutputTypes="Web">
      <buildProperties>
        <buildProperty name="OutputPath" value="bin\Debug\" condition="Debug" />
        <buildProperty name="OutputPath" value="bin\Release\" condition="Release" />
      </buildProperties>
    </rule>
    <rule name="Documentation File" type="JelleDruyts.BuildCop.Rules.DocumentationFile.DocumentationFileRule"
          excludedOutputTypes="Exe;WinExe;Web" />
  </rules>
</buildGroup>

Shared Rules

Definition

The sharedRules configuration node contains 0 or more rules as defined above inside the rules node of a buildGroup definition. The rules defined here must be fully configured, i.e. have at least their type attribute and any required rule-specific configuration element set. Rules defined inside build groups can then just refer to these shared rules by defining only their name.

Example

The following example defines a shared "Documentation File" rule that is used from inside a build group:

<buildCopConfiguration xmlns="http://schemas.jelle.druyts.net/BuildCop">
  <buildGroup name="Default">
    <buildFiles>
      <paths>
        <path rootPath="D:\Projects\Source" />
      </paths>
    </buildFiles>
    <rules>
      <rule name="Documentation File"/>
    </rules>
  </buildGroup>
  <sharedRules>
    <rule name="Documentation File" type="JelleDruyts.BuildCop.Rules.DocumentationFile.DocumentationFileRule"
          excludedOutputTypes="Exe;WinExe;Web" />
  </sharedRules>
</buildCopConfiguration>

Formatters

Definition

The formatters configuration node has the following structure:

<formatters>
  <formatter name="[...]" type="[...]" minimumLogLevel="[Information|Warning|Error|Exception]">
    [...]
  </formatter>
  <formatter ...>[...]</formatter>
</formatters>

formatters: contains 0 or more formatter nodes.
formatter: defines a formatter.

name: the name of the formatter; must be unique.
type: the fully qualified type name of the formatter class to use. The formatters that are available out of the box and their configuration details are described below. For example: type="JelleDruyts.BuildCop.Formatters.Html.HtmlFormatter, JelleDruyts.BuildCop" would load the built-in HTML formatter.
minimumLogLevel (optional): the minimum log level the formatter should display or output. By default, all entries are output.

Formatter-specific configuration: inside the formatter-node, a formatter-specific XML node is often needed to define the configuration required for that particular formatter. The formatters that are available out of the box and their configuration details are described below. Unfortunately, since these configuration nodes depend on the specific formatter type, no XSD or IntelliSense information is available for them.

Example

The following example defines that entries of log level Warning or above should be written to the console output, and that all log entries should be written to a "BuildCopReport.html" HTML file, that should also be launched in the default web browser after the tool has completed.

<formatters>
  <formatter name="Console" type="JelleDruyts.BuildCop.Formatters.Console.ConsoleFormatter" minimumLogLevel="Warning" />
  <formatter name="Html" type="JelleDruyts.BuildCop.Formatters.Html.HtmlFormatter" minimumLogLevel="Information">
    <output fileName="BuildCopReport.html" launch="true" />
  </formatter>
</formatters>

Output Type Mappings

Definition

As mentioned before, you can use the excludedOutputTypes attribute of a rule element to define output types for which the rule is not applicable. By default, BuildCop supports "Win" (for Console applications), "WinExe" (for Windows applications), "Library" (for dll's) and "Web" (for Web applications) as output types.

If you have other project types that have no built-in equivalent, you can provide an output type mapping that maps a "friendly" alias to the project type GUID used by Visual Studio.

The outputTypeMappings configuration node has the following structure:

<outputTypeMappings>
  <outputType alias="[...]" projectTypeGuid="[...]" />
</outputTypeMappings>

outputTypeMappings: contains 0 or more outputType nodes.
outputType: defines an output type mapping.

alias: the "friendly" name of the output type as used in the rule's excludedOutputTypes.
projectTypeGuid: the project type GUID used by Visual Studio to identify the project type.

Example

The following example would be the equivalent of the built-in "Web" project type (but note that it is already predefined so there is no need to redefine it inside the configuration file):

<outputTypeMappings>
  <outputType alias="Web" projectTypeGuid="{349c5851-65df-11da-9384-00065b846f21}" />
</outputTypeMappings>

UPDATED WIKI: Home

jelled — Tue, 05 Feb 2008 20:43:57 GMT

Introduction

Getting Started

Define the configuration file: this XML file determines the actions that BuildCop takes; see below for the details of the configuration file.
Run the tool: this can be done interactively on the command-line or in an automated way, e.g. during a daily build.
Open the report(s): the generated reports contain the results of the analysis and allow you to take appropriate actions to correct issues in MSBuild files; various reporting options (to the console, or to a XML, HTML or CSV file) are provided out of the box.
Create additional rules and/or formatters: BuildCop is created with extensibility in mind, so if you would like to extend BuildCop to run additional rules or provide additional reporting formats, it's quite easy to provide custom rules and formatters.

Documentation

Configuration: Provides details on how to configure the application
Built-In Rules: Lists the built-in rules and explains how to configure them
Built-In Formatters: Lists the built-in formatters and explains how to configure them
Customization: Provides details on how to add custom rules and formatters

UPDATED WIKI: Home

jelled — Tue, 05 Feb 2008 20:43:33 GMT

Introduction

Getting Started

Define the configuration file: this XML file determines the actions that BuildCop takes; see below for the details of the configuration file.
Run the tool: this can be done interactively on the command-line or in an automated way, e.g. during a daily build.
Open the report(s): the generated reports contain the results of the analysis and allow you to take appropriate actions to correct issues in MSBuild files; various reporting options (to the console, or to a XML, HTML or CSV file) are provided out of the box.
Create additional rules and/or formatters: BuildCop is created with extensibility in mind, so if you would like to extend BuildCop to run additional rules or provide additional reporting formats, it's quite easy to provide custom rules and formatters.

Documentation

Configuration: Provides details on how to configure the application
Built-In Rules: Lists the built-in rules and explains how to configure them
Built-In Formatters: Lists the built-in formatters and explains how to configure them
Customization: Provides details on how to add custom rules and formatters