Software Quality

June 26, 2015

TFS Build 2015 – Using the new build definition

Filed under: Uncategorized — David Allen @ 5:04 pm

This article records step-by-step how to create a new build definition using TFS Build 2015, and publish a website to a Microsoft Azure Web Site from an on-premises build agent. It also describes how to create custom build pools.

TFBuild 2015 is a huge transformation in how we use TFS to build solutions. It integrates with Visual Studio Online. But it also supports your favorite build tools like Ant, Maven, MSBuild and many more. It also supports a variety of scripting languages like DOS, PowerShell, bash Shell Script. This is a powerful testimony to Microsoft’s efforts to embrace cross-platform tools. You can read an Overview of Team Foundation Build 2015 at https://msdn.microsoft.com/Library/vs/alm/Build/feature-overview.
“How did I find out about this?” I was wandering around my local Visual Studio 2015 RC desktop, when I noticed two different types of builds. I saw “Build Definitions” and “XAML Build Definitions” and wondered what the difference was. I created a new Build Definition, and was transported to my VSO (Visual Studio Online) build tab, where they had a message

“We’ve built a new, scriptable build system that’s web-based and cross-platform. See vsopreview for documentation.”

So I clicked the vsopreview link and read about the wonders of this new build technology. Let’s create a build definition that will publish a website to Microsoft Azure.

Set the context for this experiment

  1.  Open Visual Studio 2015 RC or later.
  2.  Create a website. Let’s name it WebApplication1. Optionally, check the option to include unit tests.
  3. Build it locally and run it to behold your default handiwork.
  4. Check it into source control so it is accessible to your build.

Create a TFS Build 2015-style Build Definition

  1.  Open your VSO (Visual Studio Online) account
  2.  Choose the BUILD menu (within HOME CODE WORK BUILD TEST)
  3. You may see an information bar that says “We’ve built a new, scriptable build system that’s web-based and cross-platform. See vsopreview for documentation.”
    If you click on the link, you will discover the article cited above, Overview of Team Foundation Build 2015.
  4. Create a new build definition from the VSO web interface.
    1. Click the green PLUS sign.
    2. Choose the “Visual Studio” template.
    3. Click “Save” and enter comments on what you did.
      The first time you save a build definition, you will get to provide a name. I called mine WebApp1.  Comments are available each time you save, and become part of the history of changes to the build. It is great to have visibility to this. Help yourself and your teammates by entering meaningful comments.
  5.  You will see a menu of settings:
    Build Options Repository Variables Triggers General Retention History
    You should already be on the Build menu, but if not, click on it.
    You will see the four steps automatically provided by the template.
  6. Configure the “Visual Studio Build” step
    1. Solution: navigate to the solution file (xxx.sln) that corresponded to my test website.
      1. Accept defaults for other settings
      2. Save settings and entered comment on what I did
  7. Configure the “Visual Studio Test” step
    I simply left all the defaults in place.
  8. Configure the “Index Sources and Publish Symbols step
    I simply left all the defaults in place.
  9. Configure the “Publish Build Artifacts” step
    1. Copy Root: changed from blank to “$(agent.builddirectory)” per information suggestion. Otherwise, the build will fail with a message like this
      2015-06-26T19:47:58.5279679Z Start: UploadArtifact
      2015-06-26T19:47:58.5436075Z ##[error]The container 272972 could not be found.
      2015-06-26T19:47:58.5436075Z End: UploadArtifact
  10. Configured Options settings
    I left “MultiConfiguration” unchecked for my first baby step into this new world.
  11. Configure Repository settings
    1. Clean: selected “true”
    2. Mappings:
      1. I modified the Map entry to be specific to the folder where my particular solution is.
      2. I removed the cloaking as it was made irrelevant by the change above.
  12. Variables
    I simply left all the defaults in place.
  13. Triggers
    1. I chose Continuous Integration
    2. Revise Filter to include the solution folder, not the entire repository
      You want changes within this folder to trigger a build, not changes in other nearby solutions.
  14. General
    1. Default Queue
      Here it gets interesting! I wanted to run a build agent on premises, NOT in the cloud. So instead of using the Hosted queue, hosted by VSO, I created my own called HOPE, and chose it. See the section below, “Creating an on-premises agent useable by VSO,” if you are interested in this option.
    2. Description: give it one
    3. Build job authorization scope: changed from “Project Collection” to “Current Project.”
      You may choose to do otherwise.
    4. Build job timeout in minutes:
      I changed it from 60 to 10
    5. Demands
      Noted msbuild, visualstudio, vstest
      I did not change these.
    6. Accepted defaults for other settings
    7. g. Saved settings and entered comment on what I did
  15. Retention: accepted defaults

Confirm you have a new build
Then I tested it by changing the source code and checking it in.
The build succeeded.

Now, let’s try to publish to the Azure Web Site.

  1.  Modify first step “Visual Studio Build”
    Build, MSBuild Arguments/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation=”$(build.stagingDirectory)”Observe PackageLocation=”$(build.stagingDirectory)”. We will need that as a source from which to publish to Azure in a moment. Without this step, we will have no package to publish to Azure.
  2. Queue a new build.
    1. Navigate to your local file system and find your staging directory. It will be under the agent work directory noted when you installed the agent service.
    2. Observe the staging directory. In my case, it was D:\agent\_work\6d8e94d8\staging. Thanks to the new MSBuild arguments, the staging folder is not empty. It has a file named WebApplication1.zip. This will be important.
  3. Add Build Step to publish website to an Azure Website
    1. Added Deploy step “Azure Web Site Deployment”
    2. Web Site Location: North Central US
    3. Web Site Name: dallenWebApp1
      Of course, you should use your own website name here. Please do not use this one. I only share mine to make it clear what I am doing.
    4. Package: ?
      The information tool says “Path of package under the default artifact directory.”
      I specify Package=$(build.stagingDirectory)\WebApplication1.zip
      In case you are wondering, the variable $(build.stagingDirectory) was configured when you downloaded and installed the agent files in one of the earlier steps.
  4. Queue a new build by hand.
    1.  It ran for 57 seconds, and published to my Azure website without trouble!
    2. I viewed the results at http://dallenwebapp1.azurewebsites.net/ and was very pleased 🙂 You can see it too if I have not taken it down. It’s just a test website, so I don’t guarantee it will be up.

Acknowledgements and Resources

I got stuck at one point and I was thankful to find this article: http://geekswithblogs.net/jakob/archive/2015/04/29/deploying-an-azure-web-site-using-tfs-build-vnext.aspx by Jakob Ehn.

Blog advice: http://vsalmdocs.azurewebsites.net/library/vs/alm/build/overview

Advanced Topics

Installing the agent multiple times

  1.  You can install the agent multiple times. If you do, you may have multiple services running in the background. This may or may not be what you want.

Locking local agent files may block the build

  1. I was opening some log files in the installer directory and examining them.
  2. I queued a new build
  3. Build failed after 2 seconds 😦 with the following errors.
    ******************************************************************************
    Starting: Build
    ******************************************************************************
    Executing the following commandline:
    D:\Installers\Microsoft\Visual Studio Online\agent\agent\worker\vsoWorker.exe /name:Worker-67388b48-60f4-4ec2-b415-2fb999374862 /id:67388b48-60f4-4ec2-b415-2fb999374862 /rootFolder:”D:\Installers\Microsoft\Visual Studio Online\agent” /logger:Forwarding,1.0.0;Verbosity=Verbose,Name=Agent2-a6bce2f11260f0127eb451e8d5cd33a8;JobId=67388b48-60f4-4ec2-b415-2fb999374862
    The directory is not empty.
    ******************************************************************************
    Finishing Build
    ******************************************************************************
    Worker Worker-67388b48-60f4-4ec2-b415-2fb999374862 finished running job 67388b48-60f4-4ec2-b415-2fb999374862

On a hunch, I then Closed Notepad which had one of the previous local logs open.
Queue another build. This one ran successfully.

Creating an on-premises agent useable by VSO

  1.  I clicked on the “Manager” link to the right of the “Default queue” drop-down control. This opened a new window, showing me a default agent.
  2. I clicked the “Download agent” link and downloaded a file called agent.zip
  3. I unblocked it, and unzipped it .
  4. I saw a file “ConfigureAgent.ps1a” and did what anyone would have done. I ran it in Powershell as administrator. I don’t know whether the “as administrator” part was needed. Here is the script I ran
    1. cls
      d:
      cd "D:\Installers\Microsoft\Visual Studio Online\agent"
       .\configureagent.ps1
  5. It asked a bunch of questions. My answers are shown below the question.
    An existing configuration file was detected. This will update the local agent settings. Do you want to also replace the server registration (default is N)?
    I accepted the default on this.Enter the name for this agent (default is Agent-HOPE)
    Agent2-HOPE
    The first time I ran this, I specified Agent-HOPE, and put it in the Default build pool.Enter the URL for the Team Foundation Server
    https://dallen.visualstudio.com
    Be SURE to include the full URL with protocol or it won’t work.

    Configure this agent against which agent pool? (default pool name is ‘default’)
    You can just leave this blank and accept the default. That is easiest.
    But I created my own agent pool, named HOPE.
    To do this, I went into my VSO Control Panel, Agent pools, and created a new one.
    Then I entered HOPE in response to this question.Enter the path of the work folder for this agent (default is ‘D:\Installers\Microsoft\Visual Studio Online\agent\_work’) d:\agent\_work
    I accepted the default on this

    Would you like to install the agent as a Windows Service (Y/N) (default is N)
    y

    Enter the name of the user account to use for the service (default is NT AUTHORITY\LOCAL SERVICE)
    You will have to sign into your VSO/Azure account.

    Installing service vsoagent.dallen.Agent2-HOPE…
    Service vsoagent.dallen.Agent2-HOPE has been successfully installed.
    Creating EventLog source vsoagent.dallen.Agent2-HOPE in log Application…

  6. After the agent setup was complete, I looked at services on my machine and observed a new one, named “vsoagent.dallen.Agent2-HOPE”.
  7. I clicked on the drop-down “Default”
  8. I recommend you copy and save what appears on the screen. The settings are relevant.
  9. If you do create a custom agent pool, you may have to refresh your browser to see the options in your VSO screens.

2 Comments »

  1. Hi Thank you for the article. I am trying to setup a similar vNext build where the TFS and build agents are on-premise. All is working except I cannot get vNext’s Visual Studio Build to respond to this argument /p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation=”$(build.stagingDirectory)”Observe PackageLocation=”$(build.stagingDirectory)”. It builds successfully but there is not attempt to on the build server to run the publish steps to create a resulting package. Any thoughts on why /p:DeployOnBuild=true seemingly is not working? Thanks

    Comment by Patrick Neborg — March 23, 2017 @ 7:58 pm

    • I’m sorry, but I don’t think I can help you. We moved to VSTS cloud-based builds some time ago, and I no longer keep up with the on-premises stuff.

      Comment by David Allen — March 23, 2017 @ 8:42 pm


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: