BizTalk Server 2013 Support for RESTful Services (Part 1/5)

By Nick Hauenstein

This post is the thirteenth in a weekly series intended to briefly spotlight those things that you need to know about new features in BizTalk Server 2013. It is also the first part of a five-part series on REST support in BizTalk Server 2013.

BizTalk Server 2013 is trying to make BizTalk Server not only the application/integration server for the enterprise, but also for the Cloud. Here we’re referring specifically to those Software-as-a-Service solutions provided by 3rd party organizations in an elastic fashion – usually exposing an API in the form of REST endpoints.

In this post, we will begin to explore the REST support in BizTalk Server 2013 in an overview fashion. We will then continue our exploration with a series of posts that cover common scenarios (Receiving data, POST-ing data, JSON en/decoding, and finally OAuth authentication).

How Do We Do REST in BizTalk Server 2013?

We do REST through BizTalk’s new WCF-WebHttp adapter. This adapter really is just another WCF adapter (like the SFTP adapter). It can be used on the Send or Receive side, in both one-way and two-way configurations.


In this case though, it is really clear that WCF is the underlying technology. Like all other service operations within BizTalk, we are exposed to operation mapping (the mapping of operations within orchestrations to actions in the service). However with the operation mappings in the WCF-WebHttp adapter, we don’t specify WCF actions so much as resources that we want to request (since it’s all just plain-old HTTP on the other end):


Do I Need a Dynamic Send Port To Do a GET?

The operation mapping shown above begs the question of how a GET request like this would work. Here we’re showing some sort of weather service that is providing temperature readings on a postal code basis. In order to make a request for the readings, one would have to access a URL that would change on a per postal code basis (i.e., the endpoint address changes).

Typically to accomplish something like sending to a dynamic address, one would use a dynamic send port. In the case of the WebHttp adapter, however, we get to specify variables within the path (which is shown in template form). In the screenshot above, we used the {postalCode} variable. Clicking the Edit button under Variable Mapping will lead us to the following screen:


Here we can see that in order to specify those variables, we simply pull from the context of the message traveling through the port. In this case we are grabbing the value for the {postalCode} part of the path from the Context Property named ZipCode.

Since most of the time that we are using the GET method, we don’t want to include a message (really it’s a request for a resource, and the dynamic part is the URL, not the body of the request), we can suppress the body using the Suppress Body for Verbs, and specifying the methods for which we want to not include a request body.


What Don’t I Get?

So far looking through the settings, it looks like we have a pretty good story around creating RESTful requests. However, we don’t have everything out of the box that we need to consume every single RESTful API out there.

You will still have to provide things like the following:

  • Encoding/decoding support (e.g., for JSON encoded messages)
  • WCF extensions for performing authentication (e.g., OAuth)
  • Schemas representing the requests/responses

These are some of the things that we will be covering within this series, so stay tuned over the next few weeks!

Do I Need BizTalk Server 2013 To Make this Happen?

While the adapter is new in BizTalk Server 2013, the underlying mechanism that makes it work is the WCF WebHttpBinding, which was around during the BizTalk Server 2010 timeframe. I’ve actually had people complain at me while explaining the WCF-WebHttp adapter as a new feature because of this.

Does that mean you can get it all up and running using something like the WCF-Custom adapter? Yes, and no. You can technically make it function with some additional legwork (e.g., as seen here), but you’re not going to get as smooth as an experience as you will see with BizTalk Server 2013 – it really feels cobbled together without having BizTalk Server 2013 at your disposal.

Coming Up Next

Next week I will be talking through the receive side of this story as we see how to host a RESTful endpoint in BizTalk Server 2013. Until then, take care (and take our classes)! Smile

BizTalk Server 2013 and TFS 2012 – Why can’t I lock the files?

By Nick Hauenstein

This post is the twelfth in a weekly series intended to briefly spotlight those things that you need to know about new features in BizTalk Server 2013.

This week’s post will be a little bit shorter than the rest so far, as I’m getting prepped for some last minute travel to teach our TFS 2012 Developer Fundamentals class over in Houston, TX.

Since TFS 2012 is already on my mind, I decided to align this post accordingly. In this post we’re looking into some more differences that come about due to the “upgraded platform support” found in BizTalk Server 2013.

Here I’m assuming that you have taken three giant leaps at the same time: (1) You have upgraded to BizTalk Server 2013, (2) You have upgraded to Visual Studio 2012 (i.e., you intend to do some development with BizTalk Server 2013, (3) You have upgraded to Team Foundation Server 2012. Another assumption that I am operating on here is that you have (4) started a new project within a new Team Project Collection.

If those assumptions are all true, then you may run into a change in behavior when it comes to working with the rest of your team – your ability to take an exclusive check-out lock will be missing1.

What has been passed down to us?

A few years back, there was a pretty decent guide on the TechNet Wiki. for using TFS version control with BizTalk Server 2009. One of the tips it gave related to disabling multiple checkout for your BizTalk Server projects. The theory there was that this could prevent files that were typically edited from within a designer (and full of generated code) from going through a painful merge process where someone may be confronted with trying to merge a mix of XML and XLANG/s.

Is this advice still valid? Well… yes and no. Mainly yes, but it can be no. Let me take a step back, and maybe it will make a little more sense.

What has Changed?

In TFS, the mechanism behind the whole concept of preventing multiple checkout (essentially preventing two people from editing the same file at the same time)  is a lock – specifically a check-out lock.

A quick perusal of the TFS 2012 docs will reveal the following:

In Visual Studio Team Foundation Server 2012, check-out locks are generally not effective because of local workspaces (see Decide Between Using a Local or a Server Workspace). Specifically, check-out locks are:

  • Not enforceable because other users might be using local workspaces

Yes – that’s right – check-out locks are not enforceable. This is because if you create a new Team Project Collection in TFS 2012, the default setting is to have the users use local workspaces (if that doesn’t mean anything to you, click the link in the quote above).

The implication is that Visual Studio no longer has to communicate with the TFS Server every single time a file is touched – this results in less server chatter, the freedom to use multiple tools without dropping into Source Control Explorer to check out a file first, and it also results in the inability for the server to step in and say that someone else has a lock on the file.

To make it a little bit more confusing, each developer can configure their machine to use either a server or a local workspace :-/

How Do I Get My Locks Back?

Don’t get me wrong here, there are huge advantages of local workspaces, and I love them lots. However, if your team’s workflow depends on check-out locks to get the job done, and that’s going to be your best bet – then I want you to know what your options are2.

First, you can change a setting at the Team Project Collection level to ensure that new developers coming into contact with the Team Project will end up with a more traditional Server Workspace (which communicates with the server upon check-out):


Second, you will want to make sure that each developer re-configures his/her workspace to ensure that it is configured as a server-side workspace:



The End for Now

Hopefully that will help you out, if you find yourself in the situation of completely unenforced check-out locks. If you don’t find yourself in that situation (maybe because you never used them in the first place), then great.

As I mentioned above, I’m going to keep this post brief and to the point. I’ll be back into the swing of things next week with another mini-series within the new features series that’ starts to get into the REST support in BizTalk Server 2013. Until then, have a great week!

1 The option shows up, but it’s not necessarily effective.

2 I have included this disclaimer since I will take some heat on twitter regardless of which style of workspace I might seem to favor. For those that want to complain about my personal taste in source control, it’s @nickhauenstein 😛