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>
<References>
<Reference Path="C:\Documents and Settings\Administrator\My Documents\Visual Studio
Projects\Solidsoft.Biztalk.Utilities\bin\Debug\Solidsoft.Biztalk.Utilities.dll" />
</References>
<Items>
<Item Open="0" PhysicalName="in.xsd"
FriendlyName="in.xsd"
Description="In message schema" />
<Item Open="0" PhysicalName="out.xsd"
FriendlyName="out.xsd"
Description="Out message schema" />
<Item Open="0" PhysicalName="SendPipeline1.btp"
FriendlyName="SendPipeline1.btp"
Description="Some send pipeline" />
<Item Open="0" PhysicalName="testMap.btm"
FriendlyName="testMap.btm"
Description="A test map" />
<Item Open="0" PhysicalName="testOrch.odx"
FriendlyName="testOrch.odx"
Description="A test orchestration" />
</Items>
</Scenario>
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:
VSWIZARD 7.0
Wizard={A2844B0B-E8C4-4e27-93DF-5E6B03C1DFDD}
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:
The wizard interface looks like this:
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.