Adapter Variables

There are a number of variables that any custom adapter needs to handle. Values assigned to these variables influence custom logic that the adapter implements. Transport-specific or application-specific configuration properties can also help to support your solution. The following table lists these common variables. You must decide if you want to support each one in your custom adapter.

For each option, your adapter must implement specific interfaces. Following the table is a list of variable options with links to more information about writing adapter code to support your design decisions.

Adapter variable	Description
Communication direction	Receive. A receive adapter listens to a protocol-specific address for an incoming message. When a message is received, the receive adapter hands off the message to the Messaging Engine, which passes the message through a receive pipeline to eventually be persisted to the MessageBox database. Send. When the Messaging Engine needs to send a message to a specific endpoint, it passes it to the send pipeline. A send adapter accepts a message from a send pipeline and sends it to the send port.
Adapter hosting	In-process. An in-process adapter is created and hosted within the BizTalk service process, BTSNTSvc.exe. If the host is 64-bit the process is named BTSNTSvc64.exe. For simplicity we will not mention the 64-bit process again in this section. This means that BizTalk Server creates and manages the lifetime of the adapter, initializes it with the transport proxy, services the adapter requests, and terminates the adapter upon service shutdown. For in-process adapters, BizTalk Server also delivers configuration information to the adapter at run time, including handler, send port, and receive location configuration. In addition, aspects of configuration such as service windows are handled by the Messaging Engine so that the adapter does not need to ensure that a receive location or send port is outside of a service window. Note that all send adapters are in-process adapters and must run in the BTSNTSvc.exe process. Isolated. The adapter is created in an isolated host that is not part of the BizTalk Server runtime. An example of an isolated adapter is the HTTP receive adapter, which runs in the process space of Internet Information Services (IIS). The IIS process model is such that IIS manages the lifetime of ASP.NET applications and ISAPI extensions. When BizTalk Server cannot manage the lifetime of the adapter, the adapter is referred to as an isolated adapter. Because BizTalk Server does not manage the instantiation of an isolated adapter, the adapter must create its own transport proxy and register itself with that transport proxy. Note that the BizTalk Server architecture eliminates unnecessary interprocess communication. Because the isolated adapter and the BizTalk stack are in the same process, there is no interprocess communication when the adapter is calling the Messaging Engine. The only interprocess communication is between the Messaging Engine and the database, which is unavoidable. COM+ applications cannot host send adapters written in nonmanaged code.
Message exchange pattern	One-way. The message is either incoming or outgoing. Request-Response (two-way). Request-response adapters are always receive adapters. A request-response receive adapter receives a request message from the client and submits the message to BizTalk Server. After BizTalk Server has processed the request message, it sends a response message back to the adapter. The adapter then transmits the response message back to the client. Solicit-Response (two-way). Solicit-response adapters are always send adapters. A solicit-response send adapter sends a request message from BizTalk Server to a destination, waits for a response message, and then submits the response message back to BizTalk Server.
Send port binding	Dynamic Send Ports and Receive Locations. The URI variable for the send port or receive location used in dynamic binding is determined at run time. Static Send Ports and Receive Locations. The URI variable for the send port or receive location is static and is configured before run time.
Synchronous send versus asynchronous send adapters	Synchronous send adapter. While executing a send operation, the Messaging Engine blocks the transport proxy thread until it has sent the batch of messages and returned. The transport proxy handles message removal after the message is transmitted, retried, suspended, or the move to the next operation is complete. Asynchronous send adapter. The asynchronous send adapter does not block the transport proxy thread, but rather uses a separate thread while performing send operations. Unlike the synchronous adapter, this adapter must implement all delete and retry logic itself; the transport proxy does not handle the logic. Adapters that send asynchronous messages allow better BizTalk Server performance than those that send synchronous messages. This is because threads spend a lot of time waiting for inbound or outbound operations to complete. Because the Messaging Engine is highly bound to the CPU, blocking the Messaging Engine thread degrades the performance of the adapters. The use of asynchronous transmissions is strongly encouraged and improves performance.
Asynchronous receive adapters	All receive adapters are asynchronous. This means when an adapter submits new messages to the BizTalk Messaging Engine it does not wait for them to be completely processed before returning.
Transactional support	Transactional adapter. Supports transactional send and receive of messages. On the send side, only asynchronous batched send adapters support transactions. Non-transactional adapter. An adapter that does not receive or send a message within the scope of an explicit transaction. Many adapters are non-transactional because they are sending to or from a system, such as the Windows file system, that does not support transactions.
Batch-supported send adapters versus batch-unsupported send adapters	Batch-supported adapter. The send adapter can process messages in batches of operations. All adapters can collect all of the messages available for submission, and then submit them to the MessageBox database all at once, thus reducing the number of necessary database updates. In some cases, this means that the length of the batch is one. Similarly, send adapters collect all of the messages that are available for sending, extract them, and then send them to their destination all at once. In general, BizTalk Server treats a batch as a unit of work for database updates. Within the same batch, adapters can submit one-way, request-response, and solicit-response messages; suspend messages; delete messages; request that a message be retried for transmission; or request that a message be moved to the backup transport. Wherever possible, you should use batched transmissions. Both send and receive adapters can be batched, but only batched asynchronous send adapters support transactions. Batch-unsupported adapter. Each message requires independent calls to the server.
Batch-supported receive adapters	All receive adapters support batching.
Dynamic versus static design-time adapter configuration	Dynamic Adapter Design-Time. For an adapter to support dynamic design-time configuration you must develop a custom user interface (UI) to work with the Add Adapter Metadata Wizard. This interface allows the user to select a schema to add to a BizTalk project and returns its service description through a Web Services Description Language (WSDL) file. The adapter provides a custom UI to obtain the schemas. When a service is imported through the Add Adapter Metadata Wizard, it adds port types, message types, and an orchestration to the BizTalk project in addition to schemas. For more information, see Static Design-Time Adapter Configuration. Static Adapter Design-Time. For an adapter to support static design-time configuration you implement standard interfaces to allow the Add Adapter Metadata Wizard to select a schema to add to a BizTalk project. The BizTalk Adapter Framework provides the UI for the adapter. For information about modifying the sample file adapter, see Dynamic Design-Time Adapter Configuration.
Transport adapters versus application adapters	Transport adapters. Transport adapters support a specific protocol and do not use a schema. Of the twelve native adapters, nine are transport adapters: MSMQ, MQ Series, File, FTP, HTTP, SMTP, POP3, and SOAP. Application adapters. Application adapters use data schemas to send data into the specified application. Of the native adapters, two are application adapters: Windows SharePoint Services and SQL.

For information about which interfaces to implement in your custom adapter code, use the link in the following table for the type of adapter you plan to create. In some cases, you will have to combine the interfaces listed to meet one requirement with the interfaces listed on a separate page to meet another requirement.

Variable	For more information
Send adapters	Instantiating and Initializing a Send Adapter
Synchronous	Interfaces for a Synchronous Send Adapter
Asynchronous	Interfaces for an Asynchronous Send Adapter
Synchronous batch-supported	Interfaces for a Synchronous Batch-Supported Send Adapter
Asynchronous batch-supported	Interfaces for an Asynchronous Batch-Supported Send Adapter
Transactional asynchronous batch-supported	Interfaces for a Transactional Asynchronous Batch-Supported Send Adapter
Solicit-response	Interfaces for a Solicit-Response Send Adapter
Receive adapters	Instantiating and Initializing a Receive Adapter
Regular	Interfaces for an In-Process Receive Adapter
Isolated	Interfaces for an Isolated Receive Adapter
Batch-supported	Interfaces for a Batch-Supported Receive Adapter
Transactional batch-supported	Interfaces for a Transactional Batch-Supported Receive Adapter
Synchronous request-response	Interfaces for a Synchronous Request-Response Receive Adapter

See Also

Developing Custom Adapters
Using Adapters
Adapter Samples - Development