BizTalk 2009

Using PowerShell in BizTalk Post-Processing Scripts

EltonStoneman — Mon, 08 Jun 2009 20:58:18 GMT

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

Often in BizTalk deployments you need to do additional work after installation. Typically your full install process may need to:

Install BizTalk artifact assemblies to the GAC
Install application dependencies to the GAC
Register an application source name in the registry, for logging to the Event Log
Create FILE send or receive locations on the local filesystem
Add application store configuration settings to Enterprise Single Sign-On (SSO)
Add log4net configuration settings to BTSNTSvc.exe.config

You can achieve this with a single BizTalk installer by configuring resources and post-processing scripts, and exporting an MSI from the application. Various scripting languages are supported in BizTalk installations (batch files, VBScript etc.), except the most logical – PowerShell, which gives first-class support for the filesystem, the registry, XML files and .NET objects. You can still use PowerShell by including scripts as resources, and using a batch file as the post-processing script, which acts as a harness to call the PowerShell scripts.

This walkthrough addresses all the points above. The completed BizTalk application is on MSDN Code Gallery here: BizTalk PowerShell Deployment Sample – import and install the MSI to deploy with the PowerShell script, or browse the ZIP file to see the scripts and resources.

1. Install BizTalk artifact assemblies to the GAC

This is straightforward, set the resource option "Add to the global assembly cache on MSI file install" to true – this happens by default if you add a BizTalk Assembly resource in the Administration Console:

Using the command line though, this is not the default option so you need to explicitly set –Options:GacOnInstall in BTSTask:

btstask AddResource

-ApplicationName:PowerShellSample

-Type:BizTalkAssembly

-Options:GacOnInstall

-Source:PowerShellSample.Schemas.dll

-Destination:%BTAD_InstallDir%\PowerShellSample.Schemas.dll

2. Install application dependencies to the GAC

As 1), except the resource type is System.BizTalk:Assembly (in BTSTask you can omit "System.BizTalk"). The command requires the same flag to add to the GAC on install:

btstask AddResource

-ApplicationName:PowerShellSample

-Type:Assembly

-Options:GacOnInstall

-Overwrite

-Source:.\Dependencies\SSOConfig.dll

-Destination:%BTAD_InstallDir%\Dependencies\SSOConfig.dll

In this case, I'm installing the SSOConfig assembly (from SSO Config Tool) which provides static .NET classes for accessing the SSO application configuration store. The Overwrite flag is set in case the resource already exists in another application.

3. Register an application source name in the registry, for logging to the Event Log

To log to the Application event log with your own source name, you need to add a registry key with the app name, and the name of the handler:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\PowerShell.Sample

In PowerShell, this is done in using the New-Item cmdlet to create the key, and New-ItemProperty to set the key value:

New-Item -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\Eventlog\Application\PowerShellSample' -Force

New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\Eventlog\Application\PowerShellSample' -Name 'EventMessageFile' -PropertyType ExpandString -Value 'C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\EventLogMessages.dll' –Force

(HKLM: is a PowerShell drive mapped to HKEY_LOCAL_MACHINE, and the –Force flag overwrites existing values).

To execute the PowerShell script on install, we need a batch file which BizTalk can run as a post-processing script. The batch file is very simple, just separating install and uninstall logic to individual PowerShell scripts, and redirecting script output to a log file:

cd "%BTAD_InstallDir%\Deployment"

if "%BTAD_InstallMode%" == "Install" ( powershell ".\PowerShellSample.Install.ps1" >> PowerShellSample.Install.ps1.log )

if "%BTAD_InstallMode%" == "Uninstall" ( powershell ".\ PowerShellSample.Uninstall.ps1" >> PowerShellSample.Uninstall.ps1.log )

Both the CMD and PS1 files need to be added as resources to the BizTalk application. The PS1 files are of type BizTalk:File, and the CMD harness is of type BizTalk:PostProcessingScript:

btstask AddResource

-ApplicationName:PowerShellSample

-Type:File

-Source:.\Deployment\PowerShellSample.Install.ps1

-Destination:%BTAD_InstallDir%\Deployment\PowerShellSample.Install.ps1

btstask AddResource

-ApplicationName:PowerShellSample

-Type:PostProcessingScript

-Source:.\Deployment\PowerShellSample.PostProcessing.cmd

-Destination:%BTAD_InstallDir%\Deployment\PowerShellSample.PostProcessing.cmd

4. Create FILE send or receive locations on the local filesystem

If you need to create static file locations, the same New-Item cmdlet is used with the filesystem provider. Specify the full path for the directory and any intermediate directories will be created if they don't exist. Use the –Force flag to suppress warnings if the directory already exists:

New-Item –Path 'c:\receiveLocations\x\y\z' -ItemType Directory –Force

Note that the resources in the BizTalk application are copies rather than references, so if you modify your PS1 files, you'll need to update the resource (in the Administration Console, select the resource and use Modify... Refresh, or re-run the BTSTask command).

5. Add settings to Enterprise Single Sign-On (SSO)

If you're using SSO to store group-wide application config, you can create or export an XML file of the settings using SSO Config Tool. We add the .ssoconfig file as a File resource to the application, then in the install script use PowerShell to call a .NET method to import the settings using the SSOConfig.SSOApplication class. The SSOConfig assembly is a resource which has already been deployed to the GAC by this point in the installation:

[Reflection.Assembly]::Load('SSOConfig, Version=1.1.0.0, Culture=neutral, PublicKeyToken=656a499478affdaf')

$configPath = [IO.Path]::Combine($env:BTAD_InstallDir, 'Deployment\PowerShellSample.ssoconfig')

$app = [SSOConfig.SSOApplication]::LoadFromXml($configPath)

$app.SaveToSSO()

Note that the PowerShell script has access to all the environment variables set by BizTalk on the install – accessed by prefixing $env: to the variable name, as we do here to get the installation directory from the installer ($env:BTAD_InstallDir).

6. Add settings to BTSNTSvc.exe.config

Modifying XML is straightforward in PowerShell. We want to configure an Event Log appender in the BizTalk service config file by adding the following XML:

</configSections>

</layout>

</appender>

<appender-ref ref="Sixeyed.CacheAdapter.EventLogAppender" />

</logger>

</log4net>

The Get-ItemProperty cmdlet can read the BizTalk install path from the registry, then Get-Content reads the file – casting it to XML for subsequent processing:

$installPath = Get-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\BizTalk Server\3.0' -Name 'InstallPath'

$btsConfigPath = [IO.Path]::Combine($installPath.InstallPath, 'BTSNTSvc.exe.config')

$xml = [xml] (Get-Content $btsConfigPath)

On a fresh install, the config file is quite bare and doesn't include a <configSections> element, so in that case we need to add both <configSections> and <log4net> nodes. We can't guarantee that other solutions haven't already modified the config file though, so <configSections> may exist, and <log4net> may also exist – in which case, we just need to add our specific appender and logger values (log4net allows you to define multiples of these in config, and we specify names which we can expect to be unique).

To achieve this, the script checks for each element first, creates it if it doesn't exist, then adds the specific settings:

$configSections = $xml.SelectSingleNode('configuration/configSections')

if ($configSections -eq $null)

{

$configSections = $xml.CreateElement('configSections')

$firstChild = $xml.configuration.get_FirstChild()

$xml.configuration.InsertBefore($configSections, $firstChild)

}

$log4netSection = $configSections.SelectSingleNode('section[@name="log4net"]')

if ($log4netSection -eq $null)

{

$log4netSection = $xml.CreateElement('section')

$log4netSection.SetAttribute('name', 'log4net')

$log4netSection.SetAttribute('type', 'log4net.Config.Log4NetConfigurationSectionHandler, log4net, Version=1.2.10.0, Culture=neutral, PublicKeyToken=1b44e1d426115821')

$configSections.AppendChild($log4netSection )

}

...

Finally the updates are saved over the original file:

$xml.Save($btsConfigPath)

Limitations

The main limitation with any post-processing script, is that the target environment selected for the install is not available. If you have multiple bindings files, the environment selected at runtime is only alive for the duration of the MSI import – the install has no reference to it, and there's no record made in the management database (not that I can see, please correct me if there is). This means you can't switch your script based on environment (e.g. to use different SSO config settings for System Test and Production). If that's a serious restriction you may prefer to create different MSIs per-environment in your build process, each containing the correct bindings file and scripts.

Specific to this approach, you need to have PowerShell installed on all the target machines, and configured to allow script execution (by default, scripts are not permitted to execute, as a security measure). Hopefully this is becoming the norm. Security also needs to be considered – the sample app writes to the registry and to SSO, so the installing context needs to have explicit permissions. The BizTalk installer runs under a separate security context from the installing user (by a trial-and-error process, this is NT AUTHORITY\ANONOYMOUS LOGON in my Server 2003 VM), so if you're amending SSO you'll need to set your SSO Administrators group membership correctly.

Benefits

The completed PowerShell scripts should be straightforward to read and maintain. All the post-installation requirements are implemented using a single technology, and many of the functions are reusable and could easily be parameterised and moved to a central script. The script is easy to test outside of the installer runtime, either manually using a batch file as a test harness (which sets up the relevant environment variables and then calls the post-processing file), or worked into an automated unit test.

The approach is not limited to BizTalk installations, so similar tasks for .NET deployments which are currently done with custom assemblies or Wix script can be isolated in the same way. With BizTalk and .NET installs using the same technology, you'll build up a library of high-quality, reusable PowerShell scripts.

I also like having the scripts deployed as part of the install, so in combination with the log files, you can see exactly what's been done to your environment and modify if necessary.

Extensions

With native cmdlets and community scripts, together with WMI, XML and .NET code, you can achieve any desired functionality with PowerShell scripts, and have them rapidly developed and tested. So you can easily add code to update version numbers in config files, remove your assemblies from the GAC on uninstall, access performance counters etc. And PowerShell scripts are just plain text so you can extract them into a T4 template and generate different scripts for different environments in your build process.

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.

BizTalk Server 2009 Public Beta: First Look

EltonStoneman — Wed, 10 Dec 2008 06:11:39 GMT

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

The first public beta of BizTalk Server 2009 was released yesterday, and fulfils expectations by falling in line with the 2008 server and development stack, and offering a few functional extras. I've had a quick run through of it and made some initial notes below. The MSBuild integration is interesting although I haven't got a good grasp yet on whether it will replace custom MSBuild tasks to aid deployment; apparently it works nicely with TFS, but I've yet to see what's on offer.

I've installed this in accordance with the installation instructions available with the beta download, running on Windows Server 2008 Standard + SQL Server 2008 Developer, with Office 2007, WSS 3.0 and Visual Studio 2008 SP1. I started from scratch with an empty VM as I wanted to try out VirtualBox (Sun's VM acquisition which has free personal use, commercial licensed and open source flavours) as Nick Heppleston's been championing it recently and it's impressive – so I finish with a few notes on that.

Installation

Same process as BTS 2006 – install pre-requisites, install BTS, configure BTS
I had issues with auto-downloading the pre-requisites, so I downloaded the cab separately from the link in the install doc (e.g. http://go.microsoft.com/fwlink/?LinkId=81432 for 32-bit EN)
BAM and the SharePoint Adapter failed configuration, but I haven't investigated that yet

UDDI Services

A separate install option from the BTS setup.exe (as with RFID), following the install then configure model
Allows SQL Server instance for UDDI database to be specified (no more nasty hacking required to get the UDDI database on a remote SQL cluster)
UDDI Services are completely separate from BizTalk and have no integration with the BizTalk toolset (again, like RFID). A simple case of UDDI Services being bundled with the BTS product now rather than Windows Server
Very similar Web application and Web service interfaces are provided
New notification/subscription mechanism to register for alerts on changes to UDDI entries
Extended command tools provided – including a migration tool (presumably to migrate from UDDI Services 2003)

BizTalk Administration Console

Most noticeable difference is that the UI loads asynchronously now, so the lists are populated piecemeal rather than blocking the UI while the whole list is loaded – makes for a much more responsive feel
The artifact folders now have nice icons:

Still can't delete default application "BizTalk Application 1"

MSBuild

BTPROJ files are now in MSBuild format
Specific tasks to compile individual artifacts – XlangTask, SchemaCompiler, MapperCompiler, PipelineCompilerTask
- In Developer Tools\Microsoft.VisualStudio.BizTalkProject.BuildTasks.dll
Tasks referenced in .btproj via BizTalkC.targets and BizTalkCommon.targets
- Built in two passes, first pass builds: schemas, maps, pipelines; second pass builds orchestrations
VSDEPLOY output shown in Deploy from VS
- Deployment properties (application name, BTS database and server) held in BTPROJ.USER file

Visual Studio 2008

BizTalk projects currently shown with C# project icon (presumably to change)
Artifact designers and generators unchanged (that I can see)
Project Properties are now in standard VS format
- Additional Deployment tab for specific BTS settings
- Signing now standard with New/Add key file (no more ..\..\..\)
CodeAnalysis can be run within Visual Studio for BizTalk projects
- No specific BizTalk rules (potential for integrating BizTalkCop to Visual Studio)
- If you enable analysis & exclude generated code, the BizTalk generated code still triggers warnings
- You can run code metrics – although it includes generated code (an empty orchestration has 114 lines of code and a cyclomatic complexity of 50…)
Performance of the IDE is much better, in line with .NET development in VS 2008
Maps still run off compiled schema references, so a change in schema needs a recompile before the map reflects the change

Health and Activity Tracking

According to the release notes, HAT is no more: "The stand-alone Health and Activity Tracking (HAT) tool has been removed from BizTalk Server 2009"
The exe is still installed, but there's no shortcut to it on the Start menu and the exe won't run without the right parameters being passed
HAT is still mentioned in the Help documentation – although that's stated as subject to change

VirtualBox

Very performant, fast to use and to save & restore state
Reliable, intuitive, has some nice touches (recording a list of mapped ISO images is handy)
Differencing disk model is unusual – you can take snapshots and "merge" the disk by deleting earlier snapshots, but there's no obvious way of building a cumulative stack of differenced disks
No drag/drop integration with Windows which would have been good for file copying
Folder share approach (defines network share accessed as \\vbsrv\folderName) different from VPC; shares don't show in explorer, but this is more scalable (no drives mapped) and is a usable approach

So a very positive response for VirtualBox (especially as the open source version has the majority of the functionality from the other versions), slightly more muted for BTS 2009 which isn't providing any great leaps forward. The ESB Guidance 2.0 alpha is also out and has an interesting list of changes and additions, so I'll post a first look on that soon.

UPDATE: Richard Seroter's published a similar first look here; he's picked up on additional enhancements, so worth a look.