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}]  

See Also

Adapter Design Issues