Here is a small snippet of BizTalk Server wisdom which I will post for posterity. Say you are creating a custom pipeline component with custom properties. You create private fields and a public properties and write all the code to load and save corresponding property bag values from and too your properties. At some point, when you deploy the BizTalk application and test it, you get an exception from within your pipeline stating, unhelpfully, that “Value does not fall within the expected range.” Or maybe, while using the Visual Studio IDE, you notice that values you type into custom properties in the Property List are lost when you reload the pipeline editor.

What is going on? Well, the issue is probably due to having failed to initialise your custom property fields. If they are reference types and have a null value, the PipelineOM PropertyBag class will throw an exception when reading property values. The Read method can distinguish between nulls and, say, empty strings, due to the way data is serialised to XML (e.g., in the BTP file). Here is a property initialised to an empty string:

<Property Name=”MyProperty”>
<Value xsi:type=”xsd:string” />

Here is the same property set to null:

<Property Name=”MyProperty” />

The first is OK. The second causes an error and leads to the symptoms described above.

ALLWAYS initialise property backing fields in custom pipeline components. NEVER set properties to null programmatically.