Feb 282012
 

The TFS 2010 build system is very powerful but has a steep learning curve through build controllers, build agents, MSBuild, Windows Workflow Foundation, custom activities and more. With that in mind, I thought it would be helpful to explain a simple (but very useful) TFS 2010 build customisation from end to end. If you are going to follow this process along I recommend you use a development machine or temporary VM so you can break things without consequences – it’s tough to learn if you are terrified of making mistakes!

The Goal

The aim here is to:

  1. Create a sample application
  2. Create a build definition for the application
  3. Customise the build process to stamp the application’s output assembly with the full build number, so you only need the assembly to trace right back to source code and work items

The customisation also includes a common versioning approach, which is well documented in the ALM Rangers Build Customisation Guide. The ALM guide is targeted to intermediate to advanced users, whereas this is more of a tutorial for developers with little exposure to build.

I will assume you have already installed the build service and created a build controller and build agent.

Sample Application

This is going to be a console application that simply outputs the assembly properties we are interested in.

  1. Start Visual Studio and create a new C# Console Application called SampleApplication or similar (VB.NET would be fine, but the sample code below is C#). Tick the box to add it to source control.
  2. Open the AssemblyInfo.cs file and add some text within the AssemblyDescription that you will recognise – anything will do. Delete the existing comment which has an AssemblyVersion example as it will confuse the versioning workflow that comes later.
  3. Open the Program.cs file, paste in the code below, then run the application to see the output.
  4. Check in to source control.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Reflection;
using System.Diagnostics;

namespace AssemblyVersioning
{
class Program
{
static void Main(string[] args)
{
Console.WriteLine("AssemblyVersion: {0}",
Assembly.GetExecutingAssembly().GetName().Version.ToString());
Console.WriteLine("AssemblyFileVersion: {0}",
FileVersionInfo.GetVersionInfo(Assembly.GetExecutingAssembly().Location).FileVersion.ToString());
Console.WriteLine("AssemblyDescription: {0}",
FileVersionInfo.GetVersionInfo(Assembly.GetExecutingAssembly().Location).Comments.ToString());

Console.ReadLine();
}
}
}

Build Definition

We will set up a build using the default template to make sure it works before we start changing things. Note that there are many other configuration options available, but those below are the minimum required for now.

  1. In Visual Studio open the Team Explorer panel.
  2. Expand your Team Project, then right-click on Builds and select New Build Definition…
  3. Select General on the left. Give the definition a name.
  4. Select Trigger on the left. Leave this as Manual.
  5. Select Workspace on the left. Under the Source Control Folder heading modify the location to the folder containing the sample application solution file. The build system will get the latest version of everything under this folder (and it’s also the trigger folder for continuous integration builds).
  6. Select Build Defaults on the left. Ensure the build controller is selected, then enter a folder in the drop location field. Under live use this would normally be a file share accessible to the team, but for this purpose could be local to the build machine. Note that even if it’s a local folder it needs to be in the \\machinename\fileshare format.
  7. Select Process on the left. Expand Items to Build and set the Projects to Build to the sample application’s solution file. If the sample application is still open, this will have been populated for you.
  8. Save the build definition.
  9. In Team Explorer, right-click the new build definition and select Queue New Build then click the Queue button.
  10. The Build Explorer will open and you can double-click the running build to see its progress.
  11. Go to the drop location configured above and verify that the compiled application is present and runs OK.

Custom Build Activity

The template changes depend on a custom build activity, so we will need to get that in place first.

  1. Create a new source control folder called CustomActivities (or similar). (A logical location would be under the BuildProcessTemplates, or you could make both “templates” and “activities” child folders of a new BuildProcess folder.)
  2. Download the Community TFS Build Extensions. Open the zip file, copy the contents of the Visual Studio 2010 folder into the new CustomActivities folder, then add the files to source control and check-in.
  3. In Visual Studio open the Team Explorer panel.
  4. Right-click on Builds and select Manage Build Controllers…
  5. Select your build controller then click the Properties button
  6. Under Version control path to custom assemblies… enter the path to the CustomActivities folder
  7. Click OK
  8. You will now be back at the Manage Build Controllers dialog and will see that the controller and agent are both offline. This happens while new build activities are being processed. After a short while the controller then the agent should come back online.

Process Template

Now we will create a customised process template and add a custom versioning activity to it.

  1. Locate the build template DefaultTemplate.xaml in source control, by default this is under the BuildProcessTemplates folder.
  2. Make a copy of the file and rename it to CustomTemplate.xaml (or similar). Add to source control but don’t check-in yet.
  3. Create a new C# class library called BuildTemplates and put it under the BuildProcessTemplates folder. Tick the box to add it to source control.
  4. Delete the Class1.cs file.
  5. In Solution Explorer right-click the project and select Add -> Existing Item then select the CustomTemplate.xaml file. Click the small downwards pointing triangle on the Add button  and select Add As Link.
  6. Add references to all the DLLs in the CustomActivities folder.
  7. Add references to the following assemblies on the .NET tab of the Add Reference dialog: System.Drawing, System.Xaml, Microsoft.TeamFoundation.Build.Client, Microsoft.TeamFoundation.VersionControl.Client, Microsoft.TeamFoundation.WorkItemTracking.Client
  8. Add references to the following assemblies located in folder C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\PrivateAssemblies\: Microsoft.TeamFoundation.Build.Workflow, Microsoft.TeamFoundation.TestImpact.BuildIntegration
  9. Add a reference to the following assembly located in folder C:\Windows\assembly\GAC_MSIL\Microsoft.TeamFoundation.TestImpact.Client\10.0.0.0__b03f5f7f11d50a3a\: Microsoft.TeamFoundation.TestImpact.Client
  10. Double-click CustomTemplate.xaml to open the workflow editor.
  11. Open the Toolbox panel. You should see many workflow activities organised into different tabs.
    1. Right-click within the Toolbox and select Add Tab… then name the tab Community TFS Build Extensions
    2. Right-click the new tab then select Choose Items…
    3. Click the Browse button and navigate to the BuildActivities folder.
    4. Select TfsBuildExtensions.Activities.dll then click the Open button.
    5. Click the OK button
    6. Right-click the toolbox tab again and select Sort Items Alphabetically (recommended)
  12. You should now be back at CustomTemplate.xaml in the editor. Click the Arguments tab at the bottom.
  13. Add three new arguments VersioningFilespec, DisableVersioning and VersioningStartDate with types and defaults as shown under the Arguments heading below.
  14. Still in the list of arguments locate the Metadata entry and click the ellipsis button (three little dots) in the Default value column. Add three entries, one for each new argument, as shown under the Metadata heading below. In addition, set the View this parameter when: drop-down for all three to Always show the parameter.
  15. Now you need to edit the workflow.
    1. Locate the activity Run On Agent then expand it
    2. Within Run On Agent locate Initialize Workspace
    3. From the Control Flow tab of the toolbox drag an If activity right after Initialize Workspace (before If CreateLabel)
    4. Open the properties for the If activity and set the DisplayName to If Versioning and the Condition to DisableVersioning = False
    5. Expand the If Versioning activity so you can see the Then and Else boxes
    6. From the Control Flow tab of the toolbox drag a Sequence activity into the Then box then set its DisplayName to Versioning
    7. This should have given you some understanding of how to modify the workflow, but it would be tortuous to continue this way so we will cut-and-paste to finish this work
    8. Save and close CustomTemplate.xaml then right-click the file in Solution Explorer and select View Code.
    9. Locate the root Activity node and add a new namespace attribute as follows: xmlns:tat=”clr-namespace:TfsBuildExtensions.Activities.TeamFoundationServer;assembly=TfsBuildExtensions.Activities”
    10. Find the text If Versioning then replace the whole If element with the XML shown under the heading Workflow XML below.
    11. New close the file and re-open in the Workflow editor again. The versioning workflow should look like the example under the Workflow heading below.
    12. Check the template and project into source control.

Note: The forthcoming Windows Workflow Foundation 4.5 has a search function which will make finding your way around the workflow much easier

Arguments

Metadata

Parameter Name Display Name Category Description
VersioningFilespec Files to Version Versioning Enter search patterns for files where version info should be updated
DisableVersioning Disable Versioning Versioning Specify True to skip versioning assemblies; False to version as defined by the Versioning settings
VersioningStartDate Start Date Versioning Start date for calculating build element of version number

.

Workflow XML


<If Condition="[DisableVersioning = False]" DisplayName="If Versioning" sap:VirtualizedContainerService.HintSize="552,995" mtbwt:BuildTrackingParticipant.Importance="Low">
<sap:WorkflowViewStateService.ViewState>
<scg:Dictionary x:TypeArguments="x:String, x:Object">
<x:Boolean x:Key="IsPinned">True</x:Boolean>
<x:Boolean x:Key="IsExpanded">True</x:Boolean>
</scg:Dictionary>
</sap:WorkflowViewStateService.ViewState>
<If.Then>
<Sequence DisplayName="Versioning" sap:VirtualizedContainerService.HintSize="427,889">
<Sequence.Variables>
<Variable x:TypeArguments="scg:IEnumerable(x:String)" Name="VersioningFiles" />
<Variable x:TypeArguments="x:String" Name="major" />
<Variable x:TypeArguments="x:String" Name="minor" />
<Variable x:TypeArguments="x:String" Name="version" />
<Variable x:TypeArguments="x:String" Name="filecontents" />
</Sequence.Variables>
<sap:WorkflowViewStateService.ViewState>
<scg:Dictionary x:TypeArguments="x:String, x:Object">
<x:Boolean x:Key="IsExpanded">True</x:Boolean>
<x:Boolean x:Key="IsPinned">True</x:Boolean>
</scg:Dictionary>
</sap:WorkflowViewStateService.ViewState>
<mtbwa:FindMatchingFiles DisplayName="Find Versioning Files" sap:VirtualizedContainerService.HintSize="405,22" mtbwt:BuildTrackingParticipant.Importance="Low" MatchPattern="[SourcesDirectory &amp; String.Join(&quot;;&quot; &amp; SourcesDirectory, VersioningFilespec)]" Result="[VersioningFiles]" />
<ForEach x:TypeArguments="x:String" DisplayName="For Each File" sap:VirtualizedContainerService.HintSize="405,703" mtbwt:BuildTrackingParticipant.Importance="Low" Values="[VersioningFiles]">
<sap:WorkflowViewStateService.ViewState>
<scg:Dictionary x:TypeArguments="x:String, x:Object">
<x:Boolean x:Key="IsPinned">True</x:Boolean>
<x:Boolean x:Key="IsExpanded">True</x:Boolean>
</scg:Dictionary>
</sap:WorkflowViewStateService.ViewState>
<ActivityAction x:TypeArguments="x:String">
<ActivityAction.Argument>
<DelegateInArgument x:TypeArguments="x:String" Name="file" />
</ActivityAction.Argument>
<Sequence DisplayName="Version File" sap:VirtualizedContainerService.HintSize="375,597" mtbwt:BuildTrackingParticipant.Importance="Low">
<sap:WorkflowViewStateService.ViewState>
<scg:Dictionary x:TypeArguments="x:String, x:Object">
<x:Boolean x:Key="IsExpanded">True</x:Boolean>
<x:Boolean x:Key="IsPinned">True</x:Boolean>
</scg:Dictionary>
</sap:WorkflowViewStateService.ViewState>
<mtbwa:WriteBuildMessage sap:VirtualizedContainerService.HintSize="353,22" Importance="[Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.High]" Message="[String.Format(&quot;Versioning file {0}&quot;, file)]" mva:VisualBasic.Settings="Assembly references and imported namespaces serialized as XML namespaces" />
<Assign DisplayName="Read file contents" sap:VirtualizedContainerService.HintSize="353,58" mtbwt:BuildTrackingParticipant.Importance="Low">
<Assign.To>
<OutArgument x:TypeArguments="x:String">[filecontents]</OutArgument>
</Assign.To>
<Assign.Value>
<InArgument x:TypeArguments="x:String">[System.IO.File.ReadAllText(file)]</InArgument>
</Assign.Value>
</Assign>
<Assign DisplayName="Get major version" sap:VirtualizedContainerService.HintSize="353,58" mtbwt:BuildTrackingParticipant.Importance="Low">
<Assign.To>
<OutArgument x:TypeArguments="x:String">[major]</OutArgument>
</Assign.To>
<Assign.Value>
<InArgument x:TypeArguments="x:String">[New System.Text.RegularExpressions.Regex(".*?assembly: AssemblyVersion\(""(?&lt;major&gt;[\d]*)\.(?&lt;minor&gt;[\d]*)").Match(filecontents).Groups("major").Value]</InArgument>
</Assign.Value>
</Assign>
<Assign DisplayName="Get minor version" sap:VirtualizedContainerService.HintSize="353,58" mtbwt:BuildTrackingParticipant.Importance="Low">
<Assign.To>
<OutArgument x:TypeArguments="x:String">[minor]</OutArgument>
</Assign.To>
<Assign.Value>
<InArgument x:TypeArguments="x:String">[New System.Text.RegularExpressions.Regex(".*?assembly: AssemblyVersion\(""(?&lt;major&gt;[\d]*)\.(?&lt;minor&gt;[\d]*)").Match(filecontents).Groups("minor").Value]</InArgument>
</Assign.Value>
</Assign>
<tat:TfsVersion AssemblyVersion="{x:Null}" Build="{x:Null}" DateFormat="{x:Null}" FailBuildOnError="{x:Null}" IgnoreExceptions="{x:Null}" Revision="{x:Null}" TextEncoding="{x:Null}" TreatWarningsAsErrors="{x:Null}" Action="GetAndSetVersion" AssemblyDescription="[BuildDetail.BuildNumber]" CombineBuildAndRevision="False" Delimiter="." DisplayName="Set Version" Files="[{file}]" ForceSetVersion="False" sap:VirtualizedContainerService.HintSize="242,22" mtbwt:BuildTrackingParticipant.Importance="Low" LogExceptionStack="True" Major="[major]" Minor="[minor]" PaddingCount="0" PaddingDigit="" SetAssemblyDescription="True" SetAssemblyFileVersion="True" SetAssemblyVersion="False" StartDate="[VersioningStartDate]" UseUtcDate="False" Version="[version]" VersionFormat="Elapsed" VersionTemplateFormat="0.0.0.0" />
<mtbwa:WriteBuildMessage sap:VirtualizedContainerService.HintSize="353,22" Importance="[Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.High]" Message="[String.Format(&quot;Version has been set to {0}&quot;, version)]" mva:VisualBasic.Settings="Assembly references and imported namespaces serialized as XML namespaces" />
</Sequence>
</ActivityAction>
</ForEach>
</Sequence>
</If.Then>
</If>

Workflow

Update Build Definition

Now we need to modify the build definition created earlier to use the customised template.

  1. Right-click the build definition created earlier and select Edit Build Definition…
  2. Select Process on the left. On the right under Build process template click Show details.
  3. Click the New button then choose the option to Select an existing XAML file
  4. Choose CustomTemplate.xaml then click the OK button
  5. You will notice the new Versioning parameters but don’t need to edit them – the defaults will work fine.
  6. Save the build definition.
  7. Right-click the build definition and select Queue New Build the click the Queue button.
  8. Once the build has finished:
    1. In the build output click View Log and find the message saying that the version has been set
    2. Go to the drop location and check that the file version matches the one generated by the build.
    3. Also check that the file comments contains the full build number. Prior to Windows 7 you could simply bring up the file properties to see this. In Windows 7 it is frustratingly not shown in Windows Explorer but can be displayed using Powershell – change the directory to the drop folder containing the executable then run (dir “SampleApplication.exe”).VersionInfo.Comments

How it Works

After the build agent retrieves the latest files from source control, the process locates files matching the pattern specified and uses community build extension TfsVersion to do the rest – remove the read-only flag on the file, set the version and description, then put the read-only flag back on to avoid upsetting future gets from source control. Compilation then proceeds as normal, oblivious to the fact that something has been changed behind the scenes.

Feb 172012
 

The concept of technical debt can be a great educational tool, because it helps describe in business-friendly terms why working software is not necessarily good software. The analogy of financial debt being like substandard code is compelling – it feels intuitively right – but like all analogies if you stretch it too far it will break. Before going further into that, here’s a quick summary of the mainstream understanding of “technical debt”:

  • When you cut corners in software development you accumulate a “debt”
  • The additional effort required to do the job right is the amount of the debt
  • “Interest” must be paid, in the form of additional resources needed to support and maintain the software

Anyone who has coded for a while won’t need persuading that quick and dirty hacking is a false economy, but it is tough to explain a programmer’s gut feeling for good and bad code to those who shy away from Excel formulas. However, bring in the idea of technical debt and they should start to get it pretty quickly. I introduced the concept in a recent role and found it very useful – I circulated articles, banged on about it at the drinks machine, and invited the team to an online seminar by a leading expert. They were getting it.

But the online seminar concerned me. The presenter was talking about quantifying technical debt, making trade-offs, and strategic technical debt. The idea of technical debt doesn’t stand up to being stretched this far, and it is dangerous when it happens because the resulting decisions will be based on a broken model. Only luck will prevent those decisions from turning out bad. Here’s where I think the analogy breaks down:

Aspect Financial Debt Technical Debt
Visibility You can’t miss it – it’s on the balance sheet Invisible
Quantifiability Easy to quantify by definition No dependable way to quantify
Who owes who? You owe someone else You owe yourself
Payback You must make payments You aren’t obliged to pay anything back, ever
Failing to pay You go bankrupt Your business can continue and be successful

.
Looking at it soberly, technical debt is not much like financial debt at all. It’s an enlightening metaphor, no more.

What we are really trying to get people to understand through technical debt is this: quality matters, ignore it and your software will rot. It will become unreliable, risky and expensive to support and maintain, difficult to extend, and demoralising to work with. You might be able to hide the symptoms from customers by pouring money into the problem, but if that becomes uneconomical the cracks will open up and your reputation may suffer. What business wants that?

* * * * *

While writing this I came across a recent article on the topic from Better Software magazine – which is excellent further reading.

Feb 162012
 

In a perfect world, we would all be working on high quality greenfield projects using all the latest technologies and development practices. But often (in my experience at least) we are called on to support applications that have grown uncontrollably for many years, carrying enough technical debt to make Greece blush.

But even these monstrosities can benefit from modern ALM practices such as automated build and deployment. So in this post I’m going to talk about automated deployment of a real-life legacy web application using scripting, Psexec and other command-line tools – all coordinated by TFS 2010.

The Scenario

The application had been developed chaotically by many people over a decade or more using every Microsoft technology you could name: C++, VB, VBScript, VBA, C#, .NET 1.1, .NET 2.0, ASP, ASP.NET… you name it, it was in there somewhere. There had never been a rewrite, re-architecting or even any hints of refactoring. Yet development on this key application continued, and while there was an appreciation that things needed to improve there was certainly no appetite for any major rework.

The Challenge

The goal was to improve quality and productivity, and reduce risk. I know it’s a cliché, but the way to eat an elephant is one bite at a time, and that is how I approached this problem. The steps below were taken to tame this beast, tentatively, over several months while development continued relatively uninterrupted:

  1. Migrated source control from Visual SourceSafe to TFS 2010 (there is plenty of documentation on this, just make sure you practice before doing the real migration).
  2. Productised the application – defined the elements that it is (and isn’t) made of, and got them all organised in source control to establish a “single source of truth”.
  3. Migrated issue tracking from a proprietary system to TFS 2010 Work Items so changes going forward are transparently tracked.
  4. Got the application to compile with a minimal (but fully documented) set of components required to be installed. Later work cleaned up referenced dependencies, which were scattered and sometimes in conflict.
  5. Introduced TFS automated builds, starting with continuous integration.

So far, so good. By this point, we knew what we were dealing with and were building it on every check-in. There were even unit tests – which were patchy in coverage and quality, but much better than nothing.

The next step was to get this caged monster deploying to a test environment, fully automated, starting from a standard base configuration. The existing  process was documented as manual steps over dozens of pages, and it still wouldn’t work first time – days would be lost “setting it up” after following the install procedure. If you can’t easily deploy your application onto fresh hardware, then something is seriously wrong.

The benefits of a clean and endlessly repeatable deployment process are many, but getting there wouldn’t be easy.

WebDeploy

An early decision was made to restrict the deployment to a collection of ASP.NET web applications, as this was the more modern part of the app, and under constant development. The latest and greatest technology for this is the unimaginatively named Web Deployment Tool, also known as WebDeploy and MSDeploy, which is built on top of MSBuild – Microsoft’s core compilation technology.

We spent a good deal of time working with WebDeploy, but it turned into a battle. The constraints of old application and OS technology, and multiple web applications were a big headache and the pretty Visual Studio tooling soon fell short, leaving us working directly with MSBuild files.

Personally, I like the change of direction in TFS 2010 to restrict MSBuild to compilation, and use Windows Workflow for build “orchestration”. Once you go beyond compilation and directly related activities, changing XML-based MSBuild scripts feels awkward compared to the intuitive free-flow of WF (the abbreviation is not WWF – I think even Microsoft is scared of the World Wide Fund for Nature). So we ditched WebDeploy and decided to roll our own TFS Build and scripting solution.

The Solution

I came across many issues as I put our deployment solution together, so I will set the whole process out here and pick out the problems.

When to Deploy

The default TFS build process template is necessarily complex, and I intuitively put an Invoke Process activity to start the deployment after the steps which compile and test the solution. However, our solution had functional tests (calling high-level methods which use web services and the database) so you would get test failures because the tests relied on the deployment itself. So I simply moved the deployment step before the tests, and ensured any parts which the tests depended on would run synchronously so they finished before the tests started (more on this later).

There is a potential downside to this, which is that the compile and test steps are within a for-each loop for each solution and configuration combination. If you compile more than one solution and/or configuration in your build definition (which I personally don’t like to do) it will get messy. The deployment would run multiple times, but if you added a condition of some sort to ensure it runs only after the last compilation, it might be too late for any tests which depend on it. I didn’t need to deal with this issue, but controlling the order of compilation and breaking up the deployment seems like a solution. Another option would be to have multiple builds, each with a single solution and configuration, and have one build trigger the next.

Passing Parameters

It is very useful to pass information from the build definition and build system through to the deployment scripts. To achieve this I created a handful of new arguments in a new “Deployment” category, including:

  • An on/off toggle
  • Email addresses to notify of build completion
  • Processes to invoke to do the deployment
  • Text about the deployment to display in the build log

The processes argument could include placeholders in curly braces, which the build template was customised to recognise and replace appropriately. For example, placeholders of {BUILDNUMBER} and {BUILDID} would be substituted by the actual build number and numeric build ID respectively. The scripts could use this information to stamp the website with a build number and send an email with a link to the TFS Web Access version of the build log. (Incidentally, it’s an annoyance for a pedant like me that the build number is not a number, that’s the build ID – am I alone in being bothered by that?)

Strategy

I settled on a fairly simple process that worked for the first application and all those it was extended to. It used a file share on the target server as a working folder, and went like this:

  1. Clear the file share on the target server
  2. Copy the scripts and any other files to the file share on the target server
  3. Repeat steps 1 and 2 if there are multiple servers in the deployment
  4. Stop application websites and start the maintenance website on the remote server(s). I used Psexec for this initially but found it unreliable (more on that later) so switched to iisweb with much better results
  5. Package the application into one or more zip files.
    1. I used the 7-Zip command line tool 7za.exe, and a combination of copy and xcopy. Temporarily I used the incredibly flexible robocopy to deal with the horrible consequences of referencing different versions of the same assembly from different projects in the same solution – the application was fixed properly later.
    2. Any web.config or app.config transforms will need to take place before this step. I posted previously about how to trigger this without a full publish action.
  6. Copy the zip package(s) to the target server(s)
  7. Run the deployment actions in an inside-out sequence. So in a three-tier architecture: database, then the application layer, then the UI layer.
    • I used Psexec to asynchronously hand over the deployment to each target server. This takes the load off the build server and means the deployment runs as a process local to the server, which can be helpful for security and performance reasons.
    • If you want the build server to wait for the some or all of the deployment to finish, either run the deployment remotely from the build server or use a signal such as a “semaphore file” to tell the build server when the process is complete (see the ALM Rangers build guidance for more on that).
    • If using 7-Zip to extract zip files use the -y switch to avoid prompts hanging the process.
  8. When the deployment actions were complete, the final server in the deployment sequence was scripted to:
    1. Stop the maintenance website and start the application’s website
    2. Copy all the generated logs into the build drop folder
    3. Send an email notification of the deployment

Preparatory steps and signposting of deployment steps were output into the build log itself, but process calls with extensive output were set to use log files instead. The build log doesn’t lend itself well to very verbose logging.

Psexec

This is a command line tool from Sysinternals which performs the magic of triggering a process on a remote machine. It is very temperamental about how it is used but not unreliable once you find a stable usage pattern. Here are the lessons I learned:

  • Admin shares (\\server\C$ style file shares) need to be enabled on the remote machine.
    • This requires some one-time config changes if the server has been hardened against it (which should only be done on an internal network with appropriate approval). I needed to set Server and Computer Browser services to run automatically, set registry key HKLM\SYSTEM\CurrentControlSet\Services\lanmanserver\parameters to 1, and kill/restart the explorer.exe process.
  • The full path to Psexec is needed for it to be found by the build agent (even if it is under the PATH environment variable)
  • cmd /c is necessary to run Psexec from an InvokeProcess build activity as it is a console command, not a standalone executable
  • Psexec returns its own output as StdErr, causing the build log to contain an error for every line of output – and failing the whole build. You can use output handler 2>&1 to push StdErr into StdOut.
  • Psexec likes to output empty lines but you can strip them out within (or before) a WriteBuildMessage activity
  • For reliability I found I needed switches -d and -accepteula to run non-interactively and accept the embedded license agreement (the latter is common to Sysinternals tools).
  • I used Psexec only once per server, which seemed necessary to avoid overlapping processes (I don’t know why that should have been a problem, but it caused poor reliability). Having this constraint actually helped ensure the deployment process was well structured.
  • If you don’t specify a user account, Psexec uses impersonation which may result in the remote machine lacking access to network resources. This can be avoided by explicitly passing the username and password.
  • To pass the output of a remotely executed command to a log requires a middle-man script on the remote server. If you try to log on the calling server, you will get the output of Psexec itself, not the command being called.
Shared Deployment Scripts

This deployment strategy was later reused for other applications. To avoid duplication of componentised scripts and other shared items, I moved them to their own source folder and included them in the workspace of the build definition. You can’t map two source folders into the same working folder, so you have to figure out the correct relative paths, but it’s a small price to pay for the elimination of duplication (it’s evil!)

Summary

I will readily admit that this deployment approach is a little archaic. It’s also littered with gotchas, but new technology is not immune from that either.

Going forward, WebDeploy is still my first choice whenever possible. But if faced again with a trade-off between extensive MSBuild scripting and relatively transparent TFS Build + Windows scripting, I would still go for the latter.