Command line tools as MSBuild Tasks?

Mar 24, 2008 at 5:53 PM
I've been playing around with the Sancastle MSBuild examples to create API documentation for our product. One thing I noticed is that while you have core libraries for actually doing the tasks that the tool executables wrap, they are not MSBuild api based. This means that to use them from MSBuild you have to call exec tasks with all sorts of funny quoting and transforms to get the command line right. It also makes multiple item lists more difficult to pass. I understand that people want to call this from a general command line for things like powershell and general scripts, but why not make the core libraries based of MSBuild or have a MSBuild task library people can use?
Mar 24, 2008 at 8:30 PM

There's only a few tools that you need to execute and it's easy enough to call them as individual tasks if you need to. Wrapping the tools in custom MSBuild tasks isn't going to make it any easier to use.

I suggest trying DocProject, which provides a single MSBuild task that executes the entire help build process. The task is used in a few built-in Visual Studio project templates, so DocProject integrates seamlessly into VS and the same project can be used on the command-line as well.

Note that projects are not designed in a way so that you can change all of the arguments on the command-line. They are typical VS projects in the sense that they encapsulate all of the settings required to build a single set of documentation. If you need multiple unrelated sets of documentation you'll have to create multiple projects.

I think that Sandcastle Help File Builder will allow you to create a more generic project file that can be used to automate Sandcastle with different input using a response file on the command-line. (That's just an assumption from what I've read online though.)

- Dave
Mar 25, 2008 at 12:42 AM
Edited Mar 25, 2008 at 12:44 AM
Dave is correct. The console mode builder for SHFB will allow you build one or more projects and add or override project options from the command line and/or from a response file. (currently available as a beta) and later will allow you to import assembly and comments file info directly from a Visual Studio project too which lets you create a template project or do a completely project-less build from the command line.