UPDATE: This is old content, you can find updated (and much more accurate content) over at the TFS Deployer project homepage.
Earlier this year I announced the availability of TFS Integrator, a continuous integration and dependency replication engine for Team Foundation Server. Since then we haven’t been idle, in fact we have been working on another tool that will save you time in your release management processes.
Introducing TFS Deployer
TFS Deployer is installed as an agent on your test and production systems and supports the execution of PowerShell scripts when an event happens in TFS. In particular it listens fo build quality change notificaions which occur when you change the quality of a build under the Team Builds node of Team Explorer.
The way it works is that the release manager, using Team Explorer updates the build quality indicator in the build store via Team Explorer (1), the build store then notifies the event service (2) which in turn distributes notifications to all the event subscribers. In this case you can have one or more TFS Deployer installations listening across multiple machines (3). When TFS Deployer is notified it doesn’t initially know whether it needs to do anything. To determine this it grabs a deployment mapping file from a well known location in the version control store (4).
The deployment mapping file lists out each of the servers and what that server should do in the event that a build is transitioned from quality state to another. What happens is encapsulated in a PowerShell script file (*.ps1) and once that script file is identified TFS Deployer will instansiate a PowerShell host environment and execute the script (5).
Since we finished implementing TFS Deployer Readify has been using it internally along with TFS Integrator to enable us to rapidly modify, build and deploy our timesheeting system. In the remainder of this post I am going to walk through what you need to do to get up and running with TFS Deployer.
Installing TFS Deployer
Before installing TFS Deployer you first need to download and run the setup package. The setup package is a small MSI that simply drops the program files and the default configuration files into the C:\Program Files\TFS Deployer directory – from there you need to perform a few configuration steps which we haven’t fully automated yet.
The first step is to get the service to self register. This is done by executing the TFSDeployer.exe program with the -i switch. Once this is done, open the services MMC snap-in (services.msc) and scroll down to the TFS Deployer service. Change its logon behaviour to use an account that has access to Team Foundation Server.
Before starting the service review the settings in the TfsDeployer.exe.config configuration file, the relevant settings are:
- FromAddress; this is the address that all e-mails are sent from.
- SmtpServer; this is the address of the SMTP server that e-mails are sent via.
- ToAddress; this is the default address that TFS Deployer users to notify when a build either succeeds or fails.
- BaseAddress; this is the address that Team Foundation Server will use to contact this TFS Deployer instance. This address should be addressable from across the network so localhost is not acceptable.
- RegistrationUserName; this is the name of the account that the process is running under and which the subscriptions will be assigned against in Team Foundation Server.
- TeamFoundationServerUrl; this is the address at which TFS is addressable across the network.
- UseDefaultCredentials; should always be true unless you are using TFS Deployer in a cross domain configuration.
Once you have updated the configuration file you can start the TFS Deployer service. At this point in time TFS Deployer will connect to Team Foundation Server and subscribe to all build quality indicator change notifications.
Preparing Deployment Scripts
Deployment scripts are associated with specific Team Build Types and are designed to be triggered when the build quality indicator transitions from one state to another.
The configuration information which controls whether an instance of TFS Deployer springs into action is stored under version control in a Deployment sub-directory under each Team Build Type directory. For example, in the screenshot below we have a Team Build Type called CrmOnTimeContinuous which is part of the CrmOnTime team project, so the path that TFS Deployer will look for its configuration/scripts is $/CrmOnTime/TeamBuildTypes/CrmOnTimeContinuous/Deployment.
The DeploymentMappings.xml file quite simply lists out which script to execute on what computer when it transitions between two states. It also lists the e-mail address to send a notification to when the script succeds or fails. The screenshot below is a sample script.
TFS Deployer will download this file and if it has a match it will pull down the rest of the files in the Deployment directory and hen execute the script that was specified. In this case it would execute UnexaminedToTest.ps1. What the PowerShell script does is completely up to you, but one of the interesting things to note is that the BuildData (refer to Team Foundation Server SDK) object is actually exposed to the script and the script below shows how to exploit that so the script can grab the files from the drop location.
Once you have the script writen you are ready to test it out, hopefully it works as well for you as it does for us. If you have any issues using TFS Deployer please send me an e-mail or leave a comment against this post and I will help diagnose the issue.
TFS Deployer was the product of several people putting in hours above and beyond the call of duty. I’d like to thank Chris Burrows for building the core of TFS Deployer and extracting out a common TFS Listener component, and I’d like to thank Geoff Appleby for doing some of the early analysis around how to best integrate with PowerShell. Finally I’d like to thank Darren Neimke for letting us try out this deployment solution on one of his internal projects.