BizTalk Deployment

Managing Migration of Your BizTalk Apps

Daniel Toomeypresenter

Scope

Not about BizTalk Server product/platform installation

BizTalk Application/Solution deployment BizTalk Server 2006+ only Key concepts & principles Out-of-the-Box tools only

BizTalk Deployment Artefacts Assemblies:

BizTalk Assemblies (maps, schemas, orchestrations, pipelines) .NET Helper Assemblies

Physical Bindings (send/receive ports) Runtime Components:

Hosts / Host Instances Handlers

Database Scripts Rules & Policies Configuration Files COM Components BAM definitions BAS Artefacts (partner profiles, templates, etc) Security Certificates Virtual Directories Custom / Third-Party Adapters

BizTalk Applications

Introduced in BizTalk Server 2006 Logical container for a collection of related

solution artefacts Facilitates application level:

Deployment (export MSI) Start / Stop Resource management Dependencies

DEFAULT: BizTalk Application 1

BizTalk Applications

Binding Files

Describe BTS artefacts stored in the BizTalk Mgmt Database and their relationships

Exportable / Importable from BizTalk Group or Application

Represented in XML How to validate binding schema:

xsd.exe "C:\Program Files\Microsoft BizTalk Server 2006\Microsoft.BizTalk.Deployment.dll" /type:BindingInfo

Sample binding file:C:\Program Files\Microsoft BizTalk Server 2006\SDK\Samples\ ApplicationDeployment\CreateApp\Bindings\CreateApplicationSampleBindings.xml

Binding File Structure

ModuleRefCollection: Declares all the BizTalk assemblies and orchestrations used within the application. It also specifies which physical ports are used for each orchestration.

SendPortCollection: Contains all the information necessary to create or update all the send ports.

DistributionListCollection: Contains all the information necessary to create or update all the distribution lists (send port groups).

ReceivePortCollection: Contains all the information necessary to create or update all the receive ports and receive locations.

PartyCollection: Contains all the information necessary to create or update all the parties.

Importing Binding Files

Binding Files will create: Send Ports Receive Ports Receive Locations Parties

Binding Files will not create: Host Definitions Host Instances Directory Structures Passwords for credentials

Processing Scripts

Can be bundled within an MSI file Automatically run when importing, installing, or

uninstalling a BizTalk application Two types:

Pre-processing (run at beginning of import/installation process)

Post-processing (run at end of import/installation process) Multiple script types supported:

.bat, .cmd., .com, .exe, .vbs, .vbe, .js, .wsh, .wsf Any action that can be done in a script can be executed

within the exported MSI*

*excluding certain BTSTask commands during application import

Processing Scripts

Ideal tasks for a processing script: Create directory structure Add assemblies to the GAC Register COM components Create/populate a database Install a config file

Sample scripts:C:\Program Files\Microsoft BizTalk Server 2006\ SDK\Samples\ApplicationDeployment\Template\

Processing Scripts Use environment variables to control execution:

%BTAD_InstallMode% Create Update

Delete %BTAD_ChangeRequestAction%

Import Install Uninstall

Example:

REM ### Create directories prior to BizTalk assembly deploymentif "%BTAD_InstallMode%"=="Install" AND "%BTAD_ChangeRequestAction%"=="Update“(

REM ### Create the folders which will drop messagesmkdir %BTAD_InstallDir%\TestDocuments\In\mkdir %BTAD_InstallDir%\TestDocuments\Out\

)

Environment Variables

Deployment States

BTAD_ChangeRequestAction Values

BTAD_InstallMode Values

BTAD_HostClass Values

Import without overwrite flag

Create Import ConfigurationDb

Import with overwrite flag

Update Import ConfigurationDb

Install Update Install BizTalk Host Instance

Uninstall Delete Uninstall BizTalk Host Instance

Import Rollback

Delete Import ConfigurationDb

Install Rollback

Delete Install BizTalk Host Instance

Import vs. Install

STEP ONE: Import Import application to BizTalk Group Registers components in BizTalkMgmtDb Covers all BizTalk servers in group

STEP TWO: Install Must be performed on each machine in the

BizTalk Group Installs physical copies of registered

components GAC, COM, Certificates, Virtual Directories

Typical Manual Install Steps

Create an application Add references (optional) Add assemblies Create Receive Ports Create Receive Locations Create Send Ports Configure application Start application

Typical Deployment Cycle

SOURCE SERVER: Deploy solution from Visual Studio Configure the BizTalk application Export bindings Add artefacts to the application Export application to MSI file

TARGET SERVER: Import the MSI file Install the MSI file Start the application and test it

Visual Studio Deployment Steps

In Visual Studio 2005: In Project Properties, specific BizTalk Application name Choose “Deploy” from Solution file

In BizTalk Admin Console: Create Receive Ports Create Receive Locations Create Send Ports Configure application (bindings) Start application

Re-deployment from VS usually maintains configuration, assuming same version number

Exporting a BizTalk Application

Export the Bindings From BizTalk Admin Console Right-click app choose “Export Bindings…” Save multiple copies Edit each copy in an XML editor (environment

specific settings) Binding files can be added to application as

resources (next slide) Copies can be given a target environment

label (e.g. “TEST”, “PROD”)

Exporting a BizTalk Application

Add resource files From BizTalk Admin Console Right-click app choose “Add Resources…” Choose resource type:

Assembly (BizTalk or .NET helper) Binding (can specify target environment) Pre/Post-Processing Script BAM File COM (can choose to register)

“Overwrite all…” – replaces version in GAC

Exporting a BizTalk Application

Export the MSI From BizTalk Admin Console Right-click app choose “Export MSI file…” Step through the wizard Choose/Specify:

Resources (assemblies, bindings) IIS Hosts Dependencies (specified for you) Destination

Importing/Installing a BizTalk Application Import the MSI

From BizTalk Admin Console Right-click app choose “Import MSI file…” Step through the wizard Choose/Specify:

Application name Overwrite resources Environment (for binding files)

Adds references/component/binding files to BizTalk Management DB

Only need to do this once for BizTalk Group

Importing/Installing a BizTalk Application Install the MSI

Double-click the MSI file itself (Windows Explorer)

Step through the wizard Choose/Specify:

Application name Overwrite resources Environment (for binding files)

Adds physical components to current machine Need to do this on each server in the BizTalk

Group

Command Line Import/Install

Import:

BTSTask ImportApp /Package:C:\SampleApp.msi /Environment:TEST /ApplicationName:“SampleAppName" /Overwrite

Install:

msiexec /i “C:\SampleApp.msi" /passive /log “C:\SampleApp.log”

What’s Missing??

Creating hosts / host instances Modifying host / host instance properties Starting / Stopping host instances Creating send/receive handlers Adding Message Boxes Modifying Message Box properties

The Answer?? ExplorerOM WMI BTSTask

ExplorerOM

BizTalk Explorer Object Model Set of .NET classes/interfaces providing API

to the BizTalk Management Database Add reference:

[BizTalk Installation directory]\Developer Tools\Microsoft.Biztalk.ExplorerOM.dll

Three container classes: BtsCalalogExplorer BtsApplication Assembly

What Can You Do With ExplorerOM?

Create / modify / delete Applications Browse orchestration artefacts Bind / enlist / start orchestrations Stop / unenlist / unbind orchestrations Add / enlist / start send & receive ports Stop / unenlist / delete send & receive ports Add / remove maps for inbound / outbound

transformations Enable / disable receive locations Add / delete parties

BtsCatalogExplorer Class

Fundamental class: provides access to the BizTalk Management Database

All BizTalk artefacts within a group are accessible once this class is instantiated

Must set the ConnectionString property on the instance

Enumerate Send Ports Sampleusing System;using System.Text;using Microsoft.BizTalk.ExplorerOM;

namespace SendPorts{

class Program{

static void Main(string[] args){

EnumerateSendPorts();Console.ReadKey();

}

public static void EnumerateSendPorts(){

BtsCatalogExplorer catalog = new BtsCatalogExplorer();catalog.ConnectionString =

"Server=.;Initial Catalog=BizTalkMgmtDb;Integrated Security=SSPI;";foreach (SendPort sendPort in catalog.SendPorts ){

Console.WriteLine("\tPortName:{0},Status:{1}",sendPort.Name ,sendPort.Status);

}}

}}

BtsCatalogExplorer Methods

Method Name Description

AddNewApplication* Creates and adds a new Application object to the Application collection.

RemoveApplication* Removes the specified application from Application collection.

AddNewParty Creates and adds a new Party object to the Parties collection.

RemoveParty Removes the specified party from the Parties collection.

AddNewReceivePort Creates and adds a new ReceivePort object to the ReceivePorts collection.

RemoveReceivePort Removes the specified receive port from the ReceivePorts collection.

AddNewSendPort Creates and adds a new SendPort object to the SendPorts collection.

RemoveSendPort Removes the specified send port from the SendPorts collection.

AddNewSendPortGroup

Creates and adds a new SendPortGroup object to the SendPortGroups

RemoveSendPortGroup

Removes the specified send port group.

SaveChanges Commits all BtsCatalogExplorer object changes to the Management Database.

DiscardChanges Discards all BtsCatalogExplorer object changes.

*Specific to BizTalk Server 2006.

Application Class

Similar to BtsCatalogExplorer class, but specific to an application

Allows you to start, stop applications Allows you to add & remove references to

other applications Requires reference to an instance

ApplicationStartOption Enumeration

Enumeration Value Description

DeployAllPolicies Specifies all policies to be deployed

EnableAllReceiveLocations

Specifies all receive locations to be enabled

StartAllOrchestrations Specifies all orchestrations to be started

StartAllSendPortGroups Specifies all send port groups to be started

StartAllSendPorts Specifies all send ports to be started

StartReferencedApplications

Specifies all referenced applications to be started

StartAll Specifies all of the preceding to be enabled and started

Application app = catalog.Applications[“My Application"]app.Start(StartApplicationOptions.StartAll);

WMI Script

Windows Management Instrumentation Standard API for computer system

management Requires System.Management assemble Access to a host of BizTalk classes and

events Use WMI Code Creator:

http://www.microsoft.com/downloads/details.aspx?familyid=2cc30a64-ea15-4661-8da4-55bbc145c30e&displaylang=en

What Can You Do With WMI?

Deploy an assembly Create / modify / delete hosts / host instances Browse orchestration artefacts Bind / enlist / start orchestrations Stop / unenlist / unbind orchestrations Add / enlist / start send & receive ports Stop / unenlist / delete send & receive ports Add / remove maps for inbound / outbound

transformations Enable / disable receive locations Add / modify / delete message box

Basic WMI Operation - Createusing System.Management;

// sample to show MSBTS_HostSetting instance creationpublic void CreateHost(string ServerName, string HostName, int HostType, string NTGroupName, bool

AuthTrusted){

try{

PutOptions options = new PutOptions();options.Type = PutType.CreateOnly;// Create a ManagementClass object and spawn a ManagementObject instanceManagementClass objHostSettingClass = new ManagementClass("\\\\" + ServerName + "\\

root\\MicrosoftBizTalkServer", "MSBTS_HostSetting", null);ManagementObject objHostSetting = objHostSettingClass.CreateInstance();// Set the properties for the HostobjHostSetting["Name"] = HostName;objHostSetting["HostType"] = HostType;objHostSetting["NTGroupName"] = NTGroupName;objHostSetting["AuthTrusted"] = AuthTrusted;// Creating the hostobjHostSetting.Put(options);System.Console.WriteLine(string.Format("The Host '{0}'has been created successfully",

HostName ));}catch(Exception ex){

System.Console.WriteLine("CreateHost - " + HostName + " - failed: " + ex.Message);}

}

BTSTask

Replaces deprecated BTSDeploy command No wizard included (use BizTalk Admin Console) Allows you to:

Add, enumerate, remove, and uninstall BizTalk applications.

Add, list, and remove artefacts from a BizTalk application.

Export and import BizTalk applications from an MSI file.

Export and import binding information from BizTalk binding files.

Command Line Reference:http://msdn.microsoft.com/en-us/library/aa559686.aspx

What Can You Do With BTSTask?

Create / modify / delete applications Deploy assemblies Browse orchestration artefacts Bind / enlist / start orchestrations* Stop / unenlist / unbind orchestrations* Add / enlist / start send & receive** ports Stop / unenlist / delete send & receive** ports Add / remove maps for inbound / outbound

transformations** Enable / disable receive locations**

* via processing scripts only**via binding files only

Putting It All Together…

Export your bindings / MSI files Create .NET assembly as an API using

ExplorerOM classes (start with sample in SDK)

Create a master batch script that manages the full deployment using: BTSTask ExplorerOM assembly MSIExe

One-click deployment/migration!!

Deployments Made Easy…(?)

Scott Colestock’s Deployment Framework for BizTalkhttp://www.codeplex.com/biztalkdeployment

“…goes far beyond BizTalk’s out-of-the-box deployment functionality”

Includes additional tools to help developers Integration with Visual Studio, NUnit, Log4Net

Deployment Framework for BizTalk

Summary

BizTalk application deployment is inherently more complex and broader in scope than most other application deployments

Requires understanding of the components and configuration involved: Database Import vs. Server Installation Logical Ports (Assemblies) vs. Physical Ports Hosts vs. Applications Auxiliary components/artefacts

Out-of-the-box tools can facilitate the process greatly (esp. since BizTalk 2006)

Time spent compiling scripts / deployment classes can save heaps of time and errors later

Potential use of third-party deployment tools

References Best Practices for Deploying a BizTalk Application (TechNet):

http://technet.microsoft.com/en-us/library/aa577468.aspx

Structure of a BizTalk Binding File (MSDN):http://msdn.microsoft.com/en-us/library/aa559878.aspx

Customizing Binding Files (TechNet):http://technet.microsoft.com/en-us/library/aa559898.aspx

Using Pre- & Post-Processing Scripts to Customise Application Deployment (TechNet):http://technet.microsoft.com/en-us/library/aa559904.aspx

BTSTask Command Line Reference (MSDN):http://msdn.microsoft.com/en-us/library/aa559686.aspx

ExplorerOM Namespace Documentation (MSDN):http://msdn.microsoft.com/en-us/library/microsoft.biztalk.explorerom.aspx

BizTalk 2006 Recipes: A Problem – Solution ApproachMark Beckner, Benjamin Goeltz, Brandon Gross, Brennan O’Reilly, Stephen Roger, Mark Smith & Alexander WestApress Books, ISBN-13 (pbk): 978-1-59059-711-8

Pro BizTalk 2006: Solutions to Real World Issues for BizTalk ProfessionalsGeorge Dunphy and Ahmed MetwallyApress Books, ISBN-13 (pbk): 978-1-59059-699-9

Questions?