Setting up a build server with the BizTalk Deployment Framework
This chapter describes the steps to a TFS Build Server to set up BizTalk deployment with the following functionality:
• Build solution
• Perform unit testing Using BizUnit
• Create Deployment Packages Using BDTF
• Deploy to Server Using R packages created in previous step
• Create documentation BizTalkDocumenter
For this the following steps are required:• Installation Components (30 min)
• Configuring a build account (30 min)
• Setting up the build service (30 min)
• Scrum template installation (30 min)
• Share for the build output directory (10 min)
• Adjustments Build Template for use BTDF (30 min)
• Design of build definitions (60 min)
• Setting BTDF (60 min)
• Use BTDF
• Build execution / scheduling
UPDATE (21-06-2013)
- When using sharedassemblies, the following URL is a big help http://mohamedradwan.wordpress.com/2013/01/31/set-custom-assemblies-path-for-host-build-service-on-the-cloud/
- For viewing the basic instructions a video is available on the following blog
http://biztalkci.codeplex.com/releases/view/74970
The BizTalk project component
The BizTalk project component is needed to build BizTalk projects to build and is available on the BizTalk installation DVD. Run the BizTalk setup and check the 'Project Build Component.
Install [BizTalkDocumenter] and [HTML Help Workshop], it may be necessary to make an adjustment to the configuration file of the BizTalkDocumenter because it emanates from a 64-bit version of HTML Help Workshop. Adjust the configuration file as in this example is shown (highlighted in yellow);
<add key="HelpCompilerLocation" value="C:\Program Files (x86)\HTML Help Workshop\hhc.exe" />
BizTalk Deployment Framework
Install the [BizTalk Deployment Framework] through the installation process; after installation there are two that should be created/updated;
These folders are crucial in the steps described later and are very important *
Configuring a Build Account
TFS works with a build service under which the build is performed, this account requires the rights:
· Local Administrator (read registry values, create files etc.)
· BizTalk Administrator (for creating BizTalk applications)
· BizTalk SSO Administrator (for creating / reading SSO applications)
· Project Collection Build Service Accounts (TFS)
Note: the member of the build service account Collection Project Administrators is not necessary but very handy!
Setting up the Build Services
The TFS Build server uses the following components;
• Build Service
• Build Controller
• Build Agent
Setting up these components is described in the Microsoft Developer Network Guide [Configuring your build system].
the SCUM template is used to apply Agile principles in TFS, the template is available and the installation files and guide can be found at [TFS Scrum template].
Share for the build output directoryWhen a build is executed, there is location required where output files are written to. The build output directory will contain the log and other important files, this setting is essential. Create a folder and grant the build service account permissions to this folder.
Note: There also seems to be a bug in TFS causing the drop folder always to be required, if it is not configured you will receive the following error: TF270006: The drop location for this build was empty. (caused by a check in the xaml Build template)
Build Template modifications for use BTDFBecause the BizTalk Deployment Framework project file (". BTDF") is not a file type supported as a TFS project alterations to the build template are required. These steps are described in the following post [Build Projects Using BizTalk Deployment Framework TFS2010]. Remember to save the template as a new template!
Note: This section describes what the command line parameters is wrong and must be:
String.Format(“/p:SkipInvalidConfigurations=true /t:Installer {0}” , MSBuildArguments)
Build DefinitionIn order to test the code we need 2 build definitions;
1) Build BTDF, which is based on the custom Build Template, called Build Definition, this will use BTDF to generate MSI files and deploy to the build server
2) Build Classic, which carries out the unit tests (which require the BizTalk environment to be set up)
Click the right mouse in the Team Explorer window for the option "New Build Definition"
Choose a name for the build definition.
Trigger
Configure the build so that it runs every day and the morning has been completed.
Workspace
Because each build is defined per solution it is important only the relevant part of source control is taken, otherwise the entire workspace will be retrieved during the build process which will lead to a slow build.
Configuration Output folder
Configure the build output directory where the files it copies are generated during the build (very useful for logging information).
Build Template (only for BTDF)
The template must be chosen to build the BTDF projects, this template contains the previously modified changes to enable support for BTDF projects.
Build Solution + BTDF
It works with BTDF already build files, this requires that two projects are selected: the BTDF project which should be build and the associated project.
BTDF Specific settings
It is not desirable that a work item is created due to a build error, it is necessary to build for the X86 platform as the BizTalk build fails otherwise. We can provide some MSBuild properties to use in BTDF which can override MSBuild property (e.g. to define whether we work on the build server etc.).
MSBuild Arguments: / property: OnBuildServer = True
MSBuild Arguments: / property: generate documentation = * True
* (for performance reasons it is desirable to define it once in the last scheduled BTDF build)
Below shows an example where a property is defined;
Regular Build Definition
Follow the same steps as explained in the beginning "BTDF Build Definition":
• Trigger
• Workspace
• Build Output folder
• Process
For a regular build, the default template to be used;
After that the project to be build can be selected;
For the Automatic testing properties it is important to select the test the settings from the solution to select, this allows for deployment to deploy folders and the like in the projects.
It is not desirable (initially) that a work is created after each build error, it is necessary to further build the X86 to run as the BizTalk build fails otherwise.
The BizTalk Deployment Framework (BTDF) uses MSBuild, MSBuild uses definition files which to carry out steps and dependencies are determined (so called. Target files). To change the behavior of BTDF we have to modify the target file, located on the build server.
Location of the .Targets file: C:\Program Files (x86)\MSBuild\DeploymentFrameworkForBizTalk\5.0
Targets BizTalkDocumenter
To ensure that the BizTalkDocumenter is called after the build we add a target that is called based on the provided MS Build argument;
Note: The " is required because the path contains spaces! GenerateDocumentation ensures that the BizTalkDocumenter code is only called when this is provided as a MSBUILD property.
To call the BizTalkDocumenter Target the ‘DeployDependsOn’ has to be altered:
Setting up the BizTalk Deployment Framework ProjectAfter creating a BizTalk Deployment Framework Project it is necessary to perform the following steps:
· Customizing Property Group
Copy a property group (based on the Debug) and add a condition to:
Make sure that the output path contains the following value (example);
If necessary, other settings can be overwritten, below is an example of a property group based on the definition established in the MSBuild property 'OnBuildServer "
Add a BUILDSERVERPortBindingsMaster.Xml file to the .Deployment project with the bindings used in the BizUnit tests.
Common errors
Test Settings are not included in the build definitionSee the step "Process" to "Regular Build Definition '
TF270006: The drop location for this build was empty.
“The build definition '.... "(or build the request) must Specify a valid UNC path as the drop location for the build. Update the build definition and try again.”
This is a bug in the build process, there is no specified Drop Folder, even if it is unchecked that a leaflet drop is used there seems always to be specified.
Error ‘.cs files of schemas could not be found’
Change platform to X86
Dll can not be found in the project
Select the entire workspace or at least the folder that might have been used containing all the referenced assemblies.
Good luck!
• Build solution
• Perform unit testing Using BizUnit
• Create Deployment Packages Using BDTF
• Deploy to Server Using R packages created in previous step
• Create documentation BizTalkDocumenter
For this the following steps are required:• Installation Components (30 min)
• Configuring a build account (30 min)
• Setting up the build service (30 min)
• Scrum template installation (30 min)
• Share for the build output directory (10 min)
• Adjustments Build Template for use BTDF (30 min)
• Design of build definitions (60 min)
• Setting BTDF (60 min)
• Use BTDF
• Build execution / scheduling
UPDATE (21-06-2013)
- When using sharedassemblies, the following URL is a big help http://mohamedradwan.wordpress.com/2013/01/31/set-custom-assemblies-path-for-host-build-service-on-the-cloud/
- For viewing the basic instructions a video is available on the following blog
http://biztalkci.codeplex.com/releases/view/74970
The BizTalk project component
The BizTalk project component is needed to build BizTalk projects to build and is available on the BizTalk installation DVD. Run the BizTalk setup and check the 'Project Build Component.
BizTalkDocumenter + HTML Help Workshop
Install [BizTalkDocumenter] and [HTML Help Workshop], it may be necessary to make an adjustment to the configuration file of the BizTalkDocumenter because it emanates from a 64-bit version of HTML Help Workshop. Adjust the configuration file as in this example is shown (highlighted in yellow);
<add key="HelpCompilerLocation" value="C:\Program Files (x86)\HTML Help Workshop\hhc.exe" />
BizTalk Deployment Framework
Install the [BizTalk Deployment Framework] through the installation process; after installation there are two that should be created/updated;
C:\Program Files\BizTalk Deployment Framework | (contains documentation, sourcecode, binaries.) |
C:\Program Files\MSBuild\ BizTalk Deployment Framework | *Contains the MSBuild targets (normal + for WIX MSI generation). |
These folders are crucial in the steps described later and are very important *
Configuring a Build Account
TFS works with a build service under which the build is performed, this account requires the rights:
· Local Administrator (read registry values, create files etc.)
· BizTalk Administrator (for creating BizTalk applications)
· BizTalk SSO Administrator (for creating / reading SSO applications)
· Project Collection Build Service Accounts (TFS)
Note: the member of the build service account Collection Project Administrators is not necessary but very handy!
Setting up the Build Services
The TFS Build server uses the following components;
• Build Service
• Build Controller
• Build Agent
Setting up these components is described in the Microsoft Developer Network Guide [Configuring your build system].
Install the TFS Scrum template
the SCUM template is used to apply Agile principles in TFS, the template is available and the installation files and guide can be found at [TFS Scrum template].
Share for the build output directoryWhen a build is executed, there is location required where output files are written to. The build output directory will contain the log and other important files, this setting is essential. Create a folder and grant the build service account permissions to this folder.
Note: There also seems to be a bug in TFS causing the drop folder always to be required, if it is not configured you will receive the following error: TF270006: The drop location for this build was empty. (caused by a check in the xaml Build template)
Build Template modifications for use BTDFBecause the BizTalk Deployment Framework project file (". BTDF") is not a file type supported as a TFS project alterations to the build template are required. These steps are described in the following post [Build Projects Using BizTalk Deployment Framework TFS2010]. Remember to save the template as a new template!
Note: This section describes what the command line parameters is wrong and must be:
String.Format(“/p:SkipInvalidConfigurations=true /t:Installer {0}” , MSBuildArguments)
Build DefinitionIn order to test the code we need 2 build definitions;
1) Build BTDF, which is based on the custom Build Template, called Build Definition, this will use BTDF to generate MSI files and deploy to the build server
2) Build Classic, which carries out the unit tests (which require the BizTalk environment to be set up)
BizTalk Deployment Framework Build Definition
Click the right mouse in the Team Explorer window for the option "New Build Definition"
Choose a name for the build definition.
Trigger
Configure the build so that it runs every day and the morning has been completed.
Workspace
Because each build is defined per solution it is important only the relevant part of source control is taken, otherwise the entire workspace will be retrieved during the build process which will lead to a slow build.
Configuration Output folder
Configure the build output directory where the files it copies are generated during the build (very useful for logging information).
Build Template (only for BTDF)
The template must be chosen to build the BTDF projects, this template contains the previously modified changes to enable support for BTDF projects.
Build Solution + BTDF
It works with BTDF already build files, this requires that two projects are selected: the BTDF project which should be build and the associated project.
BTDF Specific settings
It is not desirable that a work item is created due to a build error, it is necessary to build for the X86 platform as the BizTalk build fails otherwise. We can provide some MSBuild properties to use in BTDF which can override MSBuild property (e.g. to define whether we work on the build server etc.).
MSBuild Arguments: / property: OnBuildServer = True
MSBuild Arguments: / property: generate documentation = * True
* (for performance reasons it is desirable to define it once in the last scheduled BTDF build)
Below shows an example where a property is defined;
Regular Build Definition
Follow the same steps as explained in the beginning "BTDF Build Definition":
• Trigger
• Workspace
• Build Output folder
• Process
For a regular build, the default template to be used;
After that the project to be build can be selected;
For the Automatic testing properties it is important to select the test the settings from the solution to select, this allows for deployment to deploy folders and the like in the projects.
It is not desirable (initially) that a work is created after each build error, it is necessary to further build the X86 to run as the BizTalk build fails otherwise.
Setting up the BizTalk Deployment Framework
The BizTalk Deployment Framework (BTDF) uses MSBuild, MSBuild uses definition files which to carry out steps and dependencies are determined (so called. Target files). To change the behavior of BTDF we have to modify the target file, located on the build server.
Location of the .Targets file: C:\Program Files (x86)\MSBuild\DeploymentFrameworkForBizTalk\5.0
Targets BizTalkDocumenter
To ensure that the BizTalkDocumenter is called after the build we add a target that is called based on the provided MS Build argument;
<Target Name="DocumentBizTalk" Condition="'$(GenerateDocumentation)' == 'True'">
<Exec Command=""C:\Program Files (x86)\Microsoft Services\BizTalk Documenter\Microsoft.Services.Tools.BiztalkDocumenter.exe" /o:C:\BizTalk\Releases\$([System.DateTime]::Now.ToString('yyyyMMdd'))\ /def /show:false" />
</Target>
Note: The " is required because the path contains spaces! GenerateDocumentation ensures that the BizTalkDocumenter code is only called when this is provided as a MSBUILD property.
To call the BizTalkDocumenter Target the ‘DeployDependsOn’ has to be altered:
...
BounceBizTalk;
DocumentBizTalk
</DeployDependsOn>
Setting up the BizTalk Deployment Framework ProjectAfter creating a BizTalk Deployment Framework Project it is necessary to perform the following steps:
· Customizing Property Group
Copy a property group (based on the Debug) and add a condition to:
Condition="'$(OnbuildServer)' == 'True' And '$(Configuration)' == 'Debug'"
Make sure that the output path contains the following value (example);
C:\BizTalk\Releases\$([System.DateTime]::Now.ToString('yyyyMMdd'))\
If necessary, other settings can be overwritten, below is an example of a property group based on the definition established in the MSBuild property 'OnBuildServer "
<PropertyGroup Condition="'$(OnbuildServer)' == 'True' And '$(Configuration)' == 'Debug'">
<OutputPath>C:\BizTalk\Releases\$([System.DateTime]::Now.ToString('yyyyMMdd'))\</OutputPath>
<DeployPDBsToGac>false</DeployPDBsToGac>
<PortBindingsMaster>BUILDSERVERPortBindingsMaster.xml</PortBindingsMaster>
</PropertyGroup>
<PropertyGroup Condition="'$(OnbuildServer)' == 'False' And '$(Configuration)' == 'Debug'">
<OutputPath>bin\debug\</OutputPath>
<DeployPDBsToGac>false</DeployPDBsToGac>
</PropertyGroup>
· Add a BUILDSERVER<bindings>
Add a BUILDSERVERPortBindingsMaster.Xml file to the .Deployment project with the bindings used in the BizUnit tests.
Common errors
Test Settings are not included in the build definitionSee the step "Process" to "Regular Build Definition '
TF270006: The drop location for this build was empty.
“The build definition '.... "(or build the request) must Specify a valid UNC path as the drop location for the build. Update the build definition and try again.”
This is a bug in the build process, there is no specified Drop Folder, even if it is unchecked that a leaflet drop is used there seems always to be specified.
Error ‘.cs files of schemas could not be found’
Change platform to X86
Dll can not be found in the project
Select the entire workspace or at least the folder that might have been used containing all the referenced assemblies.
Good luck!