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.

In the definitions below, XML nodes and attributes that are formatted in italic are optional and can be omitted. Everything else is required.

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>