Implementing Adapter Outbound Message Exchange Handler

Article
05/06/2007

Scenario: Client executes a single synchronous outbound call in the target system using the adapter

Content

1) Adapter Developer Perspective: Implement execute() method in adapter implementation of IOutboundHandler

2) Adapter Consumer Perspective: Test Adapter Outbound Handler functionality

a. Using WCF Channel Programming

b. Using Add Adapter Service Reference Visual Studio Plug-In

c. Using Consume Adapter Service BizTalk Project Add-In

Each adapter implementation of outbound handler is going to be unique depending on the type of the target system it is implementing. Follow the standard .NET programming best practices to create code that uses best practices and design patterns. This class is responsible for the majority of the implementation of an adapter. The code snippets in this post use the standard .NET classes to process the Xml messages. In a future post, I will talk about how "Metadata Driven Adapter Data Reader / Writer" functionality provided by the Adapter SDK can be used by the Adapter Developer to process input/output WCF messages.

1) Implement execute() method in Adapter implementation of IOutboundHandler

The IOutboundHandler has one key method called

public Message Execute(Message message, TimeSpan timeout);

where,

message

Incoming WCF message. If the request message is larger that the maximum message size allowed by the binding being used, a QuotaExceededException is thrown. The maximum message size is set by the MaxReceivedMessageSize property. The default value is 65536 bytes.

timeout

Time interval within which this operation should be completed.

Notes to Adapter Developers: The operation should throw a TimeoutException if the specified timeout is exceeded before the operation is completed.

This method reads a WCF message and converts it to the target system request message format. It is responsible to return the correlated WCF message response within a specified interval of time. Here is a rudimentary sample implementation of execute() method using the Hello World example. In this sample, the implementation is being provided for method with signature: string SayHelloWorld(string aName); Remember the metadata for this operation is defined using implementations of Metadata Browse Handler and Metadata Resolver Handler.

#region IOutboundHandler Members

public Message Execute(Message message, TimeSpan timeout)

{

OperationMetadata om = this.MetadataLookup.GetOperationDefinitionFromInputMessageAction(message.Headers.Action, timeout);

if (om == null)

{

throw new AdapterException("Invalid operation " + message.Headers.Action);

}

switch (message.Headers.Action)

{

case "Hello/SayHelloWorld":

string outputValue = String.Empty;

// Input Message Format

// <SayHelloWorld><aName>{text}</aName></SayHelloWorld>

using (XmlDictionaryReader inputReader = message.GetReaderAtBodyContents())

{

// Read <Name>

inputReader.MoveToContent();

inputReader.ReadStartElement("SayHelloWorld");

inputReader.MoveToContent();

string inputValue = inputReader.ReadElementString("aName");

inputReader.MoveToContent();

inputReader.ReadEndElement();

for (int count = 0; count < this.Connection.ConnectionFactory.Adapter.Count; count++)

{

outputValue += (inputValue) + " says 'Hello World!'\n";

if (count < this.Connection.ConnectionFactory.Adapter.Count - 1)

{

outputValue += " ";

}

StringBuilder outputString = new StringBuilder();

XmlWriterSettings settings = new XmlWriterSettings();

settings.OmitXmlDeclaration = true;

// Create response message

XmlWriter replywriter = XmlWriter.Create(outputString, settings);

replywriter.WriteStartElement("SayHelloWorldResponse", HelloWorldAdapter.SERVICENAMESPACE);

replywriter.WriteElementString("SayHelloWorldResult", outputValue);

replywriter.WriteEndElement();

replywriter.Close();

// Write a trace entry

HelloWorldAdapterUtilities.Trace.Trace(TraceEventType.Verbose, "HelloWorldAdapterOutboundHandler::Execute", outputValue);

XmlReader replyReader = XmlReader.Create(new StringReader(outputString.ToString()));

// Output Message Format

// <SayHelloWorldResponse><SayHelloWorldResult>{Name}</SayHelloWorldResult></SayHelloWorldResponse>

// create output message

return Message.CreateMessage(MessageVersion.Default, om.OutputMessageAction, replyReader);

default: throw new AdapterException("Invalid Operation");

}

#endregion IOutboundHandler Members

Note the use of OperationMetadata in the above example. The instance of the operation metadata for the incoming operation can be obtained by using MetadataLookup property. When creating the response message (i.e. return Message.CreateMessage(…)), use OutputMessageAction property of Operation Metadata to get the result action for the response message.

Here is the sample implementation for execute() method in the DLL adapter. As you can see, the implementation can vary for each adapter.

public Message Execute(Message message, TimeSpan timeout)

{

// Retrieve metadata based on the request WCF Message action.

// Since we are in the context of the IOutputHandler, we retrieve

// the operation metadata based on the Output Message Action.

MyExistingLibraryOperationMetadata operationMetadata =

(MyExistingLibraryOperationMetadata)this.MetadataLookup.GetOperationDefinitionFromInputMessageAction(message.Headers.Action, timeout);

if (operationMetadata == null)

{

throw new AdapterException("Invalid Operation");

}

// parse input message

Dictionary<string, object> parmValues = new Dictionary<string, object>();

this.Parse(message.GetReaderAtBodyContents(), operationMetadata, true, out parmValues);

// invoke the method

Dictionary<string, object> outParmValues = null;

Object returnObject = this.ProcessMessage(operationMetadata, parmValues, out outParmValues);

// build result

return this.GenerateMessage(message, operationMetadata, returnObject, outParmValues, true);

}

Here is a code snippet of one of the functions - ProcessMessage used by the execute() function. In this sample implementation, this function uses the .NET reflection API methods to invoke the function on the DLL.

/// <summary>

/// Invoke the operation on the target information system.

/// </summary>

/// <param name="operationMetadata"></param>

/// <param name="parameterValues"></param>

/// <param name="outParameters"></param>

/// <returns></returns>

internal object ProcessMessage(MyExistingLibraryOperationMetadata operationMetadata,

Dictionary<string, object> parameterValues,

out Dictionary<string, object> outParameters)

{

Type type = operationMetadata.Type;

MethodInfo methodInfo = operationMetadata.MethodInfo;

List<object> values = new List<object>();

foreach (object parmValue in parameterValues.Values)

{

values.Add(parmValue);

}

// create an instance of the object

object anObject = Activator.CreateInstance(type);

try

{

object result = type.InvokeMember(methodInfo.Name, BindingFlags.Default | BindingFlags.InvokeMethod, null, anObject, values.ToArray());

outParameters = new Dictionary<string, object>();

outParameters.Add(result.ToString(), result);

return result;

}

catch (MissingMethodException e)

{

throw new AdapterException("Mismatch between what's supplied in input and what the operation is expecting. " + e.Message);

}

2) Test Adapter Outbound Handler functionality

a. Using WCF Channel Programming

This method shows how Adapter’s Outbound Handler functionality can be called using WCF channel programming.

public class Program

{

static void Main(string[] args)

{

// instantiate the binding

HelloWorldAdapterBinding binding = new HelloWorldAdapterBinding();

// set the custom binding property

binding.Count = 4;

binding.OverrideWsdlBuilder = true;

// Create EndpointAddress

EndpointAddress address = new EndpointAddress("hello://");

// create channel factory using channel shape IRequestChannel

IChannelFactory<IRequestChannel> requestChannelFactory = binding.BuildChannelFactory<IRequestChannel>();

// open channel factory

requestChannelFactory.Open();

// create channel

IRequestChannel requestChannel = requestChannelFactory.CreateChannel(address);

// open channel

requestChannel.Open();

// create WCF request message

Message requestMessage = CreateSayHelloWorldRequestMessage();

// Send the WCF request message and receive the WCF response message.

Message responseMessage = requestChannel.Request(requestMessage);

// Display the response message content

XmlReader responseReader = responseMessage.GetReaderAtBodyContents();

Console.WriteLine(responseReader.ReadOuterXml());

Console.WriteLine();

Console.WriteLine(responseReader.ReadString());

Console.WriteLine();

// close channel

requestChannel.Close();

// close channel factory

requestChannelFactory.Close();

}

/// <summary>

/// Create WCF Request Message

/// </summary>

/// <returns>WCF Request Message</returns>

private static Message CreateSayHelloWorldRequestMessage()

{

// Create WCF Request Message

// Create and send the request message as the channel is now ready for the

// request/response message exchange. Construct a simple XML document that will

// contain a name passed in from the command argument.

String input = "<SayHelloWorld><Name>" + "John" + "</Name></SayHelloWorld>";

// set action string

Message requestMessage = Message.CreateMessage(MessageVersion.Default

, "Hello/SayHelloWorld"

, XmlReader.Create(new System.IO.StringReader(input)));

return requestMessage;

}

Here is the expected output, when this console program is run.

<SayHelloWorldResponse xmlns="hello://Microsoft.WCF.Samples.Adapters"><SayHelloW

orldResult>John says 'Hello World!'

John says 'Hello World!'

</SayHelloWorldResult></SayHelloWorldResponse>

Press any key to continue . . .

b. Using Add Adapter Service Reference Visual Studio Plug-In

Right-click on a VS Project (Console Application, Windows Application, Web Application, Class Library, etc.) and select “Add Adapter Service Reference…”. This will bring up the Add Adapter Service Reference UI. Once the adapter binding is registered with the WCF configuration system, the adapter binding will show up in the Select a binding drop down box. Select your adapter binding, enter Connection Uri and click on Connect. If the connection is successful, you should be able to see the browse results in left-hand tree pane labeled as Select a category.

Select the operation and click on OK. This should generate a proxy in the project from where Add Adapter Service Reference Visual Studio Plug-In was invoked along with the app.config.

Generated app.config

<?xml version="1.0" encoding="utf-8"?>

<system.serviceModel>

<binding name="HelloWorldAdapterBinding" closeTimeout="00:01:00"

openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00"

count="3" />

</helloWorldBinding>

</bindings>

<endpoint address="hello:/" binding="helloWorldBinding" bindingConfiguration="HelloWorldAdapterBinding"

contract="HelloWorld" name="HelloWorldAdapterBinding_HelloWorld" />

</client>

</system.serviceModel>

</configuration>

Generated proxy file

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]

[System.ServiceModel.ServiceContractAttribute(Namespace="hello://Microsoft.WCF.Samples.Adapters", ConfigurationName="HelloWorld")]

public interface HelloWorld {

[System.ServiceModel.OperationContractAttribute(Action="Hello/SayHelloWorld", ReplyAction="Hello/SayHelloWorld/response")]

string SayHelloWorld(string aName);

}

[System.Diagnostics.DebuggerStepThroughAttribute()]

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]

public partial class HelloWorldClient : System.ServiceModel.ClientBase<HelloWorld>, HelloWorld {

public HelloWorldClient() {

}

public HelloWorldClient(string endpointConfigurationName) :

base(endpointConfigurationName) {

}

public HelloWorldClient(string endpointConfigurationName, string remoteAddress) :

base(endpointConfigurationName, remoteAddress) {

}

public HelloWorldClient(string endpointConfigurationName, System.ServiceModel.EndpointAddress remoteAddress) :

base(endpointConfigurationName, remoteAddress) {

}

public HelloWorldClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress) :

base(binding, remoteAddress) {

}

public string SayHelloWorld(string aName) {

return base.Channel.SayHelloWorld(aName);

}

Using generated proxy in a sample console application

From adapter consumer, using a proxy is way simpler than accessing the adapter using the channel client as shown in the previous example.

class Program

{

static void Main(string[] args)

{

HelloWorldClient proxy = new HelloWorldClient("HelloWorldAdapterBinding_HelloWorld");

Console.WriteLine(proxy.SayHelloWorld("John"));

}

Here is the expected output, when this console program is run.

John says 'Hello World!'

Press any key to continue . . .

c. Using Consume Adapter Service BizTalk Project Add-In

Create a BizTalk Project in Visual Studio for experiencing Consume Adapter Service BizTalk Project Add-In. Right-click on this project, select “Add Generated Items > Consume Adapter Service …”. This will bring up the Consume Adapter Service UI. This UI has same browse behavior as the Add Adapter Service Reference UI with the exception that click on OK after selecting operations generates Schemas instead of a .NET proxy. In addition to the schema files, a port configuration XML file will be generated, which can be imported in the BizTalk Administration Console to configure a BizTalk Send Port.

Generated Schema File

<xs:schema xmlns:tns="hello://Microsoft.WCF.Samples.Adapters" xmlns:b="https://schemas.microsoft.com/BizTalk/2003" elementFormDefault="qualified" targetNamespace="hello://Microsoft.WCF.Samples.Adapters" version="1.0" xmlns:xs="https://www.w3.org/2001/XMLSchema">

<xs:element name="SayHelloWorld">

<xs:annotation>

<xs:documentation>

<doc:action xmlns:doc="https://schemas.microsoft.com/servicemodel/adapters/metadata/documentation">Hello/SayHelloWorld</doc:action>

</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="1" maxOccurs="1" name="aName" nillable="true" type="xs:string">

<xs:annotation>

<xs:documentation>Hello World is said by this name.</xs:documentation>

</xs:annotation>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="SayHelloWorldResponse">

<xs:annotation>

<xs:documentation>

<doc:action xmlns:doc="https://schemas.microsoft.com/servicemodel/adapters/metadata/documentation">Hello/SayHelloWorld/response</doc:action>

</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element minOccurs="1" maxOccurs="1" name="SayHelloWorldResult" nillable="true" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Once the schema files are generated, these schemas can be used within the BizTalk Orchestration. The logical Send Port(s) and/or Receive Port(s) can be defined using the standard BizTalk port creation mechanism. The generated port configuration file can be imported into the BizTalk Administration Console to configure the physical ports with BizTalk WCF Adapter configuration information.

Implementing Adapter Outbound Message Exchange Handler

Additional resources