Developers hate creating documentation Used to NDoc, Sandcastle (requires XML comments in code) BizTalk Documenter needs no extra comments in “code” (altho they are useful)
Covers all configuration recorded in the database Map shows XSLT that is generated (but not map itself)
Transcript of "BizTalk Documenter"
BizTalk DocumenterAutomated Documentation Generation Daniel Toomey presenter
BizTalk Server 2006 Documenter Creates compiled help files for a given BTS 2006 installation Can also generate Word files “Sandcastle” or “NDoc” for BizTalk solutions Created by Darren Jefford, Kevin Smith & Ilya Firman Latest version: v 3.2 BizTalk Server 2006 Release (April 7 2008) Available as a free download from http://biztalkdocumenter.codeplex.com/
Report Coverage 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…
Not Covered BAM artefacts Functoids Satellite / Helper Classes
Interface Comes with a basic GUI for adhoc generations Command line for using as an automated post build/deploy task Microsoft.Sdc.BiztalkDocumenter.exe /s:MyServerINST1 /p:chm /o:C:DocsBTS
Command Line UsageMicrosoft.Sdc.BiztalkDocumenter.exe optionsOptions: /outputdir The output directory for the report. Default %TEMP%. /server The BizTalk 2006 database server name (incl. instance). Default %COMPUTERNAME%. /database The BizTalk 2004 management database name to query. Default BizTalkMgmtDb. /title The documentation file name. /report The type of documentation to produce. complete (default) or schema. /provider The documentation provider to use. chm (default) or word. /show Show the documentation output when complete. /defaults Run the documenter with all the defaults.
Automated Build Task Michael Stephenson tells us how to wire up the BizTalk Documenter to an automated build process: http://geekswithblogs.net/michaelstephenson/ archive/2007/11/19/116960.aspx Sample code: http://www.box.net/shared/7mo38bsgsk
Custom Descriptions Using the “Description” field for artefacts & elements within Visual Studio designer Developer “commenting” for BizTalk solutions Text will be output in report Tedious(?), but provides much more informative generated output
Embedded Custom Content CHM option allows for custom HTML items to be embedded at the root level of the output Create a “titlePage.htm” page and any linked resources, and point Documenter to this resource directory Can embed an entire hierarchy of web pages NOTE: custom pages will not display within the navigation tree view
Demo Generating documentation using the UI Embedding custom HTML content Using the command line interface to automate as a post build task
Caveats CHM files don’t function when accessed remotely What you get out reflects what you put in (comments/descriptions) Need to install HTML Help Workshop Known bugs: Orchestration “hot-spots” don’t work ConfigFramework XML feature doesn’t work Error when port tracking enabled Error generating XML documents etc
Summary Developers hate to document Documentation generation tools are a welcome assistant to an otherwise tedious task BizTalk (integration) solutions present a significant challenge in terms of doco requirements The BizTalk Server 2006 Documenter rises to this challenge brilliantly The more effort you put in, the better the result