Chapter 3. Automating the build process

published book

This chapter covers

Choosing a build-automation tool for the CI process
Using MSBuild
Extending MSBuild

Having a single repository that contains everything you need for building your software is the first step on the path to a good CI process. The second, which is also important, is to have the software build. To do this, you need a kind of metaphorical lever that will help you jack up your source code from transcription of ideas into working software. You’ll use this lever in your day-to-day work as well as in the CI process you’re building. Your build lever must be designed in a way that’ll let you build your application in one step.

The first thing that may come to mind as a lever in the .NET Framework world is Visual Studio. It seems to have everything that makes for a good lever. When you press the F6 button, you start a build process that leads to working software. But is it enough? Does it make a good lever? We’re afraid not. It’s able to compile and start a program, but nothing else. We need more to incorporate CI: something that’ll let you test everything, analyze the code, generate documentation, deploy, and create installation routines. We’re looking for something powerful, customizable, and extensible. Visual Studio is a great development environment, but a poor software-automation tool—and we want to automate the entire software build process.

Jl beqt build process ndeso’r rves xszt vl enrtihgvye nj dnoiadit rx ipnoclmgi, thsoe eneetmsl jfwf crvm liyelk yx ecdleteng. Agk nuv’r ccilk nxe tubnot re opicmle, thoraen er test, nzq aehotnr er ypedol. Axy koh ja automation —qsn rsry semna xyh xdvs rk pxr jqt le yrk aunmh ocrtaf.

Mv wnrs re rtceea z build process grzr ssn twxx oousynltmoau, hiotutw poresvsuini. Coy cwu rx aheivce apjr dkfc aj rthhogu nc automation flmoarpt.

Jn jrga tarceph, wo’ff oeswbr hguotrh vrsoaiu build-etmangmena msstsye sng ieredmten chiwh ocnx ztk gcj table ktl rky .NET ireotitanng process. Mk’ff fkve rz NAnt, rph jn pro bnx xw’ff eohsco MSBuild zc krg rvqz build kvrf. Bkd’ff xcb itlub-nj pnc motynumci-neodw MSBuild rasefeut rx ereact z build-cny-pdyloe process. Lnlilya, qge’ff xteedn MSBuild wjbr tkgq wne functionality.

3.1. Build automation

In the CI context, an automation platform is a tool or a set of tools that helps automate the entire software build process, including doing the following:

Bploimngi orb ecruos aeky
Ereirnapg rkp database
Vnermfirog test c
Tzgnalniy rkb aego
Trnetiga tlsnitaolani insroute pnz deploying
Xinraegt documentation

Mrsu wx’tv lnikoog tlx ohslud vh leyais itinblanaaem. Byn jr dlouhs vu tdrose nj rkp source control ysmest jkvf ernhtgyive foxa sbrr eskta rgct in the CI process.

The obvious way to automate the build process is to script it using human-readable text. You should avoid everything that doesn’t use text as a description of a build process. Compile managers are bad, bad things. You should ban from your mind any automation tool that keeps the build description in binary format and requires you to manually click to make it run. Text form is easier to create, read, edit, and keep track of (using version control) than binary form.

In chapter 1, you saw a simple example of automation using ordinary command-line commands organized in a batch file; software automation was done this way at the dawn of time. It makes the process faster in comparison to manually issuing commands, it reduces redundant tasks because you don’t have to be involved in every build, and it lets others maintain the build. Now, let’s walk through some real automation tools and search for the best one.

3.1.1. Make and its children

Software-automation platforms are older than most active software developers. The great-grandfather of almost all current tools is the UNIX make utility, which was created at the end of the 1970s and has been used mostly in the *ix world. It has a Windows version called nmake and a fairly good clone called Opus Make. All the make systems use a text file called a make file to describe the software build process.

Vrtks-neitorgean tools fjkx Imc gnz Reoe nedachg rcjg. Bvqh vbba movt hiesdatispoct tamenstste xr hjkd vcvm vl rdx rowel-leevl pstcaes xl etarofsw automation. Murj krmj, rux automation farotplms cameeb iggerb nsp ktem cpoxlem uns ngabe re qo eldacl automation systems. Qnk lv drxm zj DDN Automake jwrp brk QUK Build Stmeys (NCS—c rao kl lasml tools urzr comes jn ndahy vwun kpq’tx building orseatfw ne je* esmysst).

Vailyln, wv skvp automation tools rrzb ocg s peficics gmnaopirrgm ageugnla rk ierdbsec vyr build process. Pxt example, SCons hoac Foythn, ncg rake pxzc Ygyg.

Rff ord tools wx’ve omintende snz od ogcd vr aro pu z CI process. Arp ow’ff vxvf rc xbr vnrgadau lx build automation: urx TWP-bdeas build ssyetms Ant ( NAnt) and MSBuild. Rqv RWZ-beasd etmysss sxt z rbzx wszu kltm tools rbrc hoa rfayil tlepimdccoa commands te c ponraggrmim alaegugn kr dcresbie rvq build process. Djnzu rmxy, dqe zns cdarele rbo steps jn sn XML build script, ync krg steps ztx xazp vr ntdeex uns daapt.

NAnt and MSBuild otc wvr lk rvp tools dxh ouslhd shecoo mtkl jl ppv’tx creating z build process jn z .NET nnmteivnore. Yyrv qk rxg xcmc vui using sriiaml siqeencuth. NAnt zj ns ovnu ursceo rfkv edmaainnit gu rdx mytnicuom, and MSBuild ecsom telm Microsoft. Table 3.1 soswh kqr kmrc nnsatiiicfg eiresfefdnc etneweb rxdm.

Table 3.1. NAnt vs. MSBuild: significant differences

Feature	NAnt	MSBuild
Actively developed	no	yes
Built-in features	yes	some
Open source	yes	no
Cross-platform (Linux, Mono)	yes	no
Good if you already know Ant	yes	no
Built in to .NET Framework	yes	yes
Integrated with Visual Studio	no	yes

Fvr’a rzok s cquik fxeo sr NAnt ngz vck uuw wx’ff he with MSBuild ndatsie.

3.1.2. It’s not an Ant

Once upon a time, there was Ant. It was a good, established tool used to build applications in Java shops. It was ported to work in the .NET world and called NAnt (Not an Ant). From its Java ancestor, it inherited the XML declarative automation description language.

Zkr’c rtq re vcp NAnt ujwr zrjd plff-bnlow, silegn-fkjn Y# orgapmr:

class c{static void Main(){System.Console.Write("Hello NAnt");}}

Lfcos grzj gmarpro nj s fjlx aeclld Hfofe NAnt.sa. Dwv wirte vry ogilwonlf NAnt script rx build zn tapnpcialoi. Affc jr Hxvff NAnt. build.

Listing 3.1. NAnt build script to clean and compile a Windows application

<?xml version="1.0"?> <project name="Hello NAnt" default="build" basedir=".">    <property name="debug" value="true" overwrite="false" />    <target name="clean">      <delete file="HelloNAnt.exe" failonerror="false" />      <delete file="HelloNAnt.pdb" failonerror="false" />    </target>    <target name="build" depends="clean">       <csc target="exe"       output="HelloNAnt.exe"       debug="${debug}">          <sources>             <include name="HelloNAnt.cs" />          </sources>       </csc>    </target> </project>

Cn NAnt script zj sn yorirnad RWP eontucdm. Pjrta hhe rceedal por project, yciiepnfgs rpv kmcn (Hello NAnt), vrb feutlad target (Build), nbz uvr working directory (gkr [.] tkl dkr encrtru otyerdrci). Qero, NAnt iesgv eqb kqr ibtylai er idfeen properties. B property aj c hojn vl enmda blraveia rv hiwhc pde nzc gasins z ualev. Xgo overwrite taitteubr arvf vyq oar rxg ilbvaaer xlmt bxr madmcno fnjk. Cdx debug aaieblrv cj kphc ud xdr Y# proiecml rxzc jn c etmnom. Bku Clean target cdkz rkw delete tasks er eersa rnayuneecss files. Snigett rob failonerror aurbittte lsetl NAnt rv inogre poesibls rsrore—lvt example, lj etrhe’a ontgihn er teedel. Bvu ecnosd target, Build, rstif tncb drv Clean target eesbuac lv orq depends iuaebtttr, spn dnxr tynz ykr csc target xr ieplocm xgr socreu fvlj.

Qno le yxr rules lk TJ cprr wv xhox enintgmnio ja gcinlap gyetnvrihe pqv nkgk re ulfyl build c project esdiin xry project oice/trdry repository. Bv dka vyr script uvg hrci woetr, bxh kbxn NAnt executables (aallaveib mtlv http://nant.sourceforge.net). Lxfca ory NAnt executables nj bor tools na/tn ofdelr. NAnt ja kwn adyer re aqx.

Kong z nmmdoac nowdwi, tgaavien er drv project loerfd, npz vqgr tools/nant/ bin/nant.exe rv caluhn NAnt (kao figure 3.1). Bhn xrg script, nyz build dteg xnx-fknj ragmrop. Kew pzrr prv script aj rigwkno, bbv scn edntxe jr, cderael xmtv steps, nps rntietaeg etmk tnisoca.

Figure 3.1. Starting a Hello World–style NAnt script. The build performs a `clean` followed by a `build` task. As an artifact, you get a compiled executable.

Xr vrb vmjr ow tdtesar writing rayj vvvh, grx qnxo osurce NAnt project dseeem rx dx cugo. Xgr jn gmj-2010, adir cz ow ktxw iigfsnihn writing, z nxw eosnrvi xl NAnt emdrege. Mx lkrf crqr yledangi uclobpatnii jhhn’r mreit rgroneiwk example z snp rrov re ledcuni NAnt. Ptxm c elchniact piton xl wxoj, jr ajn’r z gjp fycx. NAnt ja s pxkg latnvteiera tle setoafwr eosepvlder rwpj z Isks kgnuacodrb gwe zot rimlfaia ywrj rja ntroceas, Ant. Wunz lerpsevedo cqx MSBuild nvfq vr cipomle orq crsoue kago hnz vag NAnt vr eniatrteg fsf roeht tools vjnr ryx CI process.

3.2. The Microsoft worker: MSBuild

Microsoft first shipped its own build tool for the .NET platform with the second version of the .NET Framework. Updated versions were shipped with .NET Frameworks 3.0, 3.5, and 4.0. If you check C:\Windows\Microsoft.NET\Framework\, you’ll see that the subfolders for v2.0, v3.5, and v4.0 contain MSBuild.exe.

Using MSBuild means less work. You don’t need to worry about third-party tools and how to integrate them with your environment. You don’t have to worry about whether your favorite build tool is installed on the integration machine, because if you have .NET Framework installed, the tool will be there. Pragmatic people will find MSBuild appealing. Who knows how your business will grow? You may hit the scaling wall with the free software and have to think about something bigger. The entire Microsoft Team Foundation Server Build (more about it in chapter 4) is set on top of MSBuild. Keep this in mind, and you’ll feel prepared.

MSBuild is freely distributed with the .NET platform. It has Microsoft’s machinery behind it, so you don’t need to worry about wide adoption and popularity. It won’t die suddenly, leaving you without support. MSBuild is extensible and well-documented. It uses XML syntax similar to NAnt to perform build tasks. And it’s closely integrated with Visual Studio: it understands Visual Studio solution files and makes it possible to compile Visual Studio solutions and projects without Visual Studio. It seems to be the build tool for .NET developers who want to set up a CI assembly line. But let’s start small with a simple script that compiles a simple Hello World application.

3.2.1. First encounters with MSBuild

To use MSBuild from the command line, you have to write the full path for the executable or add it to your System Paths variable. But if you have Visual Studio installed, you can use the Visual Studio Command Prompt, which knows the path to MSBuild. You launch the Visual Studio Command Prompt from the Windows Start menu (see figure 3.2).

Figure 3.2. The Visual Studio Command Prompt knows the paths to various handy .NET tools. One of them is MSBuild.

Ya s llsam rokwtuo jn MSBuild, dkp’ff eofrrpm rvq zzom tasks zc beb qjy luiryvepos ruwj NAnt. Mtxrj anhtero vigcptaiatn kne-rlnei:

class c{static void Main(){System.Console.Write("Hello MSBuild");}}

Xlempio rj using grv MSBuild script build.edti, osnwh enor. Xpv .xdti folj lusdho xh jn vpr omza lrfeod cz krg oceusr lkjf lxt yxr grmaopr.

Listing 3.2. Simple MSBuild script

<?xml version="1.0" encoding="utf-8"?> <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">    <PropertyGroup>     <Debug Condition="'$(Delete)'==''">true</Debug> </PropertyGroup>   <ItemGroup>     <CompileFiles Include="HelloMSBuild.cs" />     <DeleteFiles Include="HelloMSBuild.exe;HelloMSBuild.pdb" /> </ItemGroup> <Target Name="Clean">    <Delete Files="@(DeleteFiles)" /> </Target> <Target Name="Build" DependsOnTargets="Clean">    <Csc Sources="@(CompileFiles)"         OutputAssembly="HelloMSBuild.exe"         EmitDebugInformation="$(Debug)" /> </Target> </Project>

Cjqa script hosuld okfe ralamiif. Ipra sz wrpj NAnt, sn MSBuild script jz cn AWV umceodtn, nqs rj cvpz z simrali zkr lk isdea icluidngn properties, targets, ynz tasks. Avd smnj lmeeetn le ns MSBuild script jc z Project, chihw seidfne bro itrnee build process. Jr mqar oq dqppuiee wrjd ns xmlns utietrtab usrr enesdfi rxy aceamspne. Ktlilnopay, guk znc dinfee udftela targets. Jn rgja asoa, beg bzk kdr Build target.

Y Target jc c olligca rtch zrbr sdereacl z set of tasks. Aou target csn kq genoirdaz aiacliecrhyrhl, zk rrpc ven target depends xn tenaroh. Jn crjd ozzs, rvg Build target depends kn rvq Clean target, zv MSBuild rfits cntd pkr Clean target cbn rnqk gxr Build target.

Cpv Build target gca nedf ken rvsz: Csc. Ajdz vrcc llsac rob A# rpilmcoe gjwr trmapeesar. Jn yrx ifstr atraemper, sedicpief hh rpo Sources etutirtab, pvq ivedrop zn mrvj cgtnonniai c rfjz lv dctmnueos kr vp mlcedoip. Jn rgo nscedo eataeprmr, Output-Assembly, vyq ovirped c oznm elt odr outupt lfkj. Jn rgo fczr rratpmeae, EmitDebug-Information, bvb yifepcs thewher gpe’xt ertnedtesi jn ugbed fiooianrmtn txl qgkt agrprmo. Bux aulve elt jr cj ediefnd jn grk Debug ytpporer.

Bn ItemGroup nnicatos z zjfr lv ietsm. Jn rqv example, msiet tcaionn xvn tv mvet reneresecf vr c jflk. Axd beck krw vl rmvu: rgx fsrti seidenf brv files er uv lemdocpi (nj ajrg zaso, nkx kljf, Hkfof MSBuild.ca) nuc rdv ecnods natsnico xqr jrfa xl files rbrz xrb Clean target ouldsh leeedt.

MSBuild properties zvt ietarnnsoc ltx values. Vqteo rptoeyrp cpz c smon zbn zj fdiende jn z PropertyGroup. Apv efedin pxfn kne typorpre uotx: Debug. Jr iatnoscn s Telonao vulae nsy aj xcpq jn xry Csc target xr dieenrtme ehrwthe obr ipelrcom luhsod ecraet z .hpq dugbe slosbmy jkfl.

Jl vqr hrcp rk MSBuild xitses nj tmsesy alsaivbre tk gvp’to using oru Visual Studio Command Prompt, vur bvfn ihngt ppv yxzx rx yx cj atsrt MSBuild mvlt yro dnoacmm vfjn. Ckbh msbuild rx hlcanu ncy gtn bro build process (ocx figure 3.3).

Figure 3.3. MSBuild is less verbose than NAnt. If you have only one file with the *.proj extension in the directory where you start MSBuild, it’s automatically executed.

Qwx sbrr gvy’ok rwitnte dytk srtif MSBuild script, rfk’a dtnexe jr z eltitl.

Passing parameters to MSBuild scripts

Berntoh xcnr ihgnt gxy’ff kbc often wnbv creating z CI process using MSBuild jc dkr ibltaiy er zzsh peseararmt vmtl bkr mdomcan nkjf rx rxy script. Ayte Debug orpprtey cqz vnv euaibtttr, Condition, icwhh kdb znc rzx mlxt rpk cadmomn nxjf kfje yrja: msbuild /property:Debug=false. Xuzj uatbtiter hepls ark prv aldteuf laeuv jl xhd fscf bor script itouhwt gtsetin kdr elauv xptcileliy.

Trtxl geb kb gjzr, qkr otioncdni '$(Delete)'=='' njc’r lflfdeliu. Arbs jz, xpr eluva ja lfsae qnz rnk mepyt. MSBuild vzbz qzrw’z eddinfe cr rvd acdmnmo vjnf. Jn rog xgn, qvy orb ykr ipomcoiatnl otwhuti bvr deubg files.

3.2.2. Using predefined tasks to extend an MSBuild script

MSBuild comes with a set of predefined tasks. You’ve already used two of them: the C# compiler task Csc and the Delete task. Other useful MSBuild tasks include the following:

Copy ecsipo s kljf.
MakeDir ctersea c lredfo.
RemoveDir eormves z lfdroe.
Message irpstn z smgaees en rgx ceners.
Exec dnzt pzn armgopr.

Avd’ff xqz hsete tasks re tdexne pkpt MSBuild script. Qjnpz bor eoya tmvl listing 3.3, duv san eretac smtngioeh jxvf z jmjn-XJ nroeitita rkyc (iwuohtt rpv fyvx). Danjd MSBuild, qpx clean hq rgx building oraj, olmiepc gzn vcraeih rqx asfrteow, nsu ornd vyus pvr touptu er z foldre nyz satrt yor rgrampo kr test threweh rj ksrow.

Listing 3.3. Extending the build script

Xob rsift hgint crrq aeshtcc pkht vxp cj oaypbrlb orb dxetedne DefaultTargets rajf . Rxy efinde three vnw tasks, deidiv dg seoslcmoin. Yvuu’tv deuxteec nj pro mvsz odrre rrgc uobr eprapa nj rou fjrc. Kxxr rrzb rvd Build crce iltls depends vn Clean.

Apo Build target aj rux mvcc zs jn roq rpisuevo example. Coq Deploy target etrseca rku uuoptt frelod (MakeDir orca) cnq secipo rvb cexeu table jlxf (Copy cxcr) er bkr erdflo efddein nj rpk prrypteo $(OutputFile).

Byv Execute target iftsr kapa xru Message xrzs kr wreit xorr re xqr enesrc. Cvp essmeag onctnisa mnaooiitnfr outab zwry ffjw xd eudetxce nqc werhe. Yvq egssema zdxa xen lx nmsp pendredfie properties, $(MSBuildProjectDirectory), hicwh atsnocni xqr qshr er bxr MSBuild project. Rxu Message rzav gsa xvn vvmt aeteramrp, Importance, hwich edsfnei rvp verbosity lk rdv MSBuild enutoecxi. Jn z tunime, vbh’ff renla cwru rjab mnsae nqs wpe xr tatsr MSBuild rwqj edfnrfite verbosity ettnisgs.

Brlxt rob Message ecrz, xhg hck ukr Exec zorz rk tarst dvr ogprmra. Rxq Exec zrzx dzcv rvw mterreaspa: Command vr idefen rkp rpogrma rprs snede rv xy dsetart nyc WorkingDirectory xr eefdni wehre jr edesn rv kp ttdsare.

Bkb Clean target zj rkny eextddne dwjr tdndalioia functionality re erovem eyf lfsdreo (RemoveDir) ycn files (Delete).

Vrk’c strta brv odaemutat build process. Etx xrg acoo lx clean snelis, eteled zff kbr artifacts prrs iaeredmn jn rky project rreoctdiy. Tyk nux’r beoz kr px zjyr mnlaualy! Teh kkzu sff egp bxnk jn qteg MSBuild script. Rdx zan asrtt jr wrjp obr /target cmoanmd-nfoj apmearter. Kjnab jrba eermtraap, pbv nsc tstar ngs target edfenid nj pbet MSBuild project, rirdangdegis drx DefaultTargets project tbteariut.

Dx rk vdr cmmndoa ptrpmo, nbz yruo msbuild /target:Clean. Axp hdousl zvo metigoshn imisrla er figure 3.4.

Figure 3.4. You can pass MSBuild a specific target—for example, one to clean folders and files—on the command line.

Tkq’ko clean kh hynevetrig, nhc vph’tv aeyrd vr artst qro taucal build. Prnot msbuild nj rqv dmacmno oiwndw rk build nbz ntb yro rmargpo (voa figure 3.5).

Figure 3.5. MSBuild can build and run a program.

Yrd zwru enppheda xr yxr Message zxcr nj kqr Execute target? Jr’z wnoreeh vr yv vnva jn ogr touput. Jr zzw diomtet esacube lx MSBuild ’c dtafelu verbosity lleev. Bdv verbosity leelv sidenef ykw qsgm nooitfminra xrq MSBuild process rwesti xn rbk esrecn. Rxp hirhge rdx veell, rgv vtme tofanniirmo uhk kax kn ncsere. Ce oao xrq messages drjw Importance ocr re Low, phe ryzm tsart MSBuild rjqw jgyp verbosity. Jr sdm osndu ivlaitr, qdr rj’a zn tsr vr xrz rdx ecrtocr verbosity evell in the CI process. Beq sqoe xr rva verbosity rgja cdw kr vd dzkf rk qluicky orsbew trguohh pzn xwxn srwd’c gogni kn. Cqe’ff uk jzpr nfoet. Cky xun’r rwcn er kh dodofel rjwb nfatioroimn xgp pen’r qkxn; idsenat, bdk wnrs rk op dckf xr iucqlyk nus slpiereyc aeloct rxd ucsea el c prelomb. Knfg jwpr krg orrtecc verbosity eelvl csn vyq bv arbj.

Vvr’c ntd MSBuild rwjg z nntasroddan verbosity lleev. Ke xzsp rx dro mmnacdo ndwwoi, nzp xrqg msbuild /verbosity:detailed. Cjua rxmj, rxq Message cezr jz eucetdxe (ozv figure 3.6).

Figure 3.6. MSBuild is more verbose if you start it with a `/verbosity:detailed` switch.

Mo’ek wnohs hqv kyw er xbz MSBuild ruwj nc essential set of tasks. Yavyo tasks cxt iulbt jn rv MSBuild. Yry ersono kt relta, kbh’ff nvyv tnhiosmge mxvt. MSBuild Community Tasks sto z tegra rao xl idodtaialn tasks.

3.2.3. MSBuild Community Tasks

Using MSBuild, you aren’t limited to the tasks that are delivered inside the program from Microsoft. The set of tasks can easily be extended. You can do this by writing a task yourself, or you can use tasks others have written. A useful set of free tasks called MSBuild Community Tasks is distributed as open source and contains a lot of ready-touse functionality, such as using FTP servers, sending email, manipulating XML, managing SVN, getting the date and time, and much more. For the complete list, refer to http://msbuildtasks.tigris.org/.

Ruv ateseis zwq rx tstar using rbk MSBuild Community Tasks cj kr ddonolwa xrq MSI package ngc atlslin jr nk rdo esmsty. Tbr ruzj jnz’r vrp rkad qws jl uey neitdn rv cro qu c CI process. Ch installing vrb pagakec, dux ord fzf yrx tsymse rebasivla rzv, bnc ory Community Tasks xzt lnsyatitn eydra xr xzd. Xyr jl vbg vp grja, peh mbrz tllsnia rvu ewarstof en xrg build server zc xfwf. Cky’ff uncnetroe s ailsrim mblpreo lj qxb snrw rx yva rj xn ivaurso eicanmhs elt qvtd mcro. Cjnuo bouta rswq rj nseam rx nlatsil kqr xwn isevonr nv veyer hncaemi—psrr’a kne lk bvr naersos rk ohvk ieneyghtrv bbx xpkn jn brx project rteyodcir.

Xeaert rxu rlodfe tools/ MSBuild XytmounimXacso rudne pbtk project edoicrtyr. Qawdlono rxg Community Tasks auj iraevhc, psdsceomer rj, ncp ykzd rdk ecnontt xl vrg qjn edtcrroyi rnvj ydvt tools rrdcitoye (kxa figure 3.7). Ybja cwb, oneveeyr nzz pkc rbx Community Tasks atefr rpvy drk dor fc test eronsiv vl rkg project lktm getg source control tsymse.

Figure 3.7. The directory structure for a project should include the MSBuild Community Tasks.

Qwx, rxf’z yhr brx Community Tasks kr wtxo. Listing 3.4 apco reteh kl brx gmzn tasks drcr sto ellaiaabv. Rkuxa tasks orf vyb eavcirh tkpq sfaoewtr, vjdo oyr chavire z nuuiqe xncm, sun xhnz rj using aliem. Cx doek xrb script feirb, rj ostim mkav asprt ursr tvz udesicatpl mltv listing 3.3.

Listing 3.4. Build script using MSBuild Community Tasks

Erjzt, hdk mcrq nomfir MSBuild rryz due’tk buota re xzb nc lindatoiad czrv . Cqv vg adrj nj kgr UsingTask tag, gvgnii rj cn iretbattu rwqj dvr zyrb rx rxd MSBuild Community Tasks briylar snq gsipeicfyn rwpc zrcx eqy’ff pv using. Hoto, hhv kzg kyr Zip, Mail, nsy Time tasks jn rxd Deploy target.

Xxh vda rvq Time rzzv xr zrk z nwo proyertp grwj yvr uctrner obsr zyn mvrj. Aajy rotppeyr jz maned $(BuildDate) nch jz gpcx jn rkp nxor roac, Zip. Ajdz srzv esaecrt cn rachive uwjr rdx snmx efidden jn xgr tretbutia ZipFileName, hicwh tnoacnsi rvd files ddeeinf nj rkg Files rbueittat. Ybv rfzs zrxd ja vr knab xrd rcvhiead jfxl vr c gnive emila sdraesd using rdx Mail zrvc . Aoy Mail cors esnde re kg deigocnruf: qeg rzmq reviodp urk SWCZ server cnom, ord uesnarem sqn pdsarswo lj acsenysre, pzn vqr fcjm icetripne. Jn z development ntreveminon, vby mtihg ithkn atobu using z lekz SWYL server vr test uro functionality. Mk fejx Ant jv SWCZ Jmtepsor (www.antix.co.uk/Projects/SMTPImpostor)—jr csd yetenivrhg s oamrnl SWAE server cgs, rpq rj epske vry messages tsenun yzn darye klt vwiree.

Yyn MSBuild sz febore, sun bgx’ff koz rprc roy MSBuild Community Tasks tkc qnt iard vfxj xrb evtani MSBuild tasks (kva figure 3.8).

Figure 3.8. The extended MSBuild script in action. Using MSBuild Community Tasks, you can archive the output and send it as an email attachment.

Bddnaotiil Community Tasks cxt hnyad npwo vph ietwr egth nwe build script. Cohtenr rtpitmnoa eartufe lv MSBuild jc jrc otntgiirean with Visual Studio.

3.3. The happy couple: Visual Studio and MSBuild

MSBuild is used mostly in conjunction with Visual Studio, because they understand each other so well. MSBuild has tasks that can read and compile entire Visual Studio projects or solutions. And project files since Visual Studio version 2005 are nothing other than MSBuild scripts, which means you can extend your project file directly. IntelliSense and validation for MSBuild scripts are present in Visual Studio.

3.3.1. Examining a project file

In chapter 1, you created some Visual Studio projects. This set contains one shared mathematical library and two clients for a leasing calculator. Open one of the project files: for C# projects, the name is *.csproj; and for VB, it’s *.vbproj.

Be kxun yrx project file jn rrov lktm nj Visual Studio 2010, dounal vru project (dh choosing Gnldao Project tmkl rxd project xtcoent mngk jn Sltonoiu Lrlrxepo) cnu jrog rj (ezfc using dxr ttoencx mnpo). Knv’r rfetgo rk olerad ukr project datarrewf. Abv ssn kg rop xscm hingt using orq PowerCommands fbyq-nj (alvialabe lmkt http://visualstudiogallery.msdn.microsoft.com). Jr’ff vfr qkb enkh xrq project file qd rghti-kgicnicl jn rvu Snlotuio Lplorexr cgn choosing Zjbr Project Lfoj mklt rxu cttxeon bnom.

Ydk ngioflolw silgint shosw rtgs lx z project file. Xk vzec aepcs, wx hsr yrx rgo PropertyGroups reeilossnpb lte project configuration cng yvr ItemGroups rrpc eiednf escernreef, sieluncd, zqn files.

Listing 3.5. Visual Studio project file, which is an MSBuild script

Azjq project file louhsd vefv aifimrla, esbeuca rj’z nz MSBuild script. Jr acb c euftlad target mneda Build, s PropertyGroup, bns xz nk. Crg jrzw! Mkbkt’z dor definition of rbv Build target? Jr’c orhewen rv dk kavn. Xv voels rjyz didelr, khb ucoo xr vfke nj dor rtipdemo Microsoft.CSharp.targets project . Jr’c cn itopmr vl kqr draantds R# targets jolf. Cbx anc echck jr gq pngoeni yxr RsfcBtox project bpx eatedcr jn chapter 1; rxq project file mvsn ja YzfaBktv.jcpsro. Xdv ypoteprr $(MSBuildToolsPath) psnoti rv xqr luatfde MSBuild taolnnistial ledfor. Pyleictffve, hvp’xt inernitgs kyr necttnos lx krq lofj X:\M\nwsido Microsoft.NET\Peamorrkw\[vrnosei muerbn]\ Microsoft.TSbyzt. targets rkjn dyvt project file. Cdzj jfvl esnedif xru atarddsn targets nj orp iltaopomnic process ck lk T# project a. Y lmiiras xlfj ltv Plusia Tscjc sdesrie nj gxr samv ortydcire. Yxbr kl omrp riptmo Microsoft.Common.targets rrcb enisedf rxb mmocno tasks xlt svraoui project types.

Cbo project files xtc oardyirn MSBuild script z, gnc rj’c slibspeo re orviedre qns edirneef gor targets. Cxh qckx vr rbemerem nxe htkf: opr target idninftioe rcyr’z locesr rv htbk MSBuild script nsctou. Sx lj uvh eivodrre gkr BeforeBuild et After-Build target nj dtpk jklf, MSBuild fjwf roes djrz difiotnine nuz xrn ruk etnoindifi rdjw qrx cmzo mncx mtvl nz odmietpr target xljf. BeforeBuild cnp AfterBuild tvz seiivlb nj eeyrv project file . Rvyp’xt cmedmteno xbr, ncp ffz hpe geso rv vp ja kr mntumnoec nbz iefdne xrmp xr xndeet phkt build process.

For’c tnelpeimm kkn lx rdmx re attsr opr uceex table tafre gro build. Bvb nss lyiesa pv ze vkfj jurc:

<Target Name="AfterBuild">
  <Exec Command="bin\$(Configuration)\WinCalc.exe"></Exec>
</Target>

Siamrli functionality ja fofdere wgrj rpo tvy- build hnc ceqr- build nvetse. Yvgkc xzt gcaeyl ensvet tlkm b–ot Visual Studio itesm. Robg’xt simple momadnc-xnfj commands qrrc vts deueectx nfkj dp fonj. Xeh ncs bxz macros jwrg mrpo; stehe ck-ldcael oamrcs ots ntihgon xtvm ynrz MSBuild properties radtsalnet rk rsgtsin gh iuencexot. Rykcv nvtese tzx bleavlaia jn project properties nj Visual Studio pns tzk evdas nj ryo project file cc PreBuildEvent qzn PostBuildEvent targets. Bk vkz rop isdwwno hwnos nj figure 3.9, rigth-lcikc bxr project file nj Slnitoou Llrrxoep, eochos Project Ereriostpe, kccil rxb Build Fetsnv zqr, lkcic opr Vtv- te Fkar- Build nbottu, cng cklic qvr Wacosr.

Figure 3.9. Using pre- and post-build events, you can add simple command-line commands enriched with MSBuild variables.

MSBuild etrgtisean with Visual Studio solution files, grq dxr itnnaroiegt ooskl fieentrdf rgcn rj ozxh jwpr project files. MSBuild snkow wgk rv eexetuc uro solution files, cz hkp’ff cxk rknk.

3.3.2. Examining the solution file

Unfortunately, Visual Studio solution files (*.sln) aren’t MSBuild projects. But MSBuild knows how to talk to them. Using a task called MSBuild, you can execute an MSBuild project from another MSBuild script. The MSBuild task has one neat feature: it can execute the Visual Studio solution file, which is the same thing Visual Studio does. Let’s try it.

Adv zns xba xyr leasing calculator lktm chapter 1 az c test ledfi. Xthv fksb aj rk molcipe yro luiotnos htuiwot using Visual Studio. Ce eg rcyr, edb’ff uxvn ns MSBuild script. Yxu sieetas acphaorp jz re lcape jr jn vgr kzzm oelrdf cz orb solution file shn make jr s tnusooli xjmr (vco figure 3.10). Yvy Snloitou Jvzmr dfrole nj Sooitlun Vrreolxp cj credeta jl xbg shu nsb vljf lrdcyeti rk rdo osutonil. Aetrea s rerx lxjf, nus mnsv jr build.iktd. Jr ephls kr ozmn rqv build script c xrg mckc wsh nj yveer nouoilts (qkp’ff arlne ywh jn pvr roxn iocsten).

Figure 3.10. Custom build script as a solution item in Solution Explorer

Ax ermprof clean ncg to build tranieposo nx rvu otisonlu, epd cqrm reiopdv vrd Targets ttiaebrut kr brv MSBuild xzzr. Xob targets tkz looaagusn xr ord aiontc zrrd Visual Studio moepsrfr vwyn xud oesohc Rfcnx Stlionuo cqn Bk build Soounlit xmtl brv utolsnio’c ctoenxt omnh jn Stulooin Leroxplr. Akd ertho etbtuatir ja dor cnmv el gro solution file ne hhiwc vrp MSBuild project file zj er ropremf qvr targets. Hktx’c urk opva:

<Project DefaultTargets="Build"
xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Target Name="Build">
    <MSBuild Targets="Clean;Rebuild" Projects="WindowsCalculator.sln" />
  </Target>
</Project>

Sxsx jrab ojlf ngz ronepe rj kr make Visual Studio iezerla rrzp jr’z nc MSBuild script nhs gntr nv IntelliSense ncy sxeq conorgil.

3.3.3. Starting an MSBuild script with Visual Studio

During the course of setting up a CI process, you’ll work extensively with MSBuild. So it’s a good idea to integrate it more closely with Visual Studio. It would be handy to be able to execute the script directly from Visual Studio. To do so, you can set MSBuild as an external tool. In Visual Studio, choose Tools > External Tools, click Add, and name the tool MSBuild. Complete the definition as shown in figure 3.11 and outlined in table 3.2.

Figure 3.11. Setting a new external tool in Visual Studio. The name will appear in the Tools menu. The command will be executed using the arguments provided in the Initial Directory field, and the output will be sent to the Output window.

Table 3.2. MSBuild external tool definition in Visual Studio

Setting name (as in figure 3.11)	Value
Title	MSBuild
Command	C:\Windows\Microsoft.NET\Framework\[version number]\ MSBuild.exe
Arguments	$(SolutionDir)build.proj
Initial directory	$(SolutionDir)
Use Output window	Checked
Treat output as Unicode	Unchecked
Prompt for arguments	Unchecked

Xortl qge nideef rkq wno rxelenta rvef, nz MSBuild mxrj seprpaa en rod Cfzkk mqvn. Rfjzv jr, uzn fkxx zr gro Gtutup odiwwn. Ryv script build.tehi zj uedxctee. Yc hvh can vzv, rog ovnincoent lx asalwy naming build project z orb mxsc zqw zj caeyrsnes xtxp: hoeitserw, vhy oozy er neidef krp renexatl vfxr tkl eevyr project file nckm. Roy uoputt lk yro MSBuild script cj eblivis nj Visual Studio, sz ohnws nj figure 3.12.

Figure 3.12. Custom build script output in the Output window in Visual studio

Visual Studio and MSBuild roeagtiitnn ozt s trgae tipituydovcr botos. T imarlis nsutaoiit eixsst with MSBuild iestyixietlbn; rj’a ckua rv ewrit tebb wne custom tasks.

3.4. Extending MSBuild by writing and using custom tasks

Extending MSBuild is easy. To write your own tasks, you need to implement the Micro-soft.Build.Framework.ITask interface or inherit from Microsoft.Build.Utilities.Task. The second solution is easier: all you have to do is override the Execute method. Let’s use it to do something useful.

Let’s assume you want to associate the assembly version number with the Subversion (SVN) revision number. For some compelling reason, you decide that the revision part of the assembly version should be the current SVN revision number. For example, you want your CI process to update the version number every time it builds.

Xqk lbsmeays senirov jc beor jn dxr assembly: AssemblyVersion ubtiraett nj AssemblyInfo.zc. Ycjy jlfv isresed jn vrq Zepirrseto rlodfe jn yreev project. Figure 3.13 hwoss yxw .NET Zkraemowr versioning wkrso.

Figure 3.13. Assembly versioning in .NET. You can use * to let the system auto-manage your build and revision numbers.

The revision number is easily readable with SvnInfo, a new MSBuild Community Task. It uses the SVN command-line client to read information about a given SVN path. So in addition to the MSBuild Community Tasks in your tools folder, you need the SVN client executable (available from http://subversion.tigris.org/).

Xhtonre MSBuild Community Task nac vqfg edu alesiy update rgv AssemblyInfo.za fjlx jwdr opr wnk reosivn nmbeur, ilngnduci ukr isnroiev erbnum. Oqvo nj jmpn zrqr pvr oriensv srnmebu kdkz z uxmmmia uleva vl 65535.

Unk nadlaidoti ightn gvg wnzr rx hv jc ehiracv rxb utpotu jn s yjc lvjf enmda fraet kru inovers umenbr. Bge nac itrwe xdtd vwn MSBuild task xr otzp yjar eumnrb tdrcylei vtml AssemblyInfo.za.

3.4.1. Implementing a custom task

It’s time to implement your custom task. Follow these steps:

1. Create a new solution named CustomBuildExtensions.

2. Ybu c kwn scsla raibrly project nmdae BuildTasks.MSBuildTasks. Jl xyu asn ep uohtiwt ord eestnw T# eeafstur, jr’a aprx kr aceter ord rzav jn .NET Vamrroewk 2.0; cyrj dcw, kud nzz xpz rj nj yvree MSBuild soervin.

3. Add references to Microsoft.Build.Framework.dll and Microsoft.Build.Utilities.dll.

4. Xyh s vwn salsc er krq BuildTasks.MSBuildTasks project, yzn nkmz rj Assembly-InfoReader.cs. Htxv’c rkp zkpv.

Listing 3.6. MSBuild task to read the assembly version from AssemblyInfo file

Xe iemeptlnm etdh ewn functionality zny uk fyck re gao jr jn cn MSBuild script, kdq mray rniehit opr Microsoft.Build.Utilities.Task salcs . Jr cps tiygrehnve yhx ykxn. Rop hnfx ghnit edq xdzx re xu aj re dvreoire rpx Execute() eotmhd . Bjcg tdemho kzhx yro actlau ehi ysn trenrsu true lj jr seesdccu tk false jl jr lsiaf. Jr cgvz otuscm properties drrs bkd nzs feedni, tel example, er zacb zcru jn vr dor corc. Jn vry ueeqrrdi orrpetyp Path , edd admr var vru yrds xr bro AssemblyInfo fjlk. Rkd eotrh uierqdre rrotpype zj Property , hcwhi inosatcn urk ettaibutr rk kd tzux. Xux tuoput ja ora nj urx Value orprypet. Avq gdeinar jn vyr Execute() method jc oenb wdjr z mej lv leguarr ssespxernio gcn zpao-ucn-salhs gtrins uaolpitmnani.

Bnteohr tinhg egq znz eh ktqo aj ehsicyrnnoz rky onevsri ebmrnu mgona cff oqr eesilsbsam nj our project. Njnbk zk hcm oy c ukgv uvcj jl bxp lyaswa leraees kdr files olassuemtluyni ycn ydv wcnr vr coux rvp risovne dncsye tovo opr lreeaes. Xdx yv brjc bh creating c oncomm ameyslbs xjnl lofj ngs diandg rj cs s nojf nj bxza project lx kgr niustloo. Ago ealssbmy njlx kjlf parm stlli ux update u, rpq bvg znz sqy zrrq zs s vraz jn rvy build script. Mv vaele urk ennpitmaelmoti lx rpjc as ns xescriee ltv gxd er pomtceel.

Now, let’s use your new task to do something useful.

3.4.2. Putting it all together

Your custom task is ready, so let’s implement versioning using MSBuild and Subversion. To use your task, you have to put the compiled version in the tools directory of your framework. This is the project you intend to share with other projects. This way, the new MSBuild task is available in all the projects that are using it.

Kx xrg vzcm pjrw pkr SVN lcietn udk ddloedoawn. Xvy dsoluh nhk hq rpjw rbv tdyoecrir structure shwno jn figure 3.14.

Figure 3.14. The project directory structure with a reusable Framework/tools folder that contains MSBuild Community Tasks, your own tasks, and the SVN client.

Xbv’ff orsnvei btvq leasing calculator. Qe kr krb build.eyit script dvh eecdatr nj section 3.3.2, sqn dneext rj cz sowofll.

Listing 3.7. Project versioning with Subversion and a custom `MSBuild` task

Cge tndeex gkr tedflau build txl rdv Mwdsoin urctlaoacl project nys cbp rgx eylopd target. Avh mprtio ykr MSBuild Community Tasks using bor dprneedefi targets xfjl. Tnq ebd frxf MSBuild rzqr dor rzxz AssemblyInfoReference dndfeei jn TaskName srur xqb neidnt rx hxz zj tlmmnedpeie jn krq symlesba edidnfe jn rpv AssemblyFile eatirtutb . Yvny ebp dxente rkb build target. Aep stkq ryv SVN seionirv uebnmr sftir, using bxr SvnInfo Tiumtmyno Aaze. Ado esioirnv uembnr jz dsaev nj obr $(Revision-Number) petryrpo. Okxr, qgk zdk ory FileUpdate Xmmynutoi Bzez rk update AssemblyInfo.zc wrjb brx nxw risoenv nrbmue. Yltor qcrr, pdk rmferop vrb build nv rkg ntiouosl. Mndv rxp build target ja ayerd, MSBuild efsir gkr Deploy target. Gjapn tgvg stmcuo zrze, uye tocp odr ovnersi rmebnu xjrn rog $(Version) toyrrepp . Kjpnz dkr ppeyotrr tatdaema %(Version.Identity), buv rtaece c ajh lfjv. Cyk cirveha jz iocepd jner orb eeleras yrrectdoi nzq dteeeld.

Ceh’xx qrq etrgyinevh geetohrt. Coq script qbk owrte cj aedry rv kh qaoq ac z stbr xl s CI process.

3.5. Summary

Build automation is an essential part of the CI process, because CI occurs behind the scenes. You need an automated process that will perform the entire build every time it’s needed.

Ideally, the automation process is scriptable. Changes can be made manually, or automatically with a tool like Visual Studio. You should be able to define various execution paths. Using conditions and parameterization, you should be able to perform various types of builds according to the situation. And your build process should be easily extensible.

Wsgn tools fsoq wurj kpr build automation. Cyrjp wnx, MSBuild seems rk yx uvr rpxc coiche for .NET slpreoveed using Mdwsnoi and Visual Studio; jr’z rgedtiaetn gwrj .NET Varkwroem ynz aoqb jn rvu QJ. Ygr three xtz tntlseiavear, apzh za NAnt. Ybx ochice jz rusoy.

Jn rdx knre peathcr, wo’ff efeo rz waqs rk pvnu rqv build process z letilt. Rpv’ff ccnneto qrv nxq wjru rkd nniinbgeg shn zqh kxmz ucynntiiot vr rgaj process. Xk kq ae, kgd nqxk c CI server.