Deployment in BizTalk Server 2006 can often be a painstaking and manual process due to the different types of artifacts that are typically part of a BizTalk application. A complex BizTalk application may include BizTalk assemblies, .NET assemblies, web services, windows services, batch scripts and a set of bindings for each environment. The manual deployment of these artifacts is very tedious and prone to error. Most IT shops end up creating a detailed deployment guide to formalize the manual process, but this is not necessarily the most efficient method. 

In BizTalk Server 2006, BTSTask provides scripting options that can be used to automate the packaging and deployment of most artifacts common to many of the BizTalk solutions. Moreover, with the help of VBScript and WMI scripts the deployment of non-BizTalk artifacts, such as web services, windows services or other dependencies, can be deployed as part of executing a single MSI executable. In this article we will explore how we can use BTSTask to automate the creation of a single deployment package that can be used to deploy all BizTalk and non-BizTalk artifacts to multiple target environments.

Before implementing a deployment strategy, it is very important that your BizTalk solution have an easy to follow structure within your Visual Studio solution. Unlike an ASP.NET or Windows Forms application, a BizTalk solution will typically contain more than just Visual Studio projects.  Figure 1 shows one particular structure that accounts for the various BizTalk artifacts. The structure in the figure uses Visual Studio Solution folders to segment the different types of artifacts that need to be tracked for a BizTalk solution. 

Figure 1 - Visual Studio Solution Structure

For example, the bindings for the entire solution are tracked under the Bindings solution folder.  In addition, the binding files follow a file naming convention that easily allows us to identify the solution and target environment based on the filename. It is also important to note that the Windows folder structure should resemble the Visual Studio solution structure to avoid any confusion. Figure 2 shows the Windows folder structure for the Visual Studio Solution from Figure 1.

Figure 2 - Windows Folder Structure

Overview

The build and deployment scripts for a solution are maintained in the /Scripts/Build directory within the BizTalk solution. Refer to Figure 3 for a listing of these files. The Windows batch files (*.bat) are used to create an MSI and must be executed manually by a developer or administrator. These batch files contain a series of Windows commands that execute BTSTask and other commands to package all the BizTalk artifacts and create an MSI. On the other hand, the VBScript files are embedded within the MSI for later execution during the deployment process. In particular, BTSTask supports two types of embeddable scripts: Post-processing and Pre-Processing. These scripts are useful for setting up or tearing down non-BizTalk related infrastructure, such as Windows folders, permissions, and IIS virtual directories. In the following sections we will review each of the script files in further detail to better understand BTSTask.

Figure 3 - Build and Deployment Scripts

RunMeToCreateMSI.bat

The RunMeToCreateMSI.bat file is a main script that simply calls BuildAndPackage.bat and captures all output to a log file (Line 17). Using a main script in this fashion allows you to easily redirect all output from the called script to a log file. Without the main script, the alternate method of logging output would require specifying the redirection (>) character for each command executed.

Figure 4 - RunMeToCreateMSI.bat

BuildandPackage.bat

The BuildandPackage.bat file is the script that does all the work of creating an MSI. Figure 5 shows lines 9-21 where the script sets up the variables needed for the rest of the script. The command in Line 12 calls the Visual Studio batch file to initialize the Visual Studio command line environment variables. 

Figure 5 - BuildandPackage.bat: Initialize variables

Lines 23-37 are needed for building the Visual Studio solution. The command in Line 27 calls devenv.exe to build the Visual Studio solution. If this step fails for any reason, the script jumps to the end of the script and does not proceed any further.

Figure 6 - BuildandPackage.bat: Build Visual Studio Solution

Once the Visual Studio solution is built successfully, the script then proceeds to create an application in the BizTalk management database (Line 47 in Figure 7). During this step, it is important that the application is not already in the management database.  Be sure to delete the application before running the RunMeToCreateMSI.bat script.

Figure 7 - BuildandPackage.bat: Create BizTalk Application

Once an application is created, the necessary BizTalk artifacts can be added to the application.  Lines 64-68 in Figure 8 show how BizTalk and .NET assemblies can be added to the application.  The Type parameter is required to specify the type of artifact that is being added. For BizTalk assemblies, the Type parameter value should be BizTalkAssembly and for .NET assemblies the value should be Assembly.

Figure 8 - BuildandPackage.bat: Add BizTalk and .NET Assemblies

Figure 9 shows how to add a Post-processing script. This script is executed when installing the MSI.

Figure 9 - BuildandPackage.bat: Add Post-Processing Script

Figure 10 shows how to add command line utilities or miscellaneous tools to the application. In this particular scenario, the script adds gacutil.exe to the application. During un-installation, gacutil.exe is used by the post-processing script to remove the BizTalk and .NET assemblies from the GAC. In this particular scenario, gacutil.exe was added to the application because it was not in the .NET Framework directory on the production servers. Most production servers will not have gacutil.exe for security reasons. Refer to Deploying Shared Components to the Global Assembly Cache on MSDN for more information.

Figure 10 - BuildandPackage.bat: Add Utilities

Figure 11 shows how to add binding files to the application. The TargetEnvironment property is used to specify the environment for each binding file added to the application. During the MSI import process, the TargetEnvironment values specified in the script are available in a drop down list for selection (Figure 12).

Figure 11 - BuildandPackage.bat: Add Bindings

Figure 12 - MSI Import Process

The final step is to use the ExportApp command to create an MSI and then also remove it from the management database. If both commands are successful, an MSI with a timestamp in the filename should be generated in the directory path specified in the -package parameter (Figure 13).

Figure 13 - BuildandPackage.bat: Export MSI

PostProcessingScript.vbs

The PostProcessingScript.vbs script is executed during the MSI installation and un-installation process. Figure 14 shows the VBScript commands required to create a directory structure for the BizTalk receive locations and send ports.

Figure 14 - PostProcessingScript.vbs: Installation

During un-installation, the PostProcessingScript.vbs script removes assemblies from the GAC and also deletes the directory structure created during the installation process. Figure 15 shows the commands that are used to call gacutil.exe to remove the assemblies from the GAC.

Figure 15 - PostProcessingScript.vbs: Un-installation

[Download Sample]

BTSTask Command-Line Reference

DevEnv Command Line Switches

Global Assembly Cache Tool (gacutil.exe)

The method of scripting discussed in this article can be extended to handle more complex artifacts such as packaging up web services, web applications and Windows services. This allows a BizTalk developer to create a single package with all the necessary artifacts for a solution.  Moreover, we have also shown how post and pre-processing scripts can be used to automate the deployment of the packaged artifacts during installation.