Understanding the BizTalk Deployment Framework

by Lex Hegt | Feb 22, 2017 | BizTalk Community Blogs via Syndication

Part 2 – Advanced setup

This is an article in a series of 2 about the BizTalk Deployment Framework (BTDF). This open source framework is often used to create installation packages for BizTalk Applications. More information about this software can be found here CodePlex.
With this series of articles, we aim to provide a useful set of hands-on documentation about the framework.

The series consists of the following parts:

• Part 1 – Introduction and basic setup
• Part 2 – Advanced setup (this article)
  • Introduction
  • Custom Targets
  • Conditions
  • Host Groups
  • Executing third party executables
  • Tips and Tricks
  • Conclusion

Introduction

In the first part  of this series we have seen how you can setup a BizTalk Deployment-project, add artefacts to the project, how you can deploy variable settings for other DTAP environments and how you can generate distributable MSI packages.
In this second article we’ll show somewhat more advanced topics like Custom Targets, Conditions, Host Groups and we’ll see how you can run third party executables from within your deployment. We’ll finish with a couple of Tips and Tricks.

Custom Targets

To be able to customize your deployments, the BizTalk Deployment Framework uses a concept called Custom Targets. These Custom Targets allow you to execute commands during certain phases of the deployment. We will describe a couple of Custom Targets and show how you can use them later on as well. The currently available Custom Targets are shown below.

Adding Custom Targets to your Deployment project

Before describing the Custom Targets, let’s first have a quick look on how to add Custom Targets to your Deployment project.
To keep your Deployment project nicely organized, it is a good idea to keep all the custom targets you will be using grouped together below all the BizTalk artefacts you will deploy. So the Custom Targets will be added at the end of your Deployment project.
Below is a picture which shows where the CustomRedist target is added to the Deployment project. This target was actually already added to the project during creation of the Deployment project.

As you can see, you can simple type the text <Target Name=”…”></Target> and at the ellipsis, provide the name of the Custom Target you will be going to use. Everything you want to perform during the execution of the target, can be entered between the start tag and the end tag. We’ll see examples of the kind of commands which can be performed later in this article.

CustomRedist

This target becomes executed right after BTDF has finished copying files. So this is the ideal moment if you would like for example to add additional files to the MSI package, which will be copied to the installation folder on deployment.
Below you have a sample in which a folder becomes created and some files are copied to that folder:

    <MakeDir Directories="$(RedistDir)SQLScripts" />
    <CreateItem Include="SQLScripts*.*">
          <Output TaskParameter="Include" ItemName="SQLScripts" />
    </CreateItem>
    <Copy DestinationFolder="$(RedistDir)SQLScripts%(RecursiveDir)" SourceFiles="@(SQLScripts)"/>

CustomDeployTarget and CustomPostDeployTarget

The CustomDeployTarget target runs just before Deployment has started, while the CustomPostDeployTarget target runs directly after Deployment has finished. Either can be used if you want to deploy additional stuff. Later we’ll describe how these targets are used to run third party executables, but you might also use these targets to create for example an EventLog source.
CustomUndeployTarget and CustomPostUndeployTarget
The CustomUndeployTarget target runs just before any undeployment has been performed, while the CustomPostUndeployTarget target runs right after the undeployment has taken place. These targets can be used if you would like to clean up stuff after undeployment. You can think of that as cleaning any created files during deployment. All just to be sure that you keep your environment nice and clean.

Conditions

The concepts of Conditions can be used in both Bindingfiles as in the BTDF project file. With Bindingfiles this might be used to create different ports in different environments.
In the BTDF project file this feature can become used when for example, you want to execute certain targets only in certain environments.
As applying Conditions is almost the same for both kind of files, let’s just have a look at the latter one.
Let’s assume that we want to execute an .exe file only for the Test and Production environment. To be able to execute certain targets just for certain environments, you need to do the following:
– Add an Environment variable to your BTDF Settings file
– Add the variable to your BTDF project file
– Add a filter to the CustomPostDeployTarget

Add an Environment variable to your BTDF Settings file

From Visual Studio open the SettingFileGenerator.xml file in Excel and add a variable called Environment. Each environment will get a unique value. Below picture shows a setting file which is extended with such a setting and contains unique values for all environments, namely DEV, SDEV, TEST and PROD.

Add the variable to your BTDF project file

To be able to use the Environment variable, you need to do the following:
• Open the Deployment.btdfproj file and look for an ItemGroup which contains the value PropsFromEnvSettings. Typically this settings contains the values SSOAppUserGroup and SSOAppAdminGroup.
• Add a semicolon and the new variable Environment. Afterwards the ItemGroup will look like below.

    <ItemGroup>
      <PropsFromEnvSettings Include="SsoAppUserGroup;SsoAppAdminGroup;Environment" />
    </ItemGroup>

Add a filter to the CustomPostDeployTarget

In the final step you’ll arrange that the step which executes the .exe file only gets executed in case you’re deploying on the TEST or PROD environment. Navigate to the target called CustomPostDeployTarget and add the condition: $(Environment)==’TEST’ OR $(Environment)==’PROD’ to it.
When you’ve done that, the target will look as follows:

    <Target Name="CustomPostDeployTarget" Condition="$(Environment)=='TEST' OR $(Environment)=='PROD'">
        <MakeDir Directories="$(RedistDir)SQLScripts" />
        <CreateItem Include="SQLScripts*.*">
                <Output TaskParameter="Include" ItemName="SQLScripts" />
        </CreateItem>
        <Copy DestinationFolder="$(RedistDir)SQLScripts%(RecursiveDir)" SourceFiles="@(SQLScripts)"/>
    </Target>

Now, when you save the project file, create an MSI and execute that MSI, the CustomPostDeployTarget will only be executed when you are deploying to the Test or the Production environment.

Host Groups

In most cases a BizTalk application uses only a couple of Host Instances. After a deployment it is a good practice to restart all relevant Host Instances. BTDF enables you to achieve this by using an BizTalkHosts ItemGroup. If you omit this ItemGroup, all Host Instances will be restarted.
You can put such an ItemGroup in the BTDF-project file. To keep the project file nicely organized you can consider to have that ItemGroup below the BizTalk artefacts you are deploying.

    <ItemGroup>
        <BizTalkHosts Include="SendHost;ReceiveHost;OrchestrationHost" />
    </ItemGroup>

As you can see, you can easily add multiple hosts by using semicolons between the separate hosts.

Executing third party executables

The BizTalk Deployment Framework enables you to execute third party executables. Below you find brief examples to show what you can achieve with this capability.

Executing SQL Server scripts

Say you have a custom database which is used by your BizTalk solution and this database needs to be extended with additional tables and stored procedures. Without using the BizTalk Deployment Framework, you would need to run the necessary SQL Server scripts on each environment by hand. This is a time-consuming and error-prone task which can be automated with BTDF.
To be able to execute SQL Server commands, you need to execute an executable called sqlcmd. Below you find an example on how to execute SQL scripts:

  <Target Name="CustomPostDeployTarget">
    <Exec Command="sqlcmd -S $(SQLServer) -i&quot;SQLScripts<Name of T-SQL deploy script>&quot;" />
  </Target>

As you can see, you can simply add an Exec command to the deployment target.
For all the ins and outs on deploying SQL Server scripts, check this article on TechNet Wiki.

Create BizTalk360 alerts

Another example of running third party executables is the creation of BizTalk360 alarms. Normally you’ll have to do this manually after each deployment of a new or changed BizTalk application. This too can be a time-consuming and error prone task. By using BTDF and a tool called BT360Deploy, you can automate the creation of alarms during the deployment of you BizTalk application.

In the picture here above, you have an example of the output of BT360Deploy. More information on BT360Deploy can be found on CodePlex.

Tips and Tricks

We’ll end this article by providing you with a couple of Tips and Tricks

Do not automatically start the Application after deployment

BTDF allows you to automatically start the deployed BizTalk application, i.e. start all ports and orchestrations after deployment. Although that sounds like a convenient feature, especially in Dev and Test environments, your BizTalk administrator probably prefers that you leave the just deployed BizTalk application not started on Production environments. The reason for this is that in this way the BizTalk Administrator has better control over the moment when the BizTalk application must be activated.

Consider (not) restarting Host Instance

We have seen that BTDF can restart the Host Instance(s) after deployment. But in case you use scripting for unattended deployment of multiple BizTalk applications at the same time, you don’t want the Host Instances restarted after each deployment package as this is a waste of time and resources. In that case, you remove the ItemGroup that contains the BizTalkHosts. Instead you set the SkipHostInstancesRestart property in the first PropertyGroup of the project file to True:

<SkipHostInstancesRestart>False</SkipHostInstancesRestart>

ItemGroups per artefact

To keep your BTDF project file organized, it is preferable that you use separate ItemGroups for all the separate types of artefacts you will be deploying.

  <ItemGroup>
    <Schemas Include="Kovai.BTDF.Schemas.dll">
      <LocationPath>..$(ProjectName).Schemasbin$(Configuration)</LocationPath>
    </Schemas>
    <Schemas Include="Kovai.BTDF.MoreSchemas.dll">
      <LocationPath>..$(ProjectName).MoreSchemasbin$(Configuration)</LocationPath>
    </Schemas>
  </ItemGroup>

  <ItemGroup>
    <Transforms Include=" Kovai.BTDF.Maps.dll ">
      <LocationPath>..$(ProjectName).Mapsbin$(Configuration)</LocationPath>
    </Transforms>
    <Transforms Include=" Kovai.BTDF.MoreMaps.dll ">
      <LocationPath>..$(ProjectName).MoreMapsbin$(Configuration)</LocationPath>
    </Transforms>
  </ItemGroup>

  <ItemGroup>
    <Orchestrations Include=" Kovai.BTDF.Orchestrations.dll ">
      <LocationPath>..$(ProjectName).Orchestrationsbin$(Configuration)</LocationPath>
    </Orchestrations>
    <Orchestrations Include=" Kovai.BTDF.MoreOrchestrations.dll ">
      <LocationPath>..$(ProjectName).MoreOrchestrationsbin$(Configuration)</LocationPath>
    </Orchestrations>
  </ItemGroup>

Conclusion

In a series of 2 articles we have seen quite a lot of the capabilities of the BizTalk Deployment Framework. In part 1 we started with pointing out the advantages of using BTDF over the out-of-the-box capabilities of BizTalk Server and we created a simple Deployment project which showed how to setup a deployment with basic artefacts like Schemas, Maps and Orchestrations. We extended this project by creating variables to be used for environment specific settings like URL’s of endpoints.
In part 2 we have seen some more advanced features like Conditions and Host Groups. We have also seen how we can run third party executables to automate your deployment as far as possible and to decrease the amount of manual and error prone labour as much as possible.
Still there are much more possibilities with BTDF which we did not discuss. For example, you can also use it to create virtual directories, deploy SSO settings, create EventLog Event Sources, create Registry keys etc. etc. etc..

It must be clear by now that the BizTalk Deployment Framework is a very powerful framework that can be used with straight forward to complex deployments. So when you are already familiar with the framework and are using it for the deployment of standard BizTalk artefacts, why not expand your experience with BTDF and start deploying less common artefacts like SQL scripts. When you do that properly, your BizTalk Administrator might become your new best friend!

Happy deploying!

Author: Lex Hegt

Lex Hegt works in the IT sector for more than 25 years, mainly in roles as developer and administrator. He works with BizTalk since BizTalk Server 2004. Currently he is a Technical Lead at BizTalk360. View all posts by Lex Hegt