Learn to Customize TFS2015 Build with Environment Variables

by

You’ve probably noticed that Team Foundation Server 2015 introduces a new automated build system.  One of the great things about this new system is that it’s based on PowerShell.  At this point, you’re probably thinking “Ok.  PowerShell.  Fantastic.  Why do I care?”  Well, that PowerShell-centric approach allows you to much more easily customize your builds.  Need to do some logic?  Stuff it in a PowerShell script, call that *.ps1 script from the build and you’re off.

When you start customizing your TFS Builds using PowerShell (ps1) scripts, you’ll pretty quickly notice that these PowerShell scripts integrate with the TFS Build system through environment variables.  When a build runs on a TFS build agent, a whole bunch of environment variables get set and those variables have all the information about that build.  For example, if you need to reference something that’s been retrieved from source control, you’ll need to access the ‘BUILD_SOURCESDIRECTORY’ environment variable in order to look up the path on the local disk where all your source code got downloaded.

There are a lot of environment variables that get set for each build and it’s initially tough to learn what they all are.  On my last build, I counted 51 separate environment variables that get set.

How do you learn what’s available?

So how do you discover and learn what all the values are that you can use?  My #1 recommendation is to create a simple build and call a PowerShell script that exports all the values for all the available environment variables.

Here’s a simple script that I wrote that does that:

[CmdletBinding()]
param()
$environmentVars = get-childitem -path env:*
foreach($var in $environmentVars)
{
 $keyname = $var.Key
 $keyvalue = $var.Value
 
 Write-Output "${keyname}: $keyvalue"
}

In order to reference that script from an automated build, you’ll need to add it to source control.  I usually create a folder off the root of my source repository called “BuildScripts” and add my custom scripts into that directory like what I did in the image below.  

 

Custom ps1 build script directory

Once you’ve added that PowerShell script to version control, you can edit your build definition to call the script.  First you’ll click “Add build step…” and add a PowerShell script step.  When that’s been added, you need to populate the “Script filename” value.  You can do this by clicking the “…” button and choosing your PowerShell script in source control.  Save the build and you’re done.

img_56994dd8561d0

When you run your build, you’ll eventually see a message saying something like “Starting task: Powershell: BuildScripts/export-environment-variables.ps1” followed by a bunch of environment variable keys and values.

img_56994efb049f8

The Environment Variables

The environment variables that get exported are going to be all of the values that are available and NOT just the values that get handed in by TFS Build.  Here are the values that got set by TFS on my build server.

VARIABLE VALUE
agent.jobstatus Succeeded
AGENT_BUILDDIRECTORY C:\tfsbuild\agent-bin\_work\2
AGENT_HOMEDIRECTORY C:\tfsbuild\agent-bin
AGENT_ID 6
AGENT_JOBNAME Build
AGENT_MACHINENAME DEMO-VS15
AGENT_NAME Agent-DEMO-VS15
AGENT_ROOTDIRECTORY C:\tfsbuild\agent-bin\_work
AGENT_WORKFOLDER C:\tfsbuild\agent-bin\_work
AGENT_WORKINGDIRECTORY C:\tfsbuild\agent-bin\_work\SourceRootMapping\14d52426-0282-40c8-862a-acee0c519442\Job-ee2f862e-a9b2-4df3-9cb6-08e8b2953d9d
build.fetchtags FALSE
BUILD_ARTIFACTSTAGINGDIRECTORY C:\tfsbuild\agent-bin\_work\2\a
BUILD_BINARIESDIRECTORY C:\tfsbuild\agent-bin\_work\2\b
BUILD_BUILDID 74
BUILD_BUILDNUMBER 20160116
BUILD_BUILDURI vstfs:///Build/Build/74
BUILD_CONTAINERID 80
BUILD_DEFINITIONNAME demo-build-1
BUILD_DEFINITIONVERSION 2
BUILD_QUEUEDBY Benjamin Day
BUILD_QUEUEDBYID 3b2afc54-cea0-40ab-b0db-b60975a7deb4
BUILD_REPOSITORY_CLEAN FALSE
BUILD_REPOSITORY_GIT_SUBMODULECHECKOUT FALSE
BUILD_REPOSITORY_ID 07b6b77a-0bc0-4698-95ba-cf826dc08c4c
BUILD_REPOSITORY_LOCALPATH C:\tfsbuild\agent-bin\_work\2\s
BUILD_REPOSITORY_NAME scrum-git-20160115
BUILD_REPOSITORY_PROVIDER TfsGit
BUILD_REPOSITORY_URI http://demotfs2015:8080/tfs/DefaultCollection/_git/scrum-git-20160115
BUILD_REQUESTEDFOR Benjamin Day
BUILD_REQUESTEDFORID 3b2afc54-cea0-40ab-b0db-b60975a7deb4
BUILD_SOURCEBRANCH refs/heads/master
BUILD_SOURCEBRANCHNAME master
BUILD_SOURCESDIRECTORY C:\tfsbuild\agent-bin\_work\2\s
BUILD_SOURCEVERSION 3e89a39e9fdb7becf6c3e72b81beffb24ebde2f4
BUILD_STAGINGDIRECTORY C:\tfsbuild\agent-bin\_work\2\a
BUILDCONFIGURATION debug
BUILDPLATFORM any cpu
COMMON_TESTRESULTSDIRECTORY C:\tfsbuild\agent-bin\_work\2\TestResults
DNX_HOME %USERPROFILE%\.dnx
PSExecutionPolicyPreference Unrestricted
SYSTEM mstf
SYSTEM_ARTIFACTSDIRECTORY C:\tfsbuild\agent-bin\_work\2
SYSTEM_COLLECTIONID 14d52426-0282-40c8-862a-acee0c519442
SYSTEM_DEFAULTWORKINGDIRECTORY C:\tfsbuild\agent-bin\_work\2\s
SYSTEM_DEFINITIONID 10
SYSTEM_HOSTTYPE build
SYSTEM_TEAMFOUNDATIONCOLLECTIONURI http://demotfs2015:8080/tfs/DefaultCollection/
SYSTEM_TEAMPROJECT scrum-git-20160115
SYSTEM_TEAMPROJECTID 68ee0de1-1d92-49aa-9f4e-667b4972c8f0
SYSTEM_WORKFOLDER C:\tfsbuild\agent-bin\_work
TF_BUILD TRUE
windir C:\Windows

 

As you can see, there are a whole lot of values that get set.  Hopefully, this gets you going on learning what they are and gets your going towards customizing your TFS2015 builds.

-Ben

 

— Looking for help adopting the new Team Foundation Server 2015 build system?  Need help customizing?  Want some help deploying your applications from your TFS automated builds?  We can help.  Drop us a line at info@benday.com


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.