Export (0) Print
Expand All

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 drive:\Program Files\Microsoft BizTalk Server 2010\Utilities\AdapterRegistryWizard folder.

ImportantImportant
  • 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

0x4000

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.

noteNote
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"
noteNote
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

© 2010 Microsoft Corporation. All rights reserved.

Community Additions

ADD
Show:
© 2014 Microsoft