Using Custom Behaviors with the BizTalk WCF Adapters, Part 2

Using Custom Behaviors with the BizTalk WCF Adapters, Part 2

Microsoft Corporation

Published: January 2009

Author: Michael McKeown

Contributors: Hanu Awasthy, Sarathy Sakshi, John Taylor

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 second 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=120275.

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

You can download the sample from http://go.microsoft.com/fwlink/?LinkId=139693. Complete instructions for its configuration and execution are available in the sample’s download package.

Applies To

BizTalk Server 2006 R2 and the WCF adapters

In the first part of this two-part series, we described what constitutes a Windows Communication Foundation (WCF) custom behavior. We discussed how a WCF behavior can be configured to run with a WCF adapter under BizTalk Server. We looked at how a WCF behavior under BizTalk Server is similar, yet different, from a BizTalk pipeline.

In this second part of the series, we will outline the creation and configuration of a WCF behavior extension running under BizTalk Server. We implement a simple security check based upon the equality of two input parameters. (In a real application, this check might be to verify if the identity of the WCF client exists in a certain Windows user group. Based upon inclusion within the user group, the forwarding of the WCF message to the WCF adapter is allowed based upon membership.) The input parameters are sent to the WCF behavior from the WCF client code, which creates a client-based authorization scheme. Alternatively, the parameters can be set by using the WCF adapter’s property page under the BizTalk Server Administration console for the WCF custom behavior. In either case, if the parameters are equal, the incoming message is allowed to go to the WCF adapter, and then to the BizTalk MessageBox database. A FILE send port subscription gets the message, and a map using the Concatenation function combines the two equal strings into one and writes the single string to a designated output folder. If the parameters are not equal, the incoming message is rejected and an exception is thrown.

This code illustrates two primary, yet unrelated, important concepts:

· How a WCF custom behavior intercepts an incoming WCF message before it gets to the WCF-Custom adapter. Custom processing in that behavior decides whether the message is rejected or passed on to BizTalk Server.

· How the functionality of a BizTalk send port and its associated maps and schemas can appear as a WCF service to a WCF client.

Developing the WCF Custom Behavior Solution

This paper further elaborates upon the documentation provided with the sample and makes every attempt not to be redundant with the sample’s documentation. For maximum understanding, before you continue reading this document, download the sample, read the documentation file, and install, build, configure and run the sample successfully.

The WCFCustomBehavior solution consists of three projects that we will now discuss: BizTalkArtifacts, WCFClient, and WCFCustomBehavior.

Exposing WCF Service Functionality with the BizTalkArtifacts Project

The BizTalkArtifacts project contains an input and output schema, along with a map to concatenate the two input parameters. This map is used by the FILE send port and thus is invoked only if the parameters are equal. Because in this application there is no actual “WCF service” code, you can view the map as the concatenation functionality of the WCF service existing solely within the BizTalk send port. The concatenation functionality is invoked by using a filter on the send port that checks to see if a message is received in the application’s receive port (BTSReceivePortName == WCFCustomBehaviorReceivePort).

BizTalk Server allows orchestrations to be exposed as WCF services by using the BizTalk WCF Service Publishing Wizard. There are two options for doing this.

The first one provides a Web application to host this WCF functionality with the Service Endpoint option. In this case, there exists an actual WCF service application developed in code that is using Internet Information Services (IIS) as its host. Alternatively, the wizard allows creation of a metadata-only endpoint (MEX) where there is no actual WCF service.

The second option was used for this sample application. In this case, IIS provides an .svc file describing the service for the client, but it does not host the service at run time because this is a metadata-only endpoint used only to describe a service that is hosted outside of IIS. The actual functionality exists in the BizTalk application in this sample. Specifically, the functionality exists in the schemas and maps associated with the FILE send port. To the WCF client however, this capability appears to be exposed as a pure WCF service, and the client calls it in code as it would any WCF service, having no knowledge of its actual implementation wrapped inside BizTalk Server.

This assembly is placed in the GAC and deployed to BizTalk Server by its project settings in Microsoft Visual Studio® after the project is built and deployed.

Accessing WCF Service Functionality with the WCFClient Project

The WCF client code appears like any code that calls a WCF service. To the client, the concatenation functionality exposed by the BizTalk send port appears like a pure traditional WCF service. The client does not know how this service is implemented, or that the WCF custom behavior resides between itself and the WCF concatenation service functionality.

Two files in the WCFClient project were created by running the svcutil.exe utility against the IIS application’s WSDL data. After completing the BizTalk WCF Service Publishing Wizard for a metadata-only endpoint, an application exists in IIS with an .svc and a web.config file. If you open Internet Information Services (IIS) Manager, and select browse on the .svc file, it brings up the page showing how to run the svcutil.exe file against the WSDL data to generate a proxy .cs file and an app.config file for the client. Here is a part of what browsing to the .svc file displays:

You have created a service. To test this service, you will need to create a client and use it to call the service. You can do this using the svcutil.exe tool from the command line with the following syntax: svcutil.exe http://localhost/WCFBizTalkConcatService/ConcatService.svc?wsdl

From a Visual Studio 2005 command prompt, go to the folder for the client project and run the preceding command line. Rename the config file to app.config, and add both that and the generated BiztalkServerInstance.cs file to the WCFClient project to be able to access the WCF endpoint.

The WCFClient code instantiates the proxy object, sets the two client parameters, and calls the WCFConcatParamsOperation operation.

static void Main(string[] args)

{

ConcatServiceClient client = new ConcatServiceClient();

Root docObj = new Root();

docObj.InputParam1 = "stringequaltest";

docObj.InputParam2 = "stringequaltest";

Console.WriteLine("Calling into WCF service with values of: {0} and {1}", docObj.InputParam1, docObj.InputParam2);

Console.WriteLine("Hit any key to allow the WCF client to call the exposed WCF service:");

Console.ReadLine();

// Use the 'client' variable to call operations on the service.

client.ConcatParamsOperation(docObj);

// Always close the client.

client.Close();

}

Providing Authorization Control with the WCFCustomBehaviorExtClass Project

It is important to understand that the WCF custom behavior does not provide any of the WCF service’s concatenation functionality. This behavior only checks if the two input values are equal and passes the message on to BizTalk Server if they are the same. If the values are not equal, the behavior returns a negative value from the BizTalkWCFCustBehaviorManager::CheckAccess method, which causes the message to be rejected before it gets to the WCF-Custom adapter.

This sample shows two options for accessing input parameters, and thus two different security schemes. When parameters are passed by using an operation invocation from within the WCF client code, this is a client-based security scheme. The second security scheme is managed on the server by setting the behavior’s exposed configuration properties in the Transport Property dialog box for the WCF-Custom adapter under its associated receive location. Each approach requires slightly different code in the behavior’s BizTalkWCFCustBehaviorManager::CheckAccess method.

In the first (client-based) option, the client’s code explicitly sets the service’s configuration properties by using the service’s proxy as shown below. A security scheme where the client manages the value of the parameters without needing any server-side intervention also may have its place in a .NET application.

ConcatServiceClient client = new ConcatServiceClient();

Root docObj = new Root();

docObj.InputParam1 = "stringequaltest";

docObj.InputParam2 = "stringequaltest";

For the WCF service to be able to access these values, the following code is used in the CheckAccess method of the WCF custom behavior. Note that this is the only code in the CustomBehaviorClass.cs module that is required for the client-based security approach.

XmlDictionaryReader x = operationContext.RequestContext.RequestMessage.GetReaderAtBodyContents();

string strClientInputParam1 = x.ReadElementString();

string strClientInputParam2 = x.ReadElementString();

return (strClientInputParam1 == strClientInputParam2);

Here an XMLDictionaryReader object is used against the WCF message context to pull out the two input parameters. If they are equal, a true value is returned, and the WCF message is allowed to be accepted by the WCF-Custom adapter. Any time CheckAccess returns a true value the call has passed the custom security check. The nice part about WCF extensibility is that you can put any custom authorization mechanism within this method to meet specific requirements. If this method does not return true, the WCF message is rejected and never gets to the WCF-Custom adapter or BizTalk Server. In the command prompt window you will see an exception notifying the user of the exception associated with the access failure.

In the second option, the explicit setting of the property values in the WCFClient program is ignored. Rather, the two configuration properties set in the BizTalk Server Administration console on the Behavior tab of the WCF-Custom adapter’s property page for the receive location are used. Having the administrator manage the values of the configured properties allows a scheme where security is managed on the server irrespective of the client.

The following line of code replaces the code fragment above in the BizTalkWCFCustBehaviorManager::CheckAccess operation to access the property strings and test for equality of the values.

return (this.strBindingProperty1String == this.strBindingProperty2String);

Throughout the CustomBehaviorClass.cs file, there are many lines of code that support the server-side security scheme. With the exception of the client-based security code in CheckAccess operation, all the remaining code exists to support the server-based approach.

· The name displayed on the WCF-Custom adapter’s Behavior tab is determined in this line of code. “BindingProperty1String” is what will be shown in the dialog box. A similar section of code exists for BindingProperty2String.

[ConfigurationProperty("BindingProperty1String", DefaultValue = "", IsRequired = true)]

Summary

This article centers around three C# projects:

· BizTalkArtifacts is a pure BizTalk Server project containing maps and orchestrations used by the send port to concatenate two strings into one string.

· WCFClient is a simple WCF client application that uses the exposed WCF service’s proxy to access its functionality. The WCF service itself exists solely in the functionality of the BizTalk send port as a concatenation service. This is exposed as a metadata-only endpoint through IIS.

· The WCFCustomBehavior project is a WCF custom behavior that is configured into the total application architecture using the WCF-Custom adapter. The behavior receives the WCF message before the adapter sees it, and controls access by its custom method and its Boolean return value from the CheckAccess operation. If True is returned, security access is granted. The message is sent to the WCF-Custom adapter, which then submits it to BizTalk Server for processing. If False is returned, access for the incoming message is denied, and the message never gets to the adapter. An exception is thrown and BizTalk Server has no record of the incoming message.

The WCF adapters are a gateway into the robust and flexible world of WCF. They allow a BizTalk application to integrate specialized WCF processing into a send port or receive location using a WCF adapter. Using a custom behavior is one way to accomplish this.

With the BizTalk ServerWCF adapters, Windows Communication Foundation (WCF) services can be extended by using a WCF custom behavior. A WCF behavior is a way to extend WCF functionality to the BizTalk Server environment. The behavior controls certain service run-time aspects such as a specific operation or an endpoint. Because it is a WCF component, a behavior can be customized through configuration settings or attributes in the source code. These extensions can be customized to do tasks such as a custom security access check, and they allow processing of a WCF message before it gets to a BizTalk ServerWCF adapter.

This article demonstrates the use of a WCF custom behavior through the use of the BizTalk Server WCF-Custom adapter. A WCF client console application sends a WCF message to a metadata-only endpoint exposed as a BizTalk Server receive location. Within the receive location the WCF-Custom adapter is configured to use the WCF custom behavior that does a simple access check by determining whether two input parameters are equal. If the access check is passed, the receive location uses a map that joins the two input strings into one string, and then writes that string to a file location using the FILE adapter through the send port.

The input parameters are sent to the WCF service in two ways by using a WCF message. In the first scenario, where some client criteria can determine if the message should be processed by the WCF adapter, the values are set in the WCF Client application and passed in as parameters. In the second scenario, which is more like an administrative server-based security scheme, the parameter values are set in the Behavior property page of the WCF-Custom adapter. You will recompile the WCF custom behavior to allow those parameter values to be used. This sample provides an example of both methods so you can decide which way makes more sense for the application structure of your WCF custom behavior.