For reasons like maintenance and knowledge transfer, it is a good practice to document the software solutions that you develop. This practice also applies to developing BizTalk Server solutions. However, if there is any task that’s considered boring and time-consuming, then it is writing documentation.
Luckily, with the BizTalk documenter, a lot of documentation of BizTalk Server solutions can be generated automatically! In this article, we will have a look at how to install and use the BizTalk Documenter.
This nifty tool has been around since 2006 and can be found on GitHub. Currently the BizTalk Documenter is maintained by Mark Brimble. After installation, the BizTalk Documenter can be executed against a BizTalk Server environment. It can generate documentation about the deployed BizTalk solutions in that environment, any configured Parties, the created Hosts, and the available Adapters.
Since the BizTalk Documenter already exists for such a long time, it supports many different BizTalk Server versions, being: 2006, 2006R2 2009, 2010, 2013, 2013R2, 2016, and 2020. Depending on the BizTalk Server version you are using, you need to download a different version of the tool. For this, see the below table.
|
BizTalk Server version |
BizTalk Documenter version |
|
2006 to 2010 |
3.6.1 |
|
2013 |
5.1.7.1 |
|
2013R2 |
5.2.0.1 |
|
2016 to 2020(*) |
5.3.0 |
(*) Support for BizTalk Server 2020 is not mentioned in the GitHub website, but we have tried it ourselves, and it seems to work properly.
Visit to the BizTalk Documenter Download folder in GitHub to get the version(s) you need.
Before generating the documentation, you can configure if you want to generate the documentation in one of the following formats:
Note: In case you want to generate a Compiled Help file, you must have HTMLHelp installed. More about HTMLHelp follows later in this article.
Below, you find an example of a page in a compiled Help file. The page shows some information about all that can be generated. The right side of the page shows information about the artifacts that are associated to a Host.
The Front page of a Compiled Help file looks very basic. It only contains a simple image, and some basic information. However, when you are a little bit creative, you can customize that Front page to something like the below.
Before:
After:
This clearly makes the documentation look much better! Sandro Pereira has written a good blog about this topic. You find the blog here.
As mentioned earlier, in case you want to generate Compiled Help files, the BizTalk Documenter depends on HTMLHelp. So, before generating such a file, you need to install HTMLHelp. This tool could previously be downloaded from MSDN, but since that website has been shut down, you now need to rely on the WayBack Machine for a copy of HTMLHelp.
Let’s have a look at how both tools must be installed.
To install the BizTalk Documenter, you need to perform the following steps:
That’s it! The tool is installed and can by started from the Windows menu.
If you intend to generate Compiled Help files, you need to install HTMLHelp. Follow the below steps, to download and install HTMLHelp.
Also, the HTML workshop tool is now installed.
Now, let’s have a look at how to use the BizTalk Documenter.
You can start the BizTalk documenter from the Windows menu. The initial screen of the tool looks like below.
The screen is divided in three different sections:
From the above-mentioned sections, the section with the configuration options, clearly is the most interesting one. Let’s have a look at what is in store there.
Server options – This is the screen that currently is shown. As mentioned, it contains the details about the BizTalk management server and database, and (if configured) also about the Business Rules Engine. If you want the Rules Engine to be documented too, enable the corresponding checkbox. Under Advanced Documentation options, you can provide the location of an exported Configuration file. This export can be generated by means of the BizTalk Server Configuration wizard. I added such a file but could not spot any difference with documentation that was generated without that file. So maybe, this does not work.
Output options – Here, you can configure whether you want the documentation to be generated as a Compiled Help file (.chm), or a Word 2003 XML file. There are also options to set the Report title and the output folder. In case you want to customize the cover page of the report, you can select the folder with the required resources here.
Additional Filters – In this section, you can configure the filters for Hosts, Adapters, BRE policies, and BRE Vocabularies that you want to include in the report. Filters are applied with the StartsWith operator, and can be delimited with the pipeline (|) character
Select documentation Scope – Here, you can select if you want to document all the BizTalk applications, or only specific ones.
Select Assemblies and Orchestrations – In this screen, you can configure which Orchestrations and Assemblies you want to be configured.
Select SSO Configuration – This screen enables you to select the SSO applications for which you want documentation to be generated.
Further, there are the buttons for generating the documentation, and a Quit button, to exit the application.
Here you have a couple of resources that you might find useful:
In this article, we had a look at the BizTalk Documenter, how it should be installed, including the installation of HTMLHelp, and what kind of documentation can be generated. We hope this article has been of help to you.
