How to use Jazz Ant Tasks for Microsoft Visual Studio RTC builds

Introduction.

This articles explains how you can use the Jazz Ant Tasks in the IBM Rational Team Concert (RTC) build for Microsoft Visual Studio (VS) projects or solutions. For integration support details please visit System Requirements

Prerequisites

• Microsoft Visual Studio 2012
• RTC 5.0.2 plugin installed in VS Download Here
• This article assumes you have already shared a VS project with RTC Source Control that you want to build with RTC Jazz Build Engine (JBE)
• Microsoft Windows SDK and .NET Framework 4
• RTC Jazz Build Tool Kit Download Here

Creating the MSBuild project XML file.

• We first create an MSBuild project file to hold common properties for re-usability such as the command to invoke Ant, the location of the Jazz build file and the location of the build properties file.

• Launch the Visual Studio IDE and open the solution you are interested in by setting the Sandbox current in Team Artifacts view or by loading the workspace which your project source code is shared in. Add a new XML File Item and name it CommonProperties.xml. Open the file for editing and add the following content to it.

<?xml version="1.0" encoding="utf-8" ?> 
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
   <AntCommand>C:\BuildToolKit\jazz\buildsystem\buildengine\eclipse\plugins\org.apache.ant_1.7.1.v20100518-1145\bin\ant -lib C:\BuildToolKit\jazz\buildsystem\buildtoolkit</AntCommand>
   <propertyFile>-propertyfile C:\BuildToolKit\jazz\buildsystem\buildengine\eclipse\build.properties</propertyFile>
   <jazzbuildxml>-f $(fetchDestination)\TBDForm\TBDForm\build.xml</jazzbuildxml>
</PropertyGroup>
</Project>

Above

AntCommand uses the ant executable packaged with the Jazz Build Tool Kit.

propertyFile can be created in any location. This is automatically created when the Build is triggered. You can chose any location where you want this file to be created.

jazzbuildxml is the file in which you will define the Ant Targets to build. see below.

Creating the Ant build XML file.

• Next create the Ant build file which will hold the RTC Build Toolkit tasks we will invoke. Add a new XML File Item to your Solution and name it build.xml. Open the file for editing, and add the following content to it. The Jazz build Ant Task Reference pages detail the various Ant tasks that RTC provides. In the build.xml file we use startBuildActivity, artifactFilePublisher and linkPublisher to contribute additional information to the build results.

<?xml version="1.0" encoding="utf-8" ?> 
<project name="jazz build targets" default="startActivity">
  <property name="userId" value="jazzadmin"/>
  <property name="password" value="jazzadmin"/>
  <import file="C:\BuildToolKit\jazz\buildsystem\buildtoolkit\BuildToolkitTaskDefs.xml"/>
  <target name="startActivity">
    <startBuildActivity repositoryAddress="${repositoryAddress}"
                userId="${userId}"
                password="${password}"
                activityIdProperty="buildactivityId"
                label="${activityLabel}"
                autoComplete="true"
                verbose="true"
                buildResultUUID="${buildResultUUID}" />
  </target>

  <target name="publishActivity">
    <tstamp/>
    <startBuildActivity
        buildResultUUID="${buildResultUUID}"
        label="${activityLabel}"
        autoComplete="true"
          repositoryAddress="${repositoryAddress}"
        userId="${userId}"
                 password="${password}"/>
    <artifactFilePublisher repositoryAddress="${repositoryAddress}"
                 userId="${userId}"
                 password="${password}"
                 buildResultUUID="${buildResultUUID}"
                 filePath="${team.scm.fetchDestination}\TBDForm\TBDForm\bin\RTCBuildDebug\TBDForm.exe"
                 label="TBDForm Debug Executable"/>
     <artifactFilePublisher repositoryAddress="${repositoryAddress}"
                 userId="${userId}"
                 password="${password}"
                 buildResultUUID="${buildResultUUID}"
                 filePath="${team.scm.fetchDestination}\TBDForm\TBDForm\bin\RTCBuildDebug\TBDForm.pdb"
                 label="TBDForm pdb symbols"/>
    <linkPublisher repositoryAddress="${repositoryAddress}"
             userId="${userId}"
             password="${password}"
             buildResultUUID="${buildResultUUID}"
             url="http://www.ibm.com"
             label="www.ibm.com" />
  </target>
</project>

Modifying the .csproj file.

• Now we import the properties defined in CommonProperties.xml into one or more of Visual Studio project files during the build process. You need to first unload the project to be able to edit its project file source in Visual Studio.You can also edit the .csproj file in note pad.

Find the following line the .csproj file

<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />

Add the following line after it:

<Import Project="..\TBDForm\CommonProperties.xml" />" />

Location of the MSbuild property file depends upon the where you have created it in the VS Project Directory.

• Save the file.

Creating a new Visual Studio Build Configuration for RTC Builds.

• Create a new build configuration for the project in Visual Studio IDE using Configuration Manager. By default you have Debug and Release. You can copy the configuration you want to use for builds and then label it for example RTCBuildDebug.

• In Visual Studio IDE , click Build > Configuration Manager > Active Solution Configuration > New .

Add Pre-Build and Post-Build Event to the MSBuild.

• Right click on the Project in Solution Explorer Tan and from the context menu select Properties.

• Under Build Events TAB add the following commands:
  • Pre-Build Command

          if $(Configuration) == RTCBuildDebug  ($(AntCommand) -DactivityLabel=Starting_$(AssemblyName) $(propertyFile) $(jazzbuildxml) startActivity)
          

  • Post-Build Command

          if $(Configuration) == RTCBuildDebug ($(AntCommand) -DactivityLabel=Finished_$(AssemblyName) $(propertyFile) $(jazzbuildxml) publishActivity)
          

• Save the .csproj file.
  • Note: After creating and modifying these files, They need to be checked-in and delivered to the Stream from which you build the Visual Studio project from. So that the Build workspace defined in the RTC Build Definition can accept them into the load directory. In essence the MS Build Pre/Post-Build event commands call Ant on the startActivity or publishActivity targets in the build.xml file. The if $(Configuration) == RTCBuildDebug ( condition ensures that those tasks are only executed if we invoke the build using the Jazz Build Definition using RTCBuildDebug build configuration, thus allowing the build to be run natively within Visual Studio using Debug or Release.

Setting up Build Definition in RTC.

• Create a new Build Defintion in RTC Eclipse client. Create Build Definition

• There are addition properties you need to set in the Microsoft Build tab in the build definition based on the above configuration we setup.
  • Build Configuration = RTCBuildDebug
  • Additional Arguments = /property:fetchDestination=${team.scm.fetchDestination}
  • Working Directory = ${team.scm.fetchDestination}
  • Properties file = build.properties or C:\yourdir\build.properties (The path is what you defined in CommonProperties.xml with propertyFile variable)

Setting up Build Engine in RTC.

• Create a new Build Engine in RTC Eclipse client for Jazz Build Engine template :Create Build Engine

• Start this Build Engine on your Build machine where the Build Definition will load the source code and MSBuild will run.

     jbe -repository https://server-vs.ibm.com:9443/ccm -userId jazzadmin -pass jazzadmin -engineId VS-Build-Engine -verbose
     

This setup is complete. You can now use the Jazz Ant Task in your Microsoft Visual Studio Builds.

Related topics: Deployment web home

External links:

• Continuous Integration with Rational Team Concert and Microsoft Visual Studio

Additional contributors: ZeeshanChoudhry,