Per-Instance Pipeline Configuration

BizTalk Server 2006 introduced a feature called “Per-Instance Pipeline Configuration”, which allows you to override certain configuration options of the components in a pipeline just for messages going through a specific send port or receive location. This setting is available from the BizTalk Server Administration Console on the port/location settings dialog.

When you export the bindings for the application, these per-instance pipeline configurations are included in the generated binding file as encoded XML. If you decode the embedded XML, you will notice that it’s a format very similar to the one used for .btp files themselves, though properties for components are specified in a slightly different format. Here’s an example:

<?xml version="1.0" encoding="utf-8"?>
<Root xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Stages>
      <Stage CategoryId="9d0e4107-4cce-4536-83fa-4a5040674ad6">
         <Components>
            <Component Name="Microsoft.BizTalk.Component.XmlAsmComp">
               <Properties>
                  <AddXmlDeclaration vt="11">0</AddXmlDeclaration>
                  <PreserveBom vt="11">0</PreserveBom>
               </Properties>
            </Component>
         </Components>
      </Stage>
      <Stage CategoryId="9d0e4108-4cce-4536-83fa-4a5040674ad6">
         <Components>
            <Component Name="Microsoft.BizTalk.Component.MIME_SMIME_Encoder">
               <Properties>
                  <ContentTransferEncoding vt="8">7bit</ContentTransferEncoding>
                  <EnableEncryption vt="11">1</EnableEncryption>
               </Properties>
            </Component>
         </Components>
      </Stage>
   </Stages>
</Root>

Applying Configuration

As of PipelineTesting 1.2.0.0, per-instance pipeline configurations are now supported. Per-instance configurations need to be specified as XML in the exact same format described above, so the best way to generate it is by exporting a binding file containing the modified options and then extracting and un-escaping the embedded XML.

There are a two ways you can apply the per-instance settings:

1. Using the ApplyInstanceConfig() method of the Pipeline wrapper classes (SendPipelineWrapper/ReceivePipelineWrapper).
2. When using the Simple API (Simple API Examples), using the WithInstanceConfig() method during pipeline construction. WithInstanceConfig() must be the last step in the pipeline construction (this is enforced by the API).

Both of these methods allow you to specify the XML either as a path to an existing XML file on-disk, or as an XmlReader instance.

Here’s an example using the new API:

XmlTextReader reader = new XmlTextReader(
   DocLoader.LoadStream("PipelineInstanceConfig.xml")
);
SendPipelineWrapper pipeline = Pipelines.Xml.Send()
   .WithAssembler(Assembler.Xml())
   .WithEncoder(new MIME_SMIME_Encoder())
   .WithInstanceConfig(reader);

Caveats

There are some caveats you need to be aware when using this feature:

1. The XML only needs to include pipeline stages for which you have components that have modified settings
2. If you include a stage, you must include a node for each component in that stage, even if you’re not overriding any properties for said component. This is because within a stage, components are located by their index (order) within that stage.
3. The pipeline will validate that for each component found in the XML within a stage, the actual component located in the pipeline has the same name as the Component/@Name attribute. If it doesn’t, an error will be raised. This can help detect some scenarios where rule (2) above was not followed.