Thursday, April 29, 2004

BizTalk Subscription Viewer Tool 

Another tool that is a life-saver when it comes to working out how messages that are submitted into BizTalk are matched to 'listening' Orchestrations and Send Ports is the BizTalk Subscription Viewer utility BTSSubcriptionViewer.exe.

This tool can be found in the following folder:

\Program Files\Microsoft BizTalk Server 2004\SDK\Utilities

Once loaded, this tool is a Windows Application that has a split pane view. Initially the views are empty. Go to the Main->Load menu to load all of the subscriptions from the message box database.

Ok, this is more like it. A list of subscriptions are displayed in the top pane. If you select a subscription, then the subscription filter expression is display in the bottom pane. This effectively gives you an idea as to what properties BizTalk is looking to match in order to fire the subcriber.

There are some items in the list that are worth pointing out. Some subscriptions may be prefixed with Activate. These are Orchestration (XLANG) subscriptions where BizTalk will activate a new instance of an orchestration when the properties of a message match the subscription. There are also EPM type subscriptions. EPM stands for the Endpoint Manager and is responsible for the messaging subservice in BizTalk Server. Therefore, these subscriptions are for Send Ports that are waiting to be fired. There is also an internal subscription that has a service type of a GUID. Looking at the subscription filter expression for these (there will be one per host) suggests that this subscription manages the cache refresh of the host application (where each service of a host will periodically refresh its internal cache from the Management database). However, I'm only making an educated guess of the cache refresh subscription. Please comment here and correct me if I'm wrong :-)

So, why is the subscription viewer so important? Well, if you've ever had to implement a complex Content Based Routing project, or worked on Correlation projects, then you'll understand why. It is essential to be able to take a view of the current subscriptions in the message box especially when waiting on a message that is due to be correlated. If things go wrong (and they almost always do when initially developing the solution) then this tool can be an absolute life-saver!!

Pipeline Command Line Tools 

Ok, for those that don't know, there are some really handy pipeline tools in the SDK under the folder:

\Program Files\Microsoft BizTalk Server 2004\SDK\Utilities\PipelineTools

These tools allow you to test your pipeline components and, even more handily, flat file schemas without having to set up the BizTalk Server environment. They are pretty much essential when developing flat file schemas (particularly when you have a header, trailer and body schema).

Here is a list of the pipeline tools available:

  • DSDump.exe - this tool outputs a textual description of the schema.
  • Pipeline.exe - this tool executes a pipeline and produces one or more output files. Very useful for testing custom pipelines.
  • XMLDasm.exe - this tool executes the XML Disassembler component by simulating a receive pipeline.
  • XMLAsm.exe - this tool executes the XML Assembler component by simulating a send pipeline.
  • FFDasm.exe - this tool executes the Flat File Disassembler component by simulating a receive pipeline. Essential for flat file development!
  • FFAsm.exe - this tool executes the Flat File Assembler component by simulating a send pipeline. Again, essential for flat file development!

Note: The pipeline.exe tool does not access the BizTalk Server databases, so executing a pipeline that contains the BizTalk Framework Assembler/Disassembler may not work as it accesses the BizTalk Management database during runtime to match up receipts to documents.

Monday, April 19, 2004

Updated BizTalk Server 2004 Tutorial 

An updated BizTalk Server 2004 tutorial is now available.

Download here.

Ok, ok, so it's been out a while.....I know ;-)

Thursday, April 15, 2004

Exposing Orchestrations as Web Services Gotcha! 

A colleague came to me today with a problem to do with duplicate schemas at runtime when running his orchestrations.

The problem turned out that during generation of the proxy (when adding a web reference to a BizTalk project) to a web service that was automatically generated by the BizTalk Web Services Publishing Wizard, then if the web service exposes a complex type such as a message, then the proxy automatically generates a schema called Reference.xsd that contains a local definition of the message.

However, this may all seem fairly benign on the surface. But, the proxy generator uses the WSDL to create the proxy orchestration (Reference.odx) and the schema (Reference.xsd), and the WSDL was created based on a web service that has been automatically generated by the BizTalk Web Services Publishing Wizard. The WSDL for the web service contains definitions for the messages that are required as parameters to the web service operations, and they are defined in the WSDL with the same root name and namespace as the real schema that they are based on!

So, when you compile the orchestration that is consuming the web service, a Reference.xsd schema containing the definitions for the messages expected as parameters to the web service, are compiled into the assembly as well.

This is a big issue, because once both assemblies are deployed (one containing the consumed orchestration that includes the original schema for the message and one containing the orchestration that is calling the web service and includes a proxy generated schema for the message) then at runtime BizTalk will fail because 2 schemas exist in the Management database with the same root element and namespace names!

So, how do we get around this? I can only think of these 2 ways:

  1. Create a .NET class that wraps the web reference, create a static method that wraps the web service call, and then call the class method from within an Expression shape in orchestration, thereby avoiding creating the web reference inside the BizTalk project.
  2. Pass the message as a string to the orchestration before running the wizard, but that way you'll need to convert the string back to a message reference within the consuming orchestration.

If anybody else has any other ideas, I'd be interested to hear about them here!

Wednesday, April 14, 2004

Working with Enumerations in a Web Service within Orchestration 

Well, this had me scratching my head for some time until the lightbulb lit up in my brain! How was I going to call a web service within an orchestration that used an enumeration as one of its parameters?

The answer is surprisingly simple but very consistent with the way that orchestration works in BizTalk Server 2004 with respect to web services.

When you want to call a web service from within orchestration you can either do one of 2 things:

  • Write a wrapper in .NET that calls the web service and call the wrapper from within an Expression shape
  • Add a web reference to the BizTalk project and then create a configured port based on the web port for the web service

So, what's wrong with the first option? Well, you will need to write code for starters just to call the web service, and then once created, then you need to expose the web methods you require access to in order for them to be invoked from orchestration.

Here's the rub though: while this isn't a particularly desirable route to calling a web service from within orchestration, sometimes it's absolutely necessary that it is done this way. There are 2 very good reasons for this:

  • You don't want to go through the message box every time you call the service (which is what happens if you call the web service through a web port in orchestration).
  • More importantly, the web service interface uses parameter names that are on the XLANG/s reserved keywords list. That's right! You can't name a parameter anything and just get away with it when using that web service from orchestration! Therefore if you have no control over the web service interface that you're calling, you will need to create a wrapper in order to be able to call it from orchestration.

So, in most circumstances you'll probably want to go the second route. When you add the web reference into the BizTalk project in Visual Studio.NET, instead of a proxy class in C# (or VB.NET if that's your preference) being generated behind the scenes, a BizTalk Orchestration is created as the proxy. Cool!

But, what happens when the web service method that you're calling contains a parameter that is based on an enumeration? Fortunately, when the web reference is added, any enumerations that are exposed in the web service definition (WSDL) are turned into schemas that are available in the project under the web reference itself.

So, with this information to hand, all we need to do is to create an XLANG/s message based on the enumeration schema, populate it with the right enumeration value, and then pass this message as a parameter to the web method.

The following code snippet shows how this is done and is located in the Message Assignment shape that sets up the request message for the call to the web service. If you take a look at the sample code, this particular web service method expects 4 parameters, one of which is a parameter based on an enumeration (which I've set up with a call to the XmlIfy static utility method). In addition, I made the enumeration value field in the schema a distinguished field by modifying the schema that was generated automatically when adding the web reference to the BizTalk project. Don't forget, if you update the web reference, you will need to promote the field as a distinguished field again otherwise the project won't compile! Note that you also need to construct the enumeration message as well as the web service request message in the Construct shape.

notifyRequestMessage.address = registrationMessage.escalation.sendTo;
notificationType = BizTalkUtility.XmlIfy( "<NotificationTypeEnum xmlns='http://somenamespace/notify' />" );
notificationType.NotificationTypeEnum = "SMTPEmail";
notifyRequestMessage.type = notificationType;
notifyRequestMessage.subject = "My Subject";
notifyRequestMessage.content = "My Content";

Note: Whenever I work on a BizTalk project, I always have a utility library written in C# that allows me to perform various useful little functions like turning an XML document into a string, and a string into an XML document. Highly useful!

Apologies for lack of update recently! 

Things are hectic here at Solidsoft Towers! Working on a big proposal that is sucking my time, so apologies for lack of recent updates. Will get back to it when the proposal is winging its way into the client's lap... ;-)

Thursday, April 08, 2004

Microsoft Webcast on BizTalk Server 2004 Architecture 

Here's a link to a great webcast on the architecture and scalability options of BizTalk Server 2004 presented by Scott Woodgate.

Click here to access the webcast.

Monday, April 05, 2004

Visio Orchestration Designer Add-In 

The add-in for Visio (2002 SR-1 or 2003) to allow business analysts to design business processes that can be used by a developer to implement orchestrations is now available.

It can be downloaded here

Sharepoint Adapter 

Those lovely folks over at GotDotNet have available a Sharepoint adapter for BizTalk Server 2004.

You can find it here

New Information Worker documentation available 

There is also new documentation available for Information Workers. Download here

BizTalk Server 2004 Rollup 1 is available 

This is a rollup patch for BizTalk Server 2004 that should be applied to the RTM build of BizTalk Server 2004. This will be included in the upcoming service pack 1 (no release dates available yet).

Click the following link to download the rollup patch: BizTalk Server 2004 Rollup 1

Friday, April 02, 2004

At last! New documentation is available for download from Microsoft 

Well, we've all been waiting for it.

New documentation for BizTalk Server 2004 can be downloaded from the following locations:

Click to download BizTalk Server 2004 documentation

Click to download BizTalk Server 2004 SDK

Installation Guide
Click to view the updated installation guide

Problem encountered installing on Windows 2000 

If you've installed BizTalk Server 2004 on the 'slipstream' SP4 Windows 2000 build, then when you get to the ConfigFramework wizard, you may well find that the file AUTHZ.DLL is missing from the Winnt\System32 folder.

If this is the case (and it almost certainly will be), then you'll need to re-install the full version of SP4 for Windows 2000. This will ensure that the AUTHZ.DLL file is installed, and you'll be able to run the ConfigFramework wizard.

Thursday, April 01, 2004

First BizTalk Tip! 

Ok, first tip.

Apologies to all of those people that know this (and if you've worked with BizTalk Server 2004 for any length of time, you will!).

Any time you deploy a new BizTalk assembly, or even GACing a component that is used by orchestration or by a pipeline (except obviously components designed to run under a COM+ server application), don't forget to restart the BizTalk Server NT service BTSNTSvc.exe.  You can do this via the BizTalk Server Administration MMC snap-in by finding the server and restarting it, or just simply restarting the relevant BizTalk Host in the Services MMC snap-in.

Simple eh?

PS: You have no idea how many times I've been caught by this........grrrrr!

Welcome to my blog! 

Well, I've been nagged and nagged to get this blog up and running, and here it is.

Now all I've got to do is to put up some worthwhile posts that will actually be of use to people....

So, with that in mind, watch this space :)

About the Author

You may be wondering who I am (or may not!), but I've been in the industry 16+ years working on a variety of systems from IBM mainframes as a CICS systems programmer, to developing on Unix and Windows based systems. At the moment, I'm currently working for a Microsoft Gold Partner in the UK called Solidsoft who specialise in systems integration using BizTalk Server. My position is generally dictated by what I'm doing, but normally as a solutions architect/consultant helping clients with their integration projects involving, yes you guessed it: BizTalk Server.

Disclaimer: all the views expressed here are my own and do not necessarily represent the views of Solidsoft Ltd or indeed any other company.