MSBuild

BizTalk Deployments with PowerShell

EltonStoneman — Thu, 11 Dec 2008 05:09:56 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

As part of my first look at ESB Guidance 2.0 (which has some excellent enhancements which I'll post about shortly) I've been interested in the way the sample solutions are deployed. The P&P team have put together PowerShell scripts which take care of the usual things you'd find in a deployment scenario – stopping services, creating applications, adding resources and bindings.

In a Continuous Integration environment, you'd typically want to deploy to a BizTalk instance as part of the build process, to ensure the application configuration is valid, and as a prerequisite for running unit and integration tests. Currently I do this with MSBuild scripts using a variety of community, Sdc and custom tasks, and command-line tools. It makes for fragmented scripts that are difficult to read and maintain, and can be fragile to execute.

In the PowerShell version a central script isolates the complexity for common functions, and then the individual install scripts use a neat, readable and hugely intuitive syntax. This is a complete install script for one of the sample solutions (MultipleWebServices_install.ps1), which builds and then deploys the artifacts:

$relativePath = "..\.."

$samplesPath = $solutionPath+"\Samples\MultipleWebServices"

. ..\..\..\..\Core\Install\Scripts\ESBFunctions.ps1

function BuildItinerarySolution

{

param([System.String] $buildType)

&$FrameworkPath"\v3.5\MSBuild.exe" $relativePath"\GlobalBank.ESB.Samples.MultipleWebServices.sln" /t:Rebuild /p:Configuration=$buildType

}

BuildItinerarySolution Debug

StopBTSApplication "Microsoft.Practices.ESB"

StopBTSApplication "GlobalBank.ESB"

StopBTSServices

ImportBTSResource "GlobalBank.ESB" "BizTalkAssembly" $relativePath"\Source\ESB.MultipleWebServices.Maps\bin\Debug\ESB.MultipleWebServices.Maps.dll"

ImportBTSResource "GlobalBank.ESB" "BizTalkAssembly" $relativePath"\Source\ESB.MultipleWebServices.Orchestrations\bin\Debug\ESB.MultipleWebServices.Orchestrations.dll"

GacOperation "-if" $relativePath"\Source\ESB.MultipleWebServices.Maps\bin\Debug\ESB.MultipleWebServices.Maps.dll"

GacOperation "-if" $relativePath"\Source\ESB.MultipleWebServices.Orchestrations\bin\Debug\ESB.MultipleWebServices.Orchestrations.dll"

ImportBinding "GlobalBank.ESB" $relativePath\Install\Binding\GlobalBank.ESB.MultipleWebServices_Bindings.xml

StartBTSApplication "Microsoft.Practices.ESB"

StartBTSApplication "GlobalBank.ESB"

StartBTSServices

The common script (ESBFunctions.ps1) defines the main functions – ImportBTSResource etc. – so the logic in the individual scripts is very clean. Common functions make use of PowerShell commands, the BizTalk Explorer OM, BTSTask and custom tools as appropriate, so there's still a variety of tools under the covers, but the common script is a facade over them all. This makes the install scripts neater and abstracts them from the actual implementation of the functions. Below are snippets for the functions to stop and to remove a BizTalk application:

function StopBTSApplication

{

param([string]$appName)

$exp = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer

$exp.ConnectionString = $btsConnectionString

$app = $exp.Applications[$appName]

if($app -eq $null)

{

Write-Host "Application " $appName " not found" -fore Red

}

else

{

if($app.Status -ne 2)

{

#full stop of application

$null = $app.Stop(63)

$null = $exp.SaveChanges()

Write-Host "Stopped application: " $appName

}

function RemoveBTSApplication

{

param([string]$appName)

Write-Output "Removing BTS Application "+ $appName

BTSTask.exe RemoveApp /A:$appName

}

There's some complexity in these common functions, but they're all tried and tested by the Patterns & Practices team. This is a new approach for the ESB Guidance installs (v1.0 used a combination of batch files to deploy the samples), but I don't think there are any inherent dependencies on BTS 2009 so this approach and the common script should work for BTS 2006 solutions. I'm going to look at migrating my current build scripts to this approach as it's so much simpler to work with, and the execution doesn't rely on chaining together unrelated tasks in MSBuild.

The ESBG samples specifically name resources to deploy, whereas my current scripts run dynamically over whichever artifacts they find, but Bart De Smet has a nice MSBuild task for running PowerShell scripts, which takes parameters so that's one option, and generating PS scripts using the ExecuteT4Template task is another.

If I do get this running for BizTalk 2006 R2 solutions, I'll post a working set of sample scripts.

Creating Shortcuts in MSBuild

EltonStoneman — Sat, 25 Oct 2008 00:13:52 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

Windows shortcuts are .LNK files – a proprietary binary format which is not simple to generate. If you want to create shortcuts as part of an MSBuild deployment, the main issue is that the paths are not relative, they need to be explicit, so you can't create your own shortcuts and copy them. Alternatives are to create .URL or batch files containing relative paths, but they don't have the niceties of shortcuts.

You can generate .LNK shortcuts in MSBuild by shelling out to some VBScript at runtime, when you've deployed your files and know the exact paths. It's not a pretty solution, but it's fast and reliable. Create a .VBS file with the following content to generate a shortcut from given parameters:

'CreateShortcut.vbs

'Generates a .LNK shortcut to the specified program

'Usage: CreateShortcut.vbs <pathToExe> <exeName> <shortcutName>

Dim args, arg

Set args = WScript.Arguments

Dim workingDirectory, exeName, shortcutName

workingDirectory=args(0)

exeName=args(1)

shortcutName=args(2)

Dim WshShell

Set WshShell = WScript.CreateObject("WScript.Shell")

Dim objLink

Set objLink = WshShell.CreateShortcut("Shortcuts\" & shortcutName & ".lnk")

objLink.Description = shortcutName

objLink.TargetPath = workingDirectory & "\" & exeName

objLink.WindowStyle = 1

objLink.WorkingDirectory = workingDirectory

objLink.Save

Then call it from MSBuild after you've deployed the target file and know the path:

Points to note:

If you have any spaces in the arguments (C:\Program Files\etc) you need to wrap them in triple double-quotes ("""C:\Program Files\etc"""), otherwise each word is parsed as a separate argument in VBScript;
The friendly name of the shortcut can end in any extension – Windows hides the final .LNK , so if you specify a .EXE it will display as an EXE;
Shortcuts aren't limited to executables, if you pass a Word file as the exeName argument and end the shortcutName with .DOC, it'll launch the document in Word and show it with the Word icon in Explorer;
You have a lot of control over the link from the CreateShortcut call – including the startup window type, arguments and the icon. The example above is a straightforward one which just sets the minimum necessary.

ExecuteT4Template MSBuild task: Updated

EltonStoneman — Sat, 04 Oct 2008 14:14:31 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

As Cory pointed out, my original task to execute T4 templates under MSBuild (replacing property markers in the T4 script with evaluated values from the build, see: An MSBuild task to execute T4 templates), fails under MSBuild 3.5. This is down to a change in the object model in the framework. All the useful classes are internal and all the useful properties are private, so they have to be reflected over - which makes my code brittle.

I've updated the task as part of a set here: Sixeyed MSBuild tasks, and it now works with either MSBuild 2.0 or 3.5.

Another update will be coming soon, to allow you to use named item group values, as well as property values and whole item groups in the script. A script can be marked with %(Collection.Identity) and when the task is called iteratively over a collection, the script will be populated with the current collection value each time. I'm also planning to change it to use the T4 engine directly rather than invoking the TextTransform console app, to hopefully speed up the execution time.

I'm using this task increasingly in builds now. It's a lot neater than having multiple XML or Regex file updates, and the template can be used to isolate logic so the builds stay clean. Currently it's used to dynamically generate Wix scripts, generate BizTalk bindings file for a set of environments, generate documentation projects for Sandcastle Help File Builder and produce config files for running DevPartner code coverage. Some of those templates may be generically useful, so I'll add them to MSDN when I get to the next update.

Installing PDB files to the GAC with MSBuild

EltonStoneman — Thu, 18 Sep 2008 02:55:01 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

There are a couple of reasons why you might want PDB files available in the GAC, say if you're running coverage reports over unit tests as part of your CI build, and the assemblies being instrumented all live in the GAC, or if you want to deploy BizTalk PDB files as a troubleshooting aid. Patrick Cauldwell has a PowerShell script to install PDBs to the GAC, which is a good basis for an MSBuild task to do the same.

The principle is straightforward – find the "hidden" GAC directory where it the assembly is deployed and copy the PDB file there. Danger here is that the GAC structure may change, so the task uses AssemblyName.CodeBase which gives you the full path to the physical location, rather than determining it from the current format.

The main work is done here:

string pdbFilename = string.Format("{0}.pdb", Path.GetFileNameWithoutExtension(this.AssemblyPath));

string pdbPath = Path.Combine(Path.GetDirectoryName(this.AssemblyPath), pdbFilename);

//if source PDB is found:

if (File.Exists(pdbPath))

{

//get the strong name info from the assembly:

AssemblyName gacAssemblyName = Assembly.LoadFile(this.AssemblyPath).GetName();

string gacPath = this.GetGacPhysicalLocation(gacAssemblyName);

//if GAC location found:

if (!string.IsNullOrEmpty(gacPath))

{

//copy PDB file:

try

{

File.Copy(pdbPath, Path.Combine(gacPath, pdbFilename));

Log.LogMessage("Added PDB file to GAC: {0}, location: {1}", pdbFilename, gacPath);

}

//log other conditions...

Where AssemblyPath is the path to the un-GACd assembly where the PDB file is expected to be found (e.g. the build output directory):

</Target>

Full source code is here: MSBuild Task to Deploy PDB Files to GAC

Running BizTalkDocumenter under MSBuild

EltonStoneman — Wed, 10 Sep 2008 00:30:33 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The BizTalkDocumenter tool on CodePlex is great for generating help files describing your BizTalk application. It runs under the command line as well as having a Windows UI, but it's missing a command-line option for specifying a single BizTalk application to document (it defaults to documenting the whole BizTalk estate on the server).

If you want to document a single BizTalk application as part of your MSBuild process, two small modifications are needed to the class Microsoft.Sdc.BizTalkDocumenter.Form1:

ProcessArgs() – add a new case to the switch statement (before the default is processed):

case "/app":

case "/application":

documenter.Applications.Clear();

documenter.Applications.Add(argValue.ToString());

documenter.IncludeReferences = true;

documenter.PublishType = PublishType.SpecificApplication;

break;
GenerateDocumentation() – modify to use the default (CHM) publisher if none is specified:

if (executionMode == ExecutionMode.Interactive)

{

documenter.Publisher = DeterminePublisher(this.comboBox1.SelectedItem.ToString());

}

else if (documenter.Publisher == null)

{

documenter.Publisher = DeterminePublisher("Compiled Help");

}

To call in MSBuild, use the following target (specify "show" as false, otherwise it defaults to true and the help file will be displayed on the build server):

<Exec Command="$(BizTalkDocumenterPath)\Microsoft.Sdc.BizTalkDocumenter.exe

/o:$(PublishDocumentDir) /t:TheApplication /app:TheApplication /show:false"/>

</Target>

T4 template to generate Wix scripts to generate WCF MSIs in MSBuild

EltonStoneman — Thu, 04 Sep 2008 19:55:11 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

Snappy title. We have a project which contains lots of WCF Service projects, and we want to generate MSIs so we can deploy them to IIS. The gaps between the projects are minimal as they all use the same structure, so instead of having separate Setup or Wix files in each of the solutions, generating the WXS files on the fly was an option.

The installer steps we wanted were reasonably simple:

install WCF artifacts to the chosen directory (.svc and web.config files)
install WCF binaries to the chosen directory\bin
install dependencies to the GAC
create a virtual directory in IIS pointing to the install directory

The only UI we particularly needed was the choice of install directory, so the Wix for this fits into a fairly straightforward T4 template:

<#@ template language="C#" #>

<#@ output extension=".xml" #>

<#@ assembly name="System.dll" #>

<#@ import namespace="System.IO" #>

<#@ import namespace="System.Security.Cryptography" #>

<#@ import namespace="System.Text" #>

<?xml version="1.0" encoding="UTF-8"?>

<Product Id="<#= this.GetProductId() #>"

Name="<#= ServiceName #>"

Language="1033"

Version="<#= VersionNumber #>"

Manufacturer="Company"

UpgradeCode="<#= this.GetUpgradeCode() #>">

<Media Id="1" Cabinet="<#= ServiceName #>.Install.cab" EmbedCab="yes" />

<# foreach (string filePath in this.WcfArtifacts.Split(';'))

{

this.AddFile(filePath);

}#>

</Component>

<# int index = 0;

foreach (string assemblyPath in this.WcfDependencies.Split(';'))

{#>

<Component Id="GACComponent_<#= index++ #>" Guid="<#= this.GetNewGuid() #>" SharedDllRefCount="yes">

<# this.AddAssemblyToGAC(assemblyPath); #>

</Component>

<#}#>

<# this.AddAssembly(this.WcfAssembly); #>

</Component>

</Directory>

<iis:WebVirtualDir Id="WcfVirtualDir" Alias="<#= ServiceName.TrimEnd(".Wcf".ToCharArray()) #>" Directory="INSTALLLOCATION" WebSite="DefaultWebSite">

<iis:WebApplication Id="WcfApplication" Name="<#= ServiceName #>" />

</iis:WebVirtualDir>

</Component>

</Directory>

<iis:WebSite Id="DefaultWebSite" Description="Default Web Site">

<iis:WebAddress Id="AllUnassigned" Port="80" />

</iis:WebSite>

<Feature Id="ProductFeature" Title="<#= ServiceName #>" Level="1">

<# int i = 0;

foreach (string assemblyPath in this.WcfDependencies.Split(';'))

{#>

<# } #>

</Feature>

</Product>

</Wix>

<#+

private string ServiceName

{ get{ return "$(ProjectName).$(ProjectFilter)"; }}

private string VersionNumber

{ get{ return "$(Version)"; }}

private string WcfArtifacts

{ get{ return @"@(WcfArtifacts)"; }}

private string WcfAssembly

{ get{ return @"@(WcfAssembly)"; }}

private string WcfDependencies

{ get{ return @"@(WcfDependencies)"; }}

…

- the full template is here: WCF Service Wix template.

A couple of interesting things here – the Guids are generated from the name of the elements (see Generating Deterministic Guids), so multiple versions will have the same Guid and will operate as updates, provided the name of the service doesn't change; the tags for MSBuild properties in the template get resolved using the ExecuteT4Template MSBuild task; the GACd assemblies flag themselves as SharedDllRefCount so if you uninstall this package, the files will be left in the GAC if any other packages use them, but removed if this is the only package that uses them.

Another custom task is needed to resolve the dependencies of the WCF assembly (sample version here: MSBuild ResolveDependencies task), and the MSBuild snippet to run it together with the Wix commands looks like this:

<ResolveDependencies AssemblyList="@(WcfAssembly)"

Filter="$(CompanyName).$(ProductName)">

</ResolveDependencies>

</Target>

<ExecuteT4Template ToolPath="$(MSBuildProjectDirectory)\$(BuildBinDir)"

TemplatePath="$(TemplateRoot)\Services.Wcf.wxs.tt"

OutputPath="$(ArtefactWixDir)\$(ProductName).$(ProjectName).Wcf.wxs">

</ExecuteT4Template>

</Target>

- we store all the intermediate files (the T4 template with resolved property values, WXS and WIXOBJ files) to help with debugging.

An MSBuild Task to run C# code

EltonStoneman — Wed, 03 Sep 2008 03:31:21 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

MSBuild is lacking in handy functions. You can check if a path exists and list the contents of a directory, but everything else has to be achieved with a task. You often find yourself choosing between clumsily stringing together tasks or writing a custom task to perform a specific function – even a simple one.

Rather than putting together a function library, I've got one simple task which takes C# code as a parameter and executes it. The code can consist of one or more statements, can read the runtime values of properties or item groups in the build, and returns a string output (currently it expects last the code statement to be like return x.ToString()).

So if you want to prefix text to a property, get the ticks of the current time or get a valid temporary file name, you can do it like this:

</CodeExecutor>

</Target>

</CodeExecutor>

</Target>

</CodeExecutor>

</Target>

The task doesn't do anything complicated; it builds a class at runtime by injecting the code statements passed to it into a T4 template (as with the T4 task, in its current form it uses the TextTransform.exe tool), compiles it in memory with CodeDom and executes a static method which now contains the code statements.

You can pass it directives if your code uses anything more exotic than System, System.Collections.Generic etc, and give it the path to any existing assemblies the code needs to reference. I'll add it as part of a set of build tasks to CodePlex but until then the code for the task is here: MSBuild CodeExecutor task.

Wix error -532459699

EltonStoneman — Fri, 25 Jul 2008 20:43:14 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

Running Wix 3.0.2420.0 I got an "object reference not set" and this error message when calling light.exe from an Exec MSBuild task:

The command ""..\bin\Wix\light" -out "c:\x\y\z\x.y.z.msi" "c:\x\y\z\x.y.z.wixobj" -ext WixIIsExtension -ext WixUiExtension -cultures:en-us" exited with code -532459699.

Annoyingly, I could run the exact same command in a command prompt immediately after the build failed, and it worked fine - and this error only happened on the build server and not on the dev boxes.

Before diving into it too much, I updated to the latest version of Wix (currently 3.0.4318.0) and the problem went away. So that solved that issue and just left me with "should we be using beta software even if it works for everything we need at the moment"…

An MSBuild task to execute T4 templates

EltonStoneman — Fri, 25 Jul 2008 18:54:23 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

I was looking for an MSBuild task which could execute a T4 template, replacing tags in the template with the value of properties or item groups from the build - giving your T4 templates access to all the runtime values used in the build scripts. So you start with a T4 template like this:

<#@ template language="C#" #>

<#@ output extension=".txt" #>

<#@ assembly name="System.dll" #>

***START

Property value: StartDir= $(StartDir)

Item Group value: TextFiles = @(TextFiles)

***END

- execute it through a call to ExecuteT4Template in your build target:

</PropertyGroup>

</ItemGroup>

</Target>

- and it produces the following output:

***START

Property value: StartDir= C:

Item Group value: TextFiles = \zeros.txt

***END

There wasn't one that I could find so I put a simple one together. A couple of fiddly things worth noting if you do something similar:

the project's property values are not exposed to the executing task in an accessible way, so you have to reflect around BuildEngine to get hold of the executing project;
if you don't want to write an ITextTemplatingEngineHost or rely on a GAX or other host, you'll end up shelling out to TextTransform.exe (as I have).

Full source for the task is here: ExecuteT4Template.cs (note this uses version 1.1 of the TextTransform tool).

A couple of things to note: this task will update all instances of property and item tags in the template - $(propertyName) or @(itemGroupName) (it's not clever enough to deal with %(itemGroupName.ValueName))- with the value from MSBuild, if the named property/item group exists in the project. Potentially you may want to leave certain tags in place in the template, in which case you'll need to ensure there are no matching properties in the build, or extend the task to take a list of names to ignore.

Also, if you're using a value in your script which is the output from another task, then the task which produces the output must be in a separate target which completes before the call to ExecuteT4Template. MSBuild seems only to store properties/item groups from task outputs when targets are completed, so if the output is created in the same target as the T4 task, the property won't be registered and the tag in the template won't be replaced.

I have a couple of other tasks which all relate to deploying BizTalk and ESB Service Providers, so I'll add them to the ESBSimpleSamples CodePlex project along with this one.

Deploying Pipeline Components in a CI Build

EltonStoneman — Fri, 25 Jul 2008 14:52:34 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

Most of the interfaces you implement for a pipeline component are boilerplate code, so I tend to put them in a base class and just override what's needed. If the base class is in a separate assembly from other pipeline components, and you're using a CI build process to build them all, you may have an issue getting your subsequent pipeline projects to build.

In a typical MSBuild script, I'll get the projects from the solution file(s), and then:

build the C# projects with MSBuild
copy any pipeline component assemblies to Program Files\Microsoft BizTalk Server 2006\Pipeline Components
shell out to devenv for the BizTalk projects
GAC all the C# and BTS assemblies

When the application is packaged up, all the assemblies will go in the GAC but on the build server, I was getting failures building the pipeline projects, with: error BTP0004: Component 'x.y.z.Decoder' could not be initialized. Pipeline component 'x.y.z' could not be resolved (is an assembly reference missing?).

It turns out the library with the pipeline component base class wasn't being found. Using fuslogvw it seems when devenv builds the pipeline project, it looks in the Pipeline Components folder and finds the component, but when it looks for the base class library, it looks in two other places:

Program Files\Microsoft BizTalk Server 2006\Developer Tools
Program Files\Microsoft Visual Studio 8\Common7\IDE

If you don't want to put your pipeline component assembly and its dependencies in the GAC before building the BizTalk projects, this MSBuild snippet copies them to the relevant places:

<PipelineComponents Include="$(BuildOutputDir)\**\x.y.*.PipelineComponents.dll"

Exclude="$(BuildOutputDir)\**\x.y.*.Test.dll"/>

</ItemGroup>

</ItemGroup>

</Target>