Tutorial 1: Develop the Echo Adapter

In this tutorial, you will develop a functional adapter using the WCF LOB Adapter SDK. The adapter simulates the operations of a fictitious line-of-business system to illustrate many of the key features of the WCF LOB Adapter SDK including:

Synchronous Inbound
Synchronous Outbound
Metadata Browse
Metadata Search
Metadata Resolve

This section contains various features supported by the echo adapter. They are message exchange, operation metadata, connection properties, and adapter properties.

Message Exchange Patterns

The echo adapter supports the following two message exchange patterns:

Synchronous outbound, that is, the consuming client sends the WCF request message via the adapter to the target system, and then waits to receive a WCF response message from the target system via the adapter. This is the most common message exchange pattern for an adapter. To support synchronous outbound, implement the IOutboundHandler interface.
Synchronous inbound, that is, the consuming client listens for data or events from the target system via the adapter. To support synchronous inbound, implement the IInboundHandler interface.

For more information about the message exchange patterns, see Using Messaging Components.

Note
The Adapter Development Wizard shows the message exchange pattern as data flow in the UI.

Metadata Support

The echo adapter supports metadata browsing, searching, and resolving capabilities. Typically, the browsing and searching retrieve operations from an LOB system. For the echo adapter, an LOB system is a set of predefined operations, as shown below:

EchoMainCategory
        Echo/EchoStrings
        Echo/EchoGreetings
        Echo/EchoCustomGreetingFromFile
        Echo/OnReceiveEcho

The following is the definition of each operation:

Name	Operation Definition	Description	Direction
EchoMainCategory	Category	Categorizes the operations.	N/A
Echo/EchoStrings	string[] EchoStrings(string data)	Echoes the incoming string a specified number of times to the calling client.	Outbound
Echo/EchoGreetings	Greeting[] EchoGreetings(Greeting greeting)	Echoes the incoming Greeting object a specified number of times to the calling client.	Outbound
Echo/EchoCustomGreetingFromFile	CustomGreeting EchoCustomGreetingFromFile(Uri greetingInstancePath)	Echoes the Greeting object by reading its instance from a file. The Greeting object's metadata is obtained from a predefined XSD file.	Outbound
Echo/OnReceiveEcho	void OnReceiveEcho(Uri path, long content)	Echoes the location and length of a file dropped in the specified folder.	Inbound

Adapter Properties

The adapter exposes the following adapter properties.

Name	Category	Data Type	Description
Count	Misc	Int32	Used to echo the input the specified number of times to the calling client. Default = 5
EnableConnectionPooling	Misc	Boolean	Used to enable or disable connection pooling for the adapter. Default = true, meaning that the connection pooling is enabled in runtime engine of the WCF LOB Adapter SDK.
InboundFileFilter	Inbound	String	Used for the inbound scenario only and used by the FileSystemWatcher to monitor the files of the extension. Default=*.txt
InboundFileSystemWatcherFolder	Inbound	String	Used to set the folder where the files will be dropped for FileSystemWatcher to raise notification to the adapter. Default = c:\inbound\watcher.

Connection Properties

The echo adapter exposes the following connection properties.

Name	Data Type	Description
Application	String	The application name within the LOB system. This property is for illustrative purpose. The echo adapter does not involve any LOB system. Default = lobapplication
EnableAuthentication	Boolean	When true, the adapter expects a value in the username field within the client credentials. Default = false
Hostname	String	The server name where an LOB system resides. This property is for illustrative purpose. The echo adapter does not involve any LOB system. Default = lobhostname

Name

Data Type

Description

Application

String

The application name within the LOB system. This property is for illustrative purpose. The echo adapter does not involve any LOB system.

Default = lobapplication

EnableAuthentication

Boolean

When true, the adapter expects a value in the username field within the client credentials.

Default = false

Hostname

String

The server name where an LOB system resides. This property is for illustrative purpose. The echo adapter does not involve any LOB system.

Default = lobhostname

Interface Implementation

The WCF LOB Adapter SDK defines a collection of classes and interfaces that must be implemented to support specific features of the adapter. The following table describes those classes and interfaces, their descriptions, and when to implement them.

Class/Interface	When to implement	Description
IConnection	If you need to define the connection to the target system.	Defines the connection to the target system.
IConnectionFactory	If you need to create a connection to the target system.	Creates the connection to the target system.
ConnectionUri	If you need to manage a connection Uri. If you need to categorize connection property within the Add Adapter Service Reference Plug-in tool.	Manages a connection Uri for the target system.
IMetadataResolverHandler	Your adapter must support metadata resolve capability.	Resolves operation and type metadata.
IMetadataSearchHandler	If your adapter supports metadata search capability.	Searches for the operations within the target system.
IMetadataBrowseHandler	Your adapter must support browse capability	Browses for the operations within the target system.
IOutboundHandler	If your adapter typically needs to support outbound capability.	Transforms the incoming WCF request message into a target system message, invokes target system specific function, and then transforms the response into an outgoing WCF response message.
IInboundHandler	If your adapter supports inbound capability.	Listens for data and/or events from the target system.

To simplify your adapter development, use the Adapter Development Wizard to generate your adapter project, which creates a set of derived classes tailored to your adapter features.

To customize the adapter and connection properties through the Add Adapter Service Reference Plug-in and Consume Adapter Service Add-in tools, modify the following files generated by Adapter Development Wizard.

{Projectname}BindingElement.cs
{Projectname}BindingElementExtensionElement.cs
{Projectname}ConnectionUri.cs

For details on how to do so, see Step 2: Categorize the Adapter and Connection Properties.

Concepts

WCF LOB Adapter SDK Tutorials