Pipeline Components

It gives me great pleasure to announce Version 1.0 of the BizTalk Message Archiving Pipeline Component and my new venture, Atomic-Scope.

The component allows you to archive Xml, flat-file, EDI and binary messages as they pass thru receive and send pipelines, without the need for complex ‘archiving’ Send Port configurations, additional load on the MessageBox database and requires zero developer time – just plug-in, configure and use! Archive filenames are created at runtime from Context-Properties written to the message by receive adapters, custom properties defined in your solution or with the standard Send Port ‘macros’. A free 14-day trial is available – download your copy now.

This new version of the component builds on the excellent feedback received following the launch of the original version on Codeplex and has spent many months in development – this release is a complete re-write and incorporates many of the community requested features, including:

The ability to enable and disable the component at runtime;

The promotion of the archive filename into the Message Context for use in orchestrations, Send Port filters etc.;

Full streaming support, even for messages that fail when being processed by downstream components (such as flat-file or EDI messages);

Support for a wide-range of adapter Context-Properties ‘out-of-the-box’ and custom, user-defined Context-Properties;

Today I’m releasing a small component that addresses an interesting problem I’ve never come across before – a null response from a web-service.

The web-service in question is provided by a third-party and unfortunately cannot be changed. Their WSDL defines the root response element with a maxOccurs=1 and a minOccurs=0, which allows for a null response to be returned. So instead of a result element with no child nodes as I would expect (below in green):

When the SOAP adapter receives this null response, it creates a message but neglects to create a body part – I presume this is because there is nothing to create it from. As a result, the message fails in both an XmlReceive and PassThruReceive pipeline; when using the PassThruReceive pipeline, the XLANG/s engine throws the following error when it tries to read the body part:

The XLANG/s message has no part at index ‘0’. The total number of parts found in the message is ‘0’. If you expect a multipart message, check that the pipeline supports multipart messages such as MIME.

To address this problem, I’ve created a very simple receive pipeline component which lives on the receive side of the web-service solicit-response port and interrogates a message to determine whether it has a message body. If a message body is not present, it creates one based on the component properties (which mimic the expected – valid – response from the web-service) allowing the response message to be passed into the Message Box without issue. It a message body is present, it passes the message through unchanged.

The CreateBodyPart Pipeline Component

The component lives in the Decode stage of the receive pipeline and simply detects for the presence of a message body. If the body part is null, a new message part is created using the component properties BodyPartName and BodyPartContent and assigned as the body part of the message, before being passed onto the next stage of the pipeline. The BodyPartName and BodyPartContent properties specify the name of the body part and the Xml you want the part to contain – given that the content of the message is likely to be small-ish (i.e. <PendingSalesOrdersResult xmlns=”…” /> in the example above).

There are a few enhancements that I can envisage for this component already, including the ability to specify whether the part should be a body part – you might just want to create extra parts on the fly, not just a body part; and also the ability to specify the encoding and character set being used with your part content. However, I’ll leave these enhancements for a later day.

As a final note, my client is currently running BizTalk 2006 (not R2) and we are running on the out-of-box SOAP adapter. Does anyone know whether this issue is a problem in the WCF-SOAP adapter or the WSE adapter?

NCover is a code coverage tool which, to quote the website, “helps you test intelligently by revealing which tests haven’t been written yet.” In laymans terms, NCover graphically shows you which lines of code were not touched during the execution of your unit tests, allowing you to create tests accordingly to achieve 100% code coverage, as shown below:

Producing command-line output similar to the following (notice the NUnit tests running between the ***Program Output*** and ***End Program Output*** text):

NCover has now determined the code coverage based of your unit tests and produces a Coverage.Xml file. This file contains information relating to the code coverage and can be loaded in the NCover.Explorer tool to produce a VS like environment that displays lines of code that were touched and un-touched by your unit tests.

4. Load the NCover.Explorer tool and open the Coverage.Xml file generated above, you will be presented with a screen detailing your code coverage. In the example below, you can see that the PerformImmediateCopy and StreamOnReadEvent methods do not have full code coverage – both have code which was not executed in our unit tests:

Clicking on one of the methods in the tree view loads the offending method, displaying the lines which were not executed by our tests in red; lines that were executed are displayed in blue:

Based on this information, we can now create tests to cater for these exceptions, ensuring we have 100% code coverage.

NCover is an excellent tool and although it isn’t free, I personally think its a must-have for any developers tool-kit.

I’ve re-worked the BizTalk 2006 Message Archiving Component as a true streaming pipeline component – utilising a forward only eventing stream – to more efficiently use process resources when archiving large files, as suggested by Mikael Håkansson. The updated version is on CodePlex as version 0.3.

Writing of the archive file is now accomplished during the read-event of the FOE stream, essentially spooling the archive file to disk (or network share) as the stream is read by downstream components or the Messaging Agent itself. The BizTalk process memory footprint using this new code-base (while testing with a large (10Mb) message) is 90% more efficient than previous versions.

A couple of days ago I uploaded a revised version of my BizTalk 2006 Message Archiving Component onto CodePlex – version 0.2 can be downloaded from the CodePlex website at http://www.codeplex.com/btsmsgarchcomp.

The component works with BizTalk 2006 & BizTalk 2006 R2 and allows messages to be written to the file system (either locally or over a network share) for archiving, using message context-properties to define the archive path. It is written in a streaming fashion, is designed for large message consumption and can handle Xml, binary and flat-files.

The component can be executed in either the Decode (receive pipeline) or Encode (send pipeline) stages – when used on the receive side, the original message can be archived before BizTalk has started to manipulate the message; on the send side, the final message before delivery via the send adapter can be captured. If message archiving fails, the message will still continue downstream.

As per the previous version, the archive path is constructed using ‘macros’ (e.g. %ReceivePortName%) which relate to message Context Properties. In the previous version, these macro’s were hard-coded into the component so changing or adding a new macro was painful, requiring a rebuild of the code base. The new version continues the theme of macros, however they have moved into an Xml configuration file, which can be configured at run-time, allowing any context-property (either a known BizTalk context property or a custom adapter/pipeline property) to be used. An example of the configuration file is shown below:

These macros are used when defining the archive file path in the component configuration (in the BizTalk Server Admin Console) – see the screenshot below. The archive file path is constructed using the ArchiveDirectory and ArchiveFilename properties. Macros can be repeated and/or used in both properties at the same time (however I can think of scenarios where you may not wish to use say ReceivePortName in the archive filename).

Note: When configuring the component properties, you are specifing the macro name, not the context property name. This is useful when you are using a single configuration file and want to read the ReceivedFileName context property from both the FTP and FILE adapters for example (both use the same property name, but different property namespaces) – in this scenario, you would call the macro’s ‘ReceivedFileNameFILE’ and ‘ReceivedFileNameFTP’ to avoid ambiguity.

The example Macro Definition Xml file shown above details macros for the System Context Properties ReceivePortName and ReceiveLocationName. To use these macros in the pipeline component, assign them in the Archive Directory or Archive Filename property, as below.

These macro’s (%ReceivePortName%, %ReceiveLocationName% and %MessageID%) will be expanded as a message is delivered via the port to their real-world values, writing the archived message to (for example):

In the example above we’re using the %MessageID% macro to build the archive filename. This is a special macro as the value does not come from the message Context, but is taken directly from the message itself, similar to using %MessageID%.xml in a Send FILE adapter.

The OverwriteExistingFile property indicates to the component whether an existing file should be overwritten if, once the archive path has been constructed from the Context Property macros, the full archive path resolves to an existing file. If set to true, the existing file will be overwritten; if false, the new file will be written to the same directory, but with an additional GUID before the file extension.

Finally, the MacroDefinitionsFile property defines the location to the Xml configuration file detailing the macro Context Property substitutions. A different file can be used per pipeline, or a single global file can be used. A more detailed example than that shown above – which includes macro’s for commonly used Message Tracking, System and File adapter properties – is available to download.

With regards to permissions, you will need to ensure that the user running the BizTalk service has read permissions on the macro definitions Xml configuration file and read/write permissions on the root of the archive directory.

Although the component is production ready it is not yet feature complete. If you are using the previous version, can I ask you to download a copy and try it out – please let me have any feedback via the comments on this post, or via the Issue Tracker pages of the CodePlex project.

I’ve spent some time recently working almost exclusively with BizTalk pipeline components and took the opportunity to use the excellent Pipeline Testing Library produced by Tomas Restrepo (more info is available here and here). If Microsoft were writing this post, they would probably say that ‘It Rocks!’. I’m British, so I’ll be a little more reserved and simply say that, imho, this is the single best tool for developing and testing custom pipeline components, period.

The library provides a framework for unit-testing components in the standard NUnit or MSTest manner, without having to go to Pipeline.exe or doing a full deployment to a BizTalk instance itself – both of which aren’t particularly quick or agile. Furthermore, the library lets you seamlessly integrate with MSBuild, without jumping through lots of hoops to get a similar effect.

The library allows you to programatticaly create pipelines, create instances of components and assign them to their respective stages (including your own custom components and the familiar out-of-the-box components), or load an existing BizTalk pipeline without the need to deploy the supporting BizTalk project.

A very simple example from my recent testing looks something like the following:

Here, I’m creating an instance of my archiving component (the component I’m testing) and the Xml Disassembler (specifying the document type it should accept). I create a new receive pipeline and assign the archiving component to the decode stage and the XmlDasm to the disassembler stage. After creating a sample message using the MessageHelper helper, I add context properties that mimic the adapter I’m trying to test (in this case the FILE adapter) and execute the pipeline. I finally test to check that the archiving component wrote the file to the archive in the expected location, with the expected filename.

If you want to test using Flat-Files, simply use a flat-file disassembler and specify the schema:

Powerful stuff – no more long-winded MSBuild tasks to deploy your solution, configure several possible adapters and push messages to those adapters over different protocols, simply to test a custom pipeline component on your development workstation (and lose 5-10 minutes in the process). Don’t get me wrong, all this should be happening in your smoke and UAT environments, but for the developer (attempting) to work in an agile manner on a BizTalk project, Tomas’ Pipeline Testing library is priceless.

In this post I’ll discuss how to generate Word 2007 documents natively from BizTalk 2006 using the Office Open Xml System.IO.Packaging API recently released by the Microsoft Office Team under .Net 3.0.

Background

Unless you’ve lived under a rock during the last year, you’ll know that the Office Open XML (OOXML) format is the new Xml format for the Office 2007 suite, namely Word, Excel and Powerpoint. OOXML uses a file package conforming to the Open Packaging Convention and contains a number of individual files that form the basis of the document; the package is then zipped to reduce the overall size of the resulting file (either a .docx, .xlsx or .pptx).

Generating Word Documents – Overview

Generating a Word document is relatively simple and only requires a custom send pipeline component that generates our OOXML package.

In this post I will be using a Sales Report scenario, generating a Word document from the output of a fictional ERP system; to that extent, I’ll also be mapping from a fictional sales summary Xml message to the required OOXML format before generating the final .docx. The final document will look something like the following (note that the areas in red will be replaced with content from our ERP sales summary message – click on the image for a larger version):

Before we start, I need to present a quick crash-course in the structure of OOXML packages. A minimal OOXML WordprocessingML document contains three parts: a part that defines the main document body, usually called document.xml; a part detailing the Content Types (which indicates to the consumer what type of content can be expected in the package); and a Relationships part (which ties the document parts and Content Types together). When using the System.IO.Packaging API we only need to concern ourselves with the main document body – the API takes care of creating the Content Types and Relationship parts. Its this feature of the API that allows us to create Word documents in BizTalk – all we need to do is create the Xml for the main document and squirt it at a custom pipeline component which does the packaging stuff for us using the API.

Note that the structure of an OOXML document is outside of the scope of this post (but a good understanding is fundamental when working with these documents) and I would recommend that you read the excellent Open Xml Markup Explained by Wouter van Vugt.

Generating Word Documents – The ‘Main’ Document

The main document body (i.e. document.xml) is the only part that is generated in the BizTalk solution. We don’t actually create a file called document.xml – the packaging API does this for us – instead we simply create a message that conforms to the OOXML schema and pass this into the custom Send pipeline.

In our scenario, we are generating a Sales Report document for distribution to the finance department – we will receive an Xml sales summary document from our fictional ERP system that resembles the following:

<?xmlversion="1.0"encoding="utf-8"?><ns0:SalesReportxmlns:ns0="http://schemas.modhul.com/erp/salesreport-1.0"><Author>Nick Heppleston</Author><Email>nick@modhul.com</Email><SalesStart>10th January 2008</SalesStart><SalesEnd>17th January 2008</SalesEnd><SalesSummary>100,48.00</SalesSummary></ns0:SalesReport>

which needs to be mapped into our OOXML main document body message (I think the layout of the OOXML message is pretty self explanatory, however I would point you at Open Xml Markup Explained if you’re after a more detailed explanation):

This transformation can be performed anywhere: in the sample solution I’ve put the map on the Receive Port. Also, because I can’t think of any way to generate this type of message using a standard BizTalk Map – how do I graphically say ‘map from this source node to this destination node’ when all of the destination nodes simply repeat themselves – I am using custom XSLT to drive the map.

Note: I’ve yet to find a satisfactory XSD for the WordprocessingML markup so the solution contains a OOXML schema that was automagically generated from the above destination format. I’m working on sourcing the schema – I have a number of ‘feelers’ out with the Office Team and I hope to be able to provide a reference in the next couple of days.

With our Sales Summary message now mapped and in the necessary OOXML format, we can send it to the custom pipeline / pipeline component for it to do its work and generate our .docx package.

Generating Word Documents – The Custom Pipeline Component

The custom pipeline component is relatively simple. It uses the System.IO.Packaging API introduced in .Net 3.0 which can be found in windowsbase.dll (C:Program FilesReference AssembliesMicrosoftFrameworkv3.0windowsbase.dll); full documentation regarding this namespace can be found online at MSDN. The API is invoked in the pipeline component Execute() method as follows:

Line 26: We load a copy of the original message data part stream into an XmlDocument to use as the main document body (the document.xml) when building the package.

Line 31: Create a new OOXML package in a new MemoryStream.

Line 34: Create a URI to the main document body (calling it document.xml).

Line 37: Create the main document body part (docPartUri and docContentType.

Lines 40 – 43: Save the contents of our BizTalk message to the main document body part (the message we created in the BizTalk map).

Line 46: Create a package relationship for the main document body part.

Line 60 & 69 – 70: Rewind the the MemoryStream and overwrite the original message with our new OOXML package.

Line 75: We return the message containing the OOXML package.

The final message is sent via the FILE adapter and written to the file system. The end result looks like this (click on the image for a larger version):

The complete solution – containing the pipeline component and a BizTalk proof of concept project – is available to download and can be found archived in the downloads area of this blog. Grab a copy, try it out for yourself; comments and suggestions are welcome.

Conclusion

In this post I hope I’ve shown you the tools necessary to generate Word 2007 documents natively using BizTalk 2006. The example I presented is extremely simple and does not include styles, themes, images, headers and footers, font tables etc. that would exist in a real-life document, but I hope it has presented a starting-point for your own custom development.

These same techniques can also be applied to create Excel spreadsheets or PowerPoint presentations – in fact, while writing this post I have had a number of ideas for enhancements to the pipeline component and will endeavour to create a CodePlex project if I can find the time.

Disclaimer

This work is licensed under a Creative Commons Attribution 2.5 License – you can use commercially and modify as necessary, but you must give the original author credit. Furthermore, sample projects and code are provided “AS IS” with no warranty.Click the image below to view further detail of the licence.