Using Adapter Development Wizard
After WCF LOB Adapter SDK is installed on the system, the Adapter Developer can use the WCF LOB Adapter Development Wizard within Microsoft Visual Studio 2005 to create skeleton code for a new adapter. To invoke the wizard, select File > New > Project > Visual C# > WCF LOB Adapter. This will bring up a dialog box that will guide the user through a few pages and generate a bunch of classes. At a high level, the user need to provide the following information –
1) Provide scheme, project namespace and service namespace
|
Scheme |
Represents the URI scheme for the transport protocol in use on the adapter binding. For example – WCF NetTcpBinding uses “net.tcp” and WSHttpBinding uses “http” as the scheme.
|
|
Project Namespace |
Generated adapter classes are defined within this project namespace. For example – Microsoft.WCF.Samples.AdapterSDK |
|
Service Namespace |
Depicts the namespace for the WSDL generated by the adapter metadata retrieval classes. For example – myadapter://Microsoft.WCF.Samples.AdapterSDK. |
2) Select message exchange patterns supported by the adapter
|
Synchronous Outbound |
Support one-way send or request/response message exchange pattern |
|
Asynchronous Outbound |
Asynchronous flavor of Outbound message exchange pattern |
|
Synchronous Inbound |
Support one-way receive or reply message exchange pattern |
|
Asynchronous Inbound |
Asynchronous flavor or Inbound message exchange pattern (not supported in ASDK Beta 2) |
3) Select metadata browsing and harvesting patterns supported by the adapter
|
Metadata Browse |
Allow browsing of the existing system metadata where some meaningful categorization is possible. For more detail, see this post. |
|
Metadata Search |
Allow searching of the metadata in systems where unfiltered metadata is too large. For more detail, see this post. |
|
Metadata Retrieval |
Allow retrieval of a WSDL/Service Contract from selected metadata after a browse and/or a search function. For more detail, see this post. |
4) Specify adapter properties
The properties defined on this page are exposed as WCF Binding Properties and can be set programmatically or application configuration files in WCF client.
See this post for information on how to surface adapter settings as adapter binding properties.
5) Specify connection properties
The properties defined on this page are used within the Connection Uri String used to connect to the target LOB system. These properties can be configured at design time using Add Adapter Service Reference Visual Studio Plug-In/Consume Adapter Service BizTalk Project Add-In > Configure > Uri Properties. At run-time these properties can be set within the Uri used to build the service endpoint address.
The following figure graphically shows high level functionality buckets within an adapter.
If we were to create an adapter called MyLegacyAdapter for an existing legacy application, the following diagram shows the components that an Developer Developer is expected to provide implementation for.
The following table provides high level description of the classes generated by the Adapter Code Generation Wizard.
|
Category |
Class Name |
Description |
|
WCF Transport Binding Element |
MyLegacyAdapter |
Adapter exposed as a WCF transport channel. This is used to configure and construct adapter channel factories and channel listeners.
The Adapter Binding Properties are defined within this class. |
|
WCF Binding Configuration |
MyLegacyAdapterBinding |
Class to surface Adapter as a WCF binding. A WCF binding is used to specify the transport, encoding and protocol details required for clients and services to communicate with each other. This class implements CreateBindingElements() method to add adapter transport channel in the binding.
It also contains three metadata related properties – SupportsMetadataBrowse, SupportsMetadataGet and SupportsMetadataSearch.
The Adapter Binding Properties are defined within this class. The properties are set into Adapter class from this class. |
|
MyLegacyAdapterBindingCollectionElement |
Class to register the Default Adapter Binding with WCF configuration system.
<system.serviceModel>
<extensions>
<bindingExtensions>
<add name="MyLegacyAdapterBinding" type="MyLegacyAdapterBindingCollectionElement,{Assembly}" />
</bindingExtensions>
</extensions>
</system.serviceModel> |
|
MyLegacyAdapterBindingElement |
Class to define a binding configuration element to specify the Default Adapter Binding. It implements InitializeFrom() and OnApplyConfiguration() methods to map the binding with the configuration properties.
The Adapter Binding properties are read/written to configuration system within this class. |
|
MyLegacyAdapterBindingElementExtension |
Class to surface Adapter as a WCF binding element extension within WCF configuration for use within a WCF-Custom binding.
<system.serviceModel>
<extensions>
<bindingElementExtensions>
<add name="MyLegacyAdapterBindingElement" type="MyLegacyAdapterBindingElementExtension, {Assembly}" />
</bindingElementExtensions>
</extensions>
</system.serviceModel>
The Adapter Binding Properties are defined within this class. |
|
Connectivity |
MyLegacyAdapterConnection |
Encapsulates the native communication API and/or protocols for interaction with the target system. It defines low-level communication contract with the existing applications. |
|
MyLegacyAdapterConnectionFactory |
This class follows a factory pattern and creates a connection to the target system. It also establishes a Connection Pool based on the Connection Uri and Client Credentials. |
|
MyLegacyAdapterConnectionUri |
Class to build and parse the connection string for the target system. It exposes a standard Uri class to the adapter clients. The adapter writer implements the parse and build methods provided within this class.
The Adapter Connection Properties are defined within this class. |
|
Metadata Exploring and Harvesting |
MyLegacyAdapterMetadataBrowseHandler |
Class to implement adapter metadata browse functionality |
|
MyLegacyAdapterMetadataSearchHandler |
Class to implement adapter metadata search functionality |
|
MyLegacyAdapterMetadataResolverHandler |
Class to implement adapter metadata resolution functionality |
|
Message Exchange Flow |
MyLegacyAdapterOutboundHandler |
Class to implement adapter outbound message exchange pattern |
|
MyLegacyAdapterAsyncOutboundHandler |
Class to implement adapter asynchronous outbound message exchange pattern |
|
MyLegacyAdapterInboundHandler |
Class to implement adapter inbound message exchange pattern |
|
MyLegacyAdapterAsyncInboundHandler |
Class to implement adapter asynchronous inbound message exchange pattern |
|
Tracing |
MyLegacyAdapterTrace |
Initializes with the adapter trace source and provides a utility trace method for implementing tracing. |
Once you have these classes generated, get started with implemening connectivity, metadata handlers (browse/search/resolver) and message exchange handlers (inbound, outbount, asynch inbound, asynch outbound). The adapter developer can also provide support for transactions and reliable messaging using the standard .NET framework as long as the target system has equivalent support. At minimum, the Adapter Developer needs to implement the following:
Enjoy developing your adapter. Let your clients use the same adapter using standard WCF service-oriented interfaces in variety of applications - Windows Console Application, Windows Forms Application, BizTalk Application Server, ASP.NET Web Applications, Windows Workflow Foundations, etc. If a client doesn't supprt WCF (e.g. non windows application or clients where .NET 3.0 is not installed and configured), the consumer-driven contracts/proxy generated from the adapter can be published as a Web Service for consumpton by these clients. Widen the reach of your adapters!!!
