Project Description

This tool creates documentation for a given BTS 2006, R2 2009 installation. It can be run on an ad-hoc basis using the UI or from the command line as a post build/deploy task to create a compiled help file or Word document describing a BizTalk installation.

It will compile:
• BTS Host configuration
• Send/Receive port configuration
• Orchestration diagrams complete with any custom code
• Schema and Map content
• Pipeline process flow
• Adapter configuration
• Rule engine vocabularies and policies
• More…
and publish them as compiled help files or Word 2003 XML.

This tool makes use of the common BizTalk OM Library so if you run into any issues with the core, or wish to debug and/or make changes, you need to get that library as well (although the PDB's are included here in the source tree to help with debugging)

Current Release - Now with 64 Bit support

The current release is v_3.4.0.0. Please see the downloads page for the release notes. Also look through the discussions for some of the fixes done on the XSLT to help with rendering documentation that is held in a local website.

Pre-Requisities
  • This is compiled against .NET 3.5 SP1 (and correspondingly VS2008 SP1 - for users of the source)
  • HTML Help Workshop. For 64 bit OS,Set the path to the help compiler in the application exe.config to <drive>:Program Files (x86)\HTML Help Workshop\hhc.exe
  • MS Word (2003 and upwards) (if you want to use the Word output option instead of CHM)

Known Issues:
  • The Word output does not include the images of the orchestrations. This is because we are writing to Word XML directly and there is no data about the image. We will accept any contributions to enhancing this area but otherwise no further work will be carried out on the Word output for this code-base. As noted below we are rewriting this tool so for the new product we will look into the Open XML SDK etc to provide richer output.
  • An old bug carried over is that the Output Folder can be selected but not the file name itself. This should be fixed in the next point release.
  • There are known issues in connecting to remote biztalk servers (reported on the forums).Basically the current systems user credentials are being passed through when connecting to the Explorer OM, SSO etc, so the local user probably doesnt have access to the remote machines. We will look into providing a username/password option for the next release to connect to the remote servers.
  • The codebase does not currently support adding custom descriptions for objects or indeed extending/customizing the default XSLT. We will look into externalizing some of this in the short term future, but most of the extensibility (via MEF and Unity) will be in the new product.

Roadmap

Point releases will be made as frequently as possible to fix reported bugs but no big functionality changes can be expected. Instead we are working on a new tool that will combine this Documenter with the Orchestration Profiler (as they share a number of common services including the Analysis OM). It is hard to work on two tools (actually 4 -if you take Profiler, Documenter and OM and the new toolset as separate projects) at the same time so please bear with us if we dont get fixes released frequently. There is also no planned date for the new toolset although we are dogfooding the new OM for some internal toolsets at the current time.

Screenshots

The screenshow below shows some of the information collected about an Orchestration, you can see what variables, maps, messages, ports, correlation sets, etc. that are used by a given Orchestration.

documenterOrchestrationInfo_1.png

The screenshot below shows further orchestration information which is collected, in this case we can see all of the inline code written by the developer for the orchestration, useful for code reviews and understanding a solution.

documenterCodeElements_1.png

Runtime Instructions

Run GUI from Start menu -> BizTalk 2006 Documenter or from the command line as follows:

Command Line Usage:

Microsoft.Sdc.BiztalkDocumenter.exe options

Options:
/o(utputdir) The output directory for the report. Default %TEMP%.
/s(erver) The BizTalk 2004 database server name (incl. instance). Default %COMPUTERNAME%.
/d(atabase) The BizTalk 2004 management database name to query. Default BizTalkMgmtDb.
/t(itle) The documentation file name.
/p(rovider) The documentation provider to use. chm (default) or word.
/show Show the documentation output when complete.
/defaults Run the documenter with all the defaults.
/a(pplications) comma separated list of target applications
/rules Include business rule documentation. true or false (default).
/rd Business rules database name. Default BizTalkRuleEngineDb.
/rs Business rules server name. Default %COMPUTERNAME%.
/h(elp) or /? This message.

Examples:
  • Microsoft.Sdc.BiztalkDocumenter.exe /def
  • Microsoft.Sdc.BiztalkDocumenter.exe /s:MyServer\INST1 /t:MyReportName /p:word
  • Microsoft.Sdc.BiztalkDocumenter.exe /s:MyServer\INST1 /r:schema /p:chm /o:C:\Docs\BTS

Overriding defaults via the command line

Although there are a number of default settings shown above which are automatically picked up when you specifiy /def on the command line, the system allows you to enter more arguments after the /def so you can customize further.
The overrides that you can specify are output folder, report name and publisher (/o, /t and /p)

Additionally to save having to type all these parameters in the command line, the system also allows you to specify some defaults (the output folder, report name and publisher) in the exe.config file (which will be activated when the appsetting allowcmdlineoverride is set to true. So you could just specify /def in th command line arguments, but if the config override is enabled, then the defaults for output folder, report name and publisher will be taken from the exe.config file.

Last edited Jun 11, 2010 at 7:45 AM by santoshbenjamin, version 20