Talk, talk and more talk about BizTalk

Root element is missing

Simply a minor facepalm moment I want to document to help both myself and others avoid unnecessarily wasting an hour. Like I just did…

You’re attempting to perform a ‘Validate Instance’ of a document against the .xsd schema definition, and receiving the following error:

   C:\path\to\sample\data.xml: warning BEC2004: Root element is missing.

Step 1: Make sure to close Excel/TextEdit/whatever external program is preventing Visual Studio from obtaining an exclusive lock on the sample file.
Step 2: Step away from the keyboard, grab a cup of tea and some air. You need it…


September 27, 2012 Posted by | BizTalk | , | 1 Comment

When to Stop/Restart a Host Instance

Further to a question I recently answered on StackOverflow, I wanted to expand a little on when it is necessary to restart a BizTalk Host Instance, and when this is overkill.

Host Instance restart required

Any change to an underlying datatype, map or orchestration will require a restart of the corresponding Host Instance.  This is due to the way the .Net runtime manages type-loading of assemblies.

All BizTalk schemas, maps and orchestrations are compiled to .Net code inside an Assembly.  The .Net runtime supports dynamic loading and type-discovery of Assemblies, but does not support removal or un-loading.  This means that any time you change any code-based .Net artefact, a Host Instance restart is required before the change will be seen.

Runtime Configuration change

The counter to this is Configuration based runtime artefacts, including the configuration and binding of BizTalk Adapters.  For example, it is possible to change the path and file-mask properties of a File based Receive Adapter, or even change from using a File Receive Adapter to a SQL Receive Adapter within the same Receive Port, with the chage reflected immediately, and with zero down-time.

September 17, 2012 Posted by | BizTalk | , | Leave a comment

Dynamics AX 2009 adapter “Unable to log on to Microsoft Dynamics AX.”

This post is just to clarify the authentication settings required for being able to receive messages from Microsoft Dynamics AX (2009) into BizTalk using the older-style Microsoft Dynamics Adapter.  The latest version of AX uses a more generic WCF based approach, so your mileage may vary.

Firstly, there are two sets of of credentials to provide into the adapter:

  • Gateway user – These are the Domain credentials used to authenticate to the AX Server
  • Proxy user – The username, and password, of an additional Domain user, as setup in Dynamics

The Proxy User details can be determined within Dynamics from the set of credentials, that the “BizTalk” service account uses to connect to AX.

July 30, 2012 Posted by | BizTalk | , , | Leave a comment

Essential plugins for Notepad++

I really, really like Notepad++ as a drop-in replacement for the standard Windows Notepad.

It’s fast, light-weight, can open just about any file format, regardless of encoding or byte-order marks. And best of all, it’s free!

There are a couple of plug-ins that I consider almost essential when developing, especially when working with Xml and Xslt files:

  • XPatherizerNPP – Supports ad-hoc testing of xpath queries against your current document.  Also provides standardised reformatting of an Xml file for readability
  • XML Tools – A host of simple tools, including reformatting, validation against schemas, escaping/un-escaping xml to HTML encoding
  • Regex Helper – Useful for testing out Regular Expressions.  Yes, I know, now I have 2 problems, but when used, and documented, well, a single RegEx can save a lot of coding effort

Notepad++ plug-ins are now fully integrated into the application itself, and these 3 can be installed simply by selecting the master “Plugin Manager” plugin from the drop-down menu.  It’s usually the first thing I do when setting up a new development environment.


July 12, 2012 Posted by | Uncategorized | | Leave a comment

Changing / Removing document namespaces

I recently ran into a requirement to both transmit and receive documents using “Plain Old Xml”. The system we were integrating was not able to understand the concept of namespaces in an Xml document, but BizTalk requires them, as messages are determined by the combination of a document’s Namespace and Root Node.

The solution was two-fold. For incoming messages, we “inject” a pre-determined namespace into the document as soon as it hits BizTalk. For outbound messages, we strip out all namespaces and alias’ just as we are sending it. The best was to do this is using a Pipeline Component.

There are a number of components and methods out there for adding a namespace to an inbound messages, see here and here.  I ended up re-using a sample I found on CodePlex.

To remove namespaces from the outbound messages, I massaged the content of the message using a Regular Expression, and some simple text replacement:

private static string RemoveNamespace(XmlDocument xdoc)
  // Regex to search for either xmlns:nsN="..." or xmlns="..."
  const string pattern = @"xmlns:?(\w+)?=""[\w:/.]*""";
  string xml = xdoc.OuterXml;

  Regex replace = new Regex(pattern);
  // Replace all occurances of the namespace declaration
  string temp = replace.Replace(xml, String.Empty);
  foreach (Match match in replace.Matches(xml))
    // Loop through each Match in the Regex, this gives us the namespace aliases found
    if (match.Success && match.Groups.Count > 1)
      if (!String.IsNullOrEmpty( match.Groups[1].Value))
        Regex alias = new Regex(@"\b" + match.Groups[1].Value + ":");
        // Replace all occurances of the
        temp = alias.Replace(temp, String.Empty);
  return temp;

The regular expression identifies namespace declarations, whether they declare an alias or not.  We then iterate all of the matched aliases, removing them from the target xml document.

Edit: I have added a link to cut-down sample project, detailing exactly how the pipeline component should be implemented.  Click here to download.

Edit2: Modified the regex pattern slightly so it also accounts for elements declared in the “empty” namespace.

June 26, 2012 Posted by | BizTalk, Pipeline | , , | 3 Comments

Unexpected use of keyword: ‘task’

I am currently using BizTalk 2010 as the integration hub between a number of systems, including Microsoft Dynamics CRM Online. The XLANG/s Orchestration compiler will complain with the following:

Unexpected use of keyword: ‘task’

One of the core entities in CRM is the ‘Task’, a sub-type of an Activity in the Sales process. However, we run into a problem in BizTalk when working with the schemas generated out of CRM, as ‘Task’ is also a reserved word in XLANG/s.

My solution was to create a ‘taskInternal’ schema alongside the generated ‘task’ schema. I set the Data Structure Type of taskInternal to the complex type ‘task’, to avoid redundant data types. Now we can build and compile our Orchestration just fine, as ‘taskInternal’ is not a reserved word.

Finally, we need a pair of very simple maps, from taskInternal->task and from task->taskInternal. These are applied on our physical Send Port, in the Outbound Maps and Inbound Maps sections respectively. Without this Inbound/Outbound mapping, we are not sending the correct Xml message types to/from CRM.

Note, there are another couple of reserved words that you might want to take a similar approach with, for example, ‘operator’ and ‘request’ are both reserved in XLANG/s.

September 27, 2011 Posted by | BizTalk, CRM 2011, WCF | , , | Leave a comment

CRM Online web services – (407) Proxy Authentication Required

I am currently in the process of integrating several back-end systems with Microsoft Dynamics CRM Online, utilising BizTalk as the integration hub platform.

WCF, and specifically the “Consume Adapter Service” within Visual Studio, abstracts the creation of CRM Schemas to the point that the process is just like any other WCF service.

However, I came to a screeching halt when trying to test the creation of any Entity within CRM Online. The ISA Server was complaining, resulting in the following exception being thrown:

System.Net.WebException: The remote server returned an error: (407) Proxy Authentication Required.

None of the inbuilt authentication settings within the WCF-Custom Transport Properties window were any help (trust me, I tried ’em all), the Adapter appears to ignore any Proxy Authentication settings.

The solution is to instruct WCF, at the Windows Process level, to use the default Windows proxy settings. This is done by adding the following section into your BTSNTSvc.exe.config file:

    <defaultProxy useDefaultCredentials="true" >
        <proxy usesystemdefault="true" />

This is, however, a less-than-ideal solution, as it applies a blanket setting to all BizTalk Host Instances on the server.
Note: If you are in a 64-bit environment, and using a 64-bit Host Instance, you need to make the change in the BTNTSvc64.exe.config file instead.

September 8, 2011 Posted by | BizTalk, CRM 2011, WCF | | 1 Comment

Post build task to add .Net component to GAC

Occasionally I’ll need to write a helper .Net function to fill the gap where standard BizTalk functionality is not flexible enough.  This is usually often enough that I follow a pattern of having a “.Helpers” assembly associated with every BizTalk application I develop.

These Helper assemblies compile and can be referenced by other projects in the solution just fine, but when the application is later deployed, or exported as an MSI package, we usually find one of the following occurs:

  • A referenced DLL is missing from the GAC (easily fixed),
  • An older, stale, version of the Helper dll is exported in the packaged MSI, due to subsequent versions of the Helper not having been updated in the BizTalk metabase
The following Post-build Event Command Line will ensure the Helper DLL is successfully added to the GAC on the local machine, then update the BizTalk application to include the latest binary copy of the DLL in its resource manifest:

"%ProgramFiles(x86)%\Microsoft SDKs\Windows\v7.0A\Bin\gacutil.exe" /i $(TargetPath)
btstask.exe AddResource -Application:{BizTalk Application Name} -Type:System.BizTalk:Assembly -Overwrite -Source:$(TargetPath)

Be sure to remember to replace the {BizTalk Application Name} token with the relevant Application Name, and change the “Run the post-build event” drop-down option to “When the build updates the project output”

Edit: For 32-bit BizTalk environments, replace %ProgramFiles(x86)% with %ProgramFiles%

Edit 2: When working with BizTalk 2010 (and later), the gacutil executable will be found in a different location.  This is due to the Framework 4.0 GAC being both structured and located differently to earlier versions.  The compatible version of gacutil.exe can now be found at:

"%ProgramFiles(x86)%\Microsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\gacutil.exe"

August 22, 2011 Posted by | BizTalk | Leave a comment

Calling helper methods from the Business Rules Engine

Here’s a trick that usually gets people new to BizTalk.

The Business Rule Engine has the ability to call (public) static methods on any .Net class, without needing to assert an instance of the class first. However, when you execute your policy, nothing is returned into the policy, and your rules will not work as expected.

The problem is that, by default, the BRE will not execute the static method, unless a specific registry setting is set.  This keeps the default behaviour backwards compatible with the original BTS2004 release of the BRE.

To enable calling these methods, add a REG_DWORD key named “StaticSupport“, with a value of “1” to the following registry path:

32-bit Windows


64-bit Windows


August 16, 2011 Posted by | BizTalk | , , , | Leave a comment

Calling a one-way WCF Service from BizTalk

I recently ran into a real conundrum at the end of a deployment when we discovered that we would be sending messages to a one way (i.e. fire-and-forget) web service using the inbuilt WCF adapters.

Easy!  Just use a one-way Send port with the WCF-BasicHttp binding!  Everything builds and deploys just fine, however, at run time, we started getting the following error messages:

System.ServiceModel.CommunicationException: The server did not provide a meaningful reply; this might be caused by a contract mismatch, a premature session shutdown or an internal server error.

A little research highlighted that Microsoft does not support sending from BizTalk to one-way Web Services, as BizTalk uses the response acknowledgement to confirm the original message has actually been delivered (remember, BizTalk is all about “Guaranteed Delivery”).  Despite these protestations, sometimes you have to go with “The Customer is Always Right”, even when the customer is actually wrong.

Thanks to a very helpful set of posts by Phillipe, I was able to convince BizTalk to actually send messages, using a “proxy” WCF Service.  The proxy accepts and forwards the Request message, and returns an empty Response message back to BizTalk.

We lose a considerable amount of configuration flexibility, as BizTalk is no longer the sole keeper of end-point information, and there is less visibility if something does go down, but it’s a reasonable workaround for an inbuilt limitation of the standard BizTalk adapters.

June 20, 2011 Posted by | BizTalk, WCF | | Leave a comment