Share via

Using Custom Behaviors with the BizTalk WCF Adapters, Part 1

  • Article

Using Custom Behaviors with the BizTalk WCF Adapters, Part 1

Microsoft Corporation
Published: January 2009
Author: Michael McKeown
Contributors: Hanu Awasthy, Sarathy Sakshi, John Taylor

Summary

You can customize message processing in Microsoft® BizTalk® Server 2006 R2 by using [[Windows Communication Foundation]] (WCF) custom behaviors. This white paper is the first of two parts discussing how using [[WCF]] custom behaviors within BizTalk Server gives you increased control over the message transmission process.

Microsoft Corporation
January 2009

Customization of message processing in Microsoft® BizTalk® Server 2006 R2 can be extended through the use of Windows Communication Foundation (WCF) custom behaviors. This article is the first of two parts discussing how the use of WCF custom behaviors within BizTalk Server gives increased control over the message transmission process.

Download Center

You can download this article from http://go.microsoft.com/fwlink/?LinkId=129615.

You can download part 2 of this article from http://go.microsoft.com/fwlink/?LinkId=120275.

Applies To

BizTalk Server 2006 R2 and the WCF adapters

One of the advantages of using Windows Communication Foundation (WCF) as a message communication mechanism is the opportunity to extend the functionality of its services by using custom code. There are different points within the flow of a WCF message to intercept the message and execute custom processing before the message reaches its final destination. WCF custom behavior extensions are one such type of interception mechanism, and can be used to extend WCF service or client functionality at different levels of granularity.  In this paper, we will discuss the different types of WCF behaviors and where you can interject their processing within the WCF architecture. We will discuss how the BizTalk WCF-Custom and WCF-CustomIsolated adapters enable you to use a WCF custom behavior extension. 

WCF Custom Behaviors

The ability to easily implement custom processing in a call to a WCF service is one of the main reasons why WCF is such a rich programming paradigm compared to other ways of communication between Web applications. This custom processing can take almost any form as dictated by extensibility requirements within a Web application. For instance, behaviors can supplement normal message processing, modify the message during processing, scrutinize certain configuration criteria and take appropriate action, validate identities of the caller and pass the message on if it is successful, and so on. It is truly a custom processing mechanism, so you can implement whatever extensibility you feel your application needs.

Behavior extensions are one of the components that differentiate WCF from other Web services technologies in the market. By using this feature, developers can add custom extensions that inspect and validate service configuration or modify run-time behavior in WCF client and service applications. Custom behavior extensions can exist at both the WCF service and client levels. Configuring a behavior on the call stack to a WCF service has no influence on the communication binding used to make the call. In fact, behaviors are typically invisible to the client because they are not displayed in the metadata that a service publishes. The client typically has no idea that the extensions are running during a call to a WCF operation. 

BizTalk Pipelines or WCF Custom Behaviors

Upon initial inspection, a WCF custom behavior is very much like a traditional BizTalk pipeline. Both leverage the basic concept of message interception to interrupt the flow of a message to its destination, execute some custom message processing on the message, and forward it on to its destination. This interception can occur both before (bound to a receive location) or after (bound to a send port) a message has been processed by BizTalk Server. How this interception occurs within pipelines and custom behaviors differs not only in implementation but also from within the point of interception. Here are just a few of the differences:

  • Pipelines can be used by an orchestration. WCF behaviors can be called only by the adapter.
  • Pipelines are an older technology limited to BizTalk Server. WCF behaviors can be used by BizTalk Server, and can also be used in other pure WCF scenarios.
  • Pipelines live within set pipeline stages, such as Decode and Validate. WCF behaviors can be plugged into the message flow at any of its four interception entry points (described in the following section).
  • Pipelines are purely runtime in their functionality. While WCF behaviors are also runtime, they can also enforce relational or data constraints upon the values set during configuration from within the BizTalk Server Administration console.
  • Pipelines can operate on a BizTalk message context. WCF behaviors operate on a WCF context.

Behavior Interception Levels

There are four levels within the WCF service architecture at which you can apply a custom behavior. At each level, the methods in which you define the interception behavior are different depending upon their ordering in the service functionality hierarchy. These levels of interception are Service, Endpoint, Contract, and Operation. The highest level of interception is that of the service itself, where the capabilities of the entire service can be extended. Unlike the other three types of behaviors, a Service-level custom behavior applies only to WCF service applications and not to WCF client applications. Custom behaviors at the Service level apply to all of the endpoints exposed by the service. However, because a service can expose multiple endpoints, you may want to extend only some of them and not others. This gives us the next level of interception at the individual Endpoint level. This allows interception for certain endpoints within the service and not for others. Endpoints expose contracts, and custom behaviors can also be applied at the individual Contract level. A WCF contract is a group of related one- or two-way message exchange operations. If you require access to the lowest level of a WCF call, you can use custom behaviors at the Operation level.

Within BizTalk Server, the only two WCF adapters that allow you to configure and use custom WCF bindings are the WCF-Custom and WCF-CustomIsolated adapters. These two adapters differ primarily in their hosting locations. WCF-Custom is hosted within the BizTalk Server process, while WCF-CustomIsolated runs within the Internet Information Services (IIS) process. Both of these adapters provide a user interface (UI) to allow you to select either an Endpoint behavior or a Service behavior. There is not BizTalk Server UI support to configure custom WCF behaviors written to run at either the Contract or Operation level.

Behavior Extensions and BizTalk Server

One of the featured deliverables for the R2 release of BizTalk Server is the set of WCF adapters. These adapters allow BizTalk Server to call existing WCF applications from an orchestration, or to expose an orchestration as a WCF service to be called by a client. Orchestrations are not required for WCF adapters to interact with WCF because you can use pure WCF messaging with a receive location and a send port. However, with the BizTalk WCF Service Publishing Wizard you typically will expose an orchestration with a WCF adapter.

By configuring a WCF adapter to use a WCF custom behavior, the behavior functionality will be invoked when the call comes into the BizTalk adapter. If the behavior’s processing of the message does not result in a positive response, the message is not allowed to be posted to a receive location. The message thus gets rejected at the transport level and is not preserved. For instance, you could check the identity of the caller posting the message to the BizTalk receives location against a list of allowed groups. The administrator can configure the group names in the property pages of the WCF behavior tab. The behavior custom code can read those groups and check access against the groups with which the identity is associated. The identity of the logged-in user is sent as part of the WCF call in the SOAP headers. That identity can be authenticated at either the transport layer or the message layer depending on the configuration. If that identity is in one of the allowed groups, the call is allowed to pass through to the receive location.

WCF custom behaviors are connected to BizTalk Server though the WCF Adapters configuration options in the BizTalk Server Administration console.

To allow the custom behavior to be visible to the WCF adapter’s configuration, you must add an entry similar to the following in the <extensions> section of the machine.config file:

<system.serviceModel>
     <extensions>
          <behaviorExtensions>
               <add name="BizTalkAuth" type="Microsoft.Samples.BizTalk.Adapters.WCFAuthorization.BizTalkWCFAuthElement, WCFAuthorization, Version=1.0.0.0, Culture=neutral, PublicKeyToken=85b32fccee4970f5"/>
          </behaviorExtensions>
     <extensions>
<system.serviceModel>

The name BizTalkAuth is given in the preceding section and will be used to subsequently identify the service extension inside the WCF adapter’s property pages. The type is a combination of the namespace of the behavior assembly (Microsoft.Samples.BizTalk.Adapters.Authorization), and the class (BiztalkWCFAuthElement) that derives from BehaviorExtensionElement. This is a class that represents a configuration element and its subelements that define behavior extensions to allow service behaviors to be customized. WCFAuthorization is the name of the assembly along with its public key token, as they exist in the GAC.

Conclusion

We have discussed what a WCF custom behavior is and how it can be used under BizTalk Server. A WCF behavior can intercept the message flow at different levels. There are similarities and differences between a WCF behavior and a BizTalk pipeline, and we compared the two technologies. We looked at how BizTalk Server uses a WCF custom behavior by the WCF adapters. WCF behaviors are an extensibility option for BizTalk applications to do custom processing of a WCF message before it gets to the actual adapter. Whatever custom authorization scheme works for your application, you can model it through a custom behavior. In the next part of this article, we will show you how to write a custom behavior and configure it to work under BizTalk Server. This behavior uses a custom authorization scheme to decide if the incoming WCF message should be passed to the adapter, and then to BizTalk Server, for processing, or rejected before it even gets to the adapter.

See Also

Another important place to find a huge amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.