Sending to a WCF Receive Adapter
by Dwight Goins
...and what the adapter does under the hood...
The WCF-Receive adapter creates a Service Host based class named BizTalkServiceInstance, which implements five service contracts: IOneWayAsync, IOneWayAsyncTxn, ITwoWayAsync, ITwoWayAsyncVoid, and ITwoWayAsyncVoidTxn (read the WCF White Paper for more information: http://www.microsoft.com/downloads/details.aspx?FamilyID=A976DC7D-2296-4F88-BE4D-0D314FCA9E59&displaylang=en).
These five service contracts are loosely designed, yielding, in some form or fashion, the basic Message In-Message Out design. In other words, the message is based on the raw System.ServiceModel.Channels.Message class. Each contract specifies whether transactions should be flowed, if a return message should be expected, if the IsOneWay attribute is applied, and/or what the action of the message should specify. The action for all the contracts is either "*" (asynchronous), or "BizTalkSubmit" (synchronous).
Of the five service contracts, only one contract matching the above need be exposed to the client for communication. The contract selected is based on the particular bindings specified inside the WCF Adapter settings. For example, if you specify a netMsmqBinding for the WCF Receive adapter, the BizTalkServiceInstance queries the binding elements and determines that the contract will be either IOneWayAsync or IOneWayAsyncTxn. Furthermore, if you enable Transactions on the netMsmqBinding, the contract used will be IOneWayAsyncTxn. What’s interesting about the implementation of the individual contracts is that all the synchronous calls throw a Not Supported exception, which means you can’t specify one of these contracts in a Client. In the case of the asynchronous calls, the message gets consumed, but never actually makes it to the MessageBox database.
In WCF, generally, you match the contract specified by the service host's ServiceType. In other words, the Service Contract in your client application that is sending a message to BizTalk should match one of the abovementioned five contracts, because the ServiceType of BizTalkServiceInstance implements all five service contracts. Normally, this is done by sharing the Contract. The problem here is that the BizTalk Team purposely doesn't want you to use any of these five contracts. If you try to use them, the BizTalk adapters throw Not Supported exceptions inside your client application.
Let’s say we have a WCF Receive Location with a default netTcpBinding:
There are many ways to send data to this service. One way is to use the WCF Publishing Wizard, and use a proxy class generated from the Add Service Reference or SvcUtil.exe tool. Another way is to take a more manual approach, one in which you create a wire matching contract that contains all the appropriate declarative markups for the Service and Operation contracts, and then create a binding collection that matches the receive location bindings. Third is the more advanced Raw WCF Model, loosely-coupled way. This method requires using the IRequestChannel (for two-way patterns), or the IOutputChannel (for one-way patterns), and using the Endpoint contracts to add the appropriate descriptions to match the Service and Operation contract markups, such as transaction flow, message action, reply action, etc.
The easiest way, without knowing anything about the WCF model, is to use the WCF Publishing Wizard to expose a Metadata Exchange Address (MEX address) for the receive location. The wizard will effectively create an IIS Virtual directory that allows the dynamic creation of a WSDL, which shows how to communicate with the netTcp WCF Receive adapter. When building a client using the Add Service Reference/SvcUtil.exe tool, a proxy class is generated. Interestingly, the proxy's implementation is based on the second way described above to send data to the WCF Receive Adapter. A custom service contract is created to match the wire compatible settings for the bindings, service, and operation contracts for the Receive Adapter, as shown below:
(WCF Service Publishing Wizard to create MEX address for the Receive Location)
(Message Contract will be based off of selected deployed BizTalk Schema)
(You can control the naming of the Soap Message, Operation, and Service for the WCF Receive Adapter)
(...a Client application can then use the SvcUtil.exe tool to generate a proxy class to communicate with the WCF Receive Adapter/Service)
(Inside a Client application, the proxy class, represented here as the London.cs file, can then be added to the project)
(Inside the London.cs file, the generated proxy source code creates a wire compatible interface named WCF_Service in this instance, along with the MessageTypes compatible parameters)
The second approach used by the automatic generated proxy is to create a custom contract, one in which you create a wire matching contract that contains all the appropriate declarative markups for the Service and Operation contracts, and create a binding collection that matches the receive location bindings. Some examples are shown here:
(Manually create a an interface, declared with the ServiceContract and an OperationContract, that contains an Action=*)
As for the final approach, you can use the IRequestChannel and IOutputChannel interfaces. These interfaces provide a more loosely-coupled, raw messaging pattern to send to the WCF Receive adapter/service. Using these interfaces, however, can be moderately challenging. The interfaces are not declared with the ServiceContract attribute, nor are the methods declared with the OperationContract. Another challenge is that these interfaces are declared within the Microsoft namespaces and assemblies, and therefore cannot be modified to include these attributes. Thus, we need a way to make these contracts wire compatible with what the WCF Receive Adapter/service expects.
Check back for a more detailed explanation of what this is and how it works. In the meantime, here is some sample code to tide you over:
(In this image, a client application manually creates a ChannelFactory instance, and dynamically adds the operation contract behaviors and descriptions to match that of the WCF Receive adapter/service, opens the channel, and sends the message).
About Dwight Goins...
Dwight Goins has more than 10 years of experience developing enterprise-level applications and teaching courses based on Microsoft products and technologies.
Prior to joining QuickLearn as an instructor, Dwight worked for Hewlett- Packard as a courseware developer and trainer with a specialization in Microsoft .NET application development. Over the last three years, Dwight has developed and delivered several .NET developer “road shows” for Microsoft at locations across the United States.
Dwight is a Microsoft Certified Trainer (MCT) and teaches C#, ASP.NET, AJAX, .NET Framework, XML/XSL, SQL Server, and advanced BizTalk Server training to developers worldwide. Dwight was also the lead author for the Microsoft BizTalk Server 2006 certification exam.
 |
BizTalk Administrator Training - QuickLearn, Inc.
Finally a BizTalk course that covers advanced BizTalk deployment and management topics. If your network administrator’s need to learn how to install, configure, deploy, monitor, and manage a BizTalk Server environment then this is the class you’ve been looking for. No other class on the market covers the advanced topics you need to know to become an effective administrator.
This is 5 days of training where you’ll participate in hands-on labs for multi-server installations, application deployment and management, trading partner integration, as well as disaster recovery. For more information please visit our website BizTalk for Administrators or call QuickLearn at 425-256-2573.
For a complete list of BizTalk courses visits www.quicklearn.com |
Take a New Look at BizTalkBlogs.com
Right before the holidays Microsoft quietly launched BizTalkBlogs.com. BizTalks Blogs is a blog aggregator bringing the most recent blog posts (from the most influential internal & external bloggers) about BizTalk, .NET Framework and other CSD technologies to one place.
You will find posts from Don Box, Scott Hanselman, Stephen Thomas, Aaron Skonnard and more. The site has received hundreds of visits since we launched in December.
Take a look at the site today and set up the RSS feed if you want to keep up on the latest Microsoft Connected Systems technology information
New R2 Training available on BizTalk-Training.com
Neal Walters, of http://BizTalk-Training.com released two new sets of Biztalk 2006/R2 videos this week, one course is an introduction to Biztalk, and the second is an advanced course covering Business Activity Monitoring (BAM).
The videos are now available online via an open source learning management system called Moodle. This allows students to submit questions and discuss topics in the videos. The intro course includes 116 videos, and the BAM includes 44.
Upgrades are available for past customers by contacting 214-403-6006. PDF files containing complete course outlines are available at http://BizTalk-Training.com.
Neal Walters is an MCT that has been teaching BizTalk classes since BizTalk 2000, he has currently spent the last 3.5 years doing Business Process Management (BPM) and BizTalk/SharePoint consulting.
Comments or Suggestions?
I welcome comments, questions, and suggestions. After all, this newsletter is about delivering content you want to hear about! Feel free to contact me through the forum or via e-mail.
Until next time...
Stephen W. Thomas -
BizTalkGurus.com
The Bottom Line:
Sometimes the road less traveled is that way for a reason. |
