How to automatically generate documentation for your BizTalk solution

1. BizTalk Documenter
Automated Documentation Generation
Daniel Toomey
presenter

2. 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/

3. 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…

4. Not Covered
 BAM artefacts
 Functoids
 Satellite / Helper Classes

5. 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

6. GUI – Server Options

7. GUI – Output Options

8. GUI – Select Documentation Type

9. GUI – Orchestration Info

10. Command Line Usage
Microsoft.Sdc.BiztalkDocumenter.exe options
Options:
/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.

11. 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

12. 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

13. 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

14. Demo
 Generating documentation using the UI
 Embedding custom HTML content
 Using the command line interface to
automate as a post build task

15. 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

16. 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

17. Questions?