TFS Check-in Validation Tool Installation Guide

New TFS Check-in Validation Tool Features in a Glance

The following screenshot summarizes the new features accessible from the TFS Check-in Validation Tool VS2008 add-in:

Installing the TFS Check-in Validation Tool

Installing the TFS Check-in Validation Tool involves the installation of following components:

Ø Install the Visual Studio 2008 Add-In

Ø Modify your TFSBuild.proj file

Ø Install the MSBuild Tasks

Ø Install the Buddy Build Web Service

Install the Visual Studio 2008 Add-In

Pre-requisites:

§ Any machine with Visual Studio 2008 installed as well as the Team Foundation Client

§ Access to the TFSCheckinValidationToolPackageSetup.msi download

Installation Steps:

1. Install the following MSI: TFSCheckinValidationToolPackageSetup.msi

2. Launch the Visual Studio 2008 IDE. A new menu -- Buddy Build -- is added to the VS 2008 menu bar after installation:

3. First time use: click on the "Queue a Check-in Validation Build":

NOTE: You will be asked to authenticate with TFS if you have not already:

You will then see the “Pre-Checkin Validation Build Scheduler” dialog:

If you have filled in some values in the Options dialog (accessed from the Settings menu), you will see those reflected in the dialog.

If you have not upgraded the Buddy Build Integration web service to the latest version that supports custom properties and you have your client configured to go through the web service, you will see this message clicking on the ‘Queue a Checkin Validation Build’ or ‘Queue a Regular Build’ menu:

Then, in that case, the ‘Additional Properties’ textbox as well as the ‘Edit Properties…’ button will be disabled, as shown in the screenshot below:

4. First time use: Customize the Settings:

a. Choose Settings… from the BuddyBuild menu.

b. Make sure you enter values for the TFS Host and the Builds Project Name:

Those values will represent the default values to start with. You can modify them in the build dialog.

c. You can also set the default Build Definition:

As mentioned above, this represents the default build definition, and it can be overridden in the build dialog.

NOTE: If you would like to launch buddy build using more than one shelveset, you will need to set the “Allow Multiple Shelvesets” setting to True under the “Miscellaneous” node as shown below.

5. After setting options, click on the "Queue a Check-in Validation Build" menu item. The "Pre-Checkin Validation Build Scheduler" dialog is displayed as shown in step 3 above. You can add a shelveset by clicking on the “Add Shelveset…” button. The “Add Shelvesets” dialog defaults to the current TFS user. You can keep the selection or enter a different user, and then click "Find" to get a list of the user's shelvesets:

6. You can also choose to queue a buddy build against pending changes in your workspace instead of manually creating a shelveset:

7. Now that you have picked a shelveset to validate (or chosen to use the workspace pending changes), you can customize the rest of the settings or leave the default values. To attempt to check in the code upon success of the buddy build, check the "Check-in shelvesets on successful Buddy Build" checkbox. To utilize all build agents registered for the team project, check the "Use Build Agent Pooling for Queuing" checkbox. This is the recommended setting if you want to avoid getting your buddy build queued against the same build agent if other build agents might be idle. You can also choose a different build agent if you like by picking one from the ‘Build Agent’ drop down. When ready, click the Queue button.

8. Accept the confirmation dialog to get the build queued:

9. The build queue can be reviewed as with normal Team Build-initiated builds:

10. Build steps prefixed with “Buddy Build:“ indicate steps that are part of the buddy build process:

Another example showing a failed validation where the check in attempt failed:

11. You can also schedule normal builds through the tool.

12. The advantage is the ability to utilize the build agent pooling that the tool allows. To utilize that, make sure the "Use Build Agent Pooling for Queuing".

NOTE: The shelvesets functionality is disabled when queuing a normal build.

Configuring Custom MSBuild Properties

You start by defining custom properties on the Buddy Build Integration web service:

1. Edit the CustomMsBuildProperties.xml file found under the App_Data subdirectory of the web service:

2. Use the commented example as the base to add your own entries. The following is an example of some custom properties defined:

<?xml version="1.0" encoding="utf-8" ?>

<!--

e.g.:

<Name>IsDeploy</Name>

<Description>Set to true to indicate that this build is to be deployed after building.</Description>

<PropertyDataType>System.Boolean</PropertyDataType>

</Property>

</Properties>

</BuildDefinition>

</TeamProject>

</Host>

</TfsHosts>

-->

<Name>IsDeploy</Name>

<Description>Set to true to indicate that this build is to be deployed after building the sources.</Description>

<PropertyDataType>System.Boolean</PropertyDataType>

</Property>

<Name>IsTest</Name>

<DefaultValue>False</DefaultValue>

<Description>Set to true to indicate that this build is to be tested after building the sources.</Description>

<PropertyDataType>System.Boolean</PropertyDataType>

</Property>

<Name>DemoMode</Name>

<DefaultValue>False</DefaultValue>

<Description>Set to true to signify demo mode.</Description>

<PropertyDataType>System.Boolean</PropertyDataType>

</Property>

<Name>BuildPrefixName</Name>

<DefaultValue>SuperBuild_</DefaultValue>

<Description>Set to the string to be used as the prefix in naming builds.</Description>

<PropertyDataType>System.String</PropertyDataType>

</Property>

<Name>BuildAccount</Name>

<DefaultValue>REDMOND\ddedlab</DefaultValue>

<Description>The domain account under which to run the build.</Description>

<PropertyDataType>System.String</PropertyDataType>

</Property>

<Name>NoValueFiller</Name>

<DefaultValue>(Unassigned)</DefaultValue>

<Description>Set to the string to be used as the filler when no value is specified.</Description>

<PropertyDataType>System.String</PropertyDataType>

</Property>

</Properties>

</BuildDefinition>

</TeamProject>

</Host>

</TfsHosts>

Note that the property can be any of the standard data types. You should use the full .NET data type name when specifying the data type for a property. For example, use System.String for string data types, System.Int32 for 32-bit integers, and so forth.

3. Once you’ve specified the custom properties on the web service, you can verify them by launching the ‘Queue Buddy Build Scheduler’ dialog from a VS2008 client. For the above properties, the dialog would look something like the following:

4. To override the property values, you can either edit them directly in the ‘Additional Properties’ textbox, or use the Properties Editor grid by clicking on the ‘Edit Properties…’ button. You will be presented with a dialog asking if you would like to override the grid with the properties found on the textbox. Choose yes if you have made changes to the property values in the textbox and would like to have them carried over to the properties grid.

5. The properties grid allows you to edit the property value. It will validate the property value according to the property datatype. In order to restore the default values from the web service, you can click the ‘Restore Default Properties…’ button:

Custom MSBuild properties can be useful if you have build scripts that would change behavior based on any MSBuild properties that you pass to them with certain values. In the example above, the IsDeploy property instructs the build script that the build should be deployed after the build succeeds, but tests should not be run (IsTest is false). In your build script, you would be referencing IsDeploy as $(IsDeploy).

For more details on the usage of Custom MSBuild Properties, please refer to the following help page:

http://www.buddybuildtool.com/buddybuild/help/content/customproperties.htm

Install the MSBuild Tasks

The MSBuild tasks should be installed on every team build agent that will potentially be used to run buddy builds.

Pre-requisites:

§ Access to the TFSBuddyBuildTasksSetup.msi download.

§ Access to the Team Build Agent machines.

Installation Steps:

1. Download and install TFSBuddyBuildTasksSetup.msi on every build agent machine that is expected to be used to run Team Build scripts for buddy build purposes.

Modifying your TFSBuild.proj file

Pre-requisites:

§ A TFS account with privileges to modify (check-out/Edit/check-in) the TFSBuild.proj file for the desired Build Definition.

Steps:

1. Check-out the TFSBuild.proj file.

2. Add the line highlighted below to the beginning of the TFSBuild.proj file (right after the TeamFoundation.Build.targets import):

3. Save and check in the file.

Install the Buddy Build Web Service

Pre-requisites:

§ A web server machine:

o Preferably with Windows 2003 (x86) installed (recommended > 2 GHz, 1-2 GB)

o Team Foundation Client installed

o IIS configured and ASP.NET 2.0 installed

o Ability to configure the firewall, if available to allow the chosen port through

§ Access to the following download:

o BuddyBuildIntegrationWebServiceSetup.msi

Installation Steps:

1. Create a new IIS web site and select a new port, say 8020. Note that you might need to configure your firewall so that it does not block this port. If you choose a different port number for this step, please replace the occurences of 8020 in the steps below with the port number you have chosen.

2. Create a new application pool: Call it "BuddyBuildIntegrationAppPool":

a. App Pool Identity:

i. Choose an account that would have TFS Contributor access to the team projects against which the tool will be used.

ii. Make sure the account also has "Administer a Build" permission on the team projects.

iii. This account needs to be further configured per item #2 in the following KB article: http://support.microsoft.com/kb/929388

i.e.:

o Include the domain account user in the following groups on the web server:

i. The local IIS_WPG group

o Note The domain account user must have the following local user rights:

i. The Impersonate a client after authentication right

ii. The Log on as a service right

o To do this, follow these steps:

i. On the web server, click Start, point to Administrative Tools, and then click Local Security Policy.

ii. Expand Local Policies, and then click User Rights Assignment.

iii. Right-click Impersonate a client after authentication, and then click Properties.

iv. Click Add User or Group. Note: You may have to click Location to select the domain instead of the local computer.

v. In the Group name box, type the name of the user who is running the BuddyBuildIntegrationAppPool Application Pool, and then click OK two times.

vi. Repeat steps c through e for the Log on as a service right.

b. NOTE: If the App Pool is created on a 64-bit OS like Vista or Windows 2008, make sure that "Enable 32-Bit Applications" to set to true on the Application Pool’s "Advanced Settings" dialog.

3. Verify that the web site has ASP.NET 2.0 mappings.

4. Run "BuddyBuildIntegrationWebServiceSetup.msi". Leave the virtual directory name as is.

a. Select the website created in step 1.

b. Select the "BuddyBuildIntegrationAppPool" created in step 2.

c. After setup completes, go to the Directory Security tab on the Virtual Directory properties dialog, click "Edit", and uncheck the Anonymous Authentication checkbox. Make sure the Integrated Windows authentication checkbox is checked.

5. On the web server machine, open a browser:

a. Enter the following URL: http://localhost:8020/IntegrationService/BuildService.asmx

b. Verify the asmx page loads correctly.

c. Invoke the "GetCurrentIdentity" method and make sure it returns your account in the reponse.

d. Invoke the "QueueBuddyBuild" method:

i. Enter values for tfsHostName (in the form: http://hostname:8080), teamProjectName, and buildDefinitionName.

ii. Verify a queued build id is returned.

e. Repeat "c" and enter a value for "msbuildCommandLinePropertyValue", say "foo=bar", and submit. Verify you do not get the permissions error.

6. Repeat "5" from an external machine. Replace "localhost" with the web server host name.

NOTE: To be able to invoke the web methods from a remote machine, you will need to uncomment the <webServices> section under <system.web> in the web.config file.

Configuring the Client to Use the Buddy Build Web Service

Open the Settings… dialog in Visual Studio and locate the TFS Check-in Validation Tool’s settings node. Go to the Build and buddy Build Settings node (see screenshot below):

a. Change the host name and port from localhost and 8020 to the host name of the server where you have the Buddy Build Web Service hosted and the correpsonding port.

b. Make sure the “Bypass Buddy Build Web Service” setting is set to false.

c. You may optionally also set the “Use Pass-through for Regular Builds” to false to have regular builds also go through the Buddy Build Web Service.

Common Web Service Configuration Problems

Problem:

You get the following error when trying to load the BuildService.asmx page:

Server Error in '/IntegrationService' Application.

________________________________________

Could not load file or assembly 'Microsoft.TeamFoundation.Build.Client' or one of its dependencies. An attempt was made to load a program with an incorrect format.

Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: System.BadImageFormatException: Could not load file or assembly 'Microsoft.TeamFoundation.Build.Client' or one of its dependencies. An attempt was made to load a program with an incorrect format.

Solution:

This typically happens when the Buddy Build web service is hosted on a 64-bit Vista or Windows Server 2008. Make sure that "Enable 32-Bit Applications" to set to true on the "Advanced Settings" dialog.

For any errors or issues, uncomment the appropriate trace-enabling section in the web.config file.

Questions? Issues? Please visit http://www.codeplex.com/BuddyBuild and click the Discussions tab.

You can also find help content and FAQs on the following page:

http://www.buddybuildtool.com/buddybuild/help/

TFS Checkin Validation Tool Installation Guide

The Buddy Build Process Flow

Buddy Build Process Sequence Diagram

New TFS Check-in Validation Tool Features in a Glance

Installing the TFS Check-in Validation Tool

Install the Visual Studio 2008 Add-In

Pre-requisites:

Installation Steps:

Install the MSBuild Tasks

Pre-requisites:

Installation Steps:

Modifying your TFSBuild.proj file

Pre-requisites:

Steps:

Install the Buddy Build Web Service

Pre-requisites:

Installation Steps:

Configuring the Client to Use the Buddy Build Web Service

Common Web Service Configuration Problems

Problem:

Solution: