Creating a New Build

Creating a New Build

Team Foundation Build uses the concept of build types. A build type is simply the container for all the configuration information related to a build. In essence, it defines all the different parts of a particular build.

You create a new build type by using the Team Explorer window. Right-click the Team Builds node and then select New Team Build Type. This will launch the New Build Type Creation Wizard.

Specifying New Build Information

The wizard will ask a series of questions about the desired build process. After you've provided the answers, the wizard will write them out into a specific file format used by the build engine.

Naming the Build

The first step is to provide a name for the build. This is the same name that is reflected within the Team Explorer Builds node and in the build reports. Figure 23.4 shows the first page in the build type wizard.

Figure 23.4. Specifying the build type name.

[View full size image]

Selecting the Solutions to Build

The second step involves selecting the projects that you want to be included as a part of the build (see Figure 23.5). The drop-down at the top of the wizard page is used to essentially filter the list of available projects based on a given workspace (refer to Chapter 19, "Source Control," for a discussion of workspaces). Every solution that exists in the workspace selected in the drop-down will be displayed in the list box. Checking or unchecking the individual solutions will include or exclude them from the build.

Figure 23.5. Selecting the projects to build.

[View full size image]

Note that this page of the wizard also allows you to specify the order of the build. The order is important in cases in which there may be an order dependency between the different binaries generated between solutions. You change the build order of the solutions by using the up and down arrows next to the list of solutions.

Selecting the Build Configurations

Build configurations dictate parameters for the build such as whether this is a release or debug build, and what the target CPU platform is. You can specify multiple configurations on the third page of the wizard (see Figure 23.6); they will be built in the order shown.

Figure 23.6. Selecting the build configuration.

[View full size image]

Providing a Build Location

Team Foundation Build will need to know which server to use as the Build server. Remember, you must have already prepared this server as a Build server by running the appropriate setup files from the Team Foundation Server install media; this will deploy the build service onto the server (which must, of course, be running before you can start a build).

The build engine will need to know where to place the build files locally on the Build server and where the build output should be published so that the team can access it. All of these parameters are captured on the Location page of the wizard, shown in Figure 23.7.

Figure 23.7. Supplying location information for the build.

[View full size image]

Selecting Build Tests

Tests can be run as part of the build process. This next page of the build type wizard (see Figure 23.8) gathers information on which tests should be run during or after the build process. By selecting a test metadata file, you can pick and choose from among any of the tests defined within the Team Project (team project tests were covered in the preceding chapter).

Figure 23.8. Options for testing the build.

[View full size image]

By using the bottom check box, you can elect to run static code analysis against the source files included in the build.

Confirming Your Selections

The sixth and final page of the New Team Build Type Creation Wizard (see Figure 23.9) summarizes all the build definition selections you have made.

Figure 23.9. Validating the build type information.

[View full size image]

Clicking Finish will do two things: It will write the various build settings into an XML file called TFSBuild.proj, and it will add that XML file to the source control system within a new project that is named the same as the build.

For instance, Figure 23.10 shows two new build projects as they appear within the Source Control Explorer window. They are located under the team project node and then within a folder labeled TeamBuildTypes.

Figure 23.10. Build type files in the Source Control Explorer.

[View full size image]

Editing a Build Type

TFSBuild.proj is an XML file used as input to the MSBuild engine. Visual Studio Team System does not offer a user interface for making changes to a build after it has been initially defined. To do this, you need to directly edit the TFSBuild.proj file.

The TFSBuild.proj Project File

Listing 23.1 shows the results of a complete sample AdventureWorks build type as it is represented within the TFSBuild.proj file. Reading through the XML, you will notice that it has captured all the major build type information categories within its individual nodes: There are nodes for storing general build, solution, configuration, location, and test option information.

Tip

You are not limited to a stock set of build tasks. It is fairly straightforward to extend any given build type with custom tasks that will run during the build process. Because a task is really just a body of code that is executed during the build, creating a new task involves writing code to implement your custom action. For information on how to extend a build using custom tasks, see the MSDN topic "Walkthrough: Extending Team Foundation Build."

The XML in the build project files is extremely well commented, and the files are fairly short. Editing a build project file is straightforward and simple. As an example, if you wanted to change the server used as the Build server, you would edit the following XML node:

<BuildMachine>NewBuildServer</BuildMachine>

Listing 23.1. Sample Build File

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="DesktopBuild" xmlns="http://schemas.microsoft.com/developer
/msbuild/2003">
 <!-- TO EDIT BUILD TYPE DEFINITION

 To edit the build type, you will need to edit this file which was generated by the Create
 New Build Type wizard.  This file is under source control and needs to be checked out
 before making any changes.

 The file is available at - $/{TeamProjectName}/TeamBuildTypes/{BuildTypeName} where you
 will need to replace TeamProjectName and BuildTypeName with your Team Project and Build
 Type name that you created

 Checkout the file
   1. Open Source Control Explorer by selecting View -> Other Windows -> Source Control 
Explorer
   2. Ensure that your current workspace has a mapping for the $/{TeamProjectName}
/TeamBuildTypes folder and that you have done a "Get Latest Version" on that folder
   3. Browse through the folders to {TeamProjectName}->TeamBuildTypes-> {BuildTypeName} folder
   4. From the list of files available in this folder, right click on TfsBuild.Proj.
 Select 'Check Out For Edit'

 Make the required changes to the file and save

 Checkin the file
   1. Right click on the TfsBuild.Proj file selected in Step 3 above and select 'Checkin
 Pending Changes'
   2. Use the pending checkin dialog to save your changes to the source control

 Once the file is checked in with the modifications, all future builds using this build
 type will use the modified settings
 -->
 <!-- Do not edit this -->
 <Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\ v8.0\TeamBuild
\Microsoft.TeamFoundation.Build.targets" />
 <ProjectExtensions>
   <!--  DESCRIPTION
    The description is associated with a build type. Edit the value for making changes.
   -->
   <Description>Full daily build of all AdventureWorks components.</Description>
   <!--  BUILD MACHINE
    Name of the machine which will be used to build the solutions selected.
   -->
   <BuildMachine>VSTSb3</BuildMachine>
 </ProjectExtensions>
 <PropertyGroup>
   <!--  TEAM PROJECT
    The team project which will be built using this build type.
   -->
   <TeamProject>AdventureWorksCMMI</TeamProject>
   <!--  BUILD DIRECTORY
    The directory on the build machine that will be used to build the selected solutions.
 The directory must be a local path on the build machine (e.g. c:\build).
   -->
   <BuildDirectoryPath>c:\builds\daily</BuildDirectoryPath>
   <!--  DROP LOCATION
     The location to drop (copy) the built binaries and the log files after
    the build is complete. This location has to be a valid UNC path of the
    form \\Server\Share. The build machine service account and application
    tier account need to have read write permission on this share.
   -->
   <DropLocation>\\VSTSb3\dailbuild</DropLocation>
   <!--  TESTING
    Set this flag to enable/disable running tests as a post build step.
   -->
   <RunTest>false</RunTest>
   <!--  WorkItemFieldValues
     Add/edit key value pairs to set values for fields in the work item created
     during the build process. Please make sure the field names are valid
     for the work item type being used.
   -->
   <WorkItemFieldValues>Priority=1;Severity=1</WorkItemFieldValues>
   <!--  CODE ANALYSIS
      To change CodeAnalysis behavior edit this value. Valid values for this
      can be Default, Always or Never.

    Default - To perform code analysis as per the individual project settings
    Always  - To always perform code analysis irrespective of project settings
    Never   - To never perform code analysis irrespective of project settings
    -->
   <RunCodeAnalysis>Default</RunCodeAnalysis>
   <!--  UPDATE ASSOCIATED WORK ITEMS
    Set this flag to enable/disable updating associated workitems on a successful build
   -->
   <UpdateAssociatedWorkItems>true</UpdateAssociatedWorkItems>
 </PropertyGroup>
 <ItemGroup>
   <!--  SOLUTIONS
    The path of the solutions to build. To add/delete solutions, edit this
    value. For example, to add a solution MySolution.sln, add following line -
        <SolutionToBuild Include="$(SolutionRoot)\path\MySolution.sln" />
    To change the order in which the solutions are built, modify the order in
    which the solutions appear below.
   -->
   <SolutionToBuild Include="$(SolutionRoot)\adventureworks\adventureworks.sln" />
   <SolutionToBuild Include="$(SolutionRoot)\AdventureWorksExtensibilityFX\
 AdventureWorksExtensibilityFX.sln" />
 </ItemGroup>
 <ItemGroup>
   <!--  CONFIGURATIONS
    The list of configurations to build. To add/delete configurations, edit
    this value. For example, to add a new configuration, add following lines -
        <ConfigurationToBuild Include="Debug|x86">
            <FlavorToBuild>Debug</FlavorToBuild>
            <PlatformToBuild>x86</PlatformToBuild>
        </ConfigurationToBuild>

    The Include attribute value should be unique for each ConfigurationToBuild node.
   -->
   <ConfigurationToBuild Include="Debug|Any CPU">
     <FlavorToBuild>Debug</FlavorToBuild>
     <PlatformToBuild>Any CPU</PlatformToBuild>
   </ConfigurationToBuild>
 </ItemGroup>
 <ItemGroup>
   <!--  TEST ARGUMENTS
    If the RunTest is set to true then the following test arguments will be
    used to run tests.

    To add/delete new testlist or to choose a metadata file (.vsmdi) file, edit this value.
    For e.g. to run BVT1 and BVT2 type tests mentioned in the Helloworld.vsmdi file, add
 the following -

    <MetaDataFile Include="$(SolutionRoot)\HelloWorld\HelloWorld.vsmdi">
        <TestList>BVT1;BVT2</TestList>
    </MetaDataFile>

    Where BVT1 and BVT2 are valid test types defined in the HelloWorld.vsmdi file.
    MetaDataFile - Full path to test metadata file.
    TestList - The test list in the selected metadata file to run.

    Please note that you need to specify the vsmdi file relative to $(SolutionRoot)
   -->
   <MetaDataFile Include="$(SolutionRoot)\adventureworks\adventureworks.vsmdi">
     <TestList> </TestList>
   </MetaDataFile>
 </ItemGroup>
 <ItemGroup>
   <!--  ADDITIONAL REFERENCE PATH
    The list of additional reference paths to use while resolving references.
    For example,
        <AdditionalReferencePath Include="C:\MyFolder\" />
        <AdditionalReferencePath Include="C:\MyFolder2\" />
   -->
 </ItemGroup>
</Project>

Note

To open the build project file in Visual Studio, you either right-click on the build type in the Team Explorer and select View Build Type, or navigate to the specific TFSBuild.proj file in Source Control Explorer and double-click on the filename.

The Role of MSBuild

As mentioned earlier, the core of the TFS Build server is a technology called MSBuild. This build engine is implemented in a single executable, msbuild.exe. Although MSBuild ships with Visual Studio, it does not have any dependencies on the IDE, which means you can run the file on machines that don't have the development environment installed. In fact, MSBuild may actually be distributed within future operating systems from Microsoft, such as Microsoft Windows Vista.

MSBuild works by taking in an XML file that describes the sequence of events for the build. It then processes those events in the order specified. MSBuild is a robust engine in that it can handle conditional builds, incremental builds, and dependencies between targets and builds. Because the TFSBuild.proj file conforms to the MSBuild specifications for its input file, Team Foundation Build is able to simply pass this file over for execution when the build is kicked off. In summary, Team Foundation Build overlays the MSBuild engine with a user interface and a series of functions to integrate the build into the overall fabric of the project team (thus allowing for notifications, changeset selections, and so on).