I have eventually got around to wiring up the BizTalk Documenter to our build process today. I did have an issue which is already logged on the codeplex site for the Documenter about problems when tracking is enabled on ports. I have worked around this problem by getting the source code for the documenter and building a local version of it with a fix until the next release where hopefully this will have been resolved. If you want more info about this please refer to:
Anyway back to the main part. So I wanted to hook in the Documenter which you can do from the command line, but while I had been looking at the code for the tool it seemed that it would be very easy to create a custom MsBuild task which would make it a little easier when adding it to build scripts.
The C# code for the build task is at the bottom of the article.
The xml to use the task looks like the following snippet:
<Acme.BizTalk.Build.Tasks.Bts.BizTalkDocumenter
Database="BizTalkMgmtDb"
OutputDirectory="C:\"
IncludeRules="false"
ReportName="MyApplication Documentation"/>
Points to Note:
- Remember to import your task using the UsingTask element)
- There are a number of other options on the task you would just set the appropriate properties, see C# below
The task I have created is intended to make it simple to document a single BizTalk application as part of that applications build process. When I want to document the full BizTalk server including all applications I tend to do this on demand and just use the tool.
In summary the BizTalk Documenter is a really cool tool and can be used to ensure you have accurate and up-to-date documentation for your BizTalk solution. I would recommend any project to use it.
using System;
using System.Collections;
using System.Collections.Generic;
using System.Diagnostics;
using System.Text;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
using Microsoft.BizTalk.ExplorerOM;
using Microsoft.Sdc.BiztalkDocumenter;
using Microsoft.Sdc.BiztalkDocumenter.Publishers;
namespace Acme.BizTalk.Build.Tasks.Bts
{
/// <summary>
/// This is an msbuild task to document a biztalk application
/// </summary>
public class BizTalkDocumenter : Task
{
private string _Application;
private string _DatabaseName;
private bool _IncludeRules;
private string _OutputDirectory;
private IPublisher _Publisher;
private string _ReportName;
private string _ResourcesFolder;
private string _RulesDatabase;
private string _RulesServer;
private string _Server;
//Note: I have omitted all of the properties from this code snippet to keep it smaller
/// <summary>
/// This will start an application
/// </summary>
/// <returns></returns>
public override bool Execute()
{
Logger.LogMessage(this, string.Format(CultureInfo.CurrentCulture, "Executing task: {0}", MethodInfo.GetCurrentMethod().ReflectedType.FullName));
if (!System.IO.Directory.Exists(this._OutputDirectory))
throw new ApplicationException("The output directory does not exist");
ArrayList applications = new ArrayList();
applications.Add(this._Application);
this._Publisher = new CompiledHelpPublisher();
if (string.IsNullOrEmpty(this._Server))
this._Server = Environment.MachineName;
if (this._IncludeRules)
{
if (string.IsNullOrEmpty(this._RulesServer))
this._RulesServer = Environment.MachineName;
}
Documenter documenter = new Documenter();
documenter.PercentageDocumentationComplete += new UpdatePercentageComplete(this.DocumenterStatus);
documenter.Applications = applications;
documenter.Database = this._DatabaseName;
documenter.DocumentRules = this._IncludeRules;
documenter.OutputDir = this._OutputDirectory;
documenter.Publisher = this._Publisher;
documenter.PublishType = PublishType.SpecificApplication;
documenter.ReportName = this._ReportName;
documenter.ResourceFolder = this._ResourcesFolder;
documenter.RulesDatabase = this._RulesDatabase;
documenter.RulesServer = this._RulesServer;
documenter.ShowOutput = false;
documenter.Server = this._Server;
documenter.GenerateDocumentation();
return true;
}
/// <summary>
/// Updates the status of the documenter
/// </summary>
/// <param name="percentage"></param>
private void DocumenterStatus(int percentage)
{
Trace.WriteLine("Documenter status: " + percentage.ToString());
}
#region Properties
/// <remarks/>
public string Server
{
get { return _Server; }
set { _Server = value; }
}
/// <remarks/>
public string RulesServer
{
get { return _RulesServer; }
set { _RulesServer = value; }
}
/// <remarks/>
public string RulesDatabase
{
get { return _RulesDatabase; }
set { _RulesDatabase = value; }
}
/// <remarks/>
public string ResourcesFolder
{
get { return _ResourcesFolder; }
set { _ResourcesFolder = value; }
}
/// <remarks/>
public string ReportName
{
get { return _ReportName; }
set { _ReportName = value; }
}
/// <remarks/>
public string OutputDirectory
{
get { return _OutputDirectory; }
set { _OutputDirectory = value; }
}
/// <remarks/>
public bool IncludeRules
{
get { return _IncludeRules; }
set { _IncludeRules = value; }
}
/// <remarks/>
public string DatabaseName
{
get { return _DatabaseName; }
set { _DatabaseName = value; }
}
/// <remarks/>
public string Application
{
get { return _Application; }
set { _Application = value; }
}
#endregion
}
}
Update 28 Jan 2008
Ive added a sample showing this to the below location. The code is slightly different than the snippets above but it should be straight forward enough. There is 2 projects the first is the msbuild task and the second is an example showing how to use it.
Note with this sample I have referenced the normal downloaded version of the BizTalk Documenter. Based on this you may experience the issue I have described at the top of this article.
Disclaimer
I have noticed a few sites that seem to copy the content of blog articles and display them in their own site. It is a bit annoying that they do not clearly reference or acknowledge the author so I have decided to put this note on the bottom of all of my posts from now so it is clear who wrote it.
This article was written by: Michael Stephenson
The source of this article is: http://www.geekswithblogs.net/michaelstephenson