StyleCop Check-in Policy updated (v 1.3)

I have updated TFS check-in policy for StyleCop 4.3.3.0 and also compiled a version for TFS 2010 (now that it has RTM’ed).

The sources and MSIs (one for TFS 2008 and one for TFS 2010) are now available at MSDN Code Gallery.

Enjoy!

Mirror from my MSDN blog

StyleCop checkin policy updated for StyleCop 4.3.2.1

StyleCop check-in policy was updated for the latest build of StyleCop available (4.3.2.1). The only change in this drop is newer StyleCop reference assemblies.

Version 1.2.2 of the policy is available as MSI installer (available AS IS).

Related posts:
- Updated StyleCop Checkin Policy (v1.2.1)
- StyleCop 4.3 Checkin Policy version 1.2
- StyleCop 4.3 Checkin Policy available
- Get New Version Of StyleCop
- StyleCop Confusion Cleared
- Source Analysis For C# Checkin Policy
- Source Analysis For C#: Custom Rules And More
- Beautify Your Code With Microsoft Source Analysis

Disposing of checkin policy

Recently while I was fixing up StyleCop checkin policy, I came across one small not-so-obvious snippet of knowledge worthwhile to share.

Any custom checkin policy inherits from PolicyBase, which in turn implements IDisposable. Meaning – if you need to clean up after yourself in your custom policy, Dispose method is the place for that.

So in StyleCop policy, I do a lot of Visual Studio related stuff and thus I thought I’d dispose of VS extensibility objects in Dispose method.

And here where non-obvious stuff starts. The policy is loaded in either of those cases:

• Project Source Control configuration (through menu Team->Team Project Settings->Source Control)
• Right-clicking in Solution Explorer and invoking “Check In…” menu
• Invoking “View Pending Changes” toolwindow

While the first case is not very interesting (no pending changes will be evaluated in configuration), two other cases are important.

In case of “Check In …”, “Check In” modal window is displayed (the policy is loaded), and when window is closed, custom policy class is unloaded and Dispose called. However, in case of “View Pending Changes” toolwindow the policy is loaded once when window is first created, and Dispose will be called only when Visual Studio is closed or TFS server connection is closed. That means you probably should not hold on any expensive resources until Dispose.

New check-in policy for VSS fans: keywords expanded

One of the much-talked-about missing features of TFS is the keyword expansion feature. You know, the ability to place the template in the beginning of every single file and then have every revision tracked in the body of the file (in addition to tracking in source control history, that is).

Personally, I am not a huge fan of the feature – mostly because the usefulness of the feature limited by the following factors

1. The comments to check in still have to be detailed (if the comments are crappy, you get a lot of garbage in the file that adds nothing)
2. If the file gets branched a lot, the revision history tend to get muddy and not to reflect the branching history very adequately
3. If the code churn is great, you might get 100 lines of code adorned with 400 lines of revisions history (yes, I actually seen this)

So I am of the opinion that all of the above is the function of source control and if your source control is not good enough for tracking history of changes – that ain’t good source control :) However, for some folks ability to have history of changes contained in the same file outweighs the disadvantages. And these folks were pretty vocal, so vocal that Buck Hodges stopped one stop short of writing actual solution and provided the verbal recipe for writing one, using check-in policy as a workaround (since keywords expansion is not making it into official product).

And voila! Two years after this post was published, there appears TFS keyword expansion checkin policy, written by Jochen Kalmbach. Jochen also published the policy on CodePlex site, under the name of LogSubstPol.

I did a short test drive of the policy, and it does work as advertised, in three simple steps:

1. Install the policy (currently using batch script)
2. Add the policy to your Team project and configure the format of the keywords string
3. Add  keyword ($log$ etc.) monikers to the file modified prior to check in

Once all of that done (and steps 1 & 2 are once per project, step 3 once per file step), as you check in you will see the revision history being updated and checked in as part of the file.

While the policy is awesome, there are few things to be aware of.

• As the policy requires you to supply the comment, it effectively replaces “Changeset Comments Policy”, so if you have it defined for Team project you might want to remove it
• Configuration dialog for the policy is somewhat complex, so read the documentation first (supplied PDF is real good)
• If you evaluate the policy but decide not to check in, due to limitations of the checkin policy mechanism the keywords in the file will get expanded anyway
• As the files are updated by the policy, VS will display the message “The file has been modified outside of the source editor” (as policy touches it right before check in). That again may be limitation of the checkin policy mechanism for keyword expansion (but perhaps can be mitigated with some creative VSX tweaking)

But regardless of these small thingies, the policy is mighty useful and it fills the big gap for those accustomed to keyword expansion. Big kudos to Jochen for creating the policy!

Mirror from MSDN blog

Updated StyleCop Checkin Policy (v1.2.1)

After countless nugdes I have updated StyleCop check-in policy for newest build of StyleCop available (4.3.1.3). While at it, I was able to incorporate a few bug fixes and add improvements.

Version 1.2.1 of the policy is available as MSI installer or as zipped source code (available AS IS).

Bugs fixed are:

• Solution containing projects with same Name is not evaluated correctly (keying schema is now by Project VS object instead of Name)
• Same file appearing in different projects causes policy exception
• C# web site projects are now supported

For the last two items, huge thanks to Clement Bouillier for bringing them to my attention.

Additionally, I have added pretty neat feature (in my opinion) to improve the navigation for the errors found by the policy. When policy is evaluated, now any violation found is added both to Checkin dialog and to Visual Studio Error List pane. Thus you can review the violations in the form similar to non-policy StyleCop violations. Additionally, clicking on policy violation either in Checkin window or Error List pane now will bring up the file and the line the violation is found in.

Policy violations are cleared from Error List pane when the policy is re-evaluated or on project build.

If you encounter any issue with the new drop, please make sure to leave a comment (and I promise to handle the issues promptly this time).

And while at StyleCop topick, I’d like to point to an excellent project driven by Howard Van Rooijen – StyleCop integration with ReSharper. If you use both, make sure you get the latest drop from Codeplex.

Related posts:
- StyleCop 4.3 Checkin Policy version 1.2
- StyleCop 4.3 Checkin Policy available
- Get New Version Of StyleCop
- StyleCop Confusion Cleared
- Source Analysis For C# Checkin Policy
- Source Analysis For C#: Custom Rules And More
- Beautify Your Code With Microsoft Source Analysis

StyleCop 4.3 Checkin Policy version 1.2

Since the last release of the policy, I have received several comments that required attention, and finally I was able to make changes to the code.

Version 1.2 of the policy is available as MSI installer or as zipped source code (available AS IS), and contains the following new features:

• Ability to import settings from existing *.StyleCop settings file when creating new policy
• Support for VS projects placed under solution folders
• Every StyleCop analysis violation is displayed as separate check-in policy violation; summary window is still available when double clicking the policy violation

Using the occasion, I would like to touch upon some points in policy implementation detail

1. Policy needs Visual Studio to execute, since it makes use of VS extensibility to analyze only the files contained in C# projects in currently opened solution. The idea behind it is as follows: if you have an analysis violation, you should be able to fix that and then compile the code, and that can be done easily only for the current solution
2. Policy supports all flavours of C# projects in VS; I have tested most and am not aware of any unsupported projects at this time. Any feedback welcome!
3. Current version of the policy displays every analysis violation as separate check-in policy failure; however, it does not support easy navigation between policy failure and source code that caused the violation. This is the big must have feature for the next release

And talking about the next release, I am hoping to move source code to CodePlex, so it would be more easily available for modifications. Right now, if you have patches be welcome to send them in.

Related posts:
- StyleCo 4.3 Checkin Policy available
- Get New Version Of StyleCop
- StyleCop Confusion Cleared
- Source Analysis For C# Checkin Policy
- Source Analysis For C#: Custom Rules And More
- Beautify Your Code With Microsoft Source Analysis

StyleCop 4.3 Checkin Policy available

In addition to recent release of StyleCop 4.3, Jason Allor has just released the documentation for extending StyleCop with custom rules (aka StyleCop SDK). CHM file contains information on writing custom rules, integration of StyleCop into build process and API reference.

Since new version of StyleCop includes many bug fixes as well as new rules and in the spirit of documented SDK available, I have updated the check-in policy for StyleCop 4.3. The changes include mostly namespace changes (to StyleCop from SourceAnalysis) as well as couple of fixes.

Please note that version 1.1 of policy is not compatible with the previous version; you will have to uninstall old version and reconfigure the Team Projects accordingly.

You can get either MSI installer or the source code. Both the compiled version and source code are provided AS IS with no warranties of any kind.

Related posts:
- Get New Version Of StyleCop
- StyleCop Confusion Cleared
- Source Analysis For C# Checkin Policy
- Source Analysis For C#: Custom Rules And More
- Beautify Your Code With Microsoft Source Analysis

Configuring check-in policies

One interesting moment to be aware of in custom check-in policies implementation is how to implement the policy configuration. Overall, it is rather easy to implement custom check-in policies and there is a whole lot of documentation available (I especially like and highly recommend excellent article in MSDN Magazine by Brian Randell).

The configuration is initially performed when you define check-in policy; later, the configuration can be performed using “Edit” button in Source Control Settings dialog. Good example of configurable check-in policy is Code Analysis policy, since there user has to specify set of rules applicable in check-in policy evaluation.

When you create your custom policy, you override Edit method from IPolicyDefinition interface to display your own custom configuration dialog. But what do you do with the values specified by the user in the dialog (no matter whether it is elementary type or custom data structure)?

None of IPolicyXXX interfaces you implement in your custom policy provides any special methods for storage or retrieval of configuration. TFS serializes the instance of your custom check-in policy class, so to make sure your custom configuration is available, you need to expose it as the class member variable. Since you policy class  is marked as Serializable, the value will be persisted and available when the policy is evaluated at check-in time.

The mechanism is very simple; only caveat is that you must make sure that any internal variables that are not to be persisted are marked as NonSerializable. Here is small example:

[Serializable]

public class Policy : 

   Microsoft.TeamFoundation.VersionControl.Client.PolicyBase

{

    // Configuration to be serialized – may be used in Evaluate etc.

    private string _configuration;

    // Required for internal logic; do not serialize

    [NonSerialized]        

    private _DTE _dte;

    //...

}

Now, what if the policy configuration should be global and easily changeable? Then the mechanism above for all its simplicity is not very suitable (since once you change the configuration, the data gets serialized into bowels of TFS and is not readily available). Another problem you might face is the versioning of the policy – since the policy is defined on per Team Project basis, when you release a new version and it contains breaking changes to configuration, you will not only have to redeploy it on all client workstations, but also re-add it in all Team Projects.

What I did in such cases (and mind you, this is only one possible approach) is to make configuration file external to the policy implementation (meaning that policy will only consume the configuration but will not edit it). It may be tempting to make that configuration local, but that will actually make things worse (think about synchronizing configuration across all workstations). The easiest solution I have found so far is to put the configuration files somewhere on TFS server and make them accessible over http (using URL similar to “http://tfsserver01/configuration/policy_v1.xml”). Since in most cases TFS server URI is readily available from insides of check-in policy code, this location can be considered well-known. Of course, you would not want to put any security related data (passwords etc.) in that configuration file, but for most custom check-in policies that should not be a concern.

Using that approach, to change the configuration for your policy, you’d modify the external XML file. It may be one global file, or one per version of the policy or even one per Team Project (depending on your custom logic) – but since it will be external to serialized policy, the configuration is easily versioned and changeable without ever touching serialized data in TFS database.