How does the checkbox "Override build agents pool settings from XML configuration" work?

Sep 28, 2009 at 5:54 AM

From the "Queue a Check-in Validation Build..." dialog, there is a checkbox "Override build agents pool settings from XML configuration" under the checbox "Use Build Agent Pooling for queuing". How does that checkbox work?

From the user manual, there is a high-lighted functionality: "Flexibility in defining your own custom build agent pool as a subset of agents assigned to your team project, using regular expressions". This is exactly what I want but the manual doesn't describe how this can be done. Is this related to that checkbox?

Sep 28, 2009 at 7:44 AM


The XML override procedure has not been publicly documented since I don't know of anyone using it outside of Microsoft.

If you are interested in using it, here's how you can get it working:

  1. Please take a look at the sample file called "TeamProject1_BuildAgents.xml" which will be located at the add-in's installation location, typically "{Program Files}\TFS Check-in Validation\TFS Check-in Validation Tool VS2008 Add-in".
  2. Rename the file using the following pattern: YourTeamProjectName_BuildAgents.xml. For example, if your team project name is $/Project1, the file name will be Project1_BuildAgents.xml. Then, open the file in an editor and make changes as you need to exclude the agents you want to exclude. You can use regular expressions.
  3. Then check in the xml file under the build definition's folder. For example, if your build definition uses the TFSBuild from $/Project1/TeamBuildTypes/MyBuddyBuild/TFSBuild.proj, then you should place the xml file next to TFSBuild.proj in that folder.
  4. Then, on the Visual Studio Buddy Build add-in, once you check the "Override build agents pool settings from XML configuration", the tool will look for the file and attempt to apply its settings in order to find the appropriate build agent. There is also a setting to have this checkbox on by default.

Let me know if you run into issues while configuring this feature.

Sep 28, 2009 at 10:17 AM
Edited Sep 28, 2009 at 10:38 AM

I tried but it doesn't work.

I then tried changing all the agent names to some invalid names. Then after clicking the "Queue Build" button, it said something like the overriden agent names doesn't match the project's build agents. So I think my Project1_BuildAgents.xml is somehow used by the system already.

However, no matter whether I exclude the unwanted agents from the Project1_BuildAgents.xml or whether I set the disabled attribute of the unwanted agent to be true, the queued builds are still assigned to some unwanted agents.

Does it need to work?

Sep 28, 2009 at 11:31 AM
Edited Sep 28, 2009 at 11:32 AM

The best way is to simplify the xml file to enable only a single build agent and see if that works. For example, the contents of the <ProjectName>_BuildAgents.xml can be something like the following:

<?xml version="1.0" encoding="utf-8" ?>
<AgentPools xmlns="">
    <AgentPool Name="Default">

Also, to verify if the XML file was successfully retrieved, look for it in the cache location. The tool caches the file using the same name plus a timestamp in the %TEMP% folder (e.g.: %TEMP%\<ProjectName>_BuildAgents_<timestamp>.xml). So, if you find this file there, that means the file was retrieved fine, but it probably contained entries that did not result in a match.

There are other ways to override the build agents using an XML file. Here is how the algorithm works:

1) First, the tool looks for a path specified in the "CustomXMLLocation" string value under the following registry key: "HKEY_CURRENT_USER\Software\Microsoft\TFS Checkin Validation Tool". If it finds a value in the registry string that represents a valid local file with the .xml extension, it will process the file looking for build agent definition. So, to use this method, you can edit the file locally and set the registry value to point to it.

2) If step 1 is not successful, the tool looks for the file under: $/<ProjectName>/TeamBuildTypes/BuildName/<ProjectName>_BuildAgents.xml. If it finds the file, it downloads it to %TEMP% as mentioned above.

3) If step 2 is not successful, the tool looks for the following file: $/<ProjectName>/BuildExtensions/BuildAgents.xml. If it finds the file, it downloads it to %TEMP%.

4) If step 3 is not successful, the tool defaults to the previous behavior (non-override).

Hope this helps explain the logic and perhaps help you troubleshoot the issue.

Please let me know if you still don't a successful configuration resulting in the desired build agent selection.


Sep 29, 2009 at 3:38 AM

I think I figured out what went wrong. It's probably due to regular expression issue. Previously, I have three agents with name like "my agent", "my agent 2", "my agent(123)", and i just want the first two. In the XML, I configured them as <Name>my agent</Name> and <Name>my agent 2</Name>. In this case, my check-in is always assigned to "my agent(123)".

Now, I rename the agents so that none of their name is prefix of any other. The problem is gone.

Thanks for the help.