Working with Bindings Files

Parent Previous Next

Managing bindings files is one of the more tedious and tricky aspects of BizTalk deployments.  There tends to be a lot of XML, some of which is double-encoded in nested XML fragments, and many environment-specific settings are usually present.


The Deployment Framework for BizTalk deploys application bindings from an XML bindings file in your deployment project.  By default, you can simply export your application's bindings to a file named PortBindingsMaster.xml in your deployment project folder.  That's very easy, but the (huge) downside is that the bindings file is completely specific to the environment from which it was exported.  This is the default configuration for new Deployment Framework for BizTalk projects.


To address this problem, the Deployment Framework defines the concept of a "master" bindings file, which is an environment-neutral XML bindings file template stored as PortBindingsMaster.xml within your deployment project folder.  When using a master bindings file, PortBindings.xml is a tool-generated file.  During the deployment process, setting values from your Excel settings spreadsheet are seamlessly merged with the master bindings file to produce an environment-specific PortBindings.xml.  To create the master bindings file, you replace environment-specific values with tokens that correspond to setting names in the spreadsheet.


NOTE: The following instructions assume that you are setting up a new Deployment Framework for BizTalk project using the Add New Project wizard.  If you take a different approach, then these instructions may not work.


If this is your first time using the Deployment Framework for BizTalk or you just want to get a bindings file going as fast as possible:


  1. Create and configure a new Deployment Framework for BizTalk project, then deploy your application from Visual Studio using the Deployment Framework.  The script will fail at the point of starting the application. That's OK because you haven't configured the bindings yet.
  2. Go into BizTalk Server Administration and manually configure all bindings. Start the application and make sure everything is working.
  3. Still in BizTalk Server Administration, export the bindings to <yourBizTalkSolution>\Deployment\PortBindingsMaster.xml.  Overwrite the existing file.
  4. Once again, deploy your solution from Visual Studio.  It should now deploy without errors.


If you want to make your PortBindingsMaster.xml into an environment-neutral template:


  1. Follow Steps 1-4 from the previous section.
  2. Open PortBindingsMaster.xml in a text editor (see tip about Visual Studio editor below) and EnvironmentSettings\SettingsFileGenerator.xml in MS Excel.
  3. In PortBindingsMaster.xml, locate an environment-specific configuration value, for example BindingInfo/SendPortCollection/SendPort/PrimaryTransport/Address could contain a file path or URL.
  4. In Excel, on an empty row enter a descriptive name for the configuration element in column A, like InvoiceOutputPath.  In the environment-specific columns or the Default Values column, enter the appropriate value for each environment.
  5. In PortBindingsMaster.xml, replace the environment-specific value with a replacement token ${NameFromExcelSpreadsheet}, like ${InvoiceOutputPath}.
  6. Repeat these steps until the entire bindings file is environment-neutral and populated with tokens.
  7. If you need to do more complex replacements, you can set the property RequireXmlPreprocessDirectives to True in your .btdfproj file and use any of the replacement capabilities of XmlPreprocess.


TIP: When editing a bindings XML file in Visual Studio, beware of auto-formatting.  Bindings XML is very touchy, and Visual Studio's auto-formatting can cause invalid XML which will fail upon import into BizTalk.


Adapter, pipeline and party configuration data is often stored within the bindings XML as nested XML strings inside elements.  Since that XML is data and not part of the bindings XML itself, it is encoded (< = &lt;, > = &gt;, etc.).  The encoding makes it difficult to read and edit that configuration data.  The Deployment Framework for BizTalk includes an automatic pre-processor that allows you to keep the nested XML decoded in PortBindingsMaster.xml.  At deployment time, the nested XML fragments are re-encoded on the fly.


If you want to store encoded adapter, pipeline and party XML fragments as unencoded XML in PortBindingsMaster.xml for ease of editing:


  1. Follow Steps 1-4 from the first section above.
  2. Rename PortBindingsMaster.xml to PortBindingsKnownGood.xml
  3. Open a Command Prompt. Run ElementTunnel.exe /i:PortBindingsKnownGood.xml /x:adapterXPaths.txt /o:PortBindingsMaster.xml /decode -- adding the appropriate directory paths to the filename parameters. ElementTunnel.exe and AdapterXPaths.txt are in the Deployment Framework install folder under Framework\DeployTools. Your PortBindingsMaster.xml now has selected nested XML fragments decoded into plain, unencoded XML, controlled by the XPath statements in AdapterXPaths.txt.
  4. Edit your .btdfproj file and ensure that the property <ApplyXmlEscape> is set to true.
  5. In Visual Studio with your solution open, run Tools\Deployment Framework for BizTalk\Preprocess BizTalk Bindings.
  6. Use WinMerge or your favorite file compare tool to compare PortBindings.xml (which was automatically generated in the previous step) to PortBindingsKnownGood.xml. Any differences should be analyzed and understood.
  7. If there are any differences related to nested XML fragments, you probably need to manually re-encode some nested XML fragments in PortBindingsMaster.xml. Sometimes there is XML nested inside XML nested inside XML. One of those nested XML fragments may not have been processed automatically (by ElementTunnel.exe based on AdapterXPaths.txt). You may need to fix it up manually.
  8. Keep adjusting the encoding of nested XML fragments in PortBindingsMaster.xml, re-running Preprocess BizTalk Bindings, and re-comparing PortBindings.xml and PortBindingsKnownGood.xml until all areas including encoded XML are an exact match.
  9. Only when you have a successful compare, proceed to Tools\Deploy BizTalk Solution, which should now fully succeed.


Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites