Sandcastleのコマンドを実行する方法

これまで紹介してきたように、Sandcastleではコマンドラインのプログラムとヘルプコンパイラを組み合わせてヘルプを生成します。実際にこの作業を行おうとすると、環境変数を設定したり、実行プログラムのパスと引数を設定したり、ファイルをコピーしたりといった、さまざまな手順が必要になり大変です。そこで、実際の業務で使用するときには、これらの手間を軽減するツールを利用することが一般的です。具体的には、以下の4つの中から使いやすい方法を選択してヘルプを生成していくことになります。

(1) バッチファイル
(2) MsBuild
(3) Windows PowerShell
(4) Sandcastle Help File BuilderなどのGUIツール

それでは、1つずつ見ていきましょう。

(1)バッチファイルによるヘルプの生成

コマンドラインのプログラムを順番に実行する方法としては、バッチファイルが有名です。この方法でヘルプを生成してみたい場合は、「C:\Program Files\Sandcastle\Examples\sandcastle」にあるバッチファイルを参考にすると良いでしょう。このフォルダにあるbuild_Sandcastle.batの場合、コマンドプロンプトから次のように実行します。

バッチファイルの実行例

build_Sandcastle.bat prototype SampleLib

このバッチファイルでは、引数にスタイル名とDLL名(拡張子は含まない)を指定して、ヘルプドキュメントを生成できます。 バッチファイルは、特別な環境が不要なため導入は容易です。その反面、エラー制御や部分実行などには適していないため、高度な操作が要求されるときには作業効率が低くなる可能性があります。

(2)MsBuildによるヘルプの生成

MsBuildは、.NET Framework2.0以上の環境で利用できるビルドツールです。MsBuildでは、XML形式のプロジェクトファイルを読み込んで、設定された作業を繰り返し実行できます。バッチファイルに比べて、個別の操作を実行したり、依存関係の管理ができるといった強みがあります。

MsBuildでドキュメントを生成してみたい場合は「C:\Program Files\Sandcastle\Examples\sandcastle」を参考にすると良いでしょう。このフォルダにあるbuild.projの場合、コマンドプロンプトから次のように実行できます(MsBuild.exeは「C:\WINDOWS\Microsoft.NET\Framework\バージョン\MSBuild.exe」にあります)。

Msbuildの実行例(ビルドファイル「build.proj」の読み込み)

Msbuild.exe build.proj /property:PresentationStyle=prototype

この実行例の場合、「build.proj」のデフォルトターゲットのBuildターゲットが動作して、HTML Help1.x形式のヘルプが生成されます。このプロジェクトファイルにあらかじめ用意されているターゲットは次の通りです。

Exampleに用意されているビルドファイルのターゲット一覧

ターゲット名 説明
Build Clean,FxReflection,Compile,Chmターゲットを順に呼び出す
Clean 作業フォルダの削除
FxReflection .NET Framework情報のリフレクション(fxReflection.proj呼び出し)
Compile C#ソースコードのビルド(csc)
Template 必要なファイル(iconやscripts)のコピー
ReflectionData MRefBuilderを呼び出してクラスとメンバの情報を取得
Manifest マニフェストファイルの生成
Html BuildAssemblerを呼び出してHtmlを生成
Chm HTML Help1.x形式のヘルプを生成
HxS HTML Help2.x形式のヘルプを生成

個別のターゲットを動作させたい場合には、「/target:HxS」のように/targetオプションとターゲット名を指定すれば、その処理を呼び出すことができます。

(3)Windows PowerShellによるヘルプの生成

Windows PowerShellは、Windowsの新しいシェルおよびスクリプト言語です。.NET Framework上に構築されており、オブジェクト指向に基づいた高度な機能が備わっています。 PowerShellでヘルプドキュメントを生成してみたい場合は、「C:\Program Files\Sandcastle\ProductionTools\scbuild.ps1」を呼び出して実行します。ただし、PowerShellは、Windows XP/VISTA/2003 Serverでは標準でインストールされていないため、別途入手してインストールする必要があります。インストールしたらスタートメニューからPowerShellを起動して、次のコマンドを入力できます。

PowerShellの実行例(HTML Help1.x形式のヘルプを生成)

$env:PATH += ";C:\Program Files\Sandcastle\ProductionTools"
$env:PATH += ";C:\Program Files\HTML Help Workshop"
cd C:\SampleLib\bin\Debug

scbuild.ps1 -BuildChm -sources SampleLib.dll,SampleLib.xml -Style prototype -Name ....\doc\MyHelp -Lcid 1041 -clean

この実行例の場合、アセンブリ「SampleLib.dll」とドキュメントコメント「SampleLib.xml」を元に、prototypeスタイルで「MyHelp.chm」というヘルプファイルが生成されます。 なお、既に解説したバッチファイルやMsBuildとは異なり、このPowerShellスクリプト「scbuild.ps1」はProductionToolsフォルダに含まれています。現バージョンのPowerShellスクリプト「scbuild.ps1」で用意されているパラメータは次の通りです。

PowerShellで用意されているパラメータ一覧

パラメータ 型 説明
-BuildChm Switch HTML Help1.x形式のヘルプを生成
-BuildHxS Switch HTML Help2.x形式のヘルプを生成
-BuildWebsite Switch Webサイトの生成
-Clean Switch 作業フォルダの削除
-Test Switch 環境のチェック
-BuildAssemblerConfig String BuildAssemblerの設定ファイル
-Config String コマンドラインの設定ファイル
-Dependencies Object[] 依存するアセンブリ
-DxRoot String Sandcastleの場所(環境変数DxRoot)
-Framework String 特定の.NET Frameworkのバージョン
-Lcid String 言語ID(既定値は1033)
-Mixin String スクリプト拡張用ファイル
-Name String 出力ファイル
-Sources Object[] アセンブリ、ドキュメントコメントファイル(カンマ区切り)
-Style String 表示するスタイル
-TempDir String 作業フォルダ
-WebBuildConfig String Webサイト構築時の設定ファイル
-WebTemplate String Webサイト構築時のテンプレートフォルダ

このパラメータの中で目を引くのは、バッチファイルやMsBuildにはなかったBuildWebsiteパラメータです。このパラメータはヘルプドキュメントをASP.NETのサイトとして作成する命令です。

PowerShellの実行例(ASP.NET Webサイトの生成) 

scbuild.ps1 -BuildWebsite -sources SampleLib.dll,SampleLib.xml -Style vs2005 -Name ....\My -Lcid 1041 -clean

上記のコマンドを実行すると、My_websiteというフォルダが生成され、このフォルダをサイトとして登録することで、Webサイトを公開することができます。