Setting Up StyleCop MSBuild Integration


This article explains how to integrate the StyleCop tool into an MSBuild based build environment, for StyleCop 4.3 and above. If you are using SourceAnalysis 4.2, please see the following article: http://blogs.msdn.com/sourceanalysis/pages/stylecop-4-2-msbuild-integration.aspx.


MSBuild integration will cause the tool to run automatically whenever the code is built, and StyleCop violations will show up alongside compiler errors in the build output.


It is possible to set up the build integration so that StyleCop violations will appear as build warnings, or as build errors if so desired.


Installing MSBuild Files


To enable build integration, first be sure to select the MSBuild option when installing the tool, as shown in the image below:


Installing MSBuild Image


This will cause the StyleCop binaries and supporting MSBuild targets files to be installed under the {Program Files}\MSBuild\Microsoft\StyleCop folder.


Adding the Import Tag


Once the StyleCop MSBuild files are installed, the next step is to import the StyleCop targets file into your C# projects. This is done by adding an Import tag to each C# project file.


For example, to integrate StyleCop to the project SampleProject, open the project file SampleProject.csproj within your favorite text editor. Scroll down to the bottom of the file and add a new tag to import the Microsoft.StyleCop.targets file. This import tag should be added just below the import of Microsoft.CSharp.targets:


<Project DefaultTargets=”Build” xmlns=”http://schemas.microsoft.com/developer/msbuild/2003″>



   …Contents Removed…


 


  <Import Project=”$(MSBuildBinPath)\Microsoft.CSharp.targets” />


  <Import Project=”$(ProgramFiles)\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets” /> 


 


   …Contents Removed…


 


</Project>


Save the modified .csproj file. The next time you build this project either within Visual Studio or on the command line, StyleCop will run automatically against all of the C# source files within the project.


Build Warnings Vs Errors


By default, StyleCop violations will show up as build warnings. To turn StyleCop violations into build errors, the flag StyleCopTreatErrorsAsWarnings must be set to false. This flag can be set as an environment variable on the machine, or within the build environment command window. Setting the flag this way will cause StyleCop violations to appear as build errors automatically for all projects where StyleCop build integration is enabled.


Alternately, this flag can be set within the project file for a particular project. Open the .csproj file for your project again, and find the first PropertyGroup section within the file. Add a new tag to set the StyleCopTreatErrorsAsWarnings flag to false. For example:


<Project DefaultTargets=”Build” xmlns=”http://schemas.microsoft.com/developer/msbuild/2003″>


  <PropertyGroup>


    <Configuration Condition=” ‘$(Configuration)’ == ” “>Debug</Configuration>


    <Platform Condition=” ‘$(Platform)’ == ” “>AnyCPU</Platform>


    <ProductVersion>8.0.50727</ProductVersion>


    <SchemaVersion>2.0</SchemaVersion>


    <ProjectGuid>{4B4DB6AA-A021-4F95-92B7-B88B5B360228}</ProjectGuid>


    <OutputType>WinExe</OutputType>


    <AppDesignerFolder>Properties</AppDesignerFolder>


    <RootNamespace>SampleProject</RootNamespace>


    <AssemblyName>SampleProject</AssemblyName>


    <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>


  </PropertyGroup>


 


Team Development


 


The configuration described above will suffice to enable StyleCop build integration on an individual development machine. However, development teams working within a well-defined development environment can set up the build integration in a more global way, so that each developer does not have to manually install StyleCop on his machine.


To do this, copy all of the files from {Program Files}\MSBuild\Microsoft\StyleCop into a custom folder within your build environment, and check all of these files into your source control system. Next, define an environment variable within your development environment which points to the location of the StyleCop targets file. For example:


set StyleCopTargets=%enlistmentroot%\ExternalTools\StyleCop\v4.3\Microsoft.StyleCop.targets


With this configuration in place, it is simply a matter of adding the following import tag to each .csproj file within your development environment:


  <Import Project=”$(MSBuildBinPath)\Microsoft.CSharp.targets” />


  <Import Project=”$(StyleCopTargets)” />


 


StyleCop will automatically run each time this project is built, no matter who is building the project. There is no need for each developer to install StyleCop manually, since the StyleCop binaries are checked directly into your source control system and are centrally integrated into your build environment.

Comments (30)

  1. The following article describes how to integrate Source Analysis into the build, so that the tool will

  2. &quot;Source Analysis, also known as StyleCop, analyzes C# source code to enforce a set of best practice

  3. Microsoft released the internal tool StyleCop to public under the fancy yet boring name of Microsoft

  4. gOODiDEA.NET says:

    Web Fantastic, Free Calendar and Datepicker Scripts .NET Evaluation Engine – a parser and interpreter

  5. Microsoft has published a great tool called Microsoft Source Analysis for C# , also known as StyleCop

  6. Wojtek says:

    Great! On my blog (wojciech.zimirski.net) you can find list of all rules currently embedded in the Microsoft Source Analysis for C#.

  7. CoqBlog says:

    Un nouvel outil est disponible pour les développeurs C#. Comme son nom l’indique il s’agit d’un analyseur

  8. FreeToDev says:

    I’ve written a task to perform analysis on custom file collections which makes it easy to integrate with TFS builds. http://freetodev.spaces.live.com/blog/cns!EC3C8F2028D842D5!400.entry

  9. I like this tool! Are there plans for NAnt tasks? As i use NAnt for hand-written build-files, this would be really nice. If there is no support planned, I would think of building a custom task for NAnt myself – however work should not be done multiple times…

  10. FreeToDev says:

    I’ve written a task to scan csutom collections. Handy for TFS builds…  http://freetodev.spaces.live.com/blog/cns!EC3C8F2028D842D5!400.entry

  11. redsolo says:

    Is it possible to output the result to an XML file similar to FxCop? If not, are you planning to add such feature?

     [Note from jasonall – An XML file is automatically produced when running through MSBuild integration]

  12. redsolo says:

    Ah, great!

    It would also be nice if the XML file could have a <rules> tag that contains all rules that are mentioned in the XML report (Similar to FxCop). Im particular looking for a URL and a longer descrption. Or is there any other way to find out a URL from the RuleId?

  13. こんにちは。手みじかですが、Microsoft Spurce Analysis for C# v4.2 が MSDN Code Gallery に公開されました。 バージョン番号を見ていただければ、わかるとおり、4.2

  14. Maor David says:

    Microsoft announce the public release of a new developer tool -&#160; Source Analysis for C# . Inside

  15. Guillaume says:

    Are you plannig to add a command line tool (as FxCop) to integrate this tool in any other build system?

  16. Greg says:

    How do you get  ExcludeFromSourceAnalysis to work?  I’ve tried

    <Compile Include="PropertiesAssemblyInfo.cs" ExcludeFromSourceAnalysis="true"/>

    but that doesn’t work (the project won’t load).

    Cheers.

  17. David says:

    I tried to integrate SourceAnalysis with MSBuild, that worked well as long as I added

    <Import Project="$(SourceAnalysisTargets)" />

    to each projects msbuild file (.proj):

    It wrote a "SourceAnalysis.Cache" file.

    Now I wanted to add this import line to the proj-file I wrote for the solution. No errors when I run MSBuild, but also no XML-Output. Any idea what can be wrong?

  18. David says:

    I tried to integrate SourceAnalysis with MSBuild, that worked well as long as I added

    <Import Project="$(SourceAnalysisTargets)" />

    to each projects msbuild file (.proj):

    It wrote a "SourceAnalysis.Cache" file. (don’t know if that is the right file?!)

    Now I wanted to add this import line to the proj-file I wrote for the solution. No errors when I run MSBuild, but also no XML-Output. Any idea what could be wrong?

    Cheers

  19. Graeme Wells says:

    Try :

    <Compile Include="PropertiesAssemblyInfo.cs">

    <ExcludeFromSourceAnalysis>true<ExcludeFromSourceAnalysis/>

    <Compile/>

    It seems to work for me

    Thanks

    Graeme

  20. Martin says:

    When reading the EULA it’s clear that you aren’t allowed to, quote: "publish the software for others to copy". As I see it putting the binaries into a repository directly violates this.

    Can you elaborate on why this is not violating the EULA and does this exception apply to any product containing this limitation in the EULA?

  21. Chaitanya says:

    I want to run this StyleCop using nant script. Can anybody know how to run stylecop on code base using Nant script? Is there any command line version of StyleCop available?  

  22. I’ve worked on a couple of projects for Microsoft UK – one of the many great aspects of those projects

  23. John K says:

    Great tool!  Any support for NAnt anytime soon?

  24. João Carlos Clementoni says:

    Hi. How we can run this tool with Nant?

  25. Amir Simantov says:

    As if Linq to SQL team members did not use StyleCop?…

    A single System.Data.Linq.DataContext derivative class, which is generated automatically when dragging items from Database/Server Explorer, break this rules (the number of breaking the rules are given in parentheses):

    1. SA1601: The partial class element must have a documentation header containing either a summary tag or a content tag.

    (Once).

    2. SA1600: The field/method/constructor must have a documentation header.

    (6 times)

    3. SA1633: The file has no header, the header Xml is invalid, or the header is not located at the top of the file.

    (Once)

    4. SA1512: A single-line comment must not be followed by a blank line. To ignore this error when commenting out a line of code, begin the comment with ‘////’ rather than ‘//’.

    5. SA1507: The code must not contain multiple blank lines in a row.

    (Once)

    6. SA1505: An opening curly bracket must not be followed by a blank line.

    (Once)

    7. SA1400: The method must have an access modifier.

    (Once)

    8. SA1201: All methods must be placed after all constructors.

    (4 times)

    9. SA1101: The call to OnCreated must begin with the ‘this.’ prefix to indicate that the item is a member of the class.

    (4 times)

    10. The famous/notorious SA1027: Tabs are not allowed. Use spaces instead.

    (41 time) and in words: forty-one.

    Mind you, the file has only 60 lines of code :-)

    Amir simantov

    Dot, Net & Beyond

  26. Bart says:

    Is it possible to integrate it with a Visual C# Express edition 2005?

  27. jasonall says:

    @Bart:

    We have not tested running StyleCop in Visual C# Express edition 2005 through MSBuild integration. I think it will _probably_ work, however, if you edit the .csproj file and add the StyleCop import tag as explained in this article.

  28. Amir Simantov says:

    I have tested it and it works just fine.

    Amir

  29. Martin says:

    Hi @ all!

    my question about MSBuild integration is following. Is there a difference between using VS2005 and VS2008?

    When i look at the *.csproj-file and would like to edit it, i find following tag:

    <Import Project="$(MSBuildToolsPath)Microsoft.CSharp.targets" />

    Might replacing this tag with …

    <Import Project="$(MSBuildBinPath)Microsoft.CSharp.targets" />

    and adding …

     <Import Project="$(ProgramFiles)MSBuildMicrosoftStyleCopv4.3Microsoft.StyleCop.targets" />

    lead to any troubles in future?

    Best regards,

    Martin

  30. A number of people have asked for tips on rolling out StyleCop on a large, pre-existing codebase. This