One key thing in the BizTalk Server Adapter Framework is the fact that adapters can have an arbitrary set of configuration properties defined both at the receive/send handler level as well as the individual send port/receive location level.
In general, the Adapter Framework makes it very easy to define this properties in the form of a simple XSD file, and most of the time the Adapter Framework automatically generates a decent UI for these properties using a Property Grid (but can be heavily customized if desired).
The documentation does a decent job of describing how it all fits together, however, I've notice that it tends to take certain things for granted and leave critical details unexplained, which can confuse the novice Adapter developer (they certainly confused the crap out of me).
So here are some useful facts to keep in mind when using the adapter framework configuration:
The XSD definition
The XSD schema you define for your adapter properties (regardless of whether it is to be used for locations or handlers) is not taken quite exactly as you define it. In particular, the adapter framework completely ignores the namespace the elements in the schema are defined in, so that doesn't matter at all. This is important to understand if you plan to use the XmlValidatingReader to validate the configuration XML against the schema.
Configuration Validation
The documentation mentions that the adapter can implement the IAdapterConfigValidation interface in order to customize the validation of the configuration defined for each case. However, this is incorrect; it is your adapter's Management class that needs to implement the interface.
Another interesting bit about this how IAdapterConfigValidation is used. The documentation provides no useful examples (although the adapter samples in the SDK do). Here are to very interesting uses:
- Implement cross-field validation rules: You can easily implement validations here of the kind if field X is set to Y, then field A cannot be B, by checking the options and throwing an exception if the configuration is incorrect. The exception message will then be presented to the user as a message box by the adapter framework. If you need single-field validation rules, they might be better implemenented as a custom TypeConverter.
- Completing the configuration: You can actually modify the configuration XML during validation, for example, by setting the value for a hidden field from the values in other fields. This is actually how most of the sample adapters get away with never presenting the mandatory URI field in location configuration yet generating a unique value for it (for example, the MSMQC sample adapter generates the URI during validation by using the queue name entered).
The properties XML in the registration
The documentation on creating the .reg file to register the adapter in the registry mentions the following on the use of the ReceiveHandlerPropertiesXML, ReceiveLocationPropertiesXML, SendHandlerPropertiesXML and SendLocationPropertiesXML fields:
"These values contain the definitions (schema) for the allowed properties of the corresponding entities related to the adapter, which can be stored in the Configuration store. These definitions are kept as an XML string being deserialized by the property bag, with property types, but without values. A nonempty value of the property element means that the property is masked. (Masked means that it is write-only, and is not returned by the Secure Store API when called in administrative mode; the Secure Store API returns VT_NULL for such properties.)"
It goes on then to present an example of the way the HTTP adapter might use it. The example, alas, is incorrect. These fields should, in general, contain always the same value: "
The reason for this is actually very simple: When you configure a handler or location, the adapter framework will take the property values entered by the user, serialize them into a simple XML based on the configuration XSD, validate it, and then will stick it as a string within the XML presented above inside the
If the XML present in the registry doesn't match what is given above, then adapter configuration will not work anymore, or, rather, will work in rather misterious ways. For example, a handler configuration will not be possible to complete and rather give strange errors about the XML being invalid. On the other hand, configuring a receive location or send port will appear to work at first, but your adapter will not get the configuration XML at runtime at all.
Handler Configuration:
In general, the Adapter Capabilities flags seem to control whether an adapter will use the Adapter Framework Configuration framework. This is true, but only partially so. For example, if your adapter's registry key contains a SendHandlerPropertiesXML value, the BizTalk Administration Console will show the property page on the send handler configuration, even if the Capabilities value does not include the eOutboundProtocolRequiresContextInitialization flag. So, make sure everything is consistent when registering the adapter, and remember that once you've installed the adapter into BizTalk changing the Capabilities value in the registry is useless because that value has been copied over to the BizTalk Management Database during adapter installation (into the adm_Adapter table, if you're curious).
Hope this helps anyone out there!
