Geeks With Blogs

Charles Young

Having blogged on an undocumented registry key recently, I’d thought I’d introduce you, gentle reader, to another bit of hidden functionality in BizTalk Server 2004.    This time, my subject is an entire wizard which is not registered or set up when you install BizTalk development tools.   It’s a simple device called, variously, the BizTalk Server Project Wizard, the BizTalk Server Scenario Wizard and event the BizTalk Project Scenario Wizard (nothing like being consistent!!).   Because of its simplicity, it is of limited use.  I don’t know why Microsoft kept its existence quiet, but the most likely reasons are that it may not have been fully tested in time to ship (there is, indeed, one feature that does not appear to work properly), Microsoft may have deemed it of relatively little worth or it is currently unfinished (which, given its current limitations, may well be the case).

The idea is simple.   You can create custom BizTalk ‘scenarios’ and then use these as the basis of new projects.   Each scenario is, very simply, a kind of project template.   BizTalk ships with a handful of Visual Studio project templates including the blank project template and templates for human workflow, BPEL import and migration from BizTalk 2002.   You can create your own additional templates and use the BizTalk Server Project Wizard to select them when creating a BizTalk project.

Unlike the existing Visual Studio project templates, scenarios consist simply of a list of files and assembly references.   There is nothing smart about them, and you cannot build custom functionality into them to generate code, etc.

We will assume, for the remainder of this article, that Visual Studio is installed at the default location on your C: drive.   Adjust paths accordingly, if this is not the case.

To create a scenario, first locate the C:\Program Files\Microsoft BizTalk Server 2004\Developer Tools\BizTalkWizards folder and add a new sub-folder called BizTalk Server Scenarios.   Each scenario will be created in its own sub-folder at this location.   Create and name a folder for your scenario and copy BizTalk project items (orchestrations, maps, schemas and pipelines), into the folder.   In addition, you should create a suitable icon (*.ico) file. 

Now create a scenario definition.   This is an XML file.   It must have exactly the same name as the scenario folder, but with an additional ‘.xml’ extension, and it must be saved to the BizTalk Server Scenarios folder.   Here is an example:

<?xml version="1.0" encoding="utf-8"?>
<Scenario IconFile="myScenarioIcon.ico" Name="My Scenario">
  <Description>This is a test scenario</Description>
    <Reference Path="C:\Documents and Settings\Administrator\My Documents\Visual Studio 
         Projects\Solidsoft.Biztalk.Utilities\bin\Debug\Solidsoft.Biztalk.Utilities.dll" />
    <Item Open="0" PhysicalName="in.xsd"  
                   Description="In message schema" />
    <Item Open="0" PhysicalName="out.xsd"  
                   Description="Out message schema" />
    <Item Open="0" PhysicalName="SendPipeline1.btp"  
                   Description="Some send pipeline" />
    <Item Open="0" PhysicalName="testMap.btm"  
                   Description="A test map" />
    <Item Open="0" PhysicalName="testOrch.odx"  
                   Description="A test orchestration" />

The XML is really very self-explanatory, so I won’t describe it in detail.   Note, however, that the Friendly name of the file is the file name used in the new project.  The Physical name is the name of the file in the scenario folder.

The ‘Open’ attribute appears to have no effect.   I think this is actually some problem with BizTalk’s Visual Studio interoperability, rather than the wizard.   If the Open attribute has a non-zero value, the wizard goes through the motions of opening the file in the new project using the EnvDTE.ProjectItem.Open method.   However, the file does not open!

The wizard appears to treat all XML elements and attributes as mandatory.   If, for example, you want to use the default icon, leave the IconFile attribute empty.  Do not remove the attribute.   Likewise, if your scenario has no references, you must still create at least one element and set the Path attribute to an empty string.

Configuring the Scenario Wizard

To register the wizard for use in Visual Studio, you need to undertake the following three steps.

First open a Visual Studio command prompt and execute the following command:

regasm "C:\Program Files\Microsoft BizTalk Server 2004\DeveloperTools\Microsoft.BizTalk.Studio.Utilities.dll"

Now create a Visual Studio wizard file.   You can do this in Notepad.   I called my file BTSScenarios.vsz.   The extension must be .vsz.  The file must be saved to the following location:

C:\Program Files\Microsoft BizTalk Server 2004\Developer Tools\BizTalkProjects

Set the contents of the file as follows:


The file must be saved as an ANSI text file.   Unicode files won’t work!

The last step is to add an entry to the BTSProjects.vsdir file contained in the BizTalkProjects folder.   This entry tells Visual Studio which resources to use for names, descriptions and icons in the Visual Studio UI.   Note that the file is marked as read-only.   You will need to temporarily change the flag on the file in order to edit it.

BTSScenarios.vsz|{ef7e327e-cd33-11d4-8326-00c04fa0ce8d}|#9|150|#10|{ef7e327e-cd33-11d4-8326-00c04fa0ce8d}|235| |#133

The file name used at the beginning of the entry must match the file name you used for your .vsz file.

Now create a new project in Visual Studio.   A new icon should appear in the Templates pane of the New Project dialog for the Scenario wizard:

New Project dialogue

The wizard interface looks like this:

BizTalk Scenario wizard

If Microsoft ever takes this further, one feature I would definitely like is the ability to use something similar to this wizard to add scenarios to existing projects.   What would be really cool, however, would be some kind of design pattern wizard that could, for example, specifically capture orchestration design patterns and allow them to be inserted, if required, into existing .odx files during orchestration design.

Posted on Thursday, February 3, 2005 6:54 PM | Back to top

Comments on this post: BizTalk Server 2004: Scenario wizardry

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
Hi Charles,
Really, every day, I find out that you r one of the best bloggers. But I wander how do u discover this information?
Anyway, I have a question:
Before I developed enterprise template for our Web Application that contains some app. blocks doc extra, and it was a great help for my team. But regarding Biztalk what is the benefits of this approach over the standard project server.
Left by Tareq Muhammad on Feb 21, 2005 9:59 AM

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
BTW, the Design patterns is brilliant Idea, I have implement the splitter pattern, I will try to create template for it
Left by Tareq Muhammad on Feb 21, 2005 10:00 AM

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
I could not really get the practical use of this wizard in present context. Can anyone explain it to me please?
Left by Biztalk Guy on Mar 10, 2005 6:06 PM

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
I could not really get the practical use of this wizard in present context. Can anyone explain it to me please?
Left by Biztalk Guy on Mar 10, 2005 6:06 PM

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
As I say in the article, I consider this wizard to be of limited use which is probably why it is switched off. I was working on one project a few months ago where we needed to create a lot of very similar orchestrations - each one dealing with different message types, but providing similar processing. The dev team originally created a separate assembly for each orchestration! Not a good idea, as load times became excessive. This wizard could really have helped them achieve the poor load times even quicker :-)

Someone somewhere will find a use for it, I'm sure.
Left by Charles Young on Mar 11, 2005 3:02 PM

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
Hi, Very interesting. I guess that in future this will fit with the whole DSL, Factories, GAT kind of idea where you can generate tons of common code and other artifacts for standard situations (eg) you need a FF pipeline to dynamically select schemas, a set of orchestrations in different patterns like debatching, aggregators etc. The way to implement these are generally the same across projects.

Quite a few possibilities actually

Left by Benjy on Aug 06, 2005 11:32 AM

# re: BizTalk Server 2004: Scenario wizardry
Requesting Gravatar...
Hi Charles,
This article is great. I would like to thank U for writing something that is not known to many of them.
Talking about your article I did try to implement the wizard .i did get the Biztalk Server Wizard Icon .However when I double click the icon I get message box saying Invalid class String. I dont know whats the problem. Please help for the same.
Left by Aakash Shah on Feb 03, 2006 3:46 AM

Your comment:
 (will show your gravatar)

Copyright © Charles Young | Powered by: