Registering an Adapter
If you are developing a custom adapter, you can register it with BizTalk Server by modifying and running one of the registry files included with the sample file adapter in the software development kit (SDK). Or, you can use the Adapter Registry Wizard to create a registry file. This wizard is located in the \Program Files (x86)\Microsoft BizTalk Server <VERSION>Utilities\AdapterRegistryWizard folder.
Important
- On a 32-bit machine, the registry (.reg) file generated by the Adapter Registration wizard must be run from the command prompt.
- On a 64-bit machine, the registry (.reg) file generated by the Adapter Registration wizard must be run both from the 32-bit and 64-bit command prompt.
After you create registry entries, you can add the adapter in the BizTalk Server Administration console or programmatically by using Windows Management Instrumentation (WMI) methods. This topic discusses each of the registry entries and then shows you where and how to modify the existing registry files for your custom adapter.
For instructions on using the Adapter Registry Wizard, see Adapter Registry Wizard. For instructions on modifying the sample registry files included in the SDK, see Adapter Registration File.
Registry keys
You need to create the following registry entries to deploy an adapter:
Registry key location
[HKEY_CLASSES_ROOT\CLSID\{%uuid of custom transport%}\BizTalk]
@="BizTalk"
Type name
The adapter type name identifies the type of adapter in the BizTalk Server computer. This key is required for any adapter.
"TransportType"="MyTransportAdapter"
Constraints
Adapter constraints define the adapter's capabilities.
This key is required for every adapter. Depending on the type of adapter you are creating, you may want to modify the bitmask value of the constraints.
"Constraints"=dword:00003C0b
The value that describes the capabilities of the adapter can be a combination of values shown in the following table.
| Value | Hex value | Flag | Description |
|---|---|---|---|
| 1 | 0x0001 | eProtocolSupportsReceive | Adapter supports receive operations. |
| 2 | 0x0002 | eProtocolSupportsTransmit | Adapter supports send operations. |
| 8 | 0x0008 | eProtocolReceiveIsCreatable | Receive handler of adapter is hosted in-process. |
| 128 | 0x0080 | eProtocolSupportsRequestResponse | Adapter supports request-response operations. |
| 256 | 0x0100 | eProtocolSupportsSolicitResponse | Adapter supports solicit-response operations. |
| 1024 | 0x0400 | eOutboundProtocolRequiresContextInitialization | Indicates that the adapter uses the Adapter Framework user interface for send handler configuration. |
| 2048 | 0x0800 | eInboundProtocolRequiresContextInitialization | Indicates that the adapter uses the Adapter Framework user interface for receive handler configuration. |
| 4096 | 0x1000 | eReceiveLocationRequiresContextInitialization | Indicates that the adapter uses the Adapter Framework user interface for receive location configuration. |
| 8192 | 0x2000 | eTransmitLocationRequiresContextInitialization | Indicates that the adapter uses the Adapter Framework user interface for send port configuration. |
| 16384 | 0x4000 | eSupportsOrderedDelivery | Indicates that the adapter supports ordered delivery of messages. |
| 32768 | 0x8000 | eInitTransmitterOnServiceStart | Send adapter starts when the service starts instead of when it sends the first message. |
| 65536 | 0x10000 | eSupport32BitOnly | Indicates that the adapter supports running only in 32-bit hosts. |
Namespace
Each adapter must define a namespace for its properties. BizTalk Server stores adapter-specific properties on the message context under this namespace. This property is required for all adapters.
"PropertyNameSpace"="namespace"
Aliases
Each adapter may have a set of prefixes that uniquely identify the adapter type within BizTalk Server. This allows resolution of the correct transport type when sending a message through a dynamic send port. The adapter needs to specify the list of its prefixes at registration time.
"AliasesXML"="<AdapterAliasList><AdapterAlias>sample://</AdapterAlias></AdapterAliasList>"
Configuration Property Pages
The adapter must have configuration property pages to configure its receive locations and send ports. Each adapter registers its property pages by specifying their respective class IDs.
"InboundProtocol_PageProv"="{%CLSID for inbound protocol prop page%}"
"OutboundProtocol_PageProv"="{%CLSID for outbound protocol prop page%}"
"ReceiveLocation_PageProv"="{%CLSID for receive location prop page%}"
"TransmitLocation_PageProv"="{%CLSID for transmit location prop page%}"
If the adapter uses the Adapter Framework's user interface for property page generation, it must specify the following values for the registry keys:
"InboundProtocol_PageProv"="{2DE93EE6-CB01-4007-93E9-C3D71689A281}"
"OutboundProtocol_PageProv"="{2DE93EE6-CB01-4007-93E9-C3D71689A283}"
"ReceiveLocation_PageProv"="{2DE93EE6-CB01-4007-93E9-C3D71689A280}"
"TransmitLocation_PageProv"="{2DE93EE6-CB01-4007-93E9-C3D71689A282}"
Note that if one of the endpoints is not required (the adapter is send or receive only), the unused registry keys can be deleted from the registry.
Runtime Component Registration
The adapter registers its runtime components by specifying their class IDs (for COM and .NET), type names, and assembly paths (for .NET) for receive and send runtime components.
Note
All the OutboundEngineCLSID and InboundEngineCLSID keys must be unique. For a single row in a database, the OutboundEngineCLSID and the InboundEngineCLSID may be the same.
"OutboundEngineCLSID"="{%CLSID of outbound transport%}"
"InboundEngineCLSID"="{%CLSID of inbound transport%}"
"InboundTypeName"="BizTalk.Samples.Adapters.MyReceiver"
"OutboundTypeName"="BizTalk.Samples.Adapters.MyTransmitter"
"InboundAssemblyPath"="C:\Program Files\MyTransport.dll"
"OutboundAssemblyPath"="C:\Program Files\MyTransport.dll"
Note
You can install a adapter's assembly into the global assembly cache and refer to it in the registry file.
Registration of Adapter Properties for SSO Configuration Store
The adapter needs to register its properties with the BizTalk Server SSO database to be able to store and retrieve the properties at design time and run time.
ReceiveHandlerPropertiesXML
ReceiveLocationPropertiesXML
SendHandlerPropertiesXML
SendLocationPropertiesXML
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 that is deserialized by the property bag containing 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.)
Example
The HTTP adapter registers its properties for the HTTP send port by defining the SendLocationPropertiesXML registry key with the following value:
<CustomProps><Username vt="8"/><Password vt="8">Encrypted</Password><Certificate vt="8"/><RequestTimeout vt="3"/><MaxRedirects vt="3"/><ContentType vt="8"/><UseProxy vt="11"/><ProxyName vt="8"/><ProxyPort vt="3"/><ProxyUsername vt="8"/><ProxyPassword vt="8">Encrypted</ProxyPassword><UseHandlerSetting vt="11"/><AuthenticationScheme vt="8"/><UseSSO vt="11"/><AffiliateApplicationName vt="8"/></CustomProps>
Registration of the Component as a Transport Provider
The adapter must be registered under its Implemented Categories attribute in the registry as a transport provider. This attribute identifies its characteristics to consumers of the adapter.
[HKEY_CLASSES_ROOT\CLSID\{%uuid of custom transport%}\Implemented Categories]
[HKEY_CLASSES_ROOT\CLSID\{%uuid of custom transport%}\Implemented Categories\{7F46FC3E-3C2C-405B-A47F-8D17942BA8F9}]