Have you ever created a custom monitoring or troubleshooting tool (or data store) for working with BizTalk, and wanted the ability to launch the HAT (Health and Activity Tracker) tool in a particular context?  Here are the command line parameters that will enable you to do just that…

First, though you can typically launch the HAT tool from "C:\Program Files\Microsoft BizTalk Server 2006\BTSHatApp.exe", for a production tool you probably want to read the install location of BizTalk from the registry at “SOFTWARE\Microsoft\BizTalk Server\3.0\InstallPath.”

The command line syntax looks like:

BTSHatApp.exe “btshat:“ViewName:<OrchDebugger|MessageFlow|SvcInstQuery> MgmtSvr:<your server> MgmtDb:<your mgmt db> SvcInstId:<service instance id> [MsgId:]<optional msg id>””

OrchDebugger and MessageFlow bring up the expected HAT views that you are familiar with.  SvcInstQuery will actually open the BizTalk Admin console, with a query set up so you can see a live service instance with associated messages, etc.

You can also launch with the name of a saved tracking query, as in:

BTSHatApp.exe "c:\program files\microsoft biztalk server 2006\tracking\queries\MessagesSentInPastDay.trq"

The BizTalk management pack for Microsoft Operations Manager appears to use this command line interface so that it can provide built-in tasks to launch HAT with the context present in captured event log entires.  This means that if you have the MOM operator console installed on a machine that is joined to a BizTalk group, you have a nicely integrated set of troubleshooting tools.

A flat file schema can be configured to generate empty elements for empty content – using the “Generate Empty Nodes” option.

It seems that at runtime, the flat file dissasembler can generate “<foo></foo>” for these empty nodes in cases where “Validate Instance…” in the IDE would have generated “<foo/>”.

Where this can cause pain is if you receive a message like: “<foo><bar></bar></foo>”

into your orchestration, and then do a series of assignments like:

xmlDocVariable = myMessage;
// xmlDocVariable2 initialized because xmlDocVariable is needed for other things...
xmlDocVariable2.LoadXml(xmlDocVariable.OuterXml);
myMessage2 = xmlDocVariable2;

At this point, myMessage2 is going to be the serialized representation of xmlDocVariable2.  By default, you will now get:

<foo>
..<bar>
..</bar>
</foo>

Notice you now have carriage returns, line feeds, and spaces (shown here as periods) involved.  Depending on how you now go after /foo/bar, this can be bad (i.e. you won’t get empty content when you might expect it.)  You can avoid this behavior by doing:

xmlDocVariable2.LoadXml(xmlDocVariable.OuterXml);
xmlDocVariable2.PreserveWhitespace = true;
myMessage2 = xmlDocVariable2;

Thanks to Tomas and Carlos for setting me straight on PreserveWhitespace – I was trying to set it before the call to LoadXml, and this doesn’t work.  Never a dull day in BizTalk land…

The documentation for PreserveWhitespace is a little strange.  This functionality would seem to be better represented as parameters to Load/Save, rather than as a property…

“If PreserveWhitespace is true before Load or LoadXml is called, white space nodes are preserved; otherwise, if this property is false, significant white space is preserved, white space is not.  If PreserveWhitespace is true before Save is called, white space in the document is preserved in the output; otherwise, if this property is false, XmlDocument auto-indents the output.”

I’ll be doing two talks on Team Foundation Server at the upcoming Minnesota Developers Conference (MDC 2007) on August 22nd, 2007.  One talk will be on release management (branching strategies, deployment, etc.) and another on options for using Scrum with TFS.  Should be a great conference all around – four great tracks and what looks to be a great keynote on BizTalk RFID solutions.

There is a new release of QuickCounters up at http://codeplex.com/quickcounters.  Great new useability additions to the viewer application by Dave Comfort, as well as fewer priviliges required against remote servers.  See here for the quick tour…

I’ll be talking about using QuickCounters with BizTalk at tonight’s Minnesota BizTalk User Group meeting.  (Last night, I was presenting on using Scrum with Team Foundation Server at the Minnesota VSTS User Group – it’s been a busy week!)

We were having a problem with a BizTalk assembly (containing only maps) having a “project” reference to a standard C# library.  As soon as the project reference was added, we were unable to open the maps – errors along the lines of “unable to open source schema” and “unexpected error encountered…vsee\internal\inc\vscomptr.inl”.  See here for a good forum discussion on the issue that we came across.

It turns out this issue crops up if you have a VSTS unit testing project in the same solution…How is that for a strange product interaction?  Possible workarounds include removing the unit testing project (and putting it in a separate solution) or using a file reference instead of a project reference.  (If you go the latter route, go to the properties of your solution and set up the project build dependencies manually to account for this!)

We opted for file references rather than removing our unit test assembly, at least for the time being.  Hopefully this will be addressed soon…

So...almost three years ago (gulp) I wrote this article on the use of orchestration naming conventions.  In the post, I described the value of orchestration diagrams and their use throughout the development cycle.  In my current engagement, we are doing analysis on the integrations between ERP, warehousing, front-end commerce systems in multiple channels, and a PIM (Product Information Management) solution.  I'm finding that the BizTalk designer - used just as a modeling tool with the constructs that it provides but not filling in deep detail - eliminates so much of the ambiguity that a simple Visio can leave on the table.  So I thought I'd repeat my (now old) thoughts on this topic:

The opportunity exists to use an orchestration diagram in several interesting ways within a project lifecycle:

1. As a way to capture an initial high-level design, using all the orchestration shapes as intended but not yet bothering with real maps and schemas.  Stubbing out schemas (so you can declare messages and variables to be of proper types) and maps will allow you to flesh out the orchestration diagram(s) quite a bit, using the compiler as just a way to check for consistency.  All of the external system interactions, communication patterns, decision points, parallel vs. joined flows, etc. can be represented at this point in a shell orchestration.
2. As a way to gain consensus with the development team & business sponsor about whether the right functionality is indeed going to be built.  The high level design just described is a great tool for this discussion.  Put your orchestration(s) up on a wall with a projector and do a walk-through with as many of the project stakeholders as makes sense.  Or use a tool like CutePDF to print the orchestration as a PDF to send around via email.
3. As a way to estimate work.  The various shapes in your initial orchestration can often represent reasonable granularity for time estimates.
4. And finally, as a way to guide project work...Rather than starting with the entire orchestration that you created to support steps 1-3, you might find it easier to create a new orchestration that represents the path(s) you are tackling at a particular point.  You can cut/paste portions of that original orchestration or simply use it as a reference for what comes next it serves as your outline.

To help realize some of these benefits, naming conventions within an orchestration are quite important

While the naming conventions are good practice for variables, Messages, Multi-Part types, etc. they are even more import for the workflow shapes.  The goal is to ensure that the intent of each shape is clear, and that the text associated with the shape conveys as much as possible given the space constraints.  Make liberal use of group shapes where needed.  In this way, a non-technical audience will be able to use the orchestration as documentation.

Another release of QuickCounters is available - check it out! Improved WCF support, and enhancements to the viewer. You really have to play with the library a bit to realize what a huge benefit it can provide both to operations and performance test investments (for fairly little investment on your part...)

Our CodePlex home is here. Downloads and source code here.

Have you ever wanted to get real-time metrics on:  How many times has a particular orchestration executed on this node in the BizTalk group?  What does the average execution time for my pipeline component looking like?  How many instances of a particular orchestration are currently executing across the group, not including dehydrated instances?

Questions like this can be tough to answer - the built-in BizTalk counters are too coarse-grained, and Tracking & BAM are only partially useful here (particularly if you want high frequency samples.)  What you would like is the ability to get fine-grained "request metrics" on all of your BizTalk orchestrations and pipelines in a way that is simple to implement and easy to consume.

I've been leading an open source project called QuickCounters for quite some time now - though we've just recently moved into CodePlex.  It is a library that will be of interest to BizTalk developers - but it can be used in much broader settings.  I had a chance to present on this topic at the Twin Cities .NET Users Group (on 11/2/2006 - presentation here.)

QuickCounters is a .NET library which makes it extremely easy to implement the common, request-level performance counters that are interesting in just about any service you might write.  You can use this library to instrument  general .Net components, web services, BizTalk orchestrations, pipeline components, remoting interfaces, enterprise service components...you get the idea.  There is special support in the library for BizTalk and WCF scenarios, but it is quite easy to use in any case.

QuickCounters recognizes that the Windows Performance Counter technology that has been with us for some time is often still the best choice for providing (and consuming) detailed performance metrics.  QuickCounters also recognizes that for any given service request there are several metrics which turn out to be interesting for performance testing, operational health analysis, and historical trending. The idea with QuickCounters is to raise the level of abstraction from that of an individual performance counter up to the request itself, using a simple API.

Suppose you want to gather these metrics for each type of request in your system:

• Requests Started
• Requests Executing
• Requests Completed
• Requests Failed
• Request Execution Time
• Requests/Hour
• Requests/Min
• Requests/Sec

Although the .NET performance classes would give you a good start, it will still be a chunk of work.  With QuickCounters, you describe your requests in a simple xml format, and include a simple code snippet in each request implementation:

void SampleRequest()
{
   RequestType someRequest = RequestType.Attach("MyApplication","someRequest");
   someRequest.BeginRequest();

   try
   {
      // Do useful work...
      someRequest.SetComplete();
   }
   catch
   {
      someRequest.SetAbort();
      throw;
   }
}
        

After a quick "install" of the xml that describes your requests (via the included "QuickCounter viewer" utility) you are on your way.  You can see all eight metrics described above for all of your requests (which each become a Performance object) - in PerfMon, with MOM, or any other performance counter consumer. 

For a BizTalk orchestration, you will simply have a variable of type RequestType, which you will assign in an expression shape at the top of your orchestration via the static "RequestType.Attach" method, followed by a call to BeginRequest: 

quickCounterDemo = QuickCounters.RequestType.Attach(
    "QuickCounterDemo","demo",
    QuickCounterDemo(Microsoft.XLANGs.BaseTypes.InstanceId)); 
quickCounterDemo.BeginRequest();           

Successful completion should end with another expression shape that calls SetComplete, otherwise SetAbort.  (Full sample referenced below.)  And yes, the library understands that an orchestration's execution will often begin on one node in your BizTalk group and continue/complete on a different node. 

Of course, if you have many requests, and many nodes in your BizTalk group, it can be a hassle to add everything to PerfMon.  20 requests * 3 servers = 60 interactions with PerfMon's UI.  You might remember to save an .msc file, but you might not.  Here is where the QuickCounter viewer comes into play.  Since you've already written an xml file that describes your requests, just let the viewer know about that file -  and a comma separated list of servers you are running on:

(click)

(The viewer has benefitted substantially from John Thom's contributions...)

Now, the WCF support in the library is...amazing, and completely the result of contributions from Tomas Restrepo.  Keep an eye on his blog for a full discussion, but the bottom line is that creation of the simple xml format and all API calls (BeginRequest/SetComplete/SetAbort) are handled for you automatically simply by applying an attribute (or a behavior - your choice) to your WCF service implementation.  How cool is that?

Our CodePlex home is here.  Downloads and source code here.  Contributors here.

I expect we'll release about once a month or so for awhile - give it a spin and let us know what you think.  It is being used by some very large BizTalk projects (in production) with good success right now.

There are two interesting BizTalk 2006 bugs to be aware of - it seems like they would be encountered fairly often, so I'm a little surprised that I haven't seen more newsgroup/forum activity around these.

The first bug is encountered when you attempt to start a BizTalk 2006 application definition with orchestrations that have been bound to different hosts.  (Say, OrchA in HostA, and OrchB in HostB.)  After the application has been deployed, the first time the application is started (and 'orchestration start/enlist' is included in the start options) you will receive an error that looks something like this:

Microsoft.BizTalk.ExplorerOM.BtsException: Could not enlist orchestration 'BizTalkSample.Orchestrations.Echo,BizTalkSample.Orchestrations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=05a4a8d4071035d9'. Could not enlist orchestration 'BizTalkSample.Orchestrations.Echo,BizTalkSample.Orchestrations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=05a4a8d4071035d9'. Value does not fall within the expected range.

You can work around this error by manually starting your orchestrations in the MMC, either one-at-a-time or grouped by host.  The error only occurs the first time you attempt to start - all future attempts will succeed.  This is because the underlying bug has to do with the creation of subscriptions for the orchestrations. 

This is actually a regression from BizTalk 2004 - where you could in fact change multiple orchestrations (across differing hosts) to a started state via the BtsOrchestration 'Explorer OM' class in a single transaction (i.e. before calling SaveChanges.)  In addition to the behavior just described with BizTalk 2006, you can't do this kind of Explorer OM work once multiple hosts are involved in BizTalk 2006.

But hey, there is a hotfix.  Contact PSS and ask about KB927052.

The second bug is encountered when you have a BizTalk 2006 application with multiple MSMQ receive locations.  You will find that restarting your host instances takes an excessively long period of time.  This is due to a bug in the adapter which was not allowing the host service to stop correctly (the Service Control Manager would eventually just terminate the service...)  Contact PSS and ask about KB928222.