Decoding JSON Data Using the BizTalk Server 2013 R2 JSONDecode Pipeline Component

This is the fourth in a series of posts exploring What’s New in BizTalk Server 2013 R2. It is also the second in a series of three posts covering the enhancements to BizTalk Server’s support for RESTful services in the 2003 R2 release.

In my last post, I wrote about the support for JSON Schemas in BizTalk Server 2013 R2. I started out with a small project that included a schema generated from the Yahoo Finance API and a unit test to verify the schema model. I was going to put together a follow-up article last week, but spent the week traveling, in the hospital, and then recovering from being sick.

However, I am back and ready to tear apart the next installment that already hit the github repo a few days back.

Pipeline Support for JSON Documents

In BizTalk Server 2013 R2, Microsoft approached the problem of dealing with JSON content in a way fairly similar to the approach that we used in the previous version with custom components – performing the JSON conversion as an operation in the Decode stage of the pipeline, thus requiring the Disassemble stage to include an XMLDisassemble component for property promotion.

The official component Microsoft.BizTalk.Component.JsonDecoder takes in two properties Root Node and Root Node Namespace that help determine how the XML message will be created.

Finally, there isn’t a JSONReceive pipeline included in BizTalk Server 2013 R2 – only the pipeline component was included. In other words, in order to work with JSON, you will need a custom pipeline.



Creating a Pipeline for Receiving JSON Messages

Ultimately, I would like to create a pipeline that is going to be reusable so that I don’t have to create a new pipeline for each and every message that will be received. Since BizTalk message types are all about the target namespace and root node name, it’s not reasonable to set that value to be the same for every message – despite having different message bodies and content. As a result, it might be best to leave the value blank and only set it at design time.

This is also an interesting constraint, because if we are receiving this message not necessarily just as a service response, we might end up needing to create a fairly flexible schema (i.e., with a lot more choice groups) depending on the variety of inputs / responses that may be received – something that will not be explored within this blog post, but would be an excellent discussion to bring up during one of QuickLearn’s BizTalk Server Developer Deep Dive classes.

In order to make the pipeline behave in a way that will be consistent with typical BizTalk Server message processing, I decided to essentially take what we have in the XMLReceive pipeline and simply add a JsonDecoder in the Decode stage, with none of its properties set at design time.


Testing the JSONReceive Pipeline

In the same vein as my last post, I will be creating automated tests for the pipeline to verify its functionality. However, we cannot use the built-in support for testing pipelines in this case – because properties of the pipeline were left blank, and the TestablePipelineBase class does not support per instance configuration. Luckily, the Winterdom PipelineTesting library does support per instance configuration – and it has a nifty NuGet package as of June.

Unfortunately, the per-instance configuration is not really pretty. It requires an XML configuration file that resembles the guts of a bindings file in the section dedicated to the same purpose. In other words, it’s not as easy as setting properties on the class instance in code in any way. To get around that to some degree, and to be able to reuse the configuration file with different property values, I put together a template with tokens in place of the actual property values.


NOTE: If you’re copying this approach for some other pipeline components, the vt attribute is actually very important in ensuring your properties will be read correctly. See KB884981 for details.

From there, the per-instance configuration is a matter of XML manipulation and use of the ReceivePipelineWrapper class’ ApplyInstanceConfig method:

private void configureJSONReceivePipeline(ReceivePipelineWrapper pipeline, string rootNode, string namespaceUri)
    string configPath = Path.Combine(TestContext.DeploymentDirectory, "pipelineconfig.xml");

    var configDoc = XDocument.Load(configPath);




The final test code includes a validation of the output against the schema from last week’s post. As a result, we’re really dealing with an integration test here rather than a unit test, but it’s a test nonetheless.

public void JSONReceive_JSONMessage_CorrectValidXMLReturned()

    string rootNode = "ServiceResponse";
    string namespaceUri = "";

    string sourceDoc = Path.Combine(TestContext.DeploymentDirectory, "sample.json");
    string schemaPath = Path.Combine(TestContext.DeploymentDirectory, "ServiceResponse.xsd");
    string outputDoc = Path.Combine(TestContext.DeploymentDirectory, "JSONReceive.out");

    var pipeline = PipelineFactory.CreateReceivePipeline(typeof(JSONReceive));

    configureJSONReceivePipeline(pipeline, rootNode, namespaceUri);

    using (var inputStream = File.OpenRead(sourceDoc))
        var result = pipeline.Execute(MessageHelper.CreateFromStream(inputStream));

        Assert.IsTrue(result.Count > 0, "No messages returned from pipeline.");

        using (var outputFile = File.OpenWrite(outputDoc))


    ServiceResponse schema = new ServiceResponse();
    Assert.IsTrue(schema.ValidateInstance(outputDoc, Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML),
        "Output message failed validation against the schema");

    Assert.AreEqual(XDocument.Load(outputDoc).Descendants("Bid").First().Value, "44.97", "Incorrect Bid amount in output file");


After giving it a run, it looks like we have a winner.


Coming Up in the Next Installment

In the next installment of this series, I will actually put to use what we have here, and build out a more complete integration that allows us to experience sending JSON messages as well, using the new JsonEncoder component.

Take care until then!

If you would like to access sample code for this blog post, you can find it on github.

Why Updated Platform Support Matters

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

Each new version of BizTalk brings with it support for the latest Microsoft Operating System, Database Engine, and Integrated Development Environment. It is listed as a new feature each time, and many tend to skip over that feature on the new features list. However, this is actually very powerful – especially when considering the change over time in those underlying platforms.

In this post, I’m going to examine how the Microsoft Fakes framework (found in Visual Studio 2012.2 Premium) can enable interesting testing scenarios for code that wasn’t built specifically for test. In the process, I’m also going to be using the Winterdom  PipelineTesting library – which is easily upgraded to 2013 with some re-referencing of BizTalk assemblies.

Testing the Un-Testable

The Microsoft Fakes framework (available in Visual Studio 2012 Ultimate, or 2012.2 Premium edition and above) provides the ability to create both stubs and shims of any .NET interface or class respectively. While the stubs capability is pretty neat, they don’t feel nearly as magical as the shims.

Consider that you have developed a pipeline component with a little bit of logic to inject a context property based on the current date/time. The scenario (although contrived) that I have come up with is that of an order processing system in which rush orders are all received through the same receive location. In that location is a custom pipeline that must promote a property to route to the warehouse that will be able to get the order picked and shipped the quickest (based on which warehouse is picking orders at the current hour, or will be doing so next). When testing the code, we will need to verify the behavior of the code at specific times.

While we could write the code in such a way that the retrieval of the current date/time was done through a special date/time provider class (which implements some interface specialized to that purpose), the logic is being re-used from another location – one which will not be modified.

BizTalk Server 2013 will rise to this occasion due to relying on Visual Studio 2012 as its development environment. We can use the included Microsoft Fakes framework to create a shim that will inject logic for all calls to DateTime.UtcNow to return a fixed DateTime object of our choosing.

getting Started with Shims

In order to get started, we need to instruct Visual Studio to generate some helper classes for the assembly or assemblies of our choosing. These classes will enable us to generate Stubs/Shims for classes within these assemblies.

For our solution, we will be working with the DateTime class, found in System. We can add a fakes assembly in two clicks via the context menu:


After adding the assembly, our project, and its references, look like this:


Now we will have to write the code in such a way that calls to DateTime.UtcNow will return the value of our choosing. In order to hook into those calls only within a specific portion of code, we will need to create a ShimsContext. Because the ShimsContext class implements IDisposable, we are able to wrap a using statement around it to provide better visibility of the scope it will control.

        public void RushOrderMarker_FirstPartOfDay_FirstWarehouseReturned()

            // Arrange
            var pipeline = GeneratePipeline();
            var testMessage = GenerateTestMessage();

            DateTime fakeTime = new DateTime(
                                    year: 2013,
                                    month: 01,
                                    day: 01,
                                    hour: 1, minute: 0, second: 0);

            using (ShimsContext.Create())

                System.Fakes.ShimDateTime.UtcNowGet = () => { return fakeTime; };
                var expectedId = WarehouseIdentifiers[0];

                // Act
                var output = pipeline.Execute(testMessage);

                // Assert
                var warehouseId = output[0].Context.Read(WAREHOUSE_ID_PROPERTY_NAME, WAREHOUSE_ID_PROPERTY_NAMESPACE);
                Assert.AreEqual(expectedId, Convert.ToString(warehouseId), "Incorrect warehouse id returned");




Here we assign logic directly to System.Fakes.ShimDateTime.UtcNowGet that will execute when any code within the scope after ShimsContext.Create() was called attempts to call DateTime.UtcNow. We then submit a message through our pipeline and verify that the correct warehouse id was promoted into the context of the message (based on the current time).

Know your Tools

If you’ve just made the move up to BizTalk Server 2013, it really is important that you not only know what feature set you have in the platform, but also what is available to you in the underlying platform, and the tools you use to create your applications.

If you want to learn BizTalk Server 2013 in the environment it was designed for, check out one of our upcoming BizTalk 2013 Developer Immersion, or BizTalk Server 2013 Deep Dive classes. The hands-on-lab environment is running the latest and greatest versions of Windows Server, SQL Server, and Visual Studio, so that you have the optimal BizTalk Server development experience.

If you would like to access sample code for this blog post, you can find it on github.

Automated Deployment and Testing of BizTalk Server 2010 Applications

Back when BizTalk Server 2009 was released, there was a lot of buzz about the new integrated support for unit testing of schemas, maps, and pipelines, and cleaner support for automated builds driven by Team Foundation Server (TFS). These were definitely welcome additions that made it much easier to enable continuous integration with automated build and testing. However, there were some things missing. In this article, I’ll review the current state of automated build and testing capabilities that exists for BizTalk Server 2010 when using Visual Studio 2010 Team Foundation Server (TFS). I will first examine the items lacking out of the box, and then direct you to community projects that can improve the situation.

When it comes to the built-in unit testing support in BizTalk Server 2009 and 2010, there are still some areas lacking. For example, testing schemas with imports yielded erroneous results, as all of the necessary schemas were not used in validation. Testing pipelines cannot be accomplished purely in memory with the API exposed. There was not really any work done to enable integration and functional testing of orchestrations. Finally, the automated build process did not take into account the necessity for the bits that were compiled to be deployed somewhere for testing — possibly due to the lack of functional and integration testing support for orchestrations (i.e., there would be no reason to deploy bits that could not be tested anyway).

Thankfully, community efforts filled in most of these gaps for BizTalk Server 2009, and indeed in most cases these community projects preceded the implementation of automated build and testing support in BizTalk Server. Pipeline, pipeline component, and flat-file schema testing was made much more elegant with Tomas Restrepo’s PipelineTesting library. Functional and integration testing of orchestrations was provided for in BizUnit, and automated deployment in preparation for test could be enabled using the bLogical Custom Tasks.

You may have used one or all of these community tools when setting up an environment with BizTalk Server 2009 and Team Foundation Server 2008, and it is still possible to use most of the functionality offered by these in BizTalk Server 2010 and Team Foundation Server 2010. If you have not had any experience with enabling automated testing of BizTalk Server applications, you may benefit from our self-paced online training course covering BizTalk testing strategies.

PipelineTesting Library

The PipelineTesting library is a mature and stable library that has been well maintained and has always remained a step ahead of what was offered out of the box with each version of BizTalk Server. It not only provides a less-clunky API, but a fuller feature set. This is best shown by a short example (although this example does not even get into the depth of what is provided in the PipelineTesting library).

Here is some rough sample code that shows basic usage of the built-in BizTalk Pipeline Testing support:

public void TimeReportFFReceivePipeline_TimeReportFF_OutputValidates()
    // Built-in BizTalk Pipeline Testing Support
    // (CON: Must be enabled on pipeline project before compilation)

    // CON: Must create the pipeline ahead of time
    TimeReportFFReceivePipeline target = new TimeReportFFReceivePipeline();

    // PRO: Can provide a list of input documents without loading them explicitly
    // CON: Input documents must exist on disk
    StringCollection inputDocuments = new StringCollection();
    inputDocuments.Add(Path.Combine(TestContext.TestDeploymentDir, "TimeReport_3.txt"));

    StringCollection parts = new StringCollection();

    Dictionary schemas = new Dictionary();
    // CON: Must reference .xsd file
    schemas.Add("TestWorkshopApplication.Messaging.TimeReportFF", @"......MessagingTimeReportFF.xsd");

    target.TestPipeline(inputDocuments, parts, schemas);

    // CON: Must locate output messages as files
    DirectoryInfo testDir = new DirectoryInfo(TestContext.TestDeploymentDir);
    FileInfo[] outputList = testDir.GetFiles("*.out");

    Assert.IsTrue((outputList.Length > 0), "No outputs for pipeline found");

    foreach (FileInfo file in outputList)

        /* Additional testing of message content */


Now compare that with a code performing roughly the same test using the PipelineTesting library:

public void TimeReportFFInPipeline_TimeReportFF_OutputValidates()

    // PipelineTesting Library Pipeline Testing Support

    String sourceFile = Path.Combine(TestContext.TestDeploymentDir, "TimeReport_4.txt");

    // PRO: Can compose a pipeline at runtime
    FFDisassembler ffDasm = Disassembler.FlatFile().WithDocumentSpec(typeof(TimeReportFF));
    ReceivePipelineWrapper target = Pipelines.Receive().WithDisassembler(ffDasm);

    MessageCollection result;

    // CON: Have to manually load input document
    // PRO: Input document can exist only in memory
    using (var readStream = File.OpenRead(sourceFile))
        IBaseMessage msg = MessageHelper.CreateFromStream(readStream);
        result = target.Execute(msg);

    Assert.IsTrue(result.Count > 0, "No outputs found from flat file pipeline");

    // PRO: Raw IBaseMessage instances of outputs are available in memory
    foreach (IBaseMessage msg in result)

        /* Additional testing of message content or context */


It actually doesn’t take too much effort to get this library working with your BizTalk Server 2010 solutions, and in turn with Team Foundation Server 2010. You will have to upgrade the solution to the Visual Studio 2010 format, and re-reference the PipelineObjects library (exists under the Program FilesMicrosoft Visual Studio 10.0Common7IDEPublicAssemblies folder). If you don’t have NUnit installed, you can exclude the Test project from the build. Once you have it built, you’re good to start writing tests against your BizTalk Server 2010 artifacts. When automating the build and test with Team Foundation Server, you will need to remember to include the .dll somewhere within source control.

BizUnit 3.1

BizUnit is a framework for performing automated integration and functional testing of BizTalk solutions. It takes a black-box approach, and requires that all artifacts are built and deployed before testing commences. If you already perform manual end-to-end testing of your BizTalk applications, you could likely benefit greatly from BizUnit over time. It provides a huge library of pre-built test steps (e.g., start BizTalk host, copy a file, wait for a file, execute a database query) that have the net effect of saving you a lot of time. Test cases, which are combinations of test steps, exist in a declarative XML format that are processed by the BizUnit class which can be invoked from within your MSTest or NUnit test assemblies.

Getting BizUnit working for BizTalk Server 2010 is not necessarily a very easy process. Before you even begin, you must consider that there are two versions currently available. The most recent version is BizUnit 4.0 Beta, which completely changes the test case format (to use XAML), and looks to be the way of the future. However, it does not look like that version has been updated in quite some time, so it is unclear when a final release will be ready. The other version available is BizUnit 3.1, which is stable and has a fully developed library of test steps along with full documentation. For the sake of this blog posting, we will go forward with 3.1, and examine some of the issues you will encounter.

This is another instance in which you will have to upgrade the solution to the Visual Studio 2010 solution file format. From there, you will notice that the solution has a project for each category of test step (e.g., BizTalk steps, LoadGen steps, MQ Series steps, Outlook automation steps, etc…). You can exclude the project for any type of step that you will not be using. Then for each of the “Steps” projects, you will need to re-reference assemblies, so that the latest versions are referenced. You might notice at this point, that the BizTalkSteps project has a dependency on the PipelineTesting library already discussed. You will definitely want to include the version that you built against the BizTalk Server 2010 binaries here. This is another place where you will need to remember to include the .dll’s for both the BizUnit runtime and the steps that you will be using within source control, or simply install BizUnit on each build server if that makes more sense in your environment.

bLogical Custom Tasks

With BizTalk Server 2009, it became possible to automate builds of BizTalk applications without installing Visual Studio on the build server (though it is required to install the Project Build Component from the BizTalk installation media). It was also possible with BizTalk Server 2009 to automate tests and, with the help of community tools, automate integration and functional tests. However it was still not possible, using only out-of-the-box functionality, to include deployment as part of the build. The custom MSBuild Tasks for BizTalk by bLogical were developed to add the missing deployment step to the automated build process. Unfortunately, there are a few issues that still need to be overcome for these to work with Team Foundation Server 2010.

First, the easiest problem to deal with is in the GacHelper.cs class within the project:

namespace Blogical.Shared.Tools.BizTalkBuildTasks.Internal
	public class GacHelper
		#region Private Fields
		const string ToolName = "bin\gacutil.exe";

This path gets concatenated with the path to the .NET Framework SDK to resolve the full path to the gacutil tool. Unfortunately, this will reference the old gacutil tool. For .NET 4 assemblies, the new tool path should be "bin\NETFX 4.0 Toolsgacutil.exe".

The second hurdle isn’t so easily solved. There is a dependency, mainly in the internal TeamBuildTask base class, on classes within the Microsoft.TeamFoundation.Build.Proxy namespace. This has been obsoleted, and no longer appears in the 2010 version of the assembly. This means that, at least for now, you will now have to provide your own solution for these small missing pieces in the automated build/deployment process. Post a comment if you have found an alternative solution, or keep watching this space for updates on this.


Using BizTalk Server 2010, you can still benefit from the automated build and testing capabilities released with BizTalk Server 2009, and most of the community solutions developed to enable continuous integration. There are a few steps necessary to get everything working and setup, and a few missing pieces that you will have to build yourself, but the end result is beautiful.

Also, bear in mind that Team Foundation Server is not just about source control and it’s not just about automated build or testing. It’s also about issue tracking, project management, and reporting. If you are paying for a license, make sure that your organization is taking full advantage of it — especially on your BizTalk Server integration solutions. Be sure to check our new collection of instructor-led training on Application Lifecycle Management using Visual Studio 2010 and Team Foundation Server 2010.