Gilles' WebLog : BizTalk 2004

BizTalk Decompiler for Reflector 5 on CodePlex

gzunino — Thu, 28 Jun 2007 01:44:00 GMT

My BizTalk Decompiler only works with Reflector 4. The updated version for Reflector 5 has been available for a while on CodePlex: http://www.codeplex.com/reflectoraddins...(read more)

Date/Time tracked with BAM must be expressed in Universal Coordinated Time (UTC)

gzunino — Wed, 19 Jul 2006 02:12:00 GMT

All date/time tracked by BAM must be expressed in UTC. BAM depends on this to provide accurate durations, among many other things. This is clearly explained here . It was also the case for BizTalk 2004 even if the documentation gave subtle hints instead...(read more)

BAM Query Service: What is it and how can I use it?

gzunino — Thu, 01 Jun 2006 00:48:00 GMT

If you have installed BAM (BizTalk Server 2004 or BizTalk Server 2006), you may have noticed that a web service called the "BAM Query Service" got installed. As its name hints, this web service allows the BAM Portal to retrieve BAM instance data without...(read more)

BizTalk Server Team Product Management has a Blog!

gzunino — Wed, 22 Mar 2006 01:47:00 GMT

Visit it here . Kris, Steve, Michael and Mark share product updates, links to training materials and even employment opportunities ! I subscribed to their RSS feed....(read more)

BizTalk BAM Portal 2006: Activity Search

gzunino — Thu, 16 Jun 2005 06:02:00 GMT

In a previous post, I described the home page of the new BAM Portal. Today, let's take a look at the Instance Search feature. The instance search allows you to search BAM data for a particular activity instance:

You can add / remove clauses using the "Add" / "Remove" buttons. You can also build a query and save it locally as an XML file for future use. Opening a query is done by clicking the "Open" button. Let take the Search for a test drive, shall we?

After selecting the business data you would like to see in the column chooser, I am looking for all purchase orders with an amount of $500. There is only one purchase order matching in my system. I can see the details of this activity by clickin on the row of interest:

Users can see all business data associated with this activity instance. Milestones appear sorted from the oldest one to the newest one. Any related document or related activity would appear in their respective sections.

Finally, the "Technical Assistance" can be used to open a technical assistance ticket. The subject / description entered below will be posted to the event log of the server, along with references to engine artifacts (messages / orchestrations) related to this activity.

Tomorow, I'll show how one can view aggregated data and create alerts when specific condition happen.

BizTalk Server 2006: What is new with Business Activity Monitoring?

gzunino — Tue, 14 Jun 2005 10:03:00 GMT

You probably already read Scott's document on what is new in Business Activity Monitoring 2006.Today, I'll shed some light on the brand new "out of the box" portal. All information are based on the CTP build you might have picked up at TechEd 2005. Keep in mind that the BAM Portal may (and probably will) change before its final version is released.

There are three main zones:

the header. This is the location users can customize for branding purposes,
the navigation bar (on the left on a light blue background) which displays all views and activities. This is the entry point to most features of the portal,
the content where users will interact with data. The main page displays a quick summary of importan BAM concepts.

The header:

The header displays branding information (which can be customized for your company), the contextual help link and the current location. On the screenshot below, I am on the Home page. You can always come back to the home page by clicking on the "Home" icon at the left of the header.

The navigation bar:

The navigation bar displays all views / activities which can be accessed by the current user. On the picture below, I have access to one view (SalesManagerView) under which there is currently one activity ("PurchaseOrder").

I can search for instances of activity "PurchaseOrder" by clicking on "PurchaseOrder" under "Activity Search". I can view aggregated data by clicking on one of the entries under "Aggregations". Finally, I can manage alerts by clicking on "PurchaseOrder" under the "Alert Manager" node. The navigation bar is the main entry point to most BAM Portal features. It will always be displayed on the left of the window.

Join me tomorow as I explore the Activity Search, Aggregations and the Alert Manager.

Get ready for TechEd 2005 in Orlando!

gzunino — Sat, 04 Jun 2005 22:20:00 GMT

Make sure you pick up a copy of BizTalk Server 2006 CTP (Community Technology Preview). Starting next week, I will start a serie of deep dive posts on some of the new BAM (Business Activity Monitoring) features ... Staty tuned!

Download BizTalk 2004 Service Pack 1 today!

gzunino — Thu, 27 Jan 2005 02:56:00 GMT

BizTalk Server 2004 Service Pack 1 was released today. You can download it at http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=f4a5ab9e-d599-4cc8-abdf-ae6ae68bac3d.

Is BizTalk supported when running under Virtual PC / Virtual Server?

gzunino — Wed, 29 Sep 2004 00:59:00 GMT

Since Virtual Server has been released, I got asked the question several times so I figured I'd put the answer here where everybody can find it. Knowledge Base Article 842301 says something like:

Current released versions of BizTalk (2000, 2002 ,2004) in any flavor (Enterprise, Developer ...) are "best effort support" on virtual machines (Virtual PC and Virtual Server). Any case opened with Microsoft Support will be supported on a best effort basis and you may be asked to reproduce the problem on physical hardware during the course of troubleshooting the issue.

Not supported does not mean that it will not run: it may very well run fine or you may run into subtle issues. Not long ago a Microsoft Technology Specialist attempted to run BizTalk on a three weeks development project. According to him, this is not worth wasting the effort again. They ran into issues and none of them reproduced on real hardware. I am sure we can find individuals who have been running BizTalk on Virtual PC / Virtual Server without any problem so far. It probably depends on what you are doing.

If you feel lucky and want to try it out by yourself, this thread (chosen among many others) discusses some tips that might help you. While running a BizTalk server on a virtual machine for development purposes might be fine, I would definitely advise against running a production server under a virtual machine.

[KB838454] Access tracked messages in the BizTalk 2004 message box

gzunino — Tue, 28 Sep 2004 17:12:00 GMT

Knowledge Base Article 838454 describes the new Microsoft.BizTalk.MessageBoxOM.MessageArchive object that was added to Microsoft.BizTalk.MessageBoxOM.dll. Currently, the package is only available through Microsoft Support.

There are a few things that this KB Article does not describe: remember that the Microsoft.BizTalk.MessageBoxOM.dll file is in the GAC. Currently, Visual Studio.NET 2003 does not allow you to add references to components in the GAC. To get past this, you can choose one alternative between these two solutions:

1 - Extract the dll from the GAC to a place where you can add reference to it (perhaps C:\<yourprojectdirectory>)

In a DOS prompt, run the following command:

copy %systemroot%\assembly\GAC\Microsoft.BizTalk.MessageBoxOM\3.0.1.0__31bf3856ad364e35\Microsoft.BizTalk.MessageBoxOM.dll <destination_path>

Where <destination_path> has been replaced by the path to your BizTalk project's directory (for instance C:\MyProject)

2 - Manually edit the Visual Studio Project file (.csproj, .btsproj, .etc)

To add a reference to this assembly you must edit the project file (.csproj, .btproj, .etc) in a text editor. The following code snippet shows the code that must be added to the reference element of the project file to reference the assembly:

<Reference
   Name = "Microsoft.BizTalk.MessageBoxOM"
            AssemblyName = "Microsoft.BizTalk.MessageBoxOM"
            HintPath = "<SystemRoot>\assembly\GAC\Microsoft.BizTalk.MessageBoxOM\3.0.1.0__31bf3856ad364e35\Microsoft.BizTalk.MessageBoxOM.dll"
/>

How do I work around "Empty choice is unsatisfiable if minOccurs not equal to 0. An error occured at file://[some path to XSD]"?

gzunino — Fri, 24 Sep 2004 22:55:00 GMT

You might have received this error message if you followed these steps:

Install BizTalk 2004 on a clean machine with Visual Studio .NET 2003,
Start Visual Studio and Create a new C# project (Windows Application for instance),
Save the solution/Project,
Right click on the project name in the solution explorer and select "Add-> New Item ...",
Click "Data Set" and press "OK",

You see the following error message (the path under the white box is the path to the XSD that has been created when you inserted the DataSet):

When you install BizTalk, there is a component called "BizTalk developer tools". This component contains all the logic to integrate with Visual Studio .NET 2003: pipeline designer, BizTalk Explorer and among many other things, a schema editor.

The error you are seeing is because the BizTalk Editor is trying to edit a DataSet schema and got confused. To workaround this, you have to ensure that DataSet schemas are opened with the Visual Studio Schema Editor and not the BizTalk Schema Editor. Here are two different workarounds:

Bypass the BizTalk Schema Editor when editing the schema (works around the problem once)
Reset the default editor to the Visual Studio Schema Editor instead of the BizTalk Schema editor (puts the Visual Studio Schema Editor back as the default XSD editor)

Bypass the BizTalk Schema Editor when editing the DataSet:

Open the solution in VS.NET 2003
Insert the DataSet as explained above (steps 4 and 5). You see the error, but you also see that the DataSet item was created and added to the solution explorer
Click "OK" to close the error box
In the solution explorer, locate the schema and right click on it
Select "Open With ..."
In the dialog box, select "XML Schema editor" and click "Open"

Set the Visual Studio Schema Editor back to default editor:

Follow the steps 1 to 5 above
In the "Select XML Schema Editor" dialog box, select "XML Schema Editor" and click "Set as default".
Press OK to open the DataSet

Ravi, I hope this page helped you in case you missed my answer in another group.

Why does BizTalk display "Status unavailable" for Isolated Hosts?

gzunino — Thu, 23 Sep 2004 16:21:00 GMT

Yet another frequently asked question. When using the BizTalk 2004 Administration Console, isolated hosts always report "Status unavailable" (see below).

BizTalk Server 2004 offers two kind of hosts: In-Process Hosts and Isolated Hosts. In-Process Hosts run in the same process as BizTalk and can be used to run orchestrations, run any send adapter and run the MSMQ or FILE receive adapters. Isolated Hosts can only run HTTP/HTTPS/SOAP receive adapters. From a pragmatic point of view, an Isolated Host is essentially an ISAPI extension running under the control of IIS. In BizTalk 2004, this ISAPI is called BTSHTTPReceive.dll. The documentation page "About Hosts" explains:

Isolated hosts primarily host adapters that must run outside of the normal BizTalk Server runtime process. For example, you use isolated hosts to host adapters for external processes such as ISAPI extensions and ASP.NET.

[...]

The status of an isolated host is always Status Unavailable. BizTalk Server does not access the status information for external processes.

So it is absolutely normal for an isolated host to report "Status unavailable". It should not happen for an in-process host.

Format of BizTalk 2004 assemblies: Pipelines

gzunino — Wed, 22 Sep 2004 16:07:00 GMT

Today, we continue our deep dive into the undocumented and unsupported bowels of the BizTalk artifacts compiler and examine how pipelines get compiled to .NET assemblies. Pipelines allow to adjust the format of inbound messages to something that is suitable for processing. There are two kind of pipelines: Send Pipelines or Receive Pipelines. The following picture shows a composite picture with a receive pipeline (left) and a send pipeline (right) being edited in Visual Studio.

It is time to dive a little deeper into the generated class. Compiling any Send or Receive Pipeline and loading it into the excellent Lutz Roeder's .NET Reflector shows the following:

We already know that when a BizTalk project is compiled, Pipelines are compiled to a public sealed class type into a .NET assembly. The class inherits from Microsoft.XLANGs.BaseTypes.PipelineBase (contained in Microsoft.XLANGs.BaseTypes.dll, available in <BTS Installation Directory>). This class is not supported as explained by this page (look at the bottom of the page). To compile a Pipeline, BizTalk generates and compiles a class close to the following C# class:

namespace <projectName> {

public sealed class <nameOfPipelineFile> : Microsoft.XLANGs.BaseTypes.PipelineBase {

public <nameOfPipelineFile>() { }

public override Guid VersionDependantGuid { get { return new Guid("<someGuid>"); } }

public override string XmlContent { get { return "<contentOfBTPFile>"; } }

// --------------------------------

// Private const properties not shown go here

// --------------------------------

}

To simplify, I have omitted the private constant members of the class. All the bold underlined words surrounded by angle brackets are placeholders that have to be replaced by an actual string adequate for the pipeline being compiled. Let look at the properties a little more closely:

VersionDependentGuid: Guid of the Pipeline, dependent of the version of the Pipeline.
XmlContent: The actual Pipeline definition, as an XML string. This is the content of the .btp file that was produced by the pipeline editor.

The base class Microsoft.XLANGs.BaseTypes.PipelineBase is abstract and contains only the properties outlined above. Alert readers have probably already noticed that the property "XmlContent" appears also on Maps as shown in my previous post. This is not a coincidence. It is used by the BizTalk assembly viewer and other tools to get a representation of the artifact in XML.

Remember that this post contains mostly undocumented, unsupported information. This content is provided "AS IS" and for entertainment purpose only. Further versions of BizTalk may change the ways things get compiled and relying on low level details like the ones outlined before will cause your application to break.

How do I reuse BizTalk 2004 maps outside of BizTalk?

gzunino — Wed, 22 Sep 2004 01:18:00 GMT

Recently, I shed some light on how Maps are compiled to .NET assemblies. Perhaps one of the most asked question on microsoft.public.biztalk.* is "Calling a map from C# or VB.NET?". This post attempts to answer that question and clarifies a few things.

It is possible to run a map produced by the BizTalk 2004 mapper outside of BizTalk and it is even possible; under certain conditions; to run the map on a machine that does not have BizTalk installed. The steps required for using a map outside of BizTalk are outlined below:

Extract the XSL document produced by the mapper,
If the map uses functoids (out of the box or custom functoids), you will need to extract the Xsl Transformation arguments,
Create a .NET System.Xml.Xsl.XslTransfom() object,
Create a .NET System.Xml.Xsl.XsltArgumentList() if there were any functoids in the map and instantiate appropriate objects,
Call Transform() on the XSL and optionally, the XsltArgumentList.

In the list of steps above 3, parts of 4 and 5 have nothing to do with BizTalk: these are just plain .NET programming. Creating the XsltArgumentList requires us to understand how the mapper saves functoids.

Extracting the XSL and the extension objects (if any) can be achieved by at least three different methods:

If you have the map file (.btm) and can open it in Visual Studio 2003, you can right click on the map file in the solution explorer and select "Validate Map". The output window will give you the path(s) to the XSL and the extension Object XML. The links can be shift-clicked to retrieve the files,
If you only have the compiled assembly, you can use the excellent Lutz Roeder's .NET Reflector to extract the required information as strings,
If you only have the compiled assembly, you can write some code that loads the assembly, creates an instance of the map object and calls the appropriate members. See the format of maps assemblies.

The only speed bump is the format of the Extension Object XML document. I have extracted the extension associated with the map Scriptor_CallExternalAssembly from the "ExtendingMapper" SDK sample and formatted it:

Creating the extension objects is now very simple. For each "ExtensionObject" node, we need to load the assembly, create an instance of the given class and add the object along with its namespace to the XsltArgumentList. Of course, the map will only run if all needed assemblies are available. This is true for custom assemblies as well as out of the box functoids. The code below does exactly this and the full solution can be downloaded here:

using System;
using System.Reflection;
using System.Xml;
using System.Xml.Xsl;
using System.IO;
using System.Text;


namespace MapReuser
{
	/// <summary>
	/// Transforms XML instances using a BizTalk map.
	/// </summary>
	public class BizTalkMap
	{
		/// <summary>
		/// Caches the XSLT stream.
		/// </summary>
		private Stream xsltStream;

		/// <summary>
		/// Caches the XSLT Arguments stream.
		/// </summary>
		private Stream xsltArguments;
		

		/// <summary>
		/// Cache the XslTransform.
		/// </summary>
		private XslTransform     xslTransform;

		/// <summary>
		/// Caches the XSltArgumentList.
		/// </summary>
		private XsltArgumentList xslArgumentList;




		/// <summary>
		/// Constructor.
		/// </summary>
		/// <param name="XsltStream">Stream of XSLT as XML.</param>
		/// <param name="XsltArguments">Stream of Extension Objects as XML.</param>
		public BizTalkMap(Stream XsltStream, Stream XsltArguments)
		{
			xsltStream    = XsltStream;
			xsltArguments = XsltArguments;
		}

		/// <summary>
		/// Transforms the given instance and returns the result as a stream.
		/// </summary>
		/// <param name="inXml">Stream of the instance to transform (XML)</param>
		/// <returns>Stream of the transformed XML.</returns>
		public Stream TransformInstance(Stream inXml)
		{
			XslTransform transform   = Transform;
			XmlDocument  xmlInputDoc = new XmlDocument();

			// Make sure we do not destroy the formatting
			xmlInputDoc.Load(inXml);

			// Output stream
			MemoryStream  outStream = new MemoryStream();
			XmlTextWriter xmlWriter = new XmlTextWriter(outStream, System.Text.Encoding.UTF8);

			// Formatting options
			xmlWriter.Formatting  = Formatting.Indented;
			xmlWriter.Indentation = 2;
			
			// Perform transformation - We do not specify a resolver
			transform.Transform(xmlInputDoc, TransformArgs, xmlWriter, null);

			// Prepare the output stream
			outStream.Seek(0, SeekOrigin.Begin);

			return outStream;
		}

		/// <summary>
		/// Gets an instance of XslTransform for the given XSL/Extension objects.
		/// </summary>
		private XslTransform Transform
		{
			get
			{
				if (xslTransform == null)
				{
					// Create a new transform
					XmlTextReader xsltReader = new XmlTextReader(xsltStream);
					XslTransform transformTemp = new XslTransform();
					transformTemp.Load(xsltReader, (XmlResolver) null, GetType().Assembly.Evidence);
					
					// Cache the transform
					xslTransform = transformTemp;
				}
				return xslTransform;
			}
		}

		/// <summary>
		/// Gets a XsltArgumentList from a BizTalk Extension Object XML.
		/// </summary>
		private XsltArgumentList TransformArgs
		{
			get
			{
				if (xslArgumentList == null)
				{
					XmlDocument      xmlExtension = new XmlDocument();
					XsltArgumentList xslArgList   = new XsltArgumentList();

					if (xsltArguments != null)
					{
						// Load the argument list and create all the needed instances
						xmlExtension.Load(xsltArguments);
						XmlNodeList xmlExtensionNodes = xmlExtension.SelectNodes("//ExtensionObjects/ExtensionObject");
						foreach (XmlNode extObjNode in xmlExtensionNodes)
						{
							XmlAttributeCollection extAttributes = extObjNode.Attributes;

							XmlNode  namespaceNode = extAttributes.GetNamedItem("Namespace");
							XmlNode  assemblyNode  = extAttributes.GetNamedItem("AssemblyName");
							XmlNode  classNode     = extAttributes.GetNamedItem("ClassName");
							Assembly extAssembly   = Assembly.Load(assemblyNode.Value);
							object   extObj        = extAssembly.CreateInstance(classNode.Value);
							xslArgList.AddExtensionObject(namespaceNode.Value, extObj);
						}
					}
					// Cache the list
					xslArgumentList = xslArgList;
				}
				return xslArgumentList;
			}
		}
	}
}

This class can be used as follows:

FileStream fsXslt       = null;
FileStream fsInput      = null;
FileStream fsExtensions = null;
FileStream outStream    = null;

try
{
	// Transform
	fsXslt         = new FileStream(xsltPath, FileMode.Open, FileAccess.Read);
	fsInput        = new FileStream(instancePath, FileMode.Open, FileAccess.Read);
	fsExtensions   = (extensionPath != null) && (extensionPath.Length > 0) ? new FileStream(extensionPath, FileMode.Open, FileAccess.Read) : null;
	BizTalkMap map = new BizTalkMap(fsXslt, fsExtensions);

	Stream sOut = map.TransformInstance(fsInput);

	// Save stream to a file
	string destPath = Path.Combine(Path.GetDirectoryName(instancePath), Path.GetFileName(instancePath) + ".trans.xml");
	outStream = new FileStream(destPath, FileMode.Create, FileAccess.Write);
	outStream.Write(((MemoryStream) sOut).ToArray(), 0, (int) sOut.Length);
}
finally
{
	if (fsXslt       != null) fsXslt.Close();
	if (fsInput      != null) fsInput.Close(); 
	if (fsExtensions != null) fsExtensions.Close();
	if (outStream    != null) outStream.Close(); 
}

Format of BizTalk 2004 assemblies: Maps

gzunino — Tue, 21 Sep 2004 15:57:00 GMT

Today, we dive deeply into the undocumented and unsupported bowels of the BizTalk artifacts compiler and examine how maps get compiled to .NET assemblies. The BizTalk 2004 Mapper allows to graphically build a transformation between an XML instance of an input schema to another XML instance conforming to an output schema. Today, we explore some undocumented (and therefore not supported) internal parts of BizTalk 2004.

The BizTalk mapper allows complex transformations between fields. On the map below, Field1 in the destination instance is set to Field1 + Field2 from the input schema:

We already know that when a BizTalk project is compiled, Maps are compiled to a public sealed class type into a .NET assembly. The class inherits from Microsoft.XLANGs.BaseTypes.TransformBase (contained in Microsoft.XLANGs.BaseTypes.dll, available in <BTS Installation Directory>). This class is not supported as explained by this page (look at the bottom of the page).

It is time to dive a little deeper into the generated class. Compiling the ExtendingMapper BizTalk 2004 SDK sample and loading it into the excellent Lutz Roeder's .NET Reflector shows the following:

Let's concentrate on one map: CBRSample.CBRInput2CANMap. The class has a default constructor and few properties, mostly strings or array of strings. There are also a few private constant members (the blue entries with a little lock). When BizTalk compiles a map, it essentially creates and compiles a class close to the following C# class:

namespace <projectName> {

public sealed class <nameOfMapFile> : Microsoft.XLANGs.BaseTypes.TransformBase {

public <nameOfMapFile>() { }

public override string[] SourceSchemas {

get { return new string[1] { "<nameOfInputSchema>" }; }

}

public override string[] TargetSchemas {

get { return new string[1] { "<nameOfTargetSchema>" }; }

}

public override string XmlContent {

get { return "<XsltContent>"; }

}

public override string[] XsltArgumentListContent {

// XsltArgument content. If no argument, returns "<ExtensionObjects />\n"

get { return "<XsltArgumentContent>"; }

}

// --------------------------------

// Private const properties not shown go here

// --------------------------------

}

To simplify, I have omitted the private constant members of the class. All the bold underlined words surrounded by angle brackets are placeholders that have to be replaced by an actual string adequate for the map being compiled. Let look at the properties a little more closely:

SourceSchemas: The source schema(s) names, as strings.
TargetSchemas: The target schema(s) names, as strings.
XmlContent: The actual Xslt used to perform the transformation.
XsltArgumentListContent: Xstl Argument(s) list, if any. These are the extension objects needed to run maps with complex transformations features like "Functoids" (small functions that can be used to extend the capabilities of the mapper). They are essentially implemented as extension objects in Xslt.

The base class Microsoft.XLANGs.BaseTypes.TransformBase is abstract and contains all the properties outlined above plus a few more interesting ones:

public XslTransform Transform { get { /* Implementation omitted */ }; }
public XsltArgumentList TransformArgs { get { /* Implementation omitted */ }; }

These members are used to get a System.Xml.Xsl.XslTansform and/or a System.Xml.Xsl.XsltArgumentList suitable to execute the map. Armed with this information, one could build a library that executes BizTalk 2004 maps outside of the BizTalk messaging engine. This is a frequently asked question in microsoft.public.biztalk.* newsgroups.

There are also a few things that may not be immediately obvious if you are looking at the output in Reflector. If the input schema or the output schema is not contained in the same assembly as the map, the compiler will emit a dummy member variable. This variable will have the type of the foreign schema(s). This forces a reference to the schema(s) assembly(ies) to be added to the manifest of the map's assembly. There are also two SchemaReferenceAttribute added to the class to facilitate discovering the input and output schema without creating an instance of the map object.