Hilfe
Registrieren
Forum
Mitglieder
Blogs
Kalender
Mehr 
Folge uns auf Twitter
Werde ein Fan auf Facebook
Sandcastle ist ein eine Kommandozeilenapplikation, um eine automatische Dokumentation von .NET Assemblies zu erzeugen. Das von Microsoft entwickelte Tool erlaubt dies mittels der XML-Summaries innerhalb von .NET Projekten. So kann man binnen weniger Minuten eine professionelle Dokumentation zu einer Klassenbibliothek erzeugen.
1. Welche Vorraussetzungen muss ich erfüllen, bzw. worauf sollte ich achten?
Das wichtigste ist natürlich, auch explizit alle Methoden, Properties, Variablen, Klassen, Namespaces und vieles mehr pinibel mithilfe der XML-Summaries zu deklarieren. Anhand dieser Informationen wird später von Visual Studio eine .xml-Datei erstellt, welche von Sandcastle analysiert wird.
Beispiel in C#:
Visual C#
/// <summary>
/// Konstruktor #1
/// </summary>
/// <param name="url">Webadresse, an der sich die Quelldatei befindet</param>
/// <param name="username">Benutzername</param>
/// <param name="password">gültiges Passwort</param>
public DownloadFile(string url, string username, string password) {
throw new NotImplementedException("visit .NET Base ;)");
}
// anstelle von:
public DownloadFile(string url, string username, string password)
{
throw new NotImplementedException("visit .NET Base ;)");
}
Darüberhinaus muss man in den Projekteigenschaften unter dem Reiter "Build", bei dem "Output" auch die "XML documentation file" setzen, da ansonsten die bereits erwähnte .xml-Datei nicht von Visual Studio erstellt werden kann.
(Natürlich varriert der Projektname, sowie Dateiname der .xml-Datei.)
Nun sind die Vorbereitungen an dem später zu dokumentierenden Projekt abgeschlossen. Widmen wir uns nun dem Download & der Installation von den benötigten Dateien.
2. Download und Installation aller bentötigten Resourcen
(alle Dateien befinden sich auch im Anhang)
Wie ich einleitend bereits erwähnt habe, handelt es sich bei Sandcastle um eine Kommandozeilenanwendung. Dies eignet sich natürlich vorzüglich um in späteren Post-Build´s automatisch eine Dokumentation zu erzeugen. Dennoch wünscht sich der ein oder andere ein grafisches Tool, mit dem er Einstellungen komfortabel festlegen kann, eine Projektdatei speichert und bei belieben bestehende Dokumentationen aktualisiert.
Zunächst benötigen wir die aktuellste Version von Sandcastle. Zu dem derzeitigen Stand ist das die Version vom Mai 2008 (2.4.10520). Diese können wir entweder von CodePlex herunterladen, oder hier direkt von der .NET Base.
Nach dem Entpacken des Archivs finden wir einen Setup-Assistenten vor, den wir zur Installation heranziehen. Für diejenigen, die gerne mit einer GUI arbeiten möchten, lege ich Sandcastle Help File Builder (Download ebenfalls auch als Anhang, Version 1.8.03 vom 3. Januar 2010) an´s Herz. Zwar muss man auch hier die Anwendung installieren, kann sich aber recht schnell einarbeiten und es werden alle Funktionen unterstützt.
Für die jeweiligen Dokumentationsarten benötigt man jedoch zusätzlich noch verschiedene Runtimes, oder Plugins:
- HtmlHelp1 (benötigt HTML Help Workshop, generiert .chm-Dateien)
- MSHelp2 (benötigt einen HTML Help 2.x Compiler [Visual Studio SDK], generiert .hxs-Dateien)
- MSHelpViewer (standardmäßig enthalten, generiert eine .mshc-Datei)
- Website (standardmäßig enthalten, generiert eine .aspx-Website)
Nach der Installation der Komponenten, können wir Anfangen, ein Beispielprojekt zu dokumentieren.
3. Dokumentieren eines Projekts mithilfe der GUI vom Sandcastle Help File Builder
Nach dem Starten der Sandcastle Help File Builder GUI (%appdir%\EWSoftware\Sandcastle Help File Builder\) sehen wir folgende Form:
Über den Punkt "File"->"New Project" können wir ein neues Projekt erstellen. Sofort öffnet sich ein Fenster indem wir einen Zielpfad für die zu erstellende Projektdatei auswählen können.
Unsere Projektdatei wurde nun erzeugt und wir können unsere (kompilierten/erzeugten) Dateien aus dem Visual Studio in die "Documentation Sources" einfügen. Entweder mit einem Rechtsklick unter "Add.." oder durch einfaches Drag&Drop auf den Ordner.
Darüberhinaus passe ich noch in den Eigenschaften die Framework Version an (bei mir 2.0), sowie ändere ein paar Einstellungen um die spätere Dokumentation etwas mehr an meine Bedürfnisse anzupassen:
Im Prinzip habe ich nur Kontaktdaten und die spätere Sprache gesetzt. wenn man herunterscrollt sollte man auch den OutputPath angebeben. Sollte man die zusätzlichen Runtimes in den Standard-Ordner installiert haben, findet der Assistent sie automatisch. Andernfalls muss man die Informationen hier erneut definieren. Mit "Documentation" -> "Build" starten wir den Vorgang und warten einen kurzen Moment. Dies kann bei umfangreichen Projekten auch einige Minuten länger dauern!
Es kann gut sein das der Assistent in dem Generationsprozess einen Moment mit einer Datei beschäftigt ist. Man sollte dann nicht die GUI schließen, sondern bis auf folgenden Status warten:
Unsere Dokumentation sieht nun ähnlich wie diese aus:
Wir sehen unsere Einstellungen (Mail/Copyright-Angaben), sowie die Internen Verlinkungen. Wir sehen jetzt, das wir hier ein <Missing summary> haben, d.h. wir haben hier vergessen, eine Methode vernünftig zu deklarieren. Dies sollten wir in einer produktiven Umgebung natürlich sofort beheben
- Ich werde für diesen Test einfach mal so stehen lassen.Die Dokumentation wurde nun erstellt. Wenn wir Änderungen an unserem Visual Studio Projekt vornehmen und einen neuen Build unserer Assembly erzeugen, wird dafür aber nicht automatisch eine Dokumentation erstellt. Bei dieser Methode müssen wir uns jetzt erneut unsere Projektdatei schnappen und diese erneut erzeugen.
3. Dokumentieren eines Projekts mithilfe des PostBuild-Events von Visual Studio
Man kann ein sogenanntes PostBuild-Event in eine Projektmappe einbetten. Dieses Event trifft dann ein, wenn die Debug oder Release-Version erfolgreich erstellt worden ist. Da die Generierung, wie ich bereits angesprochen habe, bei großen Dateien sehr lange dauern kann, empfehle ich nur eine Generierung bei einem Release-, nicht einem Debug-Build.
Dazu kann man eine Abfrage innerhalb des Event nutzen:
IF "$(ConfigurationName)"=="Debug" Goto Exit ECHO Erstelle Dokumentation ... Dies kann einige Minuten dauern! "C:\Windows\Microsoft.NET\Framework\v3.5\MSBuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(ProjectDir)Documentation\DocProj.shfbproj" :Exit
Der Quellcode ist relativ statisch, und sollte deshalb angepasst werden!
Man findet das Pre- und das PostBuild-Event in den Projekteigenschaften (Project Properties) unter dem Punkt "Build":
Wie man hier erkennen kann, habe ich die Projektdatei von Sandcastle in einem Subordner innerhalb meines Projekts eingebettet. Seit einiger Zeit soll man die MSBuild.exe anstatt eine Console-Version von SHFB nutzen. Deswegen sollte man auch hier prüfen, ob das Framework-Verzeichnis vorhanden ist, bzw. die MSBuild.exe vorhanden ist.
Wenn alles korrekt eingerichtet ist, wird bei jedem Debug-Build nur die Klassenbibliothek erstellt, und bei einem Release-Build die Klassenbibliothek und die Dokumentation.
4. Zusammenfassung
Für Programmierer, die spezielle Klassenbibliotheken für die Weiterverwendung entwickeln, ist dieses System eine sehr schnelle, professionelle sowie kostenlose Möglichkeit, eine umfassende Projektdokumentation der API anzufertigen.
Grafik: Everaldo Coelho
Dieser Artikel ist Eigentum des Autors und darf ohne eine schriftliche Gehnehmigung nicht auf anderen Websiten oder Medien publiziert werden. Dies gilt auch für evtl. Attachments sowie optionale außenstehende Resourcen.
Angehängte Datei(en)
-
htmlhelp.rar (3,3MB)
Anzahl der Downloads: 26 -
Sandcastle.rar (6,97MB)
Anzahl der Downloads: 22 -
SandcastleBuilderSetup_1803.zip (8,55MB)
Anzahl der Downloads: 19
Dieser Beitrag wurde von Dennis Alexander bearbeitet: 22. Jan 2010 - 22:08
RSS Feed