TechEd 2008 is coming!

If you are going to be at TechEd this year and want to chat face-to-face about Team System or life in general, drop me a line at eugenez_at_attrice_dot_info. See you there!

Work Item Customization tidbits (part 1 of X)

One of the typical TFS administration task is Work Item Template customization. Chances are, even if you never did it sooner or later you will.

However, while work item customization is often represented as very simple activity there is a host of things not to do and also quite a few useful tidbits of information helping to make customizations easier. Over the (three) years that I am working with TFS I have my little arsenal of tricks and I was meaning to make it public for a while. It does not mean to replace the guidance on MSDN but rather to provide less formal description of the things that matter in my opinion. The intended audience is not a seasoned TFS administrator that knows intimately the syntax and what can/cannot be done with it but rather a person who starts designing templates from scratch or contemplating changes to existing ones.

If you want to use work items, there are a few choices

• Postpone work items implementation until source control is stable
  
• Use work item types distributed with TFS (MSF/CMMI templates) or partner templates (Conchango)
  
• Use work item types distributed with TFS as a baseline with minor changes (additional data fields)
  
• Create a new work item type or perform major customization on stock work item types
  

First case does not present any difficulties; the second case also does not present any customization challenges (and is probably atypical since most organizations will have differences with predefined work item definitions).

For the last two scenarios the work item type templates will have to be customized. And that's where questions start – what is the optimal customization strategy?

In order to customize work item types templates efficiently, first prerequisite is to understand their structure. Since TFS is installed with two predefined project templates, it is logical to select one of the work item type templates that are part of those project templates as an example. Let's use MSF Agile Bug WI type, which is pretty simple and yet contains most important concepts.

Some basics to start with – every work item type is defined as XML of special format. This XML is part of the project template (how to download project template). For convenience, the XML that defines Bug work item type can be downloaded here.

The exact schema may be viewed here; I will attempt to try and deal with definitions in less structured way while still supplying links to relevant MSDN contents.

Conceptually, from the term work item one may reach the conclusion that it must have at least two logical parts:

• Data fields describing the work to be performed
  
• Status fields describing current status of work being performed
  

And indeed, simplest work item type template contains three sections (three since we also need to define user interface for WI): FIELDS section that defines data fields relevant for specific type; WORKFLOW section defining states and available transitions between them and FORM section, defining the UI representation of data fields.

Let's look in depth on each of those sections.

First, let's have a look at simple excerpt from Bug WI template FIELDS section:

<FIELD name="Issue" refname="Microsoft.VSTS.Common.Issue"
type="String">
<HELPTEXT>Used to highlight the bug.</HELPTEXT>
<REQUIRED/>
<ALLOWEDVALUES>
<LISTITEM value="Yes" />
<LISTITEM value="No" /> 
</ALLOWEDVALUES> 
<DEFAULT from="value" value="No" />
</FIELD>

In FIELDS section, every FIELD element at the very least needs to specify human readable name and reference name refname together with element type. Both name and refname are unique across Team Foundation server, however, refname is used internally both in code and database and thus cannot be renamed once created. On the other hand, name is exposed to the user and may be renamed if needed.

Another useful bit of information on reference name – in Bug work item template definition one can see that some fields start with System
prefix while others start with Microsoft.VSTS. The naming convention is very useful – the System fields are core fields that represent functionality common to all work item (regardless of the type) and should be present in every work item whereas other fields may be specific to work item type.

In addition to providing name and type, FIELD element may be contain additional elements used to define

• Field tooltip contents (HELPTEXT element)
  
• Field rules that define runtime behavior and constraints
  
• Field behavior in regards to data warehouse and reports
  

Most important of those additional elements are ones that define runtime behavior. Some of the rules available:

• Mandatory field (REQUIRED element)
  
• Read-only field (READONLY element)
  
• Field that is "frozen" – that is cannot be modified once it is set to some value (FROZEN)
  
• Field that cannot be cleared once set and saved (CANNOTLOSEVALUE)
  
• Field that must have different value from other field (NOTSAMEAS)
  
• Field value must match regular expression pattern(s) (MATCH)
  

In addition to the rules that specify certain constraint on the element, there are rules that define action to be executed on field

• Set default value for the field – that is value that will be set when new WI is created (DEFAULT)
  
• Set default value for the field on save on server (useful for such fields as date or originator of change) (SERVERDEFAULT)
  
• Copy value from the other field (COPY)
  

And finally, there are rules that define how multiple values may be specified or stored for the field:

• Allow the field to accept only valid user name (VALIDUSERS)
  
• Allow the field take only values from the list (ALLOWEDVALUES)
  
• Provide list of suggested values for the field [how it is provided is UI-specific] (SUGGESTEDVALUES)
  
• Prohibit field from accepting values in the list (PROHIBITEDVALUES)
  

With that minimal knowledge, it will be easy to understand the example FIELD definition above – it defines mandatory field "Issue" that may accept only values "Yes" or "No"; by default "No" is set (from attribute in DEFAULT specifies whether to take default from scalar value [value] or from another field value [field]).

However, the basic syntax does not provide much flexibility. For example, with that syntax one cannot make field conditionally read-only (say, only for certain users). Also, it is not hard to imagine that certain fields will have to provide certain behavior based on the values of other fields.

And indeed, those scenarios (and many more) can be handled with the help of additional syntax elements. I shall cover those in the next installment.

Source Analysis For C# Checkin Policy

It is a long weekend in US – and what do the geeks do on a holiday? They write code!

So here is my Sunday Night Live Source Analysis For C# Checkin policy (that uses Microsoft Source Analysis engine released several days ago to perform actual analysis). You can get either MSI installer or the source code. Usual caveats (both the compiled version and source code are provided AS IS with no warranties of any kind) apply.

Once you install the check-in policy using MSI above, you are set (since it includes required assemblies from Source Analysis distribution). Only prerequisite is VS 2008 with Team Explorer installed.

Now, when you define check-in policy for Team Project, you will be prompted to define Source Analysis rules to verify on check-in (in a fashion similar to Code Analysis policy). The policy will work only with C# files you check in that are part of the projects included in the active solution; if you have no solution, or the files are not part of the current solution, the policy will fail with appropriate error.

If all C# files are contained in the current solution, Source Analysis will be run on the files before check in; if it fails the policy will fail (double clicking on the failure message will display detailed dialog).

If you want to run Source Analysis on your projects with same definitions as are in the checkin policy, you will have to have Settings.SourceAnalysis file with the appropriate definitions in your project's folder. The policy does not create those files for you; however, when you check in and the policy is evaluated, the file with Source Analysis definitions will be created in the solution folder (named "<solution name>.sln.SourceAnalysis"). This file may be used to enforce same set of rules as in the policy for separate projects analysis.

I have tested the policy with stock C# projects (such as class libraries or executables); but my guess is there may be two-three bugs still hanging around the code. Drop me a line saying how helpful (or how buggy) it is at eugenez_at_attrice_dot_info.

Update: If you are wondering how I know about these Settings files, read all about it and how to use Source Analysis settings efficiently at Source Analysis team blog

Beautify your [C#] code with Microsoft Source Analysis

Hear hear! Microsoft has just released Source Analysis for C# tool! This tool analyzes C# source files for compliance to set of rules in different categories, namely

• Documentation category contains rules related to code documentation (such as "File must have formatted header" or "Elements must be documented")
  
• Layout rules are rules related to text formatting (where curly brackets should be placed etc.)
  
• Maintainability rules are the ones related to default specifiers and missing descriptions (f.e. Debug.Assert without text)
  
• Naming rules are similar to such FxCop rules
  
• Ordering rules check the order of declarations within namespace/class
  
• Readability rules verify that the code does not contain not required extras (such as redundant base specifiers)
  
• Spacing rules check for correct number of spaces in various situations
  

In all there around 200 rules provided!

The tool is installed as VS 2008 Integration Package providing tight integration with IDE. Once installed, two additional menus are available for C# projects in Solution Explorer – one to invoke Source Code Analysis, and another to configure analysis setting per project.

The configuration is somewhat similar to Static Code Analysis rules configuration (but you can look at hint window for rule detailed description)


"Run Source Analysis" menu is located right next to "Run Code Analysis"


Once you run it, Errors tool window will contain source analysis (SAxxxx) errors to handle


Additionally, there is MSBuild targets file (that may be optionally installed as part of the tool installation) that allows running Source Code Analysis as part of the build. Read the article detailing howtos on the development team's blog.

The application's first public release is 4.2 (since the tool was used internally at MS for quite a while) so it is full-featured and quite stable one. I am very excited by that release; in my opinion it may compare to first FxCop release by its importance (and it is free as is FxCop).

And according to the team's blog, the next version might also provide automatic fix options for some rules!

Static Code Analysis presentation goodies

This Wednesday it was my pleasure to present Microsoft Static Code Analysis tools stack to SF .Net user group. Thanks to everyone that has showed up after a busy day for the evening of Static Code Analysis!

Here are some related links:

• Download presentation slides in PowerPoint 2007 format
  
• Download latest version of FxCop
  
• Download Visual Studio Team System/Team Foundation Server trial VPC image
  
• Download code samples for code metrics (courtesy of Conor Morrison at VSTS code analysis team)
  

If anyone has any followup questions or ideas related to the presentation, drop me a line at eugenez_at_attrice_dot_info.

Microsoft loves you – three free tools

Sometimes it is not easy to refrain from posting links instead of original content :) But there are three recently released tools that richly deserve advertising.

Framework Design Studio allows comparing different versions of the same managed library (in binary form). You can filter the interface content being compared, comment on the differences and save the output as MS Word 2007 document.

I have tested the application a little, and it packs surprising amount of functionality. One thing to be aware of is that the user interface is somewhat quirky, so make sure you read the manual before using the app (manual docx is installed as part of the application package).

Typical usage for the app would be to compare new version of third party (meaning only binary is available) library with previous version, in order to discover the changes to interface. Another application I could think of would be to produce sort of release document to be distributed with the new versions of given library (since FDS allows commenting the differences and produces very nicely formatted Word document – beats documenting interfaces changes manually).

VSCT Power Toy is a small application that Visual Studio package developers will kill for. It retrieves command tables (including all ids) from VS packages or VS registry, and even nicely formats it for copy/paste to .vsct file. Anyone who did it without this app can appreciate the difference (look at my previous post if you want to get a feeling). I practically drooled all over the screen with this tool running

Patterns & Practices Documentation Tools is set of instruments Patterns & Practices team uses to create documentation. The tools are Word 2007 (English only) template with macro and associated toolbar to create well-formatted content and PowerShell scripts to convert the document authored through template to HTML, CHM or HxS. I did test the template, and the process of authoring document appears to be pretty smooth. The converters, on the other side, require bunch of things to be installed (in addition to PowerShell). But if you look at P&P produced documents, the result probably worth some extra work.