Category Archives: 1538

Getting the compile and test status as environment variables when extending TF Build using scripts

The Goal

When running custom batch or PowerShell scripts as part of TF Build, you want to access the compilation and test result using an environment variable.

The Solution

When you use the new TfvcTemplate.12.xaml build process template, it’s easy to run additional scripts or tools as part of the build process.

There is a tool available (TfbEnv.exe) that will create additional environment variables with the compilation/test results. It is free and can be downloaded here.

The tool will always set the following two environment variables:

  • TFB_COMPILATIONSTATUS
  • TFB_TESTSTATUS

The value corresponds to the current result (Succeeded, Failed, Unknown).

Additional environment variables:

  • If compilation succeeds, TFB_COMPILATION_SUCCESS is set to 1.
  • If compilation fails, TFB_COMPILATION_FAILED  is set to 1.
  • If tests succeed, TFB_TEST_SUCCESS is set to 1.
  • If tests fail, TFB_TEST_FAILED is set to 1.

How to use it

There are two ways to use it:

Option 1: Use TfbEnv.exe to generate a batch file which you can call from your scripts to set up the environment variables

  1. Create a batch file that invokes TfbEnv.exe and then calls “SetVars.bat” (which is created by TfbEnv.exe).

    Here’s a very simple example:

    TfbEnv-Batch-File
    (Note: In this example TfbEnv.exe is stored in a “build” folder in Version Control)
  2. In your build definition, set “Post-test script path” to run your batch file:
    TfbEnv-Batch-Parameters
  3. Done. Queue a new build!

Option 2: Use TfbEnv.exe to invoke your batch oder PowerShell script file with the additional environment variables available

  1. In your build definition, set “Post-test script path” to run TfbEnv.exe.
  2. Under Post-test script arguments use the “run” argument to specify the batch file or PowerShell script that you want to run.

    Here’s an example:

    TfbEnv-PowerShell-Parameters
    Figure: In this example, TfbEnv will set up the environment variables
    and then execute the PowerShell script “PostTest.ps1”
  3. Done. Queue a new build!

Note: TFS 2013 Update 2 (2013.2) is required. If you are not on Update 2, you can explicitly use the /collection (or just "/c") parameter to specify your TFS Collection URL.

Enjoy!

–Neno

 

Updated (May 21, 2014): Added a note that TFS 2013 Update 2 is required (+ workaround).

Updates (May 25, 2014): Updated this blog article to explain how to use the tool (2 options).

Writing the Build Report with Associated Changesets and Work Items to a file as part of the build

The Goal

TFS has a nice Build Reporting, including a list of associated changesets and work items (if any). You might want to have this information saved to a file during a build.

Figure 7.6 Build Report

The Solution

When you use the new TfvcTemplate.12.xaml build process template, it’s easy to run addition scripts or tools as part of the build process.

There is a tool available (TfbNotes.exe) that generates a build report in .TXT and .XML format. It is free and can be downloaded here.

All you need is to check-in the file into version control and reference it in the build process, for example at “3. Test” » “2. Advanced” » “Post-test script path”.

TfbNotes_Process

Note: To run more than a single tool, use batch files or PowerShell scripts.

Here’s how the .TXT output looks like:

TfsNotes.exe

Note: TFS 2013 Update 2 (2013.2) is required. If you are not on Update 2, you can explicitly use the /collection (or just "/c") parameter to specify your TFS Collection URL.

Enjoy!

–Neno

Updated (May 21, 2014): Added a note that TFS 2013 Update 2 is required (+ workaround).

Notifying users when a particular work item changes in TFS

The Goal

In TFS you can set up Project Alerts that alert users when work items change. But sometimes you would like to be able to add a list of people to be notified when a particular work item changes.

The Solution

You can achieve this by using a server-side plug-in.

Here’s a step-by-step guide:

  1. Enable SMTP settings for your TFS in TFS Admin Console (if not already done)
  2. Add a custom field to your work item types:
    Type = “string”, Reference Name = “TFS.CcNotificationReceivers”
    image
    … and display it on the Work Item form:
    image
  3. Install server-side plug-in:
    Get TFS.WorkItemTracking.CcNotifications.dll from here (for TFS 2013 only!) and copy it to the “PlugIns” folder, located at: %ProgramFiles%\Microsoft Team Foundation Server 12.0\Application Tier\Web Services\bin\Plugins
    (to uninstall, simply delete the .DLL again)
  4. Done. When you enter user names (or e-mail addresses) into the new field (separate multiple values with commas or semicolons), those users will be notified of any changes that happen to that particular work item.

image

Note: Server-side plug-ins work on TFS on-premises only (not with Visual Studio Online).

Enjoy!

–Neno

Turning off policy overrides in TFS

The Goal

Check-In policies have been around since the first version, TFS 2005, to help a team define a list of steps they want to perform prior the checking in. If a policy is not met, it alerts the user.

When policies fail, there is an option to “override” the warning(s) and continue with the check-in (the policy warnings will still be stored as part of the changeset).

Figure 6.6 CheckIn Policy Violations

While it’s easy to set up an alert to get notified when this happens, or query the TFS Warehouse to get a list of all overrides, there’s no built-in way to turn off overrides entirely.

The Solution

A server-side plug-in that intercepts all check-ins and rejects the changeset if it is a policy override. After activating the plug-in (which is simply a drag & drop of the plug-in .DLL into a specific folder on the TFS Application Tier), this is what happens if users try to override:

No Policy Overrides

How to set it up

  • To install, copy TFS.VersionControl.NoPolicyOverrides.dll to the “PlugIns” folder, located at: %ProgramFiles%\Microsoft Team Foundation Server 12.0\Application Tier\Web Services\bin\Plugins
  • Download the .ZIP package with all event-handlers here (for TFS 2013 only!).
  • To uninstall, just remove the .DLL from the “PlugIns” folder.

A word of warning

Disclaimer:
Server-side event handlers must be very well written. As they run inside of the TFS process itself, they can crash TFS, significantly degrade performance or change the behavior of built-in operations (e.g. a badly written plug-in could cause new team project creation to fail).

Note: Server-side plug-ins work on TFS on-premises only (not with Visual Studio Online).

Enjoy!

–Neno

Extending TFS’ default behavior using server-side plug-ins

In TFS 2005, Check-In Policies helped to ensure certain rules prior to check-in. However, check-in policies are executed locally and you must ensure they are available for the client (in the appropriate version) and installed.

In TFS 2010, Gated Check-Ins were introduced, which allowed validations such as the compilation, unit test execution and more (basically whatever the build script specified) to be run on the server-side and reject the check-in if they failed.

Also with TFS 2010, Microsoft introduced server-side plug-ins, which can handle TFS events and either react to them, or – in some cases – even cancel operations. Technically those plug-ins are implementing the ISubscriber interface (see this blog post how to write and debug them).

A word of warning:

Disclaimer:
Server-side event handlers must be very well written. As they run inside of the TFS process itself, they can crash TFS, significantly degrade performance or change the behavior of built-in operations (e.g. a badly written plug-in could cause new team project creation to fail).

Here’s an example:

Instead of using a check-in policy to enforce that changesets must have comments, a server-side plug-in could be used instead. This would guarantee that our rules are enforced, regardless of the client accessing TFS and if the appropriate check-in policy is available and installed for that client or not.

The server-side plug-in is installed by just copying a single .DLL to a “PlugIn” folder on the TFS Application Tier (or all Application Tier if you have more than one).

The following screenshots show how the message looks like that users will see that try to check-in without a comment.

In Visual Studio:

image
In Windows Explorer (via TFS Shell Extension from TFS Power Tools):

image
In Eclipse:

image

How to set it up

  • To install, copy TFS.VersionControl.RequireChangesetComments.dll to the “PlugIns” folder, located at: %ProgramFiles%\Microsoft Team Foundation Server 12.0\Application Tier\Web Services\bin\Plugins
  • Download the .ZIP package with all event-handlers here (for TFS 2013 only!).
  • To uninstall, just remove the .DLL from the “PlugIns” folder.

Note: Server-side plug-ins work on TFS on-premises only (not with Visual Studio Online).

Enjoy!

–Neno

Updated Tools for TFS 2013

Meanwhile I updated most of my tools for TFS 2013. Here’s a list:

  • TfsClean.exe – Finds and deletes old and unused workspaces and shelvesets.
  • TfsCreateBuild.exe – Creates “fake” builds in TFS without actually running them.(e.g. can be used to store the build results from a different build system)
  • TfsExport.exe – Download files from TFVC without the need for a workspace, set modified date to last check-in date, and remove VC bindings.
  • TfsMoveDescriptions.exe – Moves text from plaintext or HTML fields to another HTML field (e.g. to copy the work item descriptions to the new System.Description field).
  • TfsRefreshWarehouse.exe – Processes the TFS Data Warehouse and Services Cube.
  • TfsReg.exe – Reads or writes values from/to the TFS registry.
  • TfsSyncIdentities.exe – Foces TFS to synchronize identities with Active Directory.
  • TfsWarehouseController.exe – Allows you to set warehouse settings (like the refresh interval).

The most convenient way to get all the tools is to download this .ZIP file: TfsToolsSuite.zip

But wait, there’s more…

Server-Side Plug-Ins:

Download all event-handlers as .ZIP file: TfsEventHandlers.zip.

TF Build Tools:

  • CreateZip.exe
  • FtpUpload.exe
  • TfbEnv.exe – Sets additional environment variables for TF Build.
  • TfbNotes.exe – Writes build report to a file.
  • TfbNuGet.exe
  • TfbSetVer.exe
  • VerifyFile.exe

Download all event-handlers as .ZIP file: TfsBuildTools.zip

Let me know if you find them useful!

–Neno

Available Check-In Policies for Team Foundation Server 2012

Shipping as part of Visual Studio 2012:

  • Builds – Requires that build was successful (CI builds) and therefore build breaks must be fixed before a new check-in.
  • Changeset Comments Policy – Requires that user provide comments on check-ins. (new in VS 2012)
  • Code Analysis – Requires that Code Analysis is run before check-in. [More]
  • Work Items – Requires one or more work items be associated with the check-in.

Note: The Testing Policy that shipped with VS 2010 is not longer available.

Added after installing TFS 2012 Power Tools (needs to be installed an all VS clients):

  • Custom Path Policy – Allows you to scope other check-in policies to specific folders or file types.  [See here for how to use it.]
  • Forbidden Patterns Policy – Prevents users from checking in files with filenames that contain forbidden characters or patterns.
  • Work Item Query Policy – Requires that the associated work items need to be part of the result of a specified work item query.

Note: When using an older version of VS (2008/2010) you need to install the corresponding version of the TFS Power Tools (VS 2008 requires 2008 Power Tools, etc.)

Developed by the Community:
  • Code Review Checkin Policy – allows to enforce Code Reviews prior to check-in (by Colin Dembovsky). Get it here.
  • Checkin Time Tracker v3 – allows you to gather effort values from developers during check-in (by AIT TeamSystemPro Team). Get it here.
  • Column Limit Check-in Policy – prevents users from checking in files that don’t comply with your column limit coding style guidelines (by Gambitrex). Get it here.
  • Merge / Branch Only Check in Policy – Block check ins that are not part of either a branch or merge operation (by Leon Mayne). Get it here.

Note: When using an older version of VS (2008/2010) you need to install the corresponding version of the check-in policies (for a list of check-in policies for VS 2010, see here).

What about the "Override Warnings" link?

There might always be an unforeseen reason why not all policies could be fulfilled.

How can I deploy custom Check-In Policies to all team members?
How can I create custom Check-In Policies?:

Do you know another great check-in policy for TFS 2012? Let me know!

–Neno

Updated (May 17th, 2013): Added Merge / Branch Only Check in Policy.

Export TFS Work Items to an .XML file (using TFS Power Tools)

TFS Work Items can be easily exported to XMLSteps:

  1. Download Team Foundation Server Power Tools.

  2. On the command line use the TFPT.exe utility to export all work items from a team project in .XML format:

    tfpt query /collection:<URL> /format:xml /wiql:"SELECT * FROM WorkItems WHERE [System.TeamProject] = ‘<TeamProject>’ AND [System.WorkItemType] <> ‘Sprint’ ORDER BY [System.Id]" > WorkItems.xml

    As you can see I selected all work items from the team project excluding Sprint Work Items. Feel free to modify the query, if necessary.

Download: Visual Studio 2010 Project Template for TFS Utilities

If you develop small utilities for Team Foundation Server a lot, you might want to save some time and use a project template (see bottom of post for download link) that already comes equipped with the correct references to the Team Foundation Object Model (Microsoft.TeamFoundation.*.dlls) as well as the most important using statements and a few lines of code to get started.

Installation

Copy the ZIP file to {MyDocuments}\Visual Studio 2010\Templates\ProjectTemplates.

Usage

Create a new project and select “TFS Utility” from the “Visual C#” list.

TFS Utility Project Template 

The template creates a new Windows Forms application with references to the Microsoft.TeamFoundation.*.dlls (btw: the C# compiler gets rid of all references that were not used in the project during compilation)…

 References to Team Foundation Object Model

… as well as a a few using statements and some code to start from.

Generated code in Form1.cs 

Happy TFS tool development!

Download: TfsUtility.zip