How to build a StyleCop Rule to enforce 'this' keyword use on fields.
First make sure you have the latest version of StyleCop. I wrote my first rule against 4.4. In my opinion, using StyleCop without Resharper and the StyleCop-For-Resharper plug-in is just plain silly. These tools make it so easy to write code in accordance to established rules its trivial. Next you might find it very useful to download the full source for StyleCop, not necessary but I found it interesting.
Next you need to figure out how you are going to find the fragments not in accordance with your rule. But first here's how StyleCop breaks down a file of code.
StyleCop Code File Structure
StyleCop breaks a code file down into Elements, statements and expressions.
Elements are large chunks of code, the red blocks below are elements. Basically, namespaces, types, and members.
Each statement line is obviously included in the statement category. I never tested this by having two statements on one line, but having two statements one a line is an incredibly bad idea anyway, so you're on your own there. All lines above are included in this category except whitespace and braces.
Lastly each expression is then every granular item thereafter. For example "this.apple = banana" is an expression and so is "this", ".", "=", and "\"banana\"". The expression list therefore is significantly larger than the previous two categories. Each expression also offers a list of child "tokens" which are the subordinate expressions to the current one. The subordinate expressions will still be visited by the main loop despite being a child of some other expression.
StyleCop accepts three delegates from your custom rule, each one walking each of the above code element categories. Ideally, if you can discover the fault with the line you can raise a Violation right away. If not you will need to analyse the entire file then process the collected data afterwards. (This is the case forJSL StyleCop rules - see below). Each of these expression tree walkers run on its own thread, so cannot easily share state during the process.
Debugging a Rule
Ok, how to debug a rule? I personally looked into writing unit tests against my rule, but found this far too tricky and time consuming. The other option is to have two instances of Visual Studio open one to load some sample code, and the other with your rule code loaded and attach to the other's process. The only downside to this, is when you make changes you will need to close both instances to update your DLL. Suck it up, getting it done will be quicker than fiddling around with unit tests in this case. StyleCop isn't really designed for unit testing.
More specifically you need to copy your built DLL than contains your rule into the StyleCop folder inside your Program Files (or Program Files (x86)) folder, just in the root StyleCop folder is fine (although sub-folders will be searched). Your StyleCop assembly must also contain an XML file describing your rule. This is the file StyleCop will use to add it to the Configuration tree.
Build a 'This' Rule
In my case I am building a rule to enforce only the prefixing of fields with the 'this' keyword. There is a default StyleCop rule for this, but it enforces it in all instance cases (basically where it can be used it should).
I have achieved this by using the Expression delegate of the Analyse Document Walker. I can't use the element part because this is not focusing on individual statements. I have chosen not to use the statement walker delegate because I found it easier to discover the fields and check for violations using the expressions.
There's some code clean up required on the code, but here it is: