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:

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>

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>

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>

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>