by community-syndication | Jun 8, 2009 | BizTalk Community Blogs via Syndication
[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>
<section name=”log4net” type=”log4net.Config.Log4NetConfigurationSectionHandler, log4net, Version=1.2.10.0, Culture=neutral, PublicKeyToken=1b44e1d426115821″ />
</configSections>
<log4net>
<appender name=”Sixeyed.CacheAdapter.EventLogAppender” type=”log4net.Appender.EventLogAppender, log4net, Version=1.2.10.0, Culture=neutral, PublicKeyToken=1b44e1d426115821″>
<param name=”LogName” value=”Application”/>
<param name=”ApplicationName” value=”Sixeyed.CacheAdapter”/>
<layout type=”log4net.Layout.PatternLayout”>
<conversionPattern value=”%date [%thread] %logger %level – %message%newline” />
</layout>
</appender>
<logger name=”Sixeyed.CacheAdapter.Log”>
<level value=”WARN” />
<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.
by community-syndication | Jun 7, 2009 | BizTalk Community Blogs via Syndication
Cross-posted from the Silverlight Web Services Team Blog.
Silverlight 3 Beta introduces a new way to improve the performance of web services. You have all probably used the Silverlight-enabled WCF Service item template in Visual Studio to create a WCF web service, and then used the Add Service Reference command in your Silverlight application project in order to access the web service. In SL3, the item template has undergone a small change that turns on the new binary message encoder, which significantly improves the performance of the WCF services you build. Note that this is the same binary encoder which has been available in .Net since the release of WCF, so all WCF developers will find the object model very familiar.
The best part is that this is done entirely in the service configuration file (Web.config) and does not affect the way you use the service. (Check out this post for a brief description of exactly what the change is.)
I wanted to share some data that shows exactly how noticeable this performance improvement is, and perhaps convince some of you to consider migrating your apps from SL2 to SL3.
When Silverlight applications use web services, XML-based messages (in the SOAP format) are being exchanged. In SL2, those messages were always encoded as plain text when being transmitted; you could open a HTTP traffic logger and you would be able to read the messages. However using plain text is far from being a compact encoding when sending across the wire, and far from being fast when decoding on the server side. When we use the binary encoder, the messages are encoded using a WCF binary encoding, which provides two main advantages: increased server throughput and decreased message size.
Increased server throughput
Let’s examine the following graph (hat tip to Greg Leake of StockTrader fame for collecting this data). Here is the scenario we measure: the client sends a payload, the server receives it and sends it back to the client. Many clients are used to load the service up to its peak throughput. We run the test once using the text-based encoding and once using the new binary encoding and compare the peak throughput at the sever. We do this for 2 message sizes: in the smaller size the payload an array with 20 objects, and in the bigger one the payload is an array with 100 objects.
Some more details for the curious: The service is configured to ensure no throttling is happening, and a new instance of the service is created for every client call (known as PerCall instancing). There are ten physical clients driving load, each running many threads hitting service in tight loop (but with small 0.1 second think time between requests) using a shared channel to reduce client load. The graph measures peak throughput on the service at 100% CPU saturation. Note that in this test we did not use Silverlight clients but regular .Net clients. Since we are measuring server throughput it is not significant what the clients are.
When sending the smaller message we see a 24% increase in server throughput, and with the larger message size we see a 71% increase in server throughput. As the message complexity continues to grow, we should see even more significant gains from using the binary encoder.
What does that mean to you? If you run a service that is being used by Silverlight clients and you exchange non-trivial messages, you can support significantly more clients if the clients use SL3’s binary encoding. As usage of your service increases, that could mean being able to save on buying and deploying extra servers.
Decreased message size
Another feature of the binary encoder is that since messages sent on the wire are no longer plain-text, you will see a reduction in their average size. Let’s clarify this point: the main reason you would use the binary encoding is to increase the service throughput, as discussed in the previous section. The decrease in message size is a nice side-effect, but let’s face it: you can accomplish the same effect by turning on compression on the HTTP level.
This test was far less comprehensive than the previous one and we did it ad-hoc on my co-worker’s office machine. We took various objects inside a Silverlight control, and turned them into the same kind of SOAP messages that get sent to the service. We did this using the plain-text encoding and using binary encoding and then we compared the size of the messages in bytes. Here are our results:
The takeaway here is that the reduction of message size depends on the nature of the payload: sending large instances of system types (for example a long String) will result in a modest reduction, but the largest gains occur when complex object graphs are being encoded (for example objects with many members, or arrays).
What does this mean to you? If you run a web service and you pay your ISP for the traffic your service generates, using binary encoding will reduce the size of messages on the wire, and hopefully lower your bandwidth bills as traffic to your service increases.
Conclusion
We are confident that binary encoding is the right choice for most backend WCF service scenarios: you should never see a regression over text encoding when it comes to server throughput or message size; hopefully you will see performance gains in most cases. This is why the binary encoder is the new default in the Silverlight-enabled WCF Service item template in Visual Studio.
An important note: binary encoding is only supported by WCF services and clients, and so it is not the right choice if you aren’t using WCF end-to-end. If your service needs to be accessed by non-WCF clients, using binary encoding may not be possible. The binary AMF encoding used by Adobe Flex is similarly restricted to services that support it.
