With the release of the BizTalk Software Factory for BizTalk Server 2010 a lot of people ask me what it takes to customize the way it works. They know the factory could help them with development of BizTalk applications, but current company standards are preventing them.
The BizTalk Software Factory (BSF) contains best practices and coding + naming conventions and they typically are not the same in all companies. This fact limits the usage of the BSF or the company need to adjust its coding convention to the BSF, which is not very likely.
This blog post outlines how easy it is to change the default behavior of the BSF to suit your companies coding conventions. Extensibility in Visual Studio 2010 became so much easier that is shouldn’t hold you from adjusting the BSF to your needs.
If you’re new to the BSF I recommend to read the documentation first.
Adjusting the BSF actually is quite easy, the GAT/GAX prerequisites are already installed. First, grab the code from CodePlex by clicking on the ‘Download’ button.
You’ll end up with a ZIP file with all sources from all versions of the BSF. Extract it and just delete the versions you don’t need and keep the ‘BizTalkSoftwareFactory for BizTalk Server 2010’. Open the solution in Visual Studio 2010 and you’ll see this project structure.
In general the actions done by the BSF are stored in so called ‘Recipes’. A recipe contains the steps, dialogs/wizards and actions that are to be executed when a recipe is started. The main recipe for generating the project structure can be found in the ‘Recipe’ folder and is called ‘CreateSolutionRecipe.xml’. If you’re curious take a look at it, but be warned that it is quite difficult to read (let alone debug). The actions called from within a recipe are partly included in the GAX/GAT libraries and the custom ones are in the ‘Actions’ folder.
What template is being used for a certain recipe is specified in the ‘BindingRecipe.xml’. If you open that file you’ll see for example that context menu item ‘Add Map’ is bound to the ‘Items\BizTalkMap.vstemplate’ (in the templates folder) and that file refers to a recipe named ‘NewItemMap’ (which is the name of the recipe stored in the file ‘NewItemMapRecipe.xml’.
This was just to show you the complexity behind the BSF, but changing the template is not complex at all.
The most important part of the solution for this blog is the ‘Templates’ section. There you’ll find the templates that are used during generation of the project structure.
For creating the project structure and adding the individual items, templates are being used like the ones specified in the ‘Templates’ folder.
- Items – template items that can be added from the context menu, like a map or schema
- Overview – contains documentation
- Projects – template projects used in the solution generation, like BizTalk or Class Library projects
- References – assemblies that are being used in the projects or items
- Solutions – template solution used in generating the solution generation
- Text – T4 templates used with adding individual items, used for the deployment framework and unit test generation
Every item needs a vstemplate and one or more source files. The vstemplate file contains the recipe that will be executed and sometimes files that should be copies as part of the recipe. A good candidate for customization is the ‘BizTalkOrchestration’ item. Many companies have a standard way of setting up an orchestration, for example with default exception handling or logging. By creating a template for it, it will be generated by the BSF every time the ‘Add Orchestration’ is selected from the context menu.
Projects contain the non-BizTalk projects, like can be seen in the picture. Here you also find the vstemplate file which specifies which files need to be copied. Looking a the class library, the ‘SampleClass.cs’ is what is added to the class library by default. Customizing this file to your needs will speed up development. In this sample class as well as the csproj file you’ll find variables for naming.
These variables are replaced by Visual Studio when the recipe is executed. By adjusting these values you can use your own naming conventions. You’ll find these variables in every project file. More variables are available on MSDN.
This contains the BizTalk project that is the template for all generated BizTalk projects in the solution. You can customize this as well by adding for example a default file that you need in all projects.
The text section contains the files that are generated using T4 templates. While generating the project structure the ‘Deployment’ section is customized and the ‘UnitTest’ section is used when a new unit test is added using the context menu.
Generating a unit test is initiated from a recipe, which is bound to a context menu. The recipe is of course stored in the ‘Recipe’ folder. By opening for example the ‘NewItemUnitTestMapRecipe.xml’, you’ll find the location where the variables are inserted into the T4 template.
The output is a customized class file which is saved to the project by the next action. You can customize the unit test file by only adding some standard code to the class file or you can further enhance it by inserting more values, which is of course a bit more complex.
Well you have changed the templates, now what?
Like any Visual Studio project you need to recompile the solution. Make sure that you’ve uninstalled the BSF using the Extension Manager.
After compilation you can install the BSF again and run Visual Studio to test your changes.
I hope this post gave an insight in how the BSF works and that it is not that complex to customize it to your needs.
In case you run into any issue or you need assistance, let me know and I’m happy to help you.
Didago IT Consultancy