In the previous episode I intended to cover the configuration of TeamCity, but took a quick detour to talk about MSBuild and MSBuild scripts. Now that we've got a script to use we can configure TeamCity. The following will be the minimal steps to get up an running.
- To start off, log into your TeamCity installation and click on the Administration button (top right area of screen) to go to the Projects and Build Configurations screen. This screen will give you an overview of all the projects that you have configured to run on this installation.
- Click on the Create Project link on the page. Name your project and give it a description then click the Create button.
- The next screen will provide you will the options for creating a build configuration and a VCS root. Here are the values I used under the heading of General Settings:
- Name: Something that makes sense in your context (i.e., Standard MSBuild).
- Build number format: I'm currently using 2.0.{0}.{build.vcs.number.1} The initial 2.0 is static, but {0} is a placeholder for the build counter value. The {build.vcs.number.1} placeholder is, as the note below the text box says "a reference to VCS changeset number. So for example 2.0.71.144 means the 71st build using revision 144 of 2.0. There are different strategies for version number make up. The important thing is to pick something that works for you and stick with it.
- Build counter: This allows you to set the build number to a higher seed if for instance you're migrating from another configuration where you've already reached build number. Conversely, you can also decrement the value if you want to zero the build counter.
- Click on VCS settings button to continue with the setup.
- Version Control Settings are next.
- Click on Create and attach a new VCS root.
- Enter a meaningful name and choose the appropriate type of VCS, in my case Subversion.
- Fill in the blanks for the URL, and if necessary, user name and password. There is an option to test the connection at the bottom of the page.
- Save your changes to return to the previous page.
- Back on the Version Control Settings I chose Automatically on server for the VCS checkout mode and left the rest of the settings unchanged. Click the Choose Build Runner button to advance.
- From the Build runner options I chose MSBuild. The next parameter, Build file path, took me a couple of tries to get right the first I set this up. The note under the text box says "Specified path should be relative to the checkout directory" but keep in mind that your URL choice in the VCS root options will influence the relative path. If you have a traditional directory structure of branches, tags, and trunk at your VCS root and specify the root of your source tree then your Build file path may look something like trunk\MyBuildScript.xml. Two MSBuild versions should be available, the one from the 2.0 and the 3.5 version of the .NET Framework. I would suggest 3.5 even if you're building a Visual Studio 2005 project. Click Save.
At this point all of the necessary steps have been completed. However, TeamCity offers more options that can be configured around your project. The options are listed on the right side of the screen under Build Configuration Steps heading when you're editing a project. All of these options are also available from the Edit Configuration Settings link on the project tool bar. One of the options in particular is worth considering - Build Triggering. TeamCity offers many options for triggering a build. The one I found most useful is VCS Triggers. TeamCity can check for any changes to your source control repository on the interval you choose and run a new build with the changes.
In order to make use of your project you need to have an authorized build agent available. Click on the Agents tab in the top left area of the screen. Under the Agents heading you will see four tabs. One of them (probably the Unauthorized agents tab) should have a number greater than zero in parenthesis. Click on that tab. If it is the Unauthorized agents tab click on the Authorize agent link then move over to the Connected Agents tab and click the Enable agent link if necessary. Your agent is now available for use.
With your project completed you will find it listed under the Projects tab (top left area of screen). Choose your project from the drop down menu embedded in the Project tab. Under the Current status section of the Overview tab if you have a No suitable agents link return to the previous paragraph and check your settings. From this screen you can trigger a build by clicking on the Run button in the toolbar. After a second or two the page will refresh and show you the status of the build as it progresses. The build result will be shown in the Recent history section of the page.
A word about troubleshooting a failed build: If the build fails you can use the drop down menu in the history list beside the result in the Results column to view the build messages to guide your troubleshooting. A couple of things that have tripped me up are forgetting to add a newly referenced dll to source control. Along the same lines, referencing a new dll and not updating the MSBuild script accordingly caused a failed build. If you have no idea where to begin troubleshooting start by running the script locally from a Visual Studio command prompt. See the end of Episode 4 for more information.
If you're new to TeamCity I would suggest spending the time to explore the interface and become familiar with the many available options. As I said at the start of this post, I've only covered the minimal step to get you up and running from a cold start.