Developing Adapters Using the Adapter Framework

When Microsoft® BizTalk® Server connects to external systems to send and receive messages, BizTalk adapters are the first and last BizTalk components that touch a message within the BizTalk system. Out of the box, BizTalk Server includes eight adapters for connecting to certain transport protocols and locations. The Help refers to these adapters as native adapters. The eight native adapters support sending and receiving messages from a File location; a BizTalk Message Queuing, EDI, FTP, HTTP, SMTP, or SOAP protocol; or an SQL call. Additional adapters will be available from Microsoft and members of the Adapter Registration program as well. However, you may want to connect to some internal systems, for which no existing adapter is available. In this case, you can use the Adapter Framework to create a custom adapter for your unique solution. The Adapter Framework is a set of extensible APIs that enable you to leverage relevant shared services of BizTalk Server when building adapters or connectors to integrate applications and platforms. The FTP, SQL, and Base EDI adapters included in the box are built on the Adapter Framework, allowing you to see the possibilities and robustness of the platform. For information about using the native adapters, see Connecting Applications Using Native Adapters.

If you use the Adapter Framework to create your custom adapter, your adapter will share the standardized configuration, management, and setup pattern used by the native adapters. In the past, each custom adapter had unique applications for configuration, management, and setup—three new applications to learn with each adapter. With the standardization to the Adapter Framework, you only need to use two applications to manage your adapter: BizTalk Server Administration Console and BizTalk Explorer. Therefore, instead of three applications to learn per adapter, you now have only two applications to deal with, no matter how many custom adapters you create.

The following figure shows how an adapter and the Adapter Framework work together to connect your application to BizTalk Server.

Figure showing the Adapter Framework.

BizTalk adapters use the BizTalk Server Administration Console for adapter management, BizTalk Explorer for adapter configuration, and the Adapter Framework for design-time APIs.

The following figure shows where adapters fit into the message processing that occurs in BizTalk server.

Depicts the messaging process.

This diagram illustrates the following actions:

  • Data is received from the wire through a receive location that is listening for messages of a certain protocol at a specified address. The receive location is associated with an adapter and a receive pipeline. You can configure both the adapter and the pipeline components to perform certain logic on messages of a predetermined protocol.
  • After the message is received by the receive location, the message is sent to the adapter, which creates a new BizTalk message, attaches the data stream to the message (typically in the body part of the message), adds any metadata pertaining to the endpoint over which the data was received, and then submits that message into the Messaging Engine.
  • The Messaging Engine then sends the message to the receive pipeline where the data is transformed into XML, the message sender is authenticated, the message is decrypted, and the XML is validated.
  • Next, the Messaging Engine publishes the message to the MessageBox. The MessageBox is a Microsoft SQL Server™ table containing messages to be processed. Both orchestrations and send ports can subscribe to the MessageBox.
  • The Messaging Engine sends the message to either the orchestration or the send port if the message context properties match the specifications set in the filter on the subscriber (the orchestration or the send port).
  • If the send port is the subscriber, the message goes through a symmetrical process on its way out of the BizTalk system—it is passed through the Messaging Engine, send pipeline, and then to a send adapter before being transmitted over the wire by a send port.

Native adapters or custom adapters built on using the Adapter Framework can use the message processing described earlier. To aid in the rapid development of custom adapters, the BizTalk Server SDK contains a Sample File Adapter that you can use as a template for creating other custom adapters. This section provides instructions for customizing the SDK Sample File Adapter, as well as discussions of the different types of custom adapters you may want to create, tips on modifying performance variables, runtime object interaction diagrams, and fundamentals about the tools provided by the Adapter Framework.

This section contains:

To download updated BizTalk Server 2004 Help from, go to

Copyright © 2004 Microsoft Corporation.
All rights reserved.