BizTalk Documenter


Published on

How to automatically generate documentation for your BizTalk solution

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • 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)
  • BizTalk Documenter

    1. 1. BizTalk DocumenterAutomated Documentation Generation Daniel Toomey presenter
    2. 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
    3. 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. 4. Not Covered BAM artefacts Functoids Satellite / Helper Classes
    5. 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. 6. GUI – Server Options
    7. 7. GUI – Output Options
    8. 8. GUI – Select Documentation Type
    9. 9. GUI – Orchestration Info
    10. 10. 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.
    11. 11. Automated Build Task Michael Stephenson tells us how to wire up the BizTalk Documenter to an automated build process: archive/2007/11/19/116960.aspx Sample code:
    12. 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. 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. 14. Demo Generating documentation using the UI Embedding custom HTML content Using the command line interface to automate as a post build task
    15. 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. 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. 17. Questions?