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.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.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.searchPattern="*.csproj"
would only look for files with
the "csproj" extension, meaning that only C# project files are analyzed.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.type="JelleDruyts.BuildCop.Rules.BuildProperties.BuildPropertiesRule,
JelleDruyts.BuildCop"
would load the built-in "Build Properties" rule.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.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).outputTypeMappings
configuration node.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.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>
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.
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>
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.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.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.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>
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.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>