|
Slide 37 -
|
Customizing and Extending the BizTalk WCF Adapters Stephen Kaufman
Delivery Architect
Microsoft Consulting Services
Session Code: INT401 Paolo Salvatori
Principal Program Manager
BizTalk Customer Advisory Team
Microsoft Session Objectives And Takeaways Session Objective(s):
Introduction to WCF Adapters
Extending WCF Adapters
Custom Service/Endpoint Behaviors
Custom Message Inspectors
Custom Binding Elements/Channels
Takeaways
Architecture of BizTalk WCF adapters
How to increase application functionality with the extensibility points provided by WCF Adapters
Agenda Brief Introduction to WCF\WCF Adapters
WCF Extensibility Points
Lots of Demos!
Debatching Custom Channel
Protocol Transition
Throw Typed Fault From an Orchestration
Large Message Transmission
Duplex Message Exchange Pattern
WCF LOB Adapter SDK: Echo Adapter The ABC of WCF WCF is a runtime and a set of APIs for exchanging messages between components and applications.
WCF was designed according to the tenets of service orientation.
WCF services can expose one or multiple endpoints.
Every endpoint is defined by 3 elements:
A: Address
B: Binding
C: Contract C B A WCF
Service C B A Client Contract
(what) Binding
(How) Address
(Where) WCF Architecture: Messaging Runtime The WCF runtime is divided into 2 primary layers:
The Service Layer aka Service Model defines the mechanisms and attributes used by developers to define and decorate service, message and data contracts.
The Messaging Layer is responsible for preparing a WCF message for transmission on the send side and produce a WCF message for the dispatcher on the receive side.
It’s the responsibility of the proxy/dispatcher components to translate between the two layers transforming .NET method calls into Message objects. WCF Binding Comparison Performance data was taken from:
Essential Windows Communication Foundation, Addison Wesley, 2008. Chapter 4 Agenda Brief Introduction to WCF\WCF Adapters
WCF Extensibility Points
Lots of Demos!
Debatching Custom Channel
Protocol Transition
Throw Typed Fault From an Orchestration
Large Message Transmission
Duplex Message Exchange Pattern
WCF LOB Adapter SDK: Echo Adapter BizTalkServiceInstance Each WCF Receive Location is hosted by a separate instance of a ServiceHost-derived class.
BtsServiceHost for RLs running in an in-process host
WebServiceHost for RLs running in an isolated host
For each WCF Receive Location, the WCF Receive Adapter creates a separate a singleton instance of the BizTalkServiceInstance class.
The class is decorated with the ServiceBehavior attribute:
InstanceContextMode = InstanceContextMode.Single
ConcurrencyMode = ConcurrencyMode.Multiple
Hence, all incoming messages to a WCF RL are received and processed by a single well-known instance of the BizTalkServiceInstance class.
This allows to avoid service activation/deactivation costs and improve performance/scalability. [ServiceBehavior(InstanceContextMode = InstanceContextMode.Single, ConcurrencyMode = ConcurrencyMode.Multiple)]
internal sealed class BizTalkServiceInstance : ITwoWayAsync,
ITwoWayAsyncVoid,
IOneWayAsync,
IOneWayAsyncTxn,
ITwoWayAsyncVoidTxn
{
...
} Generic Service Contracts The BizTalkServiceInstance class implements multiple untyped, generic service contracts.
IOneWayAsync
IOneWayAsyncTxn
ITwoWayAsync
ITwoWayAsyncVoid
ITwoWayAsyncVoidTxn
Each contract was designed for a different scope (as suggested by their name):
OneWay vs TwoWay Message Exchange Pattern
Transactional vs Non-Transactional Communication
All the methods exposed by these service contracts are generic, asynchronous and untyped
AsyncPattern = True indicates that an operation is implemented asynchronously using a Begin and End method pair in a service contract
Action = “*” means that the method accepts a message with any Action
ReplyAction = “*” means that the method can return a message with any Action
Every method accepts as parameter or returns a generic WCF Message
As a consequence, each WCF Receive Location can accept multiple message types and versions that can be normalized into a canonical format using a different map before being published to the MessageBox.
Also Send Ports are message-type agnostic.
One-Way WCF Receive Locations When you define a one-way WCF receive location:
If the RL uses the NetMsmqBinding, the underlying WCF service will expose an endpoint using IOneWayAsync.
If the RL uses any other binding, the underlying WCF service will expose an endpoint using ITwoWayAsyncVoid.
As consequence , a WCF client application cannot use a service contract with one-way operations to send messages to a WCF RL that uses a binding <> NetMsmqBinding . [ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface IOneWayAsync
{
[OperationContract(AsyncPattern = true, IsOneWay = true, Action = "*")]
IAsyncResult BeginOneWayMethod(Message message, AsyncCallback callback, object state);
[OperationContract(IsOneWay = true, Action = "BizTalkSubmit")]
void BizTalkSubmit(Message message);
void EndOneWayMethod(IAsyncResult result);
}
[ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface ITwoWayAsyncVoid
{
[OperationContract(AsyncPattern = true, IsOneWay = false, Action = "*", ReplyAction = "*")]
IAsyncResult BeginTwoWayMethod(Message message, AsyncCallback callback, object state);
[OperationContract(IsOneWay = false, Action = "BizTalkSubmit")]
void BizTalkSubmit(Message message);
void EndTwoWayMethod(IAsyncResult result);
} One-Way WCF Receive Locations The Raw Message Data are sent over the wire.
The Transport Channel receives and decodes the incoming stream of bytes and creates a WCF Message that is processed through the Channel Stack.
The WCF message is passed on to the Dispatcher
The WCF message is passed on to the BizTalkServiceInstance.
Based on the RL configuration, the entire SOAP Envelope, the Body of the SOAP message or a specific Xml Element is used as content of the BizTalk message.
The BizTalk message is processed through the pipeline.
A Map is eventually applied.
The BizTalk message is published to the MessageBox.
Available WCF Adapters The WCF-Custom and WCF-CustomIsolated adapters offer you complete control over the channel stack and behaviors configuration, and as a consequence, they are the only WCF adapters you really need.
The WCF-Custom/WCF-CustomIsolated Adapters allow to:
Implement and exploit extensibility points.
Have full access to properties exposed by bindings/behaviors.
Enable the use of the bamInterceptor endpoint behavior.
Export/Import the binding configuration.
Disable a receive location on failure.
Run an http-based RL within an in-process host.
Use bindings (e.g. wsDualHttpBinding) for which a WCF Adapter does not exist.
WCF-Custom\WCF-CustomIsolated Adapters WCF Adapter Extensibility Points Custom Behaviors
Service Behaviors
They enable the customization of the entire service runtime including the ServiceHost.
Endpoint Behaviors
They enable the customization of service endpoints and their associated EndpointDispatcher
Custom Binding Elements\ Channels
Binding Elements, Channels, ChannelFactories, Binding Element Extension...
Custom Bindings
The WCF LOB Adapter SDK allows developers to create new bindings to use with WCF-Custom and WCF-CustomIsolated Adapters. How to Enable the WCF Extensibility Points To enable the WCF extensibility points you have to perform 3 operations:
Install the assemblies implementing the WCF extensibility points in the global assembly cache (GAC)
Modify the machine.config file on your computers.
behavior extensions
binding element extensions
binding extensions
Configure the WCF-Custom or the WCF-CustomIsolated Receive Location or Send Port by using the BizTalk Server Administration console. Agenda Brief Introduction to WCF\WCF Adapters
WCF Extensibility Points
Lots of Demos!
Debatching Custom Channel
Protocol Transition
Throw Typed Fault From an Orchestration
Large Message Transmission
Duplex Message Exchange Pattern
WCF LOB Adapter SDK: Echo Adapter Debatching Channel Problem
How can I debatch an inbound message within a WCF-Custom Send Port and make a separate call for each item?
You will see:
How to enable extensibility points.
How to configure and use a custom binding.
How to create a transactional WCF-Custom Send Port.
How to enable WCF performance counters in the BTSNTSvc.exe.config.
How to use the serviceThrottling behavior on a WCF Receive Location.
How to use the Import/Export tab in a WCF-Custom RL/SP.
How to activate the net.tcp binding protocol for a IIS 7.0 hosted application.
Debatching Channel A WCF-BasicHttp or WCF-Custom Receive Location receives a new request message from the Test Agent.
The Message Agent submits the incoming message to the MessageBox.
The inbound request is consumed by a WCF-Custom Send Port.
The WCF-Custom Send Port uses a custom channel to debatch the inbound message and make a separate call for each operation item.
The WCF web service returns a response message. The custom channel repeats this pattern for each operation, collects results and creates a unique response message (Scatter and Gather).
The WCF-Custom Send Port publishes the response message to the MessageBox.
The response message is retrieved by the WCF-BasicHttp or WCF-Custom Receive Location.
The response message is returned to the Test Agent. Transactional Debatching Channel Debatching Channel Detail Debatching Channel demo Typed Faults Problem
How can I throw Typed Faults from Orchestrations Published as WCF Services ?
You will see:
How to configure and use a custom endpoint behavior.
How to configure and use a message inspector.
How to return a typed fault from an orchestration.
How analyzing incoming/outgoing message with the Service Trace Viewer.
How to extend the WSDL exposed by a WCF Receive Location.
How to use the bam Interceptor within a WCF-CustomIsolated RL.
How to use the performance counters exposed by the bam Interceptor. WCF and Typed Faults [Serializable]
[DataContract(Name = "CustomError", Namespace = "http://microsoft.biztalk.cat/10/customerror")]
public class CustomError
{
...
}
[ServiceContract(Name = "HelloWorld", Namespace = "http://microsoft.biztalk.cat/10/helloworld")]
public interface IHelloWorld
{
[OperationContract(Action = "SayHello", ReplyAction = "SayHello")]
[FaultContract(typeof(CustomError), Action = "CustomErrorFault")]
HelloWorldResponse SayHello(HelloWorldRequest request);
}
[ServiceBehavior(Name = "HelloWorld", Namespace = "http://microsoft.biztalk.cat/10/helloworld")]
public class HelloWorld : IHelloWorld
{
[OperationBehavior]
public HelloWorldResponse SayHello(HelloWorldRequest request)
{
if (request == null || string.IsNullOrEmpty(request.Name))
{
throw CreateFault("The name cannot be null or empty.");
}
return new HelloWorldResponse(string.Format("Hi {0}!", request.Name));
}
private FaultException CreateFault(string message)
{
...
return fault;
}
} BizTalk Server and Typed Faults BizTalk Server 2006 R2 and BizTalk Server 2009 allow handling typed fault contracts when consuming WCF services from within orchestrations.
WCF adapters actually do not support returning typed fault contract exceptions within orchestrations published as WCF services.
However, untyped SOAP faults can always be returned by orchestrations or pipelines.
Extending the WSDL How can you extend the WSDL generated by the WCF Service Publishing Wizard to expose soap fault messages?
There are 2 solutions:
Manual Approach
You define a custom WSDL using a text or xml editor.
You publish the resulting WSDLfile to IIS
You configure your WCF-Custom RL to expose the newly created WSDL file using the serviceMetadata behavior.
Create a custom endpoint behavior to dynamically modify the WSDL generated by BizTalk. WsdlExtensions Endpoint Behavior The WsdlExtensions property exposed by the endpoint behavior accepts an XML snippet that allows to specify how to customize the WSDL at runtime.
The prefix for the namespace of new messages created inside the WSDL.
One or multiple Xml Schemas each defining a different typed fault. These schemas must be deployed to BizTalk. At runtime, the component is able to retrieve the content of each schema from the BizTalkMgmtDb that subsequently is inserted in the outbound WSDL.
One or multiple fault messages, each containing one or multiple parts.
One or multiple operation-fault associations. At runtime the component search through the original WSDL structure and creates faults accordingly.
bts
CustomError
http://microsoft.biztalk.cat/10/customerror
HelloWorld_SayHello_CustomErrorFault_FaultMessage
http://microsoft.biztalk.cat/10/customerror
detail
CustomError
HelloWorld
SayHello
CustomErrorFault
HelloWorld_SayHello_CustomErrorFault_FaultMessage
Typed Faults A WCF-CustomIsolated Receive Location receives a request message from the Client App.
The Message Agent submits the incoming message to the MessageBox.
The inbound request starts a new instance of the HelloWorld orchestration.
If the name contained in the request message is null or empty, the orchestration returns a CustomError message containing context information.
The HelloWorld orchestration publishes the response or error message to the MessageBox.
The response message is retrieved by the WCF-CustomIsolated Receive Location.
The CustomErrorMessageInspector intercepts the response message and eventually creates a fault message.
The response message is returned to the Client Application. Typed Faults demo Duplex Message Exchange Pattern Problem
Can I use duplex message exchange pattern to invoke a WCF Receive Location?
You will see:
How to configure a Request/Response:
WCF-NetTcp Receive Location
WCF-NetNamedPiped Receive Location
WCF-CustomIsolated + WsDualHttpBinding
To support Duplex Message Exchange
How to configure the client app to send a request and expose a callback contract to asynchronously receive the response message.
Duplex Message Exchange Pattern Duplex Message Exchange Pattern demo Resources Stephen Kaufman’s Blog
http://blogs.msdn.com/skaufman
Paolo Salvatori’s Blog
http://blogs.msdn.com/paolos
Using the Windows Communication Foundation (WCF) Adapters in BizTalk Server
http://www.microsoft.com/downloads/details.aspx?familyid=a976dc7d-2296-4f88-be4d-0d314fca9e59&displaylang=en&tm
Microsoft BizTalk Server Performance Optimization Guide
http://msdn.microsoft.com/en-us/library/cc558617.aspx
Microsoft BizTalk Server Operations Guide
http://msdn.microsoft.com/en-us/library/cc296643.aspx question & answer www.microsoft.com/teched
Sessions On-Demand & Community http://microsoft.com/technet
Resources for IT Professionals http://microsoft.com/msdn
Resources for Developers www.microsoft.com/learning
Microsoft Certification & Training Resources Resources Required Slide
Speakers,
TechEd 2009 is not producing
a DVD. Please announce that
attendees can access session
recordings at TechEd Online. Complete an evaluation on CommNet and enter to win an Xbox 360 Elite! © 2009 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.
The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION. Required Slide
|