Help

How To: Override build agents pool settings from XML configuration

The TFS Check-in Validation Tool provides a mechanism for overriding the default build agent selection algorithm and specifying some custom criteria for picking the appropriate build agent. This is provided through an XML file in which you can define the custom configuration. A sample file is provided as part of the add-in's installation.

The sample build overrides XML file typically looks like the following:

        Name          - Agent pool name. Keep value as "Default".
        
        The following is the sequence of steps followed in determining the "effective" machine
        pool agents to be used in load balancing a queued build request:
        
        1) Only BuildAgent definitions with Disabled=false are considered. Definitions with
           Disabled=true are ignored.
        2) Those BuildAgent definitions are applied to the list of agents currently assigned to 
           the Team Project.
           
        Name - A regular expression. You can use complicated expressions to define agents to be
               included in the pool. You can define multiple expressions to provide different lists
               or to break them down into multiple groups each with a different weight factor.
               You can also define individual agent names.
        Weight - The wieght factor that is considered by the load balancing algorithm to break a tie
               between different agents with identical queue lengths. The higher the Weight value, the
               more priority the corresponding BuildAgent definition is given. The weight cannot be less
               than or equal to 0, or more than 100. Weights outside that range will be considered as if
               they were 100.
               
        NOTE: If multiple expressions define a different weight for the same agent, the last definition
              is the "effective" one. This can be used, for example, to define the default attributes that
              apply to all/most machines and then individually customize the build agents that have attributes
              different from the 'default'.
              
        Other nodes that can be used in BuildAgent definitions (but not shown in the sample below):
        - DropLocation: Add this to customize the drop locations for builds occuring on certain agents.
                        e.g.: <DropLocation>\\DropSvr1\builds\</DropLocation>
        - Priority: Add this to customize the queue priority setting for the builds queued against that
                    build agent.
    

Configuration Procedure :

1. First, 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.

3. 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.

4. For example, the contents of the <ProjectName>_BuildAgents.xml can be something like the following:

   <?xml version="1.0" encoding="utf-8" ?>
   <AgentPools xmlns="http://schemas.microsoft.com/developer/tfsbuddybuild/2008/buildagents">
       <AgentPool Name="Default">
           <BuildAgent>
               <Name>BuildAgent1</Name>
               <Weight>70</Weight>
           </BuildAgent>
       </AgentPool>
   </AgentPools>

5. 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.

6. 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: BuddyBuild -> Settings...-> TFS Check-in Validation Tools -> Miscellaneous -> Build Agent Pooling Settings -> Default Override Build Agents Pool Settings from XML.

7. 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.
   

How It All Works:

The installer needs to be run with elevated privileges on Windows 2008 and Vista machines.

There are other ways to override the build agents using an XML file. Here is how the internal 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).