In this section, you will learn how to configure your builds using build types and set up custom build notifications.
If you've ever had the experience of creating custom build scripts, it can be a tedious and time-consuming process. Build types enable you to configure the build environment for your Visual Studio projects and solutions. You can configure what Team Foundation Server and workspace you want to associate to the build type, the tests you want to run, and so forth. The process of creating custom build types is made easy with the Team Foundation Build Type Creation Wizard, which is integrated in Team Explorer. Figure 23-2 shows how the build files appear in Team Explorer.
The New Team Build Type Creation Wizard is pictured in Figure 23-3.
Here is how to launch the wizard to configure a build:
Create a workspace. You can configure your workspaces using File Source Code Workspaces.
From Team Explorer, right-click on Team Builds and select New Team Build Type. The wizard window will launch as shown in Figure 23-3.
The first page of the wizard is the Welcome page. You must define a name and description for your Team Foundation Build type. The build type name is a required field and must contain a unique name.
The next page is the Selections page, from which you select a solution to build. If you have several solutions in your workspace, you can choose the ones you want to add to your build. This is a crucial step — you are creating the connective link between your source code and the build engine. If you don't see any workspaces or source code, make sure you have properly configured your Team Foundation version control (see Chapter 20 for more details).
Next is the Configurations page, which enables you to configure your build. For example, you can specify whether your build is a debug or release build. You can also define the platform: x86, x64, and so forth. These options must be set for the build to execute properly.
Next is the Location page, where you select the build machine on which to execute the build, the Drop location, and the Build directory on the selected machine. Enter the network location of the shared drop folder ("//server/share").
Next is the Options page, where you can configure your build. You can add tests using Test Metadata (.vsmdi) files or enable code analysis. Some of the tests you can enable include static code tests, unit tests, code coverage tests, and custom tests. You can configure these tests using the Team Test or Team Suite SKUs of Team System, save them in a Test Metadata file (.vsmdi) using the Test Manager, and store them in source control. Figure 23-4 shows the Options page.
On the Summary page, verify your selections and click Finish.
The New Build Type Creation Wizard only supports building Visual Studio solutions in the current version of Team System. Unfortunately, you can't build projects from other platforms such as Java. However, there is an interesting tool called MSBuild Everett Environment (MSBee), which allows you to target the .NET Framework v.1.1 using Visual Studio 2005. Please refer to Craig Lichten's blog for more details: http://www.blogs.msdn.com/clichten/.
Once you finish the process, the following will happen:
XML build scripts will automatically be generated based on the options you selected. Helper files are also created, and both are checked into Team Foundation version control.
tfsbuild.proj will be added to your project. In Team Explorer, you'll notice a new node with the name you selected for your build type.
You can create an MSI to deploy your Team build types. Please refer to the MSDN documentation for more details.
Once you create a Team build type, it will be added to version control in the form of a TFSBuild.proj file (which includes the build type definitions), TFSBuild.rsp (a response file for MSBuild which can incorporate custom MSBuild commands), and a WorkspaceMappings.xml file (which contains your workspace mappings on Team Foundation version control and locally). You must edit the TFSBuild.proj file before you can edit your build type. All of these files are located in Team Foundation version control in the following directory: $(YourProjectName)/ TeamBuildTypes/(YourBuildTypeName).
To edit the files, you should do a "Get Latest Version" on the TeamBuildTypes folder. If you are unsure how to check out a file, refer to Chapter 20. From a security standpoint, make sure the account that is editing the Build Types has the Administer a build rights.
To edit a Team build type, right-click on your Team build type in Team Explorer and select View Team Build Type. An XML description of your Team build type will open in Visual Studio 2005 (or the helper application associated with XML files). To change the description of the file, simply update the <Description> node:
<Description>A brand new Build Type</Description>
You can define what solutions you want to associate with the Team build type using the Solution ToBuild nodes. In the following example, you can add, change, or remove path information to Visual Studio 2005 solution files (.sln) to add them into the build process. You can also change the order in which the solutions are built in case one of the solutions depends on another:
<ItemGroup> <SolutionToBuild Include="$(SolutionRoot)\MEBeta\MobileExplorerBeta.sln" /> </ItemGroup>
Next, you can update the Configuration and Platform section. When you created the Team build type, you were prompted to select a configuration and platform. In this section of the XML file, you can manually change these values. For example, you can change the FlavorToBuild node from Debug to Release:
<ConfigurationToBuild Include="Debug|Any CPU"> <FlavorToBuild>Debug</FlavorToBuild> <PlatformToBuild>Any CPU</PlatformToBuild> </ConfigurationToBuild>
You can change your target build machine by changing the value of the BuildMachine node:
The Team Project to which this Team build type belongs is located in the TeamProject node. This value cannot be changed:
You can also specify the path of the build directory, any drop location, whether testing should be implemented in your build, or whether code analysis should be executed or not:
<BuildDirectoryPath>C:/drop</BuildDirectoryPath> <DropLocation>\\buildmachine\drop1</DropLocation> <RunTest>true</RunTest> <RunCodeAnalysis>Never</RunCodeAnalysis>
Finally, you can specify default states for work items created when a build fails in the WorkItemFieldValues node using key-value pairs:
<UpdateAssociatedWorkItems>true</UpdateAssociatedWorkItems> <WorkItemTitle>Build failure in build:</WorkItemTitle> <DescriptionText>This work item was created by Team Build on a build failure.</DescriptionText> <BuildlogText>The build log file is at:</BuildlogText> <ErrorWarningLogText>The errors/warnings log file is at:</ErrorWarningLogText>
To complete your updates on the Team build type file, simply save TFSBuild.proj and check-in the file. The next time you run a build, the changes you made will be applied.
To delete a Team build type, simply navigate the Team Explorer and click on the Source Control folder. You will launch the Source Control Explorer. Using the explorer, right-click and delete the folder associated with the Team build type. Performing these two tasks will delete all files for that particular Team build type after you check-in the delete operation. Be sure to check-in your pending changes to commit the delete operation.
The Administer a Build rights are required on your account in order to delete a build type.
E-mail notifications help you and your teams keep track of the status of your builds and results. The e-mails contain links to view web reports. You can also optionally view the reports in Visual Studio 2005.
The e-mail will contain a variety of details, including the Team Project, build details (when the build started and completed, build machine, and build log), open work items, and custom task events.
You can turn on the build notification e-mail alerts by following these steps:
Using the Team Explorer, right-click on your project name node and select Project Alerts, or select the Team menu and click Project Alerts.
Select what kind of alert you want to receive. There are two options for Team Foundation Build: You can receive an alert once a build has been completed, or when a tester changes the build quality state on a particular build number in the build view. The following table explains the different build quality states.
Build Quality State
Initial Test Passed
The build has passed initial testing.
Lab Test Passed
The build has passed lab tests.
Ready for Deployment
The build is ready for deployment.
Ready for Initial Test
The build is ready for initial testing.
The build did not pass required tests.
The build has been released.
The build has passed User Acceptance Testing (UAT).
The build is under investigation.
The build has been unexamined.
Enter the e-mail address for the team member(s) who will be receiving the alerts. You can enter a single e-mail address or a list of recipients. You can also select what type of e-mail should be sent to your team members, plain text or HTML.
As soon as you click the OK button, the alerts will be enabled.
Once you receive the e-mail, you will be able to access an overview web page containing your build details. The build details web page is divided into four sections:
Summary. The Summary section contains information on the build name, the name of the Team Project, the build type, the build machine name, date and timestamps for the start and completion of the build, the quality of the build, whether a work item was created for this build, and a build log.
Build Steps. These steps are associated with the targets in the Microsoft.TeamFoundation .Build.targets file. The steps include initialization, getting sources, compiling sources, compiling the solution, compiling the Project(s), getting a list of changesets, updating work items, starting tests, completing tests, dropping binaries and logs to the drop site (or directory), and building completed. Knowing the status of each step of the build will enable you to troubleshoot any problems (if they occur). A detailed explanation of the primary build steps is outlined in the chapter introduction.
Results Details. The Results Details section includes information about the build configuration you selected (as part of the build type). You'll get information such as errors, warnings, and tests and coverage results.
Associated Changesets. The Associated Changesets section provides information regarding team members that have checked in code and the changesets that were included in the build.
Executing a build is made easy using the Team Explorer. Simply right-click on a Team build type and select Build Team Project (associated with the name of your project). Then all you have to do is click the Build button and wait for the results. You can also execute a build using the Build menu. Simply click Build Your account needs the "Start a Build" permission set to execute a build. See the section "Setting up build security" for more information. You can run builds locally before checking in your code to the team source repository. Keep in mind that local builds will only run the compilation and associated tests. Obviously, steps such as work item updates (and other tasks relying on Team Foundation Server) will not be performed. Please refer to the MSDN documentation if you require more information. Here are the steps to run a desktop build by running MSBuild using the command line: Core components of the build process are the build configuration files (such as your build types). You should first copy these configuration files from the version control repository to your local workspace. The structure of your workspace looks something like the following:
C:/MyWorkspace/<the name of your portfolio project>/TeamBuildTypes/<BuildTypeName>
Your account needs the "Start a Build" permission set to execute a build. See the section "Setting up build security" for more information.
You can run builds locally before checking in your code to the team source repository. Keep in mind that local builds will only run the compilation and associated tests. Obviously, steps such as work item updates (and other tasks relying on Team Foundation Server) will not be performed. Please refer to the MSDN documentation if you require more information.
Here are the steps to run a desktop build by running MSBuild using the command line:
Core components of the build process are the build configuration files (such as your build types). You should first copy these configuration files from the version control repository to your local workspace. The structure of your workspace looks something like the following:
Launch the Visual Studio 2005 console window (by selecting Start All Programs Visual Studio 2005 Command Prompt), navigate to the configuration folder, and run MSBuild using the build types you copied locally:
MSBuild TFSBuild.proj /p:SolutionRoot=..\sources
One of the essential operations you will have to perform is assessing the progress and status of your build during the build process. For example, if your build is generating critical errors and it takes an hour to complete it, you might want to abort the build midway to fix problems.
The build status is automatically shown when you start the build. The summary and build steps are refreshed automatically as the build progresses. Another way is to run the build report, which is updated with the latest information about Team builds at each Team System Warehouse refresh.
To view the build summary report, your user account should have a minimum of view project level information privileges.