Thoughts on Systems Integration using Microsoft Technologies

Latest

WCF Error from Visual Studio Debugger: “An exception of type ‘System.ServiceModel.FaultException`1’ occurred but was not handled in user code”

This error got me stumped for a bit…  The solution was quite simple but caused a few further grey hairs so I will share here how I resolved this annoyance!

I was hosting a WCF solution in Visual Studio (for testing and debugging purposes) and calling it from a forms application.  Things were going well until I introduced typed SOAP faults: I wanted to throw a typed fault from my WCF solution and for my forms application to catch and handle the error.

When I threw the error from my WCF solution, the Visual Studio debugger complained, saying that the error was unhandled:

Visual Studio 2013 SOAP Fault Unhandled Error

Fig. 1  Visual Studio 2013 SOAP Fault Unhandled Error

However, my forms application had been built to handle the exception as follows:

But SOAP Fault Handled in my Forms App

Fig. 2  But SOAP Fault Handled in my Forms App

I couldn’t work out for sometime how to suppress the error but then noticed a check box in the VS exception message box: “Break when this exception type is user-unhandled” (highlighted in Fig. 1 above).

The wording is a bit of misnomer since I am actually handling the error in my forms app but I guess the VS debugger can’t work this out.  I unchecked the box and VS behaved as I wanted it to: my WCF solution was able to throw the exception for handling by my forms app.

I later learnt that it also possible to configure how the VS debugger behaves in regards to exceptions by selecting “DEBUG –> Exceptions…”.  This opens an exceptions windows where it is possible to configure if the debugger should break or not for certain exception types e.g.:

Specify if Debugger should Break

Fig. 3  Specified that the Debugger should not Break for Exceptions of Type ‘System.ServiceModel.FaultException`1’

 

Few Thoughts on the ESB Toolkit and an Error – “The ‘ServiceType’ property value should not be empty or null”

I have recently been experimenting with the ESB Toolkit (version 2.2 that ships with BizTalk 2013) and I think it is a good way to expedite loosely coupled BizTalk solutions, dynamically configurable at runtime using the Business Rules Engine (BRE).

At a high level, the ESB Toolkit itinerary model is an implementation of the routing slip pattern.

My immediate impression is that development using the Itinerary Designer is tightly coupled to the runtime environment, more so than “standard” BizTalk development.  By “runtime environment”, I mean artefacts/configuration viewable via the BizTalk admin console (e.g. applications, send port filters etc.) and also policies created via the BRE Composer.  Basically the target application needs to be setup before starting work building the solution using Visual Studio.  Any changes to the solution setup (changing a send port name, for example) would likely require firing up Visual Studio and propagating these changes to the itinerary, then importing into the itinerary database.

It’s also occurred to me that the itinerary pattern is in my mind an easier way to implement a message type agnostic solution, compared to using the standard BizTalk toolset.  I have recently been wrestling with a series of orchestrations processing messages in a non typed fashion, routing to/from the MessageBox purely using context properties: this is a powerful enabler of achieving a “service first” approach (instead of a “message first” approach) permitting heavy reuse of processing logic without caring about the underlying message type.  Yes, I’m thinking about SOA principles here.  However it’s been quite a mission to implement this routing using non typed messages in orchestration.

To illustrate this tight coupling of the development and runtime environments mentioned previously (and to demonstrate my noob status regarding the ESB Tookit :-)), whilst trying to export a model via Visual Studio, I was stumped with these errors:

Itinerary Property Value Errors

Itinerary Designer Property Value Errors

It was obvious clicking on my off ramp that these three properties were not configured but they looked to be read only – so how could I add values?!:

Missing Properties in the Itinerary Design

Missing Properties in the Itinerary Designer – Not Possible to Configure Here

After a bit of head scratching and a web search it soon became clear that these properties referred to filter properties on my send port – it would have been useful if the property name made it obvious what these properties referred to.

So in my BizTalk application, I created the following filters on my dynamic send port:

ESB Tookit Send Port Filters Required

ESB Toolkit Send Port Filters Required

I then re-selected the send port in the off ramp and the required properties were then populated from the BizTalk databases:

Properties Visible in Itinerary Designer

Properties Visible in Itinerary Designer After Adding Filters to Send Port

I hope this post helps out other ESB Toolkit “greenhorns”.

Using Inline XSLT to Populate an <Any> Element

I have been working recently with schemas containing <Any> elements.  Luckily I don’t need to manipulate the <Any> contents much: to do so, the standard BizTalk functoids available in the mapper can’t be used and instead, given the range of the XML that can be expected in the <Any>, some extensive custom XSLT would be required.

I have two scenarios:

  1. The contents of an <Any> element need to be copied to a known schema “as is”.
  2. The contents of a known schema need to mapped “as is” to an <Any>.

I struggled with the mass copy functoid for both scenarios – it didn’t behave quite how I expected/wanted.

After a bit of head scratching and a read of this blog post, I realised that the mass copy doesn’t copy across root elements.  I suppose, for example, the assumption is that both source and target schemas will contain a common element that can be used as the “target” of the mass copy functoid.  This wouldn’t work in my case, since the schemas being mapped are quite different and also the <Any> would contain a range of different XML, so I couldn’t specify an appropriate containing “root” element.

To get around this behaviour of the mass copy functoid, in my map I created a scripting functoid and added some inline XSLT like this:

<xsl:copy-of select=”.” />

My map then looked like this:

Map With "Mass Copy" in Inline XSLT

Map With “Mass Copy” in Inline XSLT

Here is an example instance of the source message:

Source Message

Source Message

And this is the result after passing the message above through the map:

Output Message

Output Message

Also here is the output message if the mass copy functoid is used (note that the root <Order> element is missing, under <Entities>):

Output Message Using Mass Copy Functoid

Output Message Using Mass Copy Functoid

It seems strange and limiting that the mass copy functoid doesn’t copy the root element.

BizTalk 2009 – Error Enlisting Send Port – “Exception from HRESULT: 0xC00CE557”

It’s the second time that I have encountered this obscure error in BizTalk 2009, when attempting to enlist a send port after importing bindings originally exported via the admin console:

BizTalk 2009 - Error Enlisting Send Port

BizTalk 2009 – Error Enlisting Send Port

Both times (for different customers) the issue was that an extra carriage return and line feed had been inputted before and after the <Filter> element in the offending bindings file that was being imported, like this:

Bindings File - <Filter> Element Contains Carriage Return and Line Feed

Bindings File – Element Contains Carriage Return and Line Feed

This had a two fold effect – filter expressions were missing from the send port and also the error above enlisting the send port.

I carefully checked the bindings file and discovered other <Filter> elements with extra carriage returns and line feeds: I removed them, like so:

Bindings File - Extra Carriage Return and Line Feed Removed From <Filter> Element

Bindings File – Extra Carriage Return and Line Feed Removed From Element

On import of the bindings file again, I could then see my filter expressions and also could enlist the send port…

I have only ever come across this error in BizTalk 2009.

Also, although I am doing so for the send port in the bindings file snippet, I don’t filter on receive port names in Production ready solutions…  Only sometimes during initial development do I do so!  It is better to filter on context properties such as BTS.MessageType, WCF.Action and BTS.Operation.

BizTalk WCF Service Consuming Wizard – HTTP 407 Proxy Authentication Required

I got this error recently running the BizTalk WCF Consuming Wizard whilst working at a customers office when I didn’t previously (sensitive parts of the error message have been removed):

BizTalk WCF Service Consuming Wizard HTTP 407 Error

BizTalk WCF Service Consuming Wizard HTTP 407 Error

I think it was due to installation of internet security software on my development VM by the company’s infrastructure team and/or a new set of group policies being applied to the domain in which my VM is connected too…

Anyhow, it was obvious that all traffic from my VM was now going through a web proxy for the purposes of filtering traffic and I needed to install proxy client software.  This would entail some internal processes being enacted.

Being impatient to progress (and seeing this as an opportunity to try something out that I had read about a few weeks previously) I decided to see if a I could use SvcUtil.exe, providing my proxy credentials so enabling the SvcUtil.exe to authenticate against the web proxy for me.

It would be great if the BizTalk WCF Service Consuming Wizard had proxy authentication support!  Maybe I’m missing a trick here??

Based on this article here on Stack Overflow, I created a small proxy class, created a strong name key file for it and then installed it in the GAC on my dev VM:

Proxy.cs snippet

Proxy.cs snippet

I then edited my SvcUtil config file as follows, adding a reference to the proxy class assembly:

SvcUtil.exe.config file

SvcUtil.exe.config file

Then using the simple batch script below, I could run SvcUtil with proxy authentication included and hey presto, I could download the WSDL and associated XSD import files!

GetServiceDefinition.bat file

GetServiceDefinition.bat file

This saved me the annoyance of having to download each imported XSD file individually and then modifying the path in the parent WSDL.

I have a GitHub repo here containing the source code for the solution (as usual, provided under the terms of the MIT licence).

BizTalk Instrumentation – An Initial Foray into the CAT Framework

I have spent some time recently looking into the Windows Server AppFabric Customer Advisory Teams (herein “CAT”) BizTalk instrumentation framework and I will report here on some of my findings…  In short, I have become quite excited about the potential if offers not only to instrument BizTalk solutions (in development and production environments) but also as the basis of a unit testing framework.  In this brief initial look into the framework, I will focus on tracing in orchestrations but it’s possible to introduce tracing into all BizTalk artefacts (and also non BizTalk/custom components).

The framework itself has been around for sometime now (since May 2010?) – this blog entry from the CAT is a well written article introducing the tracing facilities it provides (at the end of the article is a link to the framework source code).  This white paper looks to have been heavily based on the blog article (or vice-versa) and is similarly well written and easy to follow.

I have to confess and admit that in the past, like a lot of developers, I have used the System.Diagnostics.Trace .NET class in conjunction with DebugView to trace execution of orchestrations during development.  One thing I have observed is that CPU utilization increases dramatically whilst DebugView runs: it’s not a tool that should be run outside of a development environment.  The CAT observed this and came up with a framework leveraging the Event Tracing for Windows (ETW) facility.  The framework is a wrapper around the TraceProvider class from the Microsoft.BizTalk.Diagnostics namespace in Microsoft.BizTalk.Tracing.dll.  As CAT mention, this is a “hidden gem” and is utilised in all major components in the BizTalk runtime (you can observe this by running DebugView while the BizTalk engine is executing – heaps of trace events are outputted).

Now the framework doesn’t mean you should run DebugView outside of a development environment: instead, it allows rapid and efficient tracing to a log file.  This means that it won’t crash your development VM and also it permits tracing in Production and Production like environments.

I will briefly describe here how I setup the framework to trace  orchestration execution…

After downloading the framework from the CAT blog, I opened the solution using Visual Studio 2012 and successfully ran the Conversion Wizard.

There are 3 projects:

  1. Microsoft.BizTalk.CAT.BestPractices.Framework
  2. Microsoft.BizTalk.CAT.BestPractices.Samples.TracingBenchmark
  3. Microsoft.BizTalk.CAT.BestPractices.Tests

The Microsoft.BizTalk.CAT.BestPractices.Framework project is the one I will need to reference in my solution.

A few immediate/gut observations about the Microsoft.BizTalk.CAT.BestPractices.Framework project that piqued my interest:

  1. Pre processor directives have been specified that output trace statements using System.Diagnostics.Trace .NET class for a debug build only.  So one could infer from this that this is designed for development, where a debug build of the framework could be used for outputting to DebugView.   A release build will not include the calls to System.Diagnostics.Trace, precluding the use of DebugView in Production for example.
  2. Lots of passing of object arrays – no generic collections evident: possibly a boxing/unboxing overhead here.

In order to get the Microsoft.BizTalk.CAT.BestPractices.Framework project to build (under .NET 4.5), I had to specify the full namespace (Microsoft.BizTalk.CAT.BestPractices.Framework) for the Func<string> delegate in the ComponentTraceProvider class.

Next I selected the option to sign the project assembly and created a strong name key then installed the assembly in the GAC.

It’s then a matter of adding a reference to Microsoft.BizTalk.CAT.BestPractices.Framework.dll in my orchestrations project in my BizTalk solution.

The white paper indicated in the introduction to this post presents usage of the framework well but I will demonstrate here how I implemented tracing in my orchestration…

Expression shapes containing tracing statements should be strategically added to the orchestration.

  • Tracing should kick off with a call to the TraceIn method immediately after orchestration activation.  The method returns a GUID that can be used to trace specific instances (the GUID can be prefixed to the trace output for example – thanks Johann for this tip!).
TraceIn

TraceIn

  • Message body content can be outputted using the TraceInfo method.  Note that the variable debugMessage is of type System.XML.XMLDocument.
TraceInfo

TraceInfo

  • It’s possible to trace scope execution using the TraceStartScope and TraceEndScope methods.  The framework will output scope execution time.
TraceStartScope

TraceStartScope

TraceEndScope

TraceEndScope

  • Tracing should be added into exception blocks like so, using the TraceError method (passing in the exception object):
TraceError

TraceError

  • Finally the orchestration should end with a call to TraceOut, passing in the GUID (stored in the callToken variable below) returned from calling the TraceIn method.
TraceOut

TraceOut

The BizTalk CAT Instrumentation Framework Controller available on CodePlex is an excellent GUI based tool for starting and stopping traces.  It has options to write tracing to DebugView and/or a log file (DebugView shouldn’t be used in Production though, just development environments).  It has a bit of a limitation in that the log file is not human readable until a trace is stopped.

Here’s an example of a trace written to DebugView:

DebugView

DebugView

I have an example BizTalk 2013 solution here that is available for download under the terms of the MIT licence where tracing has been implemented.  The example screenshots above are taken from this solution.

Now 2 things have got me really excited about the BizTalk CAT instrumentation framework:

  1. The opportunity to log real time tracing events from Production environments in an efficient way – this has implications for monitoring solutions in Production, parsing tracing events to trigger other events e.g. error alerting, reporting.  Tracing could be written to Azure providing a central repository of data that could be analysed and reported on.
  2. The facility to track flow through an orchestration would be the excellent basis for a unit testing framework.  Tests could be run by writing trace events to a queue (Windows service bus?) to preserve the order in which events have been triggered.  The BizUnit testing framework could then be extended to monitor the events on the queue and compare against expected execution flow configured in the business rules engine (BRE).  Events associated with each test run could also be persisted to a database and provide the basis for analysis of test coverage (i.e. have all paths of execution been tested in a given orchestration?).

In regards to point 1, this facility looks similar to recent functionality added to the BizTalk360 monitoring solution.

The Testing inside BizTalk by using ETW Tracing project on CodePlex looks almost a perfect fit for point 2 and something I intend to explore soon!

In summary, I hope this post provides a good introduction to the CAT tracing framework and how it could be used during development (as a unit testing tool) and subsequently in Production (real time tracing and monitoring).

BizTalk and WCF, Consuming a WCF Service, Part 4 – Exception Handling

This is the last post in a four part series looking at BizTalk and WCF.

Here are the previous three posts:

Part 1 – A Look at the Service to be Consumed

Part 2 – The BizTalk WCF Service Consuming Wizard and a Look at the Artefacts Created

Part 3 – Building the BizTalk Solution

In this final post, I will show how exception handling has been added to the RandomPresentService orchestration controlling our business process.

Some BizTalk Exception Considerations: 101 Course

Firstly, here is a quick brain dump of items that should be considered when thinking about handling exceptions in an orchestration:

  1. What are the customers requirements in regards to messages that fail inside BizTalk?  Should alerting and/or logging be implemented so remedial action can be carried out and if so who should be the recipients of any such alerting?  What steps should be carried out to recover from the error condition (what is the process)?  Often the customer has only a vague idea here and some teasing out of requirements may be required.
  2.  What is the impact if a particular process/action fails in your orchestration?  Does this is invalidate subsequent previously successful actions?  Should previously committed actions be rolled back therefore in a compensation block?
  3. What about business process type errors?  Can these be handled without the need to jump to an exception condition?  Preferably, business type errors that happen routinely (and are therefore not exceptional) should not be handled by throwing an exception but handled in the “body” of the orchestration.
  4. Do you need to handle any custom exceptions?  Hopefully this is well documented in any service that needs to be consumed, for example.

Often error handling is forgotten until the very end of the development phase and is not instead considered at the start of a project – this is a mistake!  Or alternatively, the customers requirements are not taken into consideration when building exception handling.

By thinking about exception handling at the start of a project, it can be “built in” to the solution.  Also it allows time for discussions with the customer around how exceptions should be handled (in the analysis and design phase).  It’s costly to implement exception handling logic retrospectively.

One of the big selling points in regards to BizTalk and another tenant of the platform is that it is “robust” and ensures “guaranteed message delivery”.  In order to live up to these expectations it’s important that error conditions are handled in such a way that resubmission of failed messages is secured, with possibly multiple options for error recovery.  These processes also need to be tested and well documented.

What Exceptions Need to Handled?

A concept that can be hard to determine is: what exceptions should my solution handle?  By their very nature, exceptions are exceptional/rare so are a challenge to define and pin down.

It is a decision guided by some of the following factors:

  1. Experience – harnessed to try and make troubleshooting of “exceptional” type errors easier to investigate when the solution is running in Production.
  2. The needs of the customer.
  3. The type of exceptions that any called services could return.

This analysis will generate a list of exceptions that need to be handled.

As with any solution, the most specific exceptions should be handled first with the most general exception caught last.

And no doubt, not all exceptions will (or should) be catered for.  They will generate a nasty runtime error that will require investigation using a tool like the Orchestration Debugger.  This is where a good support team have a chance to shine :-).

Exception 1: PersistenceException

This is the first exception that I’m going to explicitly handle.

My friend and colleague Johann Cooper has written an excellent blog article about this exception.

Specifying direct binding on send ports in your orchestration is a good idea – this decouples physical send ports from the logical send ports specified in your orchestration.  But this pattern can fail if the physical ports are ever unenlisted.

If physical ports are unenlisted, this removes any associated subscription and an exception of type Microsoft.XLANGs.BaseTypes.PersistenceException will manifest in the orchestration.

(You will also get a nonresumable “Routing Failure Report”, to help with troubleshooting the routing error).

So first up, I have modified the RandomPresentService orchestration like so:

  1. Added a non transactional scope shape around the send and receive shapes for the RandomPresentService WCF service.
  2. Added an exception block to the scope to handle the PersistenceException.  This includes the creation of an ESB fault message (so the error will surface in the ESB exception management portal) and a suspend orchestration shape.
  3. Note the addition of looping: this ensures that the orchestration can be resumed in a valid state, since the RandomPresentService will be called again.
Handling PersistenceException in Orchestration

Handling PersistenceException in Orchestration

Exception 2: Handling SOAP Faults Returned from the RandomPresentService WCF Service

To handle any SOAP faults returned from the RandomPresentService service, I added a new fault type to the operation on the logical port in the orchestration designer (right click on the operation and select “New Fault Message”) and selected a message type of BTS.soap_envelope_1__2.Fault: this denotes that the fault should be wrapped in a SOAP version 1.2 fault:

Adding a SOAP Fault on the Logical Port for the WCF Service

Adding a SOAP Fault Handler on the Logical Port for the WCF Service

The fault doesn’t need to be connected to a receive shape or anything like that – it can be left as is, and instead the fault can be handled by defining another exception block and selecting the SOAP fault as the “Exception Object Type”.  When the fault is defined, it will subsequently be viewable in the “Exception Object Type” drop down, like so:

Specifying the SOAP Fault Type in the for the Exception Block

Specifying the SOAP Fault Type in the Exception Block

It’s important to handle SOAP faults: if not, this will cause an unhandled exception in your orchestration (due to an unexpected message type being returned) and it will not be possible to recover from this error by resuming the orchestration.

Also note that in order to extract the SOAP fault message, the orchestration XPath function can be used like this:

strFaultMsg = xpath(exSOAPFault, “string(/*[local-name()=’Fault’ and namespace-uri()=’http://schemas.xmlsoap.org/soap/envelope/’%5D/*%5Blocal-name()=’faultstring&#8217; and namespace-uri()=”])”);

(Where strFaultMsg is of type System.String and exSOAPFault is of type Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults.FaultMessage).

Exception 3: Handling System.Exception – “Catch-all” Exception Blocks

The final exception block (that will be evaluated last by the orchestration engine) is a “catch all” block since it will handle exceptions of type System.Exception.  Since all exceptions in .NET inherit from System.Exception, any errors, not previously handled explicitly by previous exception blocks, will be caught by this handler.

Also I have wrapped the entire orchestration in a global scope and specified one exception block for System.Exception to ensure than my default exception handling mechanism will be exercised.

Series End

So this concludes this four part series looking at BizTalk and WCF.

As is to be expected, WCF is interleaved tightly into the BizTalk framework and it is possible to leverage it heavily in your BizTalk solutions.

It’s been a journey looking at the creation of a WCF service; using the “out-of-the-box” BizTalk tooling to consume the service; building upon the artefacts created by the WCF Service Consuming Wizard; finally ending with this brief (!) look at implementing exception handling in the orchestration controlling the business process.

I hope it provides a good introduction to the subject!

The RandomPresentService WCF service is available here.

The full BizTalk 2013 solution is available here.

(Both solutions are available under the terms of the MIT licence, a copy of which is included with each).

BizTalk and WCF, Consuming a WCF Service, Part 3 – Building the BizTalk Solution

This post builds on part 1 and part 2 of this series looking at BizTalk and WCF.

The first post looked at the RandomPresent WCF service and looked at design considerations, hosting and testing.

The second post touched on how to consume the WCF service from BizTalk, using the BizTalk WCF Service Consuming Wizard.

Process Flow

The business want to send to each customer, a random Christmas present with their order.  To achieve this, the RandomPresent WCF service will be called by BizTalk and it will return a random present XML, wrapped in a SOAP envelope.  The present response needs to be appended to the order, so the guys in the warehouse can add the present to the shipment.

It’s a matter of combining the original order and the response from the web service.

Orchestration

I’ll start with an overview of the single orchestration driving this process, since all other artefacts hang off this.

In the end, I created a new orchestration from scratch and didn’t use the one generated for me by the BizTalk WCF Service Consuming Wizard:

RandomPresentService Orchestration

RandomPresentService Orchestration

I will summarise the flow here and call out some interesting bits!:

  1. A map on my receive port converts the external format PO to the canonical version (check out my blog post here on the canonical messaging pattern).  The canonical message has an element called “Status” that is assigned the value “NEW” in the map.  This element is mapped to a property called “POStatus” of type MessageContextPropertyBase.   So, as you can guess, I had to create a property schema which I added to my internal schemas project (it contains just this one property).  The type MessageContextPropertyBase identifies “POStatus” as a context property that can be written to the context of a message and, as will be discussed, this is what I want to achieve for the purposes of routing and to prevent my orchestration from being caught in an endless activation loop.
  2. The canonical PO is written to the MessageBox and an instance of the orchestration fires up ; the orchestration subscribes to messages of type canonical PO and also on the “POStatus” promoted property: it is activated when the status is “NEW” only.  The reason for this additional subscription on “Status” is because on completion, the orchestration will write the modified canonical PO to the MessageBox and an infinite activation loop will occur if orchestrations are activated only on publishing of a canonical PO message type (not good!).  Of course, there are other ways of working around this: I think this is why, in some solutions I have seen, solutions have more than one canonical schema with a different namespace to differentiate them – this seems a mad way of getting around the “activation infinite loop” issue though, since this introduces the overhead of maintaining two canonical schemas and also the design principle of a canonical messaging pattern is that there is only “source of truth”.
  3. Note that I have designed my orchestration such that it only works with internal solution type messages only (not on the original, external, versions received).  This protects the orchestration from changes to the format of the external PO which might require changes and redeployment of the orchestration.
  4. Next I create a request message for the RandomPresent WCF service…  I have created a C# classes project that contains a C# class representation of the request schema: I created the class using Xsd.exe, by pointing Xsd.exe at my schema.  I instantiate an instance of the request message in a Construct Message shape using the New keyword.  Another way of creating a message in an orchestration is to create a map for this purpose.  There is a serious caveat to instantiating a message using the New keyword however: it is vital that changes to the schema are reflected in the class representation (maybe this could be achieved in a Visual Studio “post build event” on the schemas project).  As has happened to me in the past, if you assign a message created from your schema (via a map) to an (outdated) message created from a class (e.g. in a Construct Message shape), any missing elements will be silently lost in the output message…  For some reason, creating a new message in an orchestration is a torturous process, it seems to me!
  5. A multipart message map combines the canonical and RandomPresent XML into a new instance of a canonical PO.  This map will be discussed further in the “Maps” section below.
  6. Finally I set the “POStatus” context property to “PROCESSED” in a Message Assignment shape and write the new canonical message to the MessageBox.  The final Send Shape initializes a correlation set but not for the purposes of supporting an asynchronous process, but for routing purposes: the correlation set contains just the “POStatus” context property and initializing this in the Send Shape causes the property to become promoted, enabling it to be used for routing.  Setting this context property to different statuses on completion of processing is my way of preventing an endless activation loop, as discussed in point 1.

(Note the lack of error handling – this will be the subject of my next post).

Schemas

The BizTalk WCF Service Consuming Wizard created the necessary schemas for me to communicate with the RandomPresent service however I deleted the RandomPresentService_schemas_microsoft_com_2003_10_Serialization.xsd  schema (as discussed in part 2, I haven’t found a use for this schema yet).  I also typically rename the service schema filename to something shorter and more descriptive.

If my solution modifies messages and/or involves an orchestration, I create 2 schema projects: an internal schemas project and an external schemas project, as is the case here.

Maps

Finally, a quick look at the map used to combine the canonical PO and the RandomPresent XML into a new instance of a canonical PO:

Canonical PO 1 and RandomPresent Response to Canonical PO 2 Map

Canonical PO 1 and RandomPresent Response to Canonical PO 2 Map

Typically, I use an inline XSLT template in my map for tasks such as these – I find it too frustrating and time consuming using functoids.

As mentioned in this previous blog post, I write my XSLT in a separate file and import it’s contents into my map.

This is the XSLT used:

Inline XSLT Template in Map

Inline XSLT Template in Map

Conclusion

So I hope you enjoyed this tour.  In part 4 of this series, I will show how error handling has been implemented in the solution.

When the solution has been completed, I will make it available for download.

BizTalk and WCF, Consuming a WCF Service, Part 2 – The BizTalk WCF Service Consuming Wizard and a Look at the Artefacts Created

This post builds on part 1 of this series looking at BizTalk and WCF.

The previous post gave an overview of the RandomPresent WCF service, discussing design considerations, hosting and testing using SOAPUI.

In this post, we will examine how to consume the web service using the BizTalk WCF Service Consuming Wizard.  The next post will delve into the detail of actually building our BizTalk solution, using (some) of the artefacts generated by the wizard.

The Scenario

Our mythical company is feeling generous and management have decided that each customer will receive a gift with their order.  The gift will be assigned by calling our newly created web service and then adding an extra order line item for the present.

The BizTalk WCF Service Consuming Wizard

To consume the RandomPresent web service, the BizTalk WCF Service Consuming Wizard could be used.  This will generate all the artefacts we need to invoke the service, into our BizTalk solution.  However, some of the artefacts generated we will discard in favour of our own (better) implementation (to be discussed in part 3).

Here are the steps below:

  1. Right click on your solution (typically an external schemas project) and select Add –> Add Generated Items
  2. Select Consume WCF Service in the Add Generated Items dialogue box.  This will fire up the BizTalk WCF Service Consuming Wizard welcome page – click on the Next button
  3. On the next screen of the wizard we have two choices:
    Image

    Choose MEX endpoint

    • Metadata Exchange (MEX) endpoint – this option enables a service description to be downloaded (WSDL file) by pointing the wizard directly to the running RandomPresent web service.  Note from part 1 of this post, that we exposed a MEX endpoint by configuring the services web.config file to allow metadata to be downloaded via a HTTP GET
    • Metadata Files (WSDL and XSD) – I always think of this as a second best option, since instead of downloading service data directly from source, this option will allow artefacts to consume the service to be created from a WSDL or XSD on the file system.  There is a risk that the WSDL and/or XSD that has been obtained is out of date, so I try and avoid using this function if possible (it’s a last resort :-))
  4. Ensure that the Metadata Exchange (MEX) endpoint option is selected and click Next – this will take you to a screen where the service WSDL can be obtained and loaded into the wizard:
    Load WSDL for service endpoint

    Load WSDL for service endpoint – enter WSDL URL and click “Get” (for HTTP GET)

    • (Note that it is common practice for a service endpoint to expose it’s service definition using the convention servicename?wsdl)
  5. Click Next and then Import.  The wizard will then process the WSDL and generate artefacts into our BizTalk solution.  Click Finish.

The Ajax.BT.Fulfilment BizTalk Solution

So the wizard has consumed our WSDL and generated various BizTalk solution artefacts into our BizTalk purchase order fulfilment solution.  Lets take a quick look at what has been created:

BizTalk solution artefacts created by the BizTalk WCF Service Consuming Wizard

BizTalk solution artefacts created by the BizTalk WCF Service Consuming Wizard

  1. 2 x bindings files for importing into our BizTalk application:  one of these files can be imported into our eventual BizTalk application to create a send port to communicate with the RandomPresent service:
    • RandomPresentService.BindingInfo.xml – from the WSDL, the wizard has detected that the WCF service implements wsHttpBinding and therefore this file will create a send port using the WCF-WSHttp adapter
    • RandomPresentService_Custom.BindingInfo.xml – this is another option for creating a send port in our BizTalk application.  This will create a send port which will use the WCF-Custom adapter.  Utilising this adapter offers greater WCF extensibility compared to the WCF-WSHttp adapter
    • An interesting conundrum is: what bindings should I use in my solution, that utilising WCF-WSHttp or WCF-Custom?  I would contend that WCF-Custom is the better option over WCF-WSHttp, to support future/evolving requirements
  2. RandomPresentService.odx – this is a “starter” orchestration to call the service and contains just the types required.  I always move this orchestration into my specific orchestrations project (or just create an orchestration from scratch)
  3. RandomPresentService_schemas_ajax_randompresentservice.xsd – this schema defines the WCF message types required to construct a request to the service and what we can expect the response to look like
  4. RandomPresentService_schemas_microsoft_com_2003_10_Serialization.xsd – this contains type details.  I suppose if you wish to serialize to a class representation, this XSD would be useful but otherwise I haven’t found a use for this

That’s it for now…  In part 3 of this post I will walk you through my BizTalk solution utilising the service.  This will build on artefacts created by the BizTalk WCF Service Consuming Wizard, which was the main topic of this post.

BizTalk and WCF: Consuming a WCF Service, Part 1 – A Look at the Service to be Consumed

I thought I would do a series of posts on BizTalk and Windows Communication Foundation (WCF).

The main aim of this post is to cement my experiences so far exposing and consuming WCF services using BizTalk.

First up (and the focus of this post) is a look at a (very simple) WCF service that will be hosted in IIS.  Further posts will detail how the service can be consumed using BizTalk and the tools available, error handling and recovery and monitoring.

What’s WCF you may ask?  Further information/background is available here.  In a nutshell, it is Microsoft’s implementation of remote communication specifications maintained by groups such as the World Wide Web Consortium (W3C) and the Web Services Interoperability Organization (WS-I).

The RandomPresent WCF Service

Yes, you read correctly…!  The purpose of my WCF service is to return a random present (gift) to the client application.

As per Microsoft recommended best practice, the service contract is exposed to the outside world via an interface:

IRandomPresentService

IRandomPresentService

It’s possible to expose a class by applying attributes directly to the class (the attributes define the service’s runtime behaviour).  However by exposing the interface to the outside world (i.e. the WSDL will map to the interface) it is possible to change how the service is implemented without necessitating modifications to the WSDL.  Changing the WSDL (a file that describes the functionality of a web service) would necessitate clients downloading the WSDL and updating their proxy code accordingly.  So using an interface provides a level of abstraction between the specification of the service and how the service is actually implemented, thus protecting clients from any changes to the implementation of the service.

This is the class implementation:

RandomPresentService

RandomPresentService

Here are a few notes/pointers on the most interesting aspects of this interface and it’s implementation:

  1. Note the inclusion of the System.ServiceModel namespace – this contains all the WCF types
  2. Note that I have specified a namespace for some attributes – this is crucial for a professional looking WCF service!  If a namespace is not explicitly specified like this, the WSDL exposed by WCF to the outside world will contain the default namespace http://tempuri.org

WCF services can be hosted in numerous ways – for the purposes of this demo, I will host my service in IIS 8.  I did this by creating a new application via IIS manager and pointing it directly to my .cs files – this is OK for a development environment but in a Production environment, you would point to an assembly.

In the root of my IIS application I created a Service.svc file, which represents my WCF endpoint and a Web.config file.

My Service.svc file looks like this:

Service.svc

Service.svc

Note that the service attribute points to the implementation of the service using the full namespace and class name.  If you attempt to specify the interface in your .svc file, you will receive the following error when you attempt to view your service: ServiceHost only supports class service types.

Here is the contents of my web.config file:

web.config

web.config

A few items of interest here that I will summarise:

  1. Two endpoints have been specified for my service: a wsHttpBinding endpoint and a MEX endpoint.  The wsHttpBinding endpoint supports the WS-* specifications which defines a common standard for remote client communication.  MEX stands for “metadata interchange” so it describes how a client can communicate with the service using a WSDL file exposed to the outside world by the service (meta in this context means “about” so metadata means “data about data”).
  2. Note that a behaviour has been specified in the <behaviors> section that enables service metadata to be downloaded via a HTTP GET.  So this enables a WSDL file to be downloaded for my service (using a web browser, for example)
  3. And lastly, to enable me to call my service using SOAPUI, I had to add specific details about security for my endpoint, in a <wsHttpBinding> section.  So this is WS-Security configuration for my service.

Now if  browse to my service using a web browser, the following web page is displayed with details about the service:

RandomPresentServiceIE

RandomPresentServiceIE

This page nicely describes how to create a proxy class for this service with help from the svcutil.exe tool, a link to a WSDL that describes the functionality of the service and then example code showing how to invoke the proxy class.  However, we will be calling the service from BizTalk so won’t be requiring this information (except the handy link to the WSDL).

Finally, SOAPUI is a great tool (although sometimes a bit of a fiddle to work with WCF) for testing a service.

Invoke your web service by pointing SOAPUI to the service WSDL:

  1. Right click on the “Projects” node and select “New soapUI project”
  2. In the “New soapUI Project” dialogue box, add the location of the service WSDL and ensure that the “Create Requests” check box is ticked (this will create a sample request that can be used to invoke and test the service):

    New SoapUI Project

    New SoapUI Project

  3. Invoke the service by double clicking on the request and click on the green arrow to submit the request to the service.  On the “WS-Addressing” tab you will need to ensure that “WS-Addressing” is enabled and that the “Add default wsa:To” is ticked.  This is because the service implements wsHttpBinding, as described previously, which implements WS-Addressing (part of the WS-* specifications):

    Hooray, a Cabbage for Christmas!

    Hooray, a Cabbage for Christmas!

So this introduces a test WCF service that needs to be consumed by BizTalk, which will be the topic of my next post…

(The Visual Studio 2012 project is available here).