Fachhochschul-Masterstudiengang SOFTWARE ENGINEERING 4232 Hagenberg, Austria

Aktualisierung von NDoc und Integration in Visual Studio 2008

Diplomarbeit

zur Erlangung des akademischen Grades Master of Science in Engineering

Eingereicht von

Thomas Gassner, B.Sc.

Betreuer: Dipl.-Ing. (FH) Stefan Papp, HSG Hagenberg Begutachter: Dipl.-Ing. Dr. Herwig Mayr

August 2008 Inhaltsverzeichnis

Kurzfassung iv

Abstract v

Danksagung vi

1Einfuhrung¨ 1 1.1 Motivation und Ziele fur¨ die Weiterentwicklung von NDoc . . 1 1.2GliederungderArbeit...... 2

2 Grundlagen 5 2.1.netFramework...... 5 2.1.1 Einleitung...... 5 2.1.2 Versionenvon.netFramework...... 7 2.2MicrosoftVisualStudio...... 10 2.2.1 Einleitung...... 10 2.2.2 VersionenvonVisualStudio...... 10 2.2.3 AufbauderProjektmappe...... 11 2.2.4 Add-Ins...... 12 2.2.5 XML-Kommentare...... 13 2.3GenerischeTypen...... 15 2.4XML...... 18 2.4.1 XML-TransformationenmitXSLT...... 19

3 Analyse der Ist-Situation von NDoc 22 3.1EntwicklungvonNDoc...... 22 3.2BestehendesDesignvonNDoc...... 23 3.2.1 AufbauderProjektmappe...... 23 3.2.2 NDoc-Projekte...... 27 3.2.3 LadenvonAssemblies...... 28 3.2.4 MSDN-Dokumentierer...... 28 3.3AlternativenzuNDoc...... 30

i INHALTSVERZEICHNIS ii

4 Anforderungen an die Erweiterungen 36 4.1 Umgang mit aktuellen Visual Studio-Dateien ...... 36 4.2UmgangmitgenerischenTypen...... 37 4.3 Integration in Visual Studio 2008 ...... 38 4.4 Kompatibilit¨at...... 38 4.5Erweiterbarkeit...... 39 4.5.1 Anderungen¨ von Projekten und Projektmappen . . . . 39 4.5.2 Syntaktische Anderungen...... ¨ 39 4.5.3 SonstigeErweiterungen...... 40

5 Konzept 41 5.1 Anpassungen an die Anderungen¨ der Visual Studio-Dateien . 41 5.1.1 Projektmappendateien...... 42 5.1.2 Projektdateien...... 45 5.2AnpassungangenerischeTypen...... 47 5.3AufbaueinesVisualStudioAdd-Ins...... 49

6 Implementierung 53 6.1 Visual Studio-Projektmappen und -Projekte ...... 53 6.1.1 Architektur...... 53 6.1.2 Codierung...... 55 6.2VisualStudioAdd-In...... 56 6.2.1 Architektur...... 56 6.2.2 Codierung...... 57 6.3MSDN-Dokumentierer...... 58 6.3.1 Architektur...... 58 6.3.2 Codierung...... 58

7 Evaluierung 61 7.1ErreichteZiele...... 61 7.2 Testbeschreibung ...... 63 7.2.1 InterneTests...... 63 7.2.2 Externe Tests - Verarbeitung des Testprojektes . . . . 63 7.3Testergebnisse...... 64 7.3.1 InterneTests...... 64 7.3.2 ExterneTests...... 64

8Resumee¨ 65 8.1Zusammenfassung...... 65 8.2 Ver¨offentlichungdesErgebnisses...... 66 8.3Ausblick...... 66

A E-Mail von Kevin Downs 68

Literaturverzeichnis 70 Abbildungsverzeichnis

2.1.netFrameworkArchitektur...... 6 2.2FunktionsweiseXSLT...... 20 2.3XSLT-Beispiel...... 21

3.1 UML-Klassendiagramm der Dokumentierer-Hierarchie . . . . 25

4.1 Dialogfenster zur Auswahl der Konfiguratinonen ...... 37

5.1EntwurfsmusterFabrikmethode...... 42 5.2 Projektmappendatei Visual Studio .net 2003 ...... 43 5.3 Projektmappendatei Visual Studio 2008 ...... 43 5.4 Projektmappendatei Visual Studio 2008 mit 2. Plattform . . 44 5.5 Konfigurationen und Plattformen in einer Projektmappe . . . 45 5.6 ReflectionEngine – MSDN-Dokumentierer ...... 47 5.7 Beispiel: online MSDN-Link – nicht generischer Typ . . . . . 48 5.8 Beispiel: online MSDN-Link – generischer Typ ...... 49 5.9 Ereignisse der Schnittstelle IDTExtensibility2 ...... 50

6.1 Alte Architektur des Projekts VisualStudio ...... 54 6.2 Neue Architektur des Projekts VisualStudio ...... 54 6.3 Architektur des NDoc Visual Studio-Add-Ins ...... 57

iii Kurzfassung

Dokumentation ist eine sehr wichtige und von Entwicklern oft untersch¨atzte Aufgabe im Bereich der Softwareentwicklung. Oft werden Dokumentations- arbeiten erst im Nachhinein erledigt, wodurch die Qualit¨at der Dokumen- tation leidet und der Arbeitsaufwand steigt. Moderne Programmierspra- chen bieten die M¨oglichkeit, Typen, Mitglieder, Eigenschaften, Methoden, Schnittstellen etc. direkt im Quelltext und damit w¨ahrend der Implementie- rung zu dokumentieren. Diese Kommentare k¨onnen dann mit Hilfe spezieller Werkzeuge zu ubersichtlichen¨ Dokumentationen weiterverarbeitet werden. Bekannte Vertreter dieser Werkzeuge sind Javadoc, NDoc und Doxygen. NDoc ist ein weit verbreitetes Werkzeug, welches aus .net-Assemblies mit Hilfe von Reflection und der vom C#-Compiler generierten XML-Dokumen- tationsdateien ubersichtliche¨ und strukturierte Dokumentationen erzeugen kann. NDoc ist ein Open Source-Projekt, das auf der online Plattform Sour- ceforge gehostet wird. Die Implementierung wurde seitens der Entwickler aus pers¨onlichen Grunden¨ eingestellt, bevor Neuerungen wie generische Typen von .net 2.0 oder das neue Dateiformat von Visual Studio 2005 unterstutzt¨ wurden. Ziel dieser Arbeit ist die Erweiterung von NDoc auf der Basis der Ver- sion 1.3.1 und den Erweiterungen von Richard Jonas in der Version 16. Die Erweiterung besteht grob gegliedert aus drei Teilen:

1. Eine Unterstutzung¨ des MSDN-Dokumentierers von generischen Ty- pen wurde implementiert. Diese umfasst den korrekten Umgang von generischen Typen, sowohl in der Verarbeitung, in der Anzeige, als auch bei den Referenzen auf eine lokal installierte oder die online- Version der Microsoft MDSN-Bibliothek.

2. Eine Unterstutzung¨ fur¨ das Laden von Projektmappendateien und Projektdateien von Visual Studio 2005 und Visual Studio 2008 wurde entwickelt.

3. Eine Integration in Form eines kleinen Add-Ins in Visual Studio 2008 wurde implementiert, sodass Entwickler direkt eine Dokumentation er- stellen k¨onnen, ohne explizit eine Drittanwendung starten zu mussen.¨

iv Abstract

Documentation is a very important task and often underestimated by de- velopers in the field of software development. Documentation work is often done only in retrospect, so the documentation loses some of its quality and it involves a lot of work. Modern programming languages offer the possi- bility of documenting types, members, properties, methods, interfaces, etc. directly in the source code and during implementation. These comments can be processed using special tools to clearly represented documentation. Well known representatives of these tools are Javadoc, NDoc and Doxygen. NDoc is a widely used tool, which can produce clear and structured do- cumentations from Assemblies with .net with the help of reflection and the C# compiler generated XML documentation files. NDoc is an open source project, hosted on the online platform sourceforge. The implementation was set from the developer due to personal reasons before innovations such as generic types from .net 2.0 or the new file format of Visual Studio 2005 could be supported. The aim of this work is the extension of NDoc based on the version 1.3.1 and the extensions by Richard Jonas in the 16th version. The upgrade is roughly divided into three parts:

1. A support of the MSDN documenter of generic types was implemented. This includes the correct use of generic types in the processing, in the visualisation as well as the references to a locally installed or the online version of Microsoft MDSN library.

2. A support for loading solution files and project files of Visual Studio 2005 and Visual Studio 2008 was developed.

3. An integration in the form of a small add-in in Visual Studio 2008 was implemented, with the result that developers are able to create a documentation directly, without an explicit third party application start.

v Danksagung

Ich danke

Herrn Dipl.-Ing. Dr. Herwig Mayr fur¨ die Betreuung und Begutachtung meiner Arbeit,

Dipl.-Ing. (FH) Stefan Papp fur¨ die Betreuung meines Masterprojekts und der Firma Hagenberg Software GmbH, die der Auftraggeber des Projekts ist,

Gabriela, Martina und Anton Gassner, die diese Arbeit Korrektur ge- lesen haben

und meiner Freundin Veronika Hoffelner fur¨ die seelische Unterstutz-¨ ung und Motivation.

vi Kapitel 1

Einfuhrung¨

Die folgende Diplomarbeit entstand in Zusammenarbeit mit der Hagenberg Software GmbH (HSG). Die HSG ist das Zentrum fur¨ kommerzielle Softwa- reentwicklungen in Hagenberg und ist von der Systemauswahl uber¨ Projekt- unterstutzung¨ bis hin zur Maßkonfektion von Software t¨atig.

1.1 Motivation und Ziele fur¨ die Weiterentwick- lung von NDoc

Motivation NDoc ist nach wie vor ein sehr weit verbreitetes Open Source-Werkzeug zur Erstellung von Dokumentationen von .net-Projekten und Bibliotheken. Die Entwicklung dieser Anwendung wurde eingestellt (siehe Anhang A). Die letzte offizielle Version unterstutzt¨ keine generischen Typen und kann die Projektmappendateien der beiden neueren Visual Studio Versionen nicht ¨offnen. Seit dem Erscheinen des .net Frameworks 2.0 und der integrierten Ent- wicklungsumgebung Visual Studio 2005 besteht eine Nachfrage nach einer Version von NDoc, die mit den Neuerungen umgehen kann. Es gibt eine Reihe kommerzieller Dokumentationsanwendungen, die die entstandene Lucke¨ auffullen,¨ auch im Bereich der Open Source-Projekte gibt es einige Bestrebungen, in die Fußstapfen des originalen NDoc-Projekts zu steigen, doch ist bis dato kaum ein Open Source-Projekt verfugbar,¨ das die Anforderungen erfullt.¨ Eine Ausnahme hiefur¨ ist das Sandcastle-Projekt (siehe Abschnitt 3.3) von Microsoft.

Problemstellung Die Dokumentationsanwendung NDoc sollte auf die Anforderungen der ak- tuellen .net-Versionen angepasst werden. Insbesondere sollte die Unterstut-¨ zung fur¨ die Dokumentation von generischen Typen, Projektmappendateien

1 KAPITEL 1. EINFUHRUNG¨ 2 und Projektdateien aller Visual Studio-Versionen, die eine Programmierung unter der Verwendung des .net Frameworks erlauben, importiert werden k¨onnen. Eine einfache Integration in Visual Studio 2008 sollte in Form ei- nes kleinen Add-Ins verwirklicht werden. Dadurch wurden NDoc aktuellen Bedurfnissen¨ gerecht.

Zielsetzung Ziel dieser Arbeit ist eine weiterentwickelte NDoc Version. Es soll Entwick- lern durch Aufrufen eines Menupunkts¨ in Visual Studio 2008 m¨oglich sein, Dokumentationen von .net-Projekten erstellen zu k¨onnen. Diese Software- projekte sollen generische Typen definieren und verwenden k¨onnen. Es soll auch m¨oglich sein, Dokumentationen durch das Offnen¨ von Projektmap- pendateien aktueller Visual Studio Versionen in NDoc-Dokumentationen zu erstellen. Diese Arbeit verdeutlicht die verwendeten Konzepte und legt die inter- essantesten Details der Implementierung dar.

1.2 Gliederung der Arbeit

Diese Arbeit beschreibt die Grundlagen, die Ausgangssituation und die Um- setzung der Aufgabenstellung.

Kapitel 2 beschreibt die Grundlagen, die zu Grunde liegenden Technolo- gien und die zu Grunde liegenden Softwareprodukte. Dieses Kapitel ist in vier Bereiche gegliedert. Der erste Bereich beschreibt das .net Framework. Hier wird die Aufga- be, der Aufbau, die Entwicklungsgeschichte und die Eigenheiten des .net Frameworks behandelt. Der zweite Bereich beschreibt die integrierte Entwicklungsumgebung Vi- sual Studio. Hier werden die Entwicklungsgeschichte, die Besonderheiten und der Aufbau der Projekte und der Projektmappen beschrieben. Der dritte Bereich behandelt generische Typen. Welche Eigenschaften und welche Besonderheiten generische Typen haben und im Besonderen, wie generische Typen in der Programmiersprache C# verwendet werden. Der vierte Bereich behandelt XML, einen Uberblick¨ in die Technologie, Transformationen auf Basis von XML mit XSLT und Abfragen mit XPath.

Kapitel 3 analysiert die Ausgangssituation. Dieses Kapitel besteht aus drei Teilen. Der erste Teil beschreibt die Entwicklung der Anwendung von NDoc bis zum Entwicklungsstopp. Das Design, der Aufbau und die Funktionsweise von Ndoc und die vor- handenen Dokumentierer werden im zweiten Teil beschrieben. KAPITEL 1. EINFUHRUNG¨ 3

Der dritte Teil gibt einen Uberblick¨ uber¨ bestehende kommerzielle und nicht kommerzielle Alternativen zu NDoc.

Kapitel 4 beschreibt die Anforderungen an die in dieser Arbeit beschrie- benen Erweiterungen. Dieses Kapitel besteht aus funf¨ Teilen. Der erste Teil beschreibt den Umgang mit Projektmappen- und Projekt- dateien von Visual Studio. Der zweite Teil beschreibt den Umgang mit generischen Typen und wie deren Ausgabe in der Dokumentation aussehen soll. Die Integration in die Entwicklungsumgebung Visual Studio mit Hilfe eines Add-Ins wird im dritten Teil beschrieben. Der vierte Teil definiert die Kompatibilit¨at zu ¨alteren Versionen. Im funften¨ Teil wird die Erweiterbarkeit fur¨ zukunftige¨ Anderungen¨ be- schrieben.

Im Kapitel 5 wird das Konzept der Anpassungen erl¨autert. Dieses Kapi- tel besteht aus drei Teilen, die die drei Bereiche, die im Zuge dieser Arbeit an der Software NDoc erweitert werden, widerspiegeln. Der erste Teil beschreibt die Anpassungen und deren Design bezuglich¨ der Projektmappen- und Projektdateien von Visual Studio. Der zweite Teil beschreibt die Anpassungen und Ver¨anderungen fur¨ die Unterstutzung¨ von generischen Typen. Der dritte Teil dieses Kapitels beschreibt den Aufbau eines Add-Ins in Visual Studio.

Das Kapitel 6 beschreibt die Implementierung gem¨aß des in Kapitel 5 be- schriebenen Konzepts der Erweiterungen in drei Teilen. Der erste Teil beschreibt die Implementierung der Anpassungen und die Architektur bezuglich¨ der neuen Dateiformate der Projektmappen- und Pro- jektdateien. Die Implementierung des Visual Studio Add-Ins fur¨ die Integration von NDoc in Visual Studio wird im zweiten Teil beschrieben. Der dritte Teil beschreibt die programmatischen Anderungen,¨ die im Do- kumentierer MSDN vorgenommen werden.

Das Kapitel 7 evaluiert das Projekt und besteht aus zwei Teilen. Der erste Teil vergleicht die Anforderungen und die erreichten Ziele mit- einander. Der zweite Teil beschreibt die Tests, die wiederum in interne und externe Tests aufgeteilt sind.

Kapitel 8 fasst noch einmal die wichtigsten Aspekte und Erkenntnisse zu- sammen. Es wird ein kurzer Uberblick¨ uber¨ die erzielten Ergebnisse gegeben und zeigt einen Ausblick auf denkbare Erweiterungen und Verbesserungen KAPITEL 1. EINFUHRUNG¨ 4 fur¨ zukunftige¨ Versionen.

Im Anhang A ist das E-Mail von NDoc-Entwickler Kevin Downs zu lesen, das er der Community im Zuge der Niederlegung der Arbeiten an NDoc gesendet hat. In diesem E-Mail legt er die Grunde¨ fur¨ die Einstellung der Entwicklung an NDoc dar. Kapitel 2

Grundlagen

Im folgenden Kapitel werden jene Grundlagen behandelt, die fur¨ das Verst¨and- nis der Arbeit n¨otig sind. Um sich jedoch in einzelne Themengebiete zu vertiefen, sollte die angefuhrte¨ Literatur studiert werden.

2.1 .net Framework

2.1.1 Einleitung Entstehungsgeschichte Microsoft hat verschiedene Technologien einge- fuhrt,¨ um Entwicklern ihre Arbeit bei der Entwicklung von Applikationen fur¨ das Betriebssystem Windows zu erleichtern. Einige davon sind: Microsoft Foundation Class Library (MFC) – eine C++-Abstraktion fur¨ die Entwick- lung von grafischen Benutzeroberfl¨achen, Visual Basic, Active Server Pages (ASP) zum Erstellen von dynamischen Webseiten und die Active Templa- te Library (ATL) fur¨ die Erstellung von Komponenten. Diese Technologien hatten einen Nachteil: Ein Entwickler musste verschiedene Sprachen ler- nen und die Interoperabilit¨at zwischen den einzelnen Technologien war zwar m¨oglich, aber eher komplex. Mit der Entwicklung des .net Frameworks hat sich Microsoft das Ziel gesetzt, eine Abstraktionstechnologie fur¨ verschie- dene Programmiersprachen und verschiedene Arten von Anwendungen zur Verfugung¨ zu stellen und dabei eine gewisse Abw¨artskompatibilit¨at zu ¨alte- ren Windows-Technologien zu wahren. Das .net Framework ist eine Softwareplattform, die von Microsoft ent- wickelt wurde. Sie besteht aus mehreren Teilen: Die Common Language Runtime (CLR) und die Framework Class Library (FCL). Die CLR ist die Laufzeitumgebung von .net und stellt ein objektorientiertes Programmier- modell zur Verfugung.¨ Sie beinhaltet eigene Komponenten, wie z.B. Spei- cherverwaltung, Sicherheitssystem, Dateilader, Threadpool etc. Die FCL ist die vom .net Framework zur Verfugung¨ gestellte Klassenbi- bliothek. Sie umfasst einige tausend Klassen, die in Namensr¨aume eingeteilt

5 KAPITEL 2. GRUNDLAGEN 6

Abbildung 2.1: .net Framework Architektur (Quelle: http://technet.microsoft.com/en-us/library/bb496996.aspx)

sind und eine Vielzahl an Typendefinitionen fur¨ ein breites Spektrum an An- wendungsf¨allen bietet. Mit den im .net Framework verwendeten Techniken ist es sehr einfach, wiederverwendbaren Code zu erzeugen. Die Abbildung 2.1 zeigt die Architektur des .net Frameworks. Ubersetzte¨ Programmteile werden in Assemblies zusammengefasst. Sie haben die unter Windows bekannten Endungen .dll und .exe,sindaber intern v¨ollig anders strukturiert. Assemblies enthalten ausfuhrbaren¨ Code und eine Reihe verschiedener Metadaten. Programme und Bibliotheken, die in einer .net-Sprache geschrieben werden, werden vom Compiler nicht wie z.B. ein C++-Programm in nativen Code ubersetzt,¨ den nur ein bestimm- ter Prozessor versteht, sondern in einen Zwischencode. Dieser Zwischencode wird Common Intermediate Language (CIL oder IL) genannt. W¨ahrend der Laufzeit ubersetzt¨ die CLR mit Hilfe eines Just-in-Time-Compilers (JIT- Compiler) den IL-Code in CPU-spezifische Befehle. Fur¨ spezielle Anwen- dungsgebiete kann CIL in nativen Code ubersetzt¨ werden, damit zur Lauf- zeit keine JIT-Kompilierung erfolgen muss. Durch den Einsatz von IL-Code erreichen Programme, die auf dem .net Framework basieren, eine gewisse Plattformunabh¨angigkeit. Einzige Bedin- gung ist eine vorhandene CLR fur¨ die Zielplattform. Unter Windows werden CLRs von Microsoft fur¨ x86, x64 und Itanium-Prozessoren angeboten. Das Mono-Projekt [Mon, 2008] hat sich als Ziel gesetzt, eine echte plattformun- abh¨angige Open-Source-Implementierung des .net Framework zu schaffen. Der .net-Entwickler kann sich aussuchen, welche Sprache er verwen- det. Bei einem .net-Projekt k¨onnen einzelne Komponenten in verschiede- nen Programmiersprachen implementiert werden, z.B.: Ein in VB.net defi- nierter Typ kann in einem C#-Programm instanziiert werden. Durch diese so genannte Sprachneutralit¨at erleichtert das .net Framework die Zusam- KAPITEL 2. GRUNDLAGEN 7 menarbeit in einem heterogenen Entwicklerteam, das eine gemischtsprachi- ge Programmierung durchfuhrt.¨ Diese Sprachenvielfalt ist m¨oglich, da das Common Type System (CTS) eine gemeinsame Schnittmenge von Datenty- pen beschreibt, die eine .net-Programmiersprache unterstutzen¨ muss. Auch ¨altere Komponenten, die auf der COM-Technologie basieren, k¨onnen ohne Probleme in einer .net-Applikation verwendet werden. Altere¨ C++-Projekte k¨onnen zwar nicht automatisiert auf die .net-Technologie portiert werden, aber Microsoft hat Wert auf Migrationspfade gelegt. Die CLR pruft¨ die Integrit¨at des Codes. Damit ist im .net Framework eine Typsicherheit gegeben. Auch um die Speicherverwaltung kummert¨ sich die CLR. Allokierter Speicher wird am Heap automatisch wieder frei ge- geben. Diese Aufgabe ubernimmt¨ der Garbage Collector. Code, bei dem Speicher automatisch wieder freigegeben wird, wird managed Code genannt, im Vergleich zu unmanaged Code, bei dem der Entwickler den reservierten Speicher selbst wieder freigeben muss (z.B.: C++-Code). Durch die Typsi- cherheit und die automatisierte Speicherverwaltung werden viele verbreitete Programmierfehler, wie sie z.B. in C++-Programmen vorkommen, von vorn- herein verhindert. Fur¨ spezielle Sonderf¨alle kann man in C# so genannten unsicheren Code verwenden, der Zeigerarithmetik erlaubt. Mit dem Reflection-API k¨onnen Metadaten aus Objekten ausgelesen werden und Informationen uber¨ deren Typ, Methoden, Eigenschaften, Events usw. bestimmt werden. NDoc nutzt diese Technologie um Informationen aus Assemblies zu extrahieren. Die .net Framework Laufzeitumgebung und das .net Framework SDK werden von Microsoft kostenlos fur¨ verschiedene Windows-Versionen und verschiedene Hardwareplattformen angeboten. Die integrierte Entwicklungs- umgebung Visual Studio (siehe Abschnitt 2.2) wird, bis auf eine kostenlose Expressversion, kostenpflichtig von Microsoft angeboten. Fur¨ mobile Endger¨ate, wie Smartphones und PDAs gibt es das .net Com- pact Framework, das ein Teil des .net Frameworks ist. Das .net Compact Framework ist optimiert fur¨ ressourcenarme kleine Endger¨ate und bietet nur eine Untermenge der Typen des normalen .net Framework an.

2.1.2 Versionen von .net Framework .net Framework 1.0 Das .net Framework in der Version 1.0 wurde 2002 ausgeliefert. Das dazu- geh¨orige SDK enth¨alt den C#-Compiler in der Version 7.0. Das Erscheinen des .net Frameworks 1.0 war eng mit der Erscheinung von Visual Studio .net 2002 (siehe Abschnitt 2.2.2 Versionsnummer 7.0) gekoppelt. KAPITEL 2. GRUNDLAGEN 8

.net Framework 1.1 Das .net Framework in der Version 1.1 wurde 2003 ausgeliefert. Das dazu- geh¨orige SDK enth¨alt den C#-Compiler in der Version 7.1. Das Erscheinen des .net Frameworks 1.1 war eng mit der Herausgabe von Visual Studio .net 2003 (siehe Abschnitt 2.2.2 Versionsnummer 7.1) gekoppelt. Die Versi- on 1.1 des .net Frameworks bietet einige Erweiterungen und Verbesserungen im Vergleich zur Version 1.0, z.B. verbesserte Skalierbarkeit und Leistung, Unterstutzung¨ fur¨ die Entwicklung fur¨ mobile Ger¨ate mit ASP.NET Mobile- Steuerelementen, Unterstutzung¨ fur¨ IPv6, ADO.NET-Klassen fur¨ die syste- meigene Kommunikation mit ODBC-(Open Database Connectivity-) und Oracle-Datenbanken etc. Im .net Framework 1.1 ist die CLR in der Version 1.1 inkludiert.

.net Framework 2.0 Das .net Framework in der Version 2.0 wurde 2005 ausgeliefert. Das dazu- geh¨orige SDK enth¨alt den C#-Compiler in der Version 8.0. Die Herausgabe des .net Frameworks 2.0 war eng mit dem Erscheinen von Visual Studio 2005 (siehe Abschnitt 2.2.2 Versionsnummer 8.0) gekoppelt. Die Version 2.0 des .net Frameworks und der C#-Compiler unterstutzen¨ die Sprache C# in der Version 2.0 und viele andere wichtige neue Elemente. Einige dieser Neue- rungen sind: Generische Typen (siehe Abschnitt 2.3), Iteratoren, anonyme Methoden und partielle Datentypen. Im .net Framework 2.0 ist die CLR in der Version 2.0 inkludiert, die nativ mit generischen Typen umgehen kann.

.net Framework 3.0 Das .net Framework 3.0 wurde 2006 ausgeliefert. Es basiert auf der CLR in der Version 2.0. Es wurde lediglich die Bibliothek unter anderem um vier große Bereiche erweitert:

1. Die Windows Communication Foundation (WCF) stellt eine neue dienst- orientierte Kommunikationsplattform dar. Besonders fur¨ verteilte An- wendungen werden viele Netzwerkfunktionen unter einer einheitlichen API zusammengefuhrt.¨ Service-orientierte Architekturen sind das Haupt- anwendungsgebiet der WCF.

2. Die Windows Presentation Foundation (WPF) ist die neue Pr¨asenta- tionsschnittstelle fur¨ Windows. Im Vergleich zu ¨alteren Pr¨asentations- und Grafikschnittstellen setzt WPF auf DirectX auf und bietet da- durch einen Performanzgewinn durch Hardwarebeschleunigung. Zur Beschreibung von Oberfl¨achen wird eXtensible Application Markup Language (XAML) verwendet. KAPITEL 2. GRUNDLAGEN 9

3. Windows Workflow Foundation (WF) ist ein erweiterbares Framework fur¨ die Entwicklung von Workflow-L¨osungen. Es stellt Werkzeuge und APIs zum Erstellen und Ausfuhren¨ von workflow-gesteuerten Anwen- dungen zur Verfugung.¨

4. CardSpace ist eine Technologie zur Identit¨atsverwaltung und kann zur Identifizierung und Authentifizierung gegenuber¨ Webservices und Webseiten verwendet werden.

.net Framework 3.5 Das .net Framework 3.5 wurde 2007 ausgeliefert. Es basiert ebenfalls wie das .net Framework 3.0 auf der CLR der Version 2.0. In der Version 3.5 des .net Framework wurde nicht nur die Bibliothek, sondern auch der C#- Compiler erweitert. Der im .net Framework SDK enthaltene C#-Compiler in der Version 3.5 1 unterstutzt¨ die Version 3.0 der Programmiersprache C#. Die wichtigsten Erneuerungen der Version 3.0 von C# und der Bibliothek sind:

Language INtegrated Query (LINQ), mit dem Abfragen in die Pro- grammiersprache integriert werden und somit zur Ubersetzungszeit¨ vom Compiler uberpr¨ uft¨ werden k¨onnen. Die Art der Datenquelle k¨onnen SQL-Daten, Auflistungen, XML und DataSets sein.

Lambda-Ausdrucke¨ sind anonyme Funktionen, die Anweisungen und Ausdrucke¨ enthalten. Sie k¨onnen fur¨ die Erstellung von Delegaten ver- wendet werden.

Durch implizit typisierte lokale Variablen und dem Schlusselwort¨ var wird dem Entwickler das Deklarieren einer Variablen, ohne ausdruck-¨ lich deren Typ angeben zu mussen,¨ erlaubt.

Mit Erweiterungsmethoden kann der Entwickler beliebige Typen er- weitern.

Durch die neuartige Objektinitialisierung k¨onnen bei der Initialisie- rung von Objekten gleichzeitig Werte festgelegt werden.

In C# 3.0 ist es m¨oglich, anonyme Typen zu definieren.

ASP.NET 3.5 wurde um einige AJAX-Erweiterungen und einige neue Steuerelemente erweitert. 1Bis zur Compilerversion 8 ist die Nummerierung des C#-Compilers analog zum Mi- crosoft C++-Compiler. Die aktuelle Compilerversion 3.5 des C#-Compilers hat die Ver- sionsnummer des .net-Frameworks mit dem er ausgeliefert wird. KAPITEL 2. GRUNDLAGEN 10

2.2 Microsoft Visual Studio

2.2.1 Einleitung Visual Studio ist eine integrierte Entwicklungsumgebung der Firma Micro- soft. Seit der Version Visual Studio .net (7.0) sind .net-Framework-spezifi- sche Funktionen integriert. Visual Studio verfugt¨ uber¨ viele Funktionen wie z.B. die Projektverwaltung. Es k¨onnen verschiedene Projekte angelegt wer- den. Diese Projekte k¨onnen auch in unterschiedlichen Programmiersprachen entwickelt werden. Die Metainformationen werden fur¨ jedes Projekt in einer Projektdatei gespeichert. Fur¨ C#-Projekte hat diese Datei die Erweiterung .csproj. Die Projekte werden in einer Projektmappe zusammengefasst. Die Metadaten einer Projektmappe werden in einer Datei mit der Erweiterung .sln gespeichert (siehe Abschnitt 2.2.3). Diese Datei liest NDoc aus, wenn der Menupunkt¨ New from Visual Studio Solution“ aktiviert wird. Visual ” Studio verfugt¨ uber¨ einen sehr komfortablen Quellcode-Editor und einen De- signer fur¨ grafische Benutzeroberfl¨achen. Eine Vielzahl an Assistenten und Werkzeugen erleichtern dem Entwickler seine Arbeit. Compiler, Linker und Debugger erm¨oglichen die eigentliche Erstellung der Software. Visual Stu- dio erlaubt auch das Verwenden und Erstellen von Add-Ins (siehe Abschnitt 2.2.4).

2.2.2 Versionen von Visual Studio Visual Studio .net 2002 Visual Studio .net 2002 ist der Nachfolger von Visual Studio 6.0 und hat die Versionsnummer 7.0. Es ist die erste Version von Visual Studio, die auf dem .net Framework aufbaut.

Visual Studio .net 2003 Visual Studio .net 2003 ist eine Erweiterung der Version 2002 und hat die Versionsnummer 7.1. Wichtigste Neuerung ist, dass seit Visual Studio 2003 das .net Compact Framework, mit dem Entwicklung von Software fur¨ mobile Ger¨ate, wie Smartphones und PDAs durchgefuhrt¨ werden kann, unterstutzt¨ wird.

Visual Studio 2005 Der Namenszusatz .net wurde von Microsoft ab der Version 2005 des Visual Studios nicht mehr verwendet. Die Unterstutzung¨ des .net Frameworks in der Version 2.0 ist ein zentrales Merkmal. Eine Neuheit, die Entwicklern helfen soll, ihre Produktivit¨at zu steigern, ist die M¨oglichkeit, Codeausschnitte fur¨ Standardaufgaben w¨ahrend der Entwicklung schnell einzufugen.¨ Eine visu- elle Drag-&-Drop-Unterstutzung¨ fur¨ Entwicklungen mit Datenbanken, eine KAPITEL 2. GRUNDLAGEN 11

Erweiterung der Intellisense-Funktion und eine umfangreiche Unterstutzung¨ von mehreren Plattformen (x86, x64, IA64 und IL) geh¨oren zu den Neue- rungen von Visual Studio 2005. Das Dateiformat der Projektmappendatei tr¨agt die Version 9.0.

Visual Studio 2008 Visual Studio 2008 bietet eine bessere Werkzeug-Unterstutzung¨ der Funk- tionalit¨aten von .net Framework 3.0 und 3.5. Die Webentwicklung wurde ebenfalls wesentlich verbessert. Das Dateiformat der Projektmappendatei tr¨agt die Version 10.0, unterscheidet sich aber nur sehr wenig von der Versi- on 9.0 von Visual Studio 2005. Wie schon in fruheren¨ Versionen von Visual Studio gibt es verschiedene Editionen. Visual Studio 2008 gibt es in vier Versionen: Die Express Edition, eine kostenlose Einsteigerversion, von der es fur¨ C#-, VB.net-, C++- und Webentwickler je eine eigene Variante gibt, die Standard Edition, die Professional Edition, die uber¨ eine zus¨atzliche Integration des SQL-Servers und einige andere Erweiterungen verfugt¨ und die Team System Edition, bei der verschiedene Entwicklerrollen zugeteilt werden k¨onnen.

2.2.3 Aufbau der Projektmappe Die Projektmappendatei hat die Erweiterung .sln und ist ein Textdoku- ment, das die Projektmappe beschreibt. Sie enth¨alt Informationen uber¨ Kon- figurationen, Plattformen und die in der Projektmappe enthaltenen Projek- te. Die .sln-Datei enth¨alt keine benutzerdefinierten Daten wie Haltepunkte, ge¨offnete Dateien, Inhalte des Augabenlistenfensters etc. Diese benutzerde- finierten Daten befinden sich in der .suo-Datei. Da die benutzerdefinierten Daten fur¨ die Entwicklung von NDoc keine Rolle spielen, beschreibt die- ser Abschnitt nur die benutzerunabh¨angigen Daten, die in der .sln-Datei gespeichert sind. Das folgende Beispiel zeigt eine einfache Projektmappe, die Visual Stu- dio 2008 erstellt hat. Die erste Zeile definiert die Dateiversion, gefolgt von einem Kommentar, der den Namen der IDE darstellt. Anschließend folgt eine Auflistung der in der Projektmappe enthaltenen Projekte. Jedes dieser Pro- jekte ist zwischen Projekt und EndProjekt eingeschlossen. Die erste GUID beschreibt die Art des Projekts. In diesem Beispiel ist es ein C#-Projekt. Anschließend wird der Name des Projekts und die Position der Projektdatei angefuhrt.¨ Mit der zweiten GUID wird das Projekt im weiteren Verlauf der Projektmappendatei eindeutig identifiziert. Im globalen Bereich werden die Konfigurationen und die dazugeh¨origen Plattformen zun¨achst projektmap- penweit, und dann fur¨ jedes einzelne Projekt spezifiziert. KAPITEL 2. GRUNDLAGEN 12

Beispiel Projektmappen-Datei Microsoft Visual Studio Solution File, Format Version 10.00 # Visual Studio 2008 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Projekt1", "Projekt1\Projekt1.csproj", "{F82263EE-4B0E-4FBE-89B3-A01FFB2C4105}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU Release|Any CPU = Release|Any CPU EndGlobalSection GlobalSection(ProjectConfigurationPlatforms) = postSolution {F82263EE-4B0E-4FBE-89B3-A01FFB2C4105}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {F82263EE-4B0E-4FBE-89B3-A01FFB2C4105}.Debug|Any CPU.Build.0 = Debug|Any CPU {F82263EE-4B0E-4FBE-89B3-A01FFB2C4105}.Release|Any CPU.ActiveCfg = Release|Any CPU {F82263EE-4B0E-4FBE-89B3-A01FFB2C4105}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE EndGlobalSection EndGlobal

2.2.4 Add-Ins Visual Studio bietet die M¨oglichkeit, uber¨ Makros und Add-Ins erweitert zu werden. Diese Technologien dienen zum Einen zur Automatisierung von Ar- beiten in Visual Studio und zum Anderen fur¨ die Anpassung von Visual Stu- dio. Add-Ins bieten einen besseren Schutz des geistigen Eigentums und eine h¨ohere Arbeitsgeschwindigkeit, da sie direkt in der IDE ausgefuhrt¨ werden. Add-Ins k¨onnen einen sehr großen Funktionsumfang haben: Manipulationen im Quelltexteditor, Bearbeiten der Projektmappe und der Projekte, Anbin- dung externer Werkzeuge uber¨ Menus,¨ Implementierung eigener Befehle, Verwaltung der Konfigurationen, Manipulationen von Toolfenstern und Er- stellung benutzerdefinierter Toolfenster. Genauere Informationen uber¨ die vom Add-In fur¨ Visual Studio von NDoc verwendeten Techniken werden in Abschnitt 5.3 beschrieben. KAPITEL 2. GRUNDLAGEN 13

2.2.5 XML-Kommentare XML-Kommentare sind strukturierte Kommentare im Quelltext eines C#- Programms, einer Komponente etc. Auch von anderen .net-Sprachen als C# werden XML-Kommentare unterstutzt,¨ diese k¨onnen sich aber syntaktisch etwas unterscheiden. Deshalb beziehen sich die in dieser Arbeit beschriebe- nen XML-Kommentare auf solche, die in C#-Quelltexten vorkommen. Alle XML-Kommentare beginnen mit drei Schr¨agstrichen (///). Die ersten bei- den Schr¨agstriche identifizieren einen Kommentar und teilen dem Compiler mit, den restlichen Text der Zeile zu ignorieren. Der dritte Schr¨agstrich signalisiert dem Parser, dass es sich um einen XML-Kommentar handelt. Wenn der Entwickler drei Schr¨agstriche eingibt, uberpr¨ uft¨ Visual Studio, ob die aktuelle Cursorposition im Quelltext vor einer Definition eines identifi- zierbaren Typs oder eines Typelements ist. Nach erfolgreicher Uberpr¨ ufung¨ fugt¨ Visual Studio automatisch je nach Art und Aufbau des Typs leere XML-Kommentare ein, welche der Entwickler mit der Beschreibung befullen¨ kann. Die automatisch eingefugten¨ Tags repr¨asentieren nur eine Untermenge der Kommentare, die vom C#-Compiler unterstutzt¨ werden. Weitere Tags k¨onnen manuell hinzugefugt¨ werden.

Beispiel ///

/// Sets the value of a named config property. ///

/// Name of the property to set. /// A string representation of /// the desired property value. /// Property name matching is /// case-insensitive. public abstract void SetValue(string name, string value);

Wenn Visual Studio verwendet wird, kann in den Projekteinstellungen defi- niert werden, welche XML-Kommentar-Datei fur¨ welche Konfiguration und fur¨ welche Zielplattform im Zuge eines Erstellungsvorganges erstellt werden soll. Wenn der C#-Compiler uber¨ die Kommandozeile aufgerufen wird, muss die Option /doc: angegeben werden. Der C#-Parser extrahiert die XML-Kommentare, fuhrt¨ bei Bedarf For- matierungen durch und fugt¨ sie in eine XML-Datei ein. Fur¨ jedes Projekt in Visual Studio kann eine eigene XML-Datei definiert werden, in die der Par- ser die Kommentare schreibt. Tags, die nicht vordefiniert sind (z.B.: HTML- Tags), werden unver¨andert in die XML-Datei geschrieben. KAPITEL 2. GRUNDLAGEN 14

Tags (Quelle: [Mic, 2008]) < > < > c : Der c -Tag beinhaltet einen einzeiligen Quelltextabschnitt. Dieser Tag wird oft fur¨ Quellcodebeispiele verwendet (z.B. Zuweisun- gen). < > < > code : Der code -Tag beinhaltet einen mehrzeiligen Quelltext- abschnitt. Dieser Tag wird oft fur¨ l¨angere Quellcodebeispiele verwen- det (z.B. wie ein bestimmter Typ verwendet wird oder welche Metho- den in welcher Reihenfolge aufgerufen werden sollen). < > < > example : Der example -Tag beschreibt ein Beispiel. In diesem Tag kann ein beliebiger Text oder aber auch Quellcode sein. Oft wird im Zusammenhang mit dem -Tag der -Tag oder der -Tag verwendet. < > < > exception : Der exeption -Tag beschreibt eine Ausnahme, die in einem Tpyelement auftreten kann. < > < > include : Der include -Tag bindet eine externe XML-Datei, wel- che XML-Kommentare beinhaltet, ein. < > < > list : Der list -Tag definiert eine Aufz¨ahlung oder eine Tabelle. < > < > para : Der para -Tag definiert einen Absatz in einem Kommen- tar. < > < > param : Der param -Tag beschreibt einen Parameter einer Me- thode oder einer Eigenschaft. < > < > paramref : Der paramref -Tag definiert, dass ein Wort ein Pa- rameter ist. < > < > permission : Der permission -Tag beschreibt den Zugriff auf ein Element (public, private, protected, internal, static etc.). < > < > ¨ remarks : Der remarks -Tag beschreibt einen Uberblick uber¨ einen Typ. < > < > returns : Der returns -Tag beschreibt den Ruckgabewert¨ einer Methode. < > < > see : Der see -Tag referenziert auf ein anderes Element. < > < > seealso : Der seealso -Tag referenziert auf ein ¨ahnliches Ele- ment. KAPITEL 2. GRUNDLAGEN 15

< > < > summary : Der summary -Tag beschreibt eine Zusammenfas- sung uber¨ ein Element (Methode, Eigenschaft, Feld etc.). < > < > typeparam : Der typeparam -Tag beschreibt einen Typpara- meter bei einem generischen Typ oder eine generischen Methode. < > < > typeparamref : Der typeparamref -Tag referenziert auf einen generischen Parameter (z.B.: in einem

-Block). < > < > value : Der value -Tag beschreibt den Wert, den eine Eigen- schaft eines Typs darstellt.

Eine genauere Beschreibung der einzelnen Kommentare und Beispiele wer- den in [Schafer, 2002] erl¨autert.

2.3 Generische Typen

Das Paradigma der generischen Programmierung wird in allen Programmier- sprachen, die generische Typen verwenden, unterstutzt.¨ Zwei verschiedene Ans¨atze werden von den Programmiersprachen verwendet. Der eine ist die Anwendung von Templates, wie es z.B. die Programmiersprache C++ um- setzt. Der Typparameter wird zur Erstellungszeit durch den Compiler direkt durch die konkrete Auspr¨agung ersetzt. Der andere Ansatz ist, dass fur¨ alle Objekte derselbe Code verwendet wird und die Eigenschaften des konkreten Typs durch dynamische Bindung verwendet werden. Die generischen Typen, die das .net Framework seit der Version 2.0 un- terstutzt,¨ beschreiten einen Mittelweg, um die Vorteile beider Ans¨atze zu kombinieren: Bei der Verwendung von Wertetypen wird bei der erstmaligen Benutzung ein eigener Codepfad erstellt. Bei der Verwendung von Referenz- typen wird immer der gleiche Code verwendet, da die Repr¨asentation in Form einer Referenz immer gleich ist. Generische Typen sind in der Version 2.0 Teil der Programmiersprache C# und der Common Language Runtime (CLR). Sie erm¨oglichen die Ver- wendung von zur Entwicklungszeit unbekannten Datentypen innerhalb von Schnittstellen, Klassen, Strukturen und Methoden und stellen deren Typ- sicherheit bei der Erstellung durch den Compiler sicher. Besonders eignen sich generische Typen bei der Verwendung in Containern. Vor .net 2.0 konnten entweder typisierte Felder fur¨ die Speicherung von Daten oder nicht typisierte Container verwendet werden. Fur¨ viele Anwen- dungsf¨alle sind Felder zu unflexibel, deshalb gibt es in der .net-Bibliothek verschiedene Container. In nicht typisierten Containern kann nicht sicher- gestellt werden, dass in einem bestimmten Container nur Elemente eines bestimmten Typs gespeichert werden. Ohne generische Typen kann die Typ- sicherheit nur durch die explizite Implementierung eines typisierten Contai- ners gew¨ahrleistet werden. Die beiden Basisklassen CollectionBase und KAPITEL 2. GRUNDLAGEN 16

DictionaryBase unterstutzen¨ den Entwickler bei der Erstellung von typi- sierten Containern. Der Aufwand ist aber unverh¨altnism¨aßig hoch und diese Vorgehensweise fuhrt¨ bei mehreren Implementierungen zu sehr ¨ahnlichem Code und das wiederum fuhrt¨ zu einer sehr schlechten Wartbarkeit. Generische Typen vereinfachen die Typisierung wesentlich. Durch die Verwendung von zur Entwicklungszeit unbekannten Datentypen kann auf relativ einfache Art und Weise generischer Code entwickelt werden. Dazu wird an Stelle eines konkreten Datentyps ein Typparameter angegeben. Die Typparameter werden in spitzen Klammern angegeben und innerhalb der Klasse wie regul¨are Datentypen verwendet. Bei der Initialisierung wird ein Objekt eines generischen Typs mit einem konkreten Datentyp angelegt. Der Compiler kann uberpr¨ ufen,¨ ob alle Referenzen mit dem bei der Initialisierung definierten Datentyp ubereinstimmen.¨

Beispiel: Generischer Typ (Quelle: [Kuhnel,¨ 2006]) class Stack { private readonly int size; private T[] elements; private int pointer = 0;

public Stack(int size) { this.size = size; elements = new T[size]; }

public void Push(T element) { ... }

public T Pop() { ... } }

Beispiel: Verwendung eines generischen Typs (Quelle: [Kuhnel,¨ 2006]) static void Main(string[] args) { try { Stack stack = new Stack(10); stack.Push(123); stack.Push(4711); stack.Push(34); for (int i = stack.Length; i >= 1; i--) { Console.WriteLine(stack.Pop()); KAPITEL 2. GRUNDLAGEN 17

} stack.Pop(); } catch (Exception e) { Console.WriteLine(e.Message); } Console.ReadLine(); }

Die Entwurfsrichtlinien von Microsoft besagen, dass generische Parame- ” tervariablen entweder den Namen T haben oder zumindest mit dem Groß- buchstaben T beginnen sollten (wie in TKey und TValue). Das große T steht f¨ur Typ, wie ein großes I f¨ur Interface (Schnittstelle) steht (zum Beispiel in IComparable).“ [Richter, 2006] Typen k¨onnen auch mehrere Typparameter haben. Ein Beispiel ist die Klasse Dictionary aus dem Namensraum System.Collec- tions.Generic, in der sowohl der Schlussel¨ als auch der zugeordnete Wert uber¨ Typparameter definiert werden k¨onnen. Auch Klassen mit mehr als zwei Typparametern sind m¨oglich. In einigen F¨allen kann es vorkommen, dass gewisse Bedingungen an einen Typparameter gestellt werden mussen,¨ z.B. dass ein Typparameter eine be- stimmte Schnittstelle implementieren muss. Diese Bedingung kann der Ent- wickler mit Hilfe des Schlusselworts¨ “where“ definieren. Solche Bedingungen k¨onnen auch separat fur¨ mehrere verschiedene Typparameter definiert wer- den.

Beispiel: Generischer Typ mit zwei Typparametern (Quelle: [Kuhnel,¨ 2006]) public class SpezializedList where T : IComparable, ICloneable where K : SomeBaseClass { ... }

Methoden k¨onnen ebenfalls generische Typparameter haben. Es ist unab- h¨angig davon, ob die Klasse, in der sich die Methode befindet, einen ge- nerischen Typparameter definiert oder nicht. Wenn eine Methode in einer Klasse, die neben einem Typparameter auch einen generischen Typparame- ter besitzt, sind die beiden Typen unabh¨angig. KAPITEL 2. GRUNDLAGEN 18

Beispiel: Generische Methode in einem generischen Typ (Quelle: [Kuhnel,¨ 2006]) class GenericClass { public void GenericMethod(K obj) { ... } }

2.4 XML

Die Abkurzung¨ XML steht fur¨ eXtensible Markup Language. Sie ist eine Aus- zeichnungssprache zur Darstellung hierarchisch strukturierter Daten, die in Textdateien gespeichert werden. Ein sehr großer Vorteil von XML ist, dass auf Grund der Verwendung von Textdateien XML-Dateien auf allen Platt- formen verarbeitet werden k¨onnen. Sie sind zu einem gewissen Teil auch ohne Werkzeug-Unterstutzung¨ von Menschen lesbar. Ein XML-Dokument, das alle XML-Regeln einh¨alt, heißt wohlgeformt. Das Konzept von XML ist die Trennung von Inhalt und Struktur. Der Inhalt steht im XML-Code, die Struktur in der Document Type Definition (DTD) oder im XML-Schema. DTD und Schema definieren den Aufbau von XML-Dokumenten. Ein kon- kretes XML-Dokument kann eine Instanz eines Schemas oder einer DTD sein. Die Elemente in einer XML-Datei sind durch ein Starttag und ein Endtag gekennzeichnet. Tags sind in Spitzklammern gefasste Bezeichner. Fur¨ leere Tags gibt es eine verkurzte¨ Schreibweise, bei der im Starttag am Ende ein Schr¨agstrich das Ende des Tag definiert und so auf den Endtag verzichtet werden kann. Tags k¨onnen mit Attributen mit zus¨atzlichen Infor- mationen versehen sein. Zu Beginn haben XML-Dokumente einen Header, der die Version und die Textkodierung definiert. KAPITEL 2. GRUNDLAGEN 19

Beispiel: XML-Datei

(Quelle: [Hauser, 2006])

³ ³ ³

³ ³ ³ Tobias

Hauser ³

³ ³ ³ Erik

Franz ³

2.4.1 XML-Transformationen mit XSLT XSLT steht fur¨ eXtensible Stylesheet Language Transformation und dient zur Umwandlung von XML-Dokumenten und baut auf XPath auf. XPath ist eine Anfragesprache, mit der Teile eines XML-Dokuments adressiert werden k¨onnen [XPa, 2008]. XSLT definiert Transformationsregeln. Die von NDoc verarbeiteten Daten werden, wie in Abschnitt 3.2.4 am Beispiel des MSDN- Dokumentierers beschrieben, zun¨achst in eine XML-Datei geschrieben und anschließend mit XLST weiterverarbeitet. Dabei baut XSLT auf der logi- schen Baumstruktur eines XML-Dokuments auf und dient zur Definition von Umwandlungsregeln.

Funktionsweise von XSLT Abbildung 2.2 zeigt schematisch und stark vereinfacht die Funktionswei- se von XSL-Transformationen. Dem XSLT-Prozessor werden die Daten in Form einer XML-Datei und die Regeln fur¨ die Umwandlungen in Form ei- ner XSL-Stylesheet-Datei ubergeben¨ [Mangano, 2006]. Der Prozessor fuhrt¨ die Transformationen, die in der XSL-Stylesheet-Datei definiert sind, auf die Daten der XML-Datei aus. Das Ergebnis ist abh¨angig von der Transformati- onsdefinition. Mit dieser Technologie k¨onnen z.B. automatisiert Java-Beans oder HTML-Dateien erstellt werden. Ein XSL-Stylesheet besteht aus 2 Tei- len: Muster und Schablonen. Muster dienen zur Identifizierung von Knoten in der XML-Datei und basieren auf XPath. Schablonen definieren die Trans- formation selbst und bestehen aus Erg¨anzungsregeln. Das Beispiel in Abbildung 2.3 zeigt, wie aus einem XML-Dokument, welches Personendaten enth¨alt, und einem XLS-Stylesheet eine HTML-Datei KAPITEL 2. GRUNDLAGEN 20

Abbildung 2.2: Funktionsweise XSLT

generiert wird. Dieses Beispiel verdeutlicht, dass der Inhalt fur¨ das Ergebnis aus der XML-Datei und die Transformation, die den Aufbau der HTML- Datei bestimmt und somit das Aussehen und die Struktur, aus der XSLT- Datei kommt. KAPITEL 2. GRUNDLAGEN 21

Abbildung 2.3: XSLT-Beispiel Kapitel 3

Analyse der Ist-Situation von NDoc

Im folgenden Kapitel wird die Ist-Situation analysiert. Die Entwicklung der Open-Source-Anwendung NDoc wird beschrieben. Es wird erl¨autert, in wel- chem Stadium die Entwicklung von NDoc abgebrochen, wie NDoc aufgebaut wurde, beziehungsweise welchen Ablauf ein Dokumentierdurchgang hat. Des Weiteren wird ein Uberblick¨ uber¨ bestehende Alternativen zu NDoc gege- ben.

3.1 Entwicklung von NDoc

NDoc ist ein Open Source-Projekt, welches unter der GNU General Public License (GPL) steht. Das Projekt wird auf Sourceforge [Kackman et al., 2005] (siehe Abschnitt 3.1) gehostet, wurde im September 2001 registriert und hat 12 Mitglieder. Federfuhrend¨ an der Entwicklung war Kevin Downs. Im J¨anner 2005 wurde die letzte Version (1.3.1) ver¨offentlicht. Danach wurde das Projekt nicht weitergefuhrt.¨ Kevin Downs, der bereits an der Version 2 von NDoc arbeitete, unterbrach seine Arbeit an NDoc und schrieb in einem offenen E-Mail (siehe Anhang A) im Juli 2006, dass er von der Community zu wenig finanzielle und Entwicklungsunterstutzung¨ bekommen und Micro- soft das Projekt Sandcastle (siehe Abschnitt 3.3) ver¨offentlicht hat. Der eigentliche Stein des Anstoßes war eine automatisierte Mailbombenattacke auf seine beiden ¨offentlichen E-Mailadressen.

Erweiterungen von Richard Jonas Richard Jonas hat die Version 1.3.1 von NDoc in Form einer einfachen Un- terstutzung¨ von .net Framework 2.0 etwas erweitert. Die letzte Version von Richard Jonas ist NDoc 1.3.1v16. Diese Version unterstutzt¨ .net Framework 2.0-Assemblies und generische Typen. Bei der Anzeige von Membervariablen

22 KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 23 gibt es Probleme und es mussen¨ alle Assemblies einer Projektmappe und de- ren XML-Kommentardateien einzeln in das NDoc Projekt geladen werden. Des Weiteren gibt es keine durchgehend funktionierende Unterstutzung¨ fur¨ die Verlinkung auf die aktuelle Version der online MSDN-Bibliothek. Der Quellcode der Version 1.3.1v16 ist die Basis fur¨ die Erweiterungen, die im Zuge dieser Arbeit implementiert wurden.

Sourceforge Sourceforge [Kackman et al., 2005] heißt w¨ortlich ubersetzt¨ so viel wie Quellcodeschmiede“ und ist ein Software-Entwicklungsmanagementsystem. ” Entwickelt und vertrieben wird die Software Sourceforge von der Firma Sour- ceForge, Inc. Zun¨achst war Sourceforge eine freie Software. Mittlerweile wird die Software aber kommerziell vertrieben. Die Webseite SourceForge.net“ ist ein von der Firma SourceForge, Inc. ” gehostetes Webportal, das die SourceForge-Software nutzt. Auf diesem Por- tal wird eine große Anzahl an Open-Source-Projekten betreut. NDoc und einige Alternativen zu NDoc wurden bzw. werden auf dieser Webseite betreut und entwickelt.

3.2 Bestehendes Design von NDoc

3.2.1 Aufbau der Projektmappe Die Projektmappe NDoc enth¨alt 14 relevante Projekte.

Visual Studio Das Projekt Visual Studio ist zust¨andig fur¨ das Laden von Visual Studio Projektmappen in NDoc. Dazu parst es die .sln-Dateien und ermittelt die enthaltenen Projekte und die enthaltenen Konfigurationen. Zu jedem Pro- jekt wird die dazugeh¨orende .csproj-Datei geparst und die Positionen der Assemblies und der dazugeh¨orenden XML-Kommentar-Datei im Dateisys- tem ermittelt. Die Ermittlung der Ausgabedateien erfolgt in Abh¨angigkeit der jeweiligen Konfiguration, da es fur¨ ein Projekt mehrere Ausgabedateien geben kann (z.B. die Debug und die Release Version). Es werden Projekt- mappendateien von Visual Studio .net 2002 und Visual Studio .net 2003 unterstutzt.¨

GUI Das Projekt GUI realisiert die grafische Benutzeroberfl¨ache. Die Benutzero- berfl¨ache enth¨alt Bedienelemente fur¨ das Laden von Projektmappen, Assem- blies und bereits vorhandene NDoc-Projekte. Optionen fur¨ die Erstellung von Dokumentationen werden angezeigt und k¨onnen manipuliert werden. KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 24

W¨ahrend der Erstellung, die abh¨angig vom Umfang der Projekte und der Leistung des verwendeten Computers einige Minuten dauern kann und im Hintergrund abl¨auft, wird der aktuelle Status in einer Fortschrittsanzeige vi- sualisiert. Die jeweilige Bearbeitungsphase und sonstige Informationen uber¨ die Erstellung werden in einem Textfenster ausgegeben.

Core Im Projekt Core werden die Metadaten der Assemblies ermittelt und die Schnittstellen der Dokumentierer defininiert. Alle Assemblies, deren Daten in die Dokumentation einfließen sollen, werden mit Hilfe von Reflection ana- lysiert. Es werden alle in den Assemblies vorkommenden Typen und deren Typmitglieder durchiteriert und deren Metainformationen extrahiert. Fur¨ die mit Hilfe von Reflection gewonnenen Metainformationen werden abstrakte Datentypen, Zwischenspeicher und Routinen zu deren Verwen- dung bereitgestellt. Diverse in NDoc global ben¨otigten Klassen und Tools sind ebenfalls im Projekt Core angesiedelt. Fur¨ die einzelnen Dokumentierer werden im Projekt Core Schnittstellen und abstrakte Basisklassen fur¨ die einheitliche Verwendung jedes einzelnen Dokumentierers definiert. Darauf aufbauend kann fur¨ jeden Dokumentierer die individuelle Implementierung entwickelt werden (siehe Abbildung 3.1).

Console Das Projekt Console dient zum Aufruf von NDoc uber¨ die Kommandozeile oder in Batchverarbeitungen. Alle relevanten Parameter k¨onnen uber¨ Kom- mandozeilenparameter angegeben werden.

ExtendedUI Das Projekt ExtendedUI stellt einige systemnahe Operationen zur Verfu-¨ gung, die intern vom Projekt Core verwendet werden.

UsersGuide Das Projekt UsersGuide stellt den Anwendern von NDoc ein Benutzerhand- buch zur Verfugung.¨

Dokumentierer Ausgehend von den Schnittstellen und Basisklassendefinitionen im Projekt Core gibt es einige konkrete Dokumentierer-Implementierungen (siehe Ab- bildung 3.1). KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 25

Abbildung 3.1: UML-Klassendiagramm der Dokumentierer-Hierarchie KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 26

Intellisense Der Dokumentierer Intellisense erzeugt fur¨ jedes Assembly eine Intellisense- XML-Datei. Diese Dateien liefern die Informationen fur¨ die automatische Vervollst¨andigung bei der Bearbeitung von Quellcode in Visual Studio. Da- durch wird einem Entwickler die Verwendung einer eingebundenen Biblio- thek erleichtert.

Javadoc Der Dokumentierer Javadoc erstellt eine HTML-Dokumentation, wie sie aus der Javawelt von Javadoc bekannt ist.

Latex Der Dokumentierer Latex erstellt eine .tex-Datei, in der die gesamte Do- kumentation enthalten ist. Ein optional installierter LaTeX-Compiler wird von NDoc angestoßen, aus der .tex-Datei eine .dvi-Datei zu kompilieren.

LinearHtml Der Dokumentierer LinearHtml erstellt eine Dokumentation in Form einer einzigen HTML-Datei. Typen und Namensr¨aume werden in Form von re- lativen Links auf der Seite verknupft.¨ Diese HTML-Datei kann z.B. fur¨ die Vorstellung einer kleinen Bibliothek auf einer Entwicklerhomepage verwen- det werden.

Msdn Der Dokumentierer Msdn erstellt eine Dokumentation in der Form der MSDN- Bibliothek, wie sie bei ¨alteren Visual Studio Versionen verwendet wurde. Die Ausgabedatei ist eine kompilierte HTML-Datei (.chm). Fur¨ die Erstellung der Datei wird das externe Tool Microsoft HTML Help Compiler, welches explizit installiert werden muss, verwendet.

Msdn2 Der Dokumentierer Msdn2 erstellt eine Dokumentation in der Form der moderneren MSDN-Bibliothek, wie sie ab Visual Studio .net 2003 verwendet wird. Die Ausgabedatei ist eine kompilierte HTML-Datei (.chm). Fur¨ die Erstellung der Datei wird das externe Tool Microsoft HTML Help Compiler, welches explizit installiert werden muss, verwendet. KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 27

NativeHtmlHelp2 Der Dokumentierer NativeHtmlHelp2 wird in der NDoc Applikation unter dem Namen VS.NET 2003“ aufgelistet und erstellt eine Dokumentation im ” Format Microsoft Help Storage File“, welche die Dateiendung .HxS hat. ” NativeHtmlHelp2 verwendet fur¨ die Erstellung Microsoft Help 2.0 SDK“, ” welche explizit installiert werden muss.

Xml Der Dokumentierer Xml erstellt eine XML-Datei mit der Metainformation der verarbeiteten Assemblies. Diese XML-Datei kann fur¨ Debuggingzwecke oder als Eingabe fur¨ eine andere Applikation genutzt werden.

3.2.2 NDoc-Projekte NDoc unterstutzt¨ das Abspeichern und Laden von Dokumentationsprojek- ten. Diese gespeicherten Projekte haben die Dateierweiterung .ndoc und basieren auf XML. Gegliedert ist eine .ndoc-Datei in drei Bereiche. Eine Schemaversionsnummer zu Beginn des Dokuments definiert die Version des zu Grunde liegenden Formats.

Drei Bereiche einer NDoc-Projektdatei

Assemblies Der Bereich Assemblies (assemblies) speichert die von NDoc zu dokumentierenden Assemblies und die dazugeh¨origen XML-Doku- mentation-Dateien und deren Position im Dateisystem.

Namensr¨aume Der Bereich Namensr¨aume (namespaces)isteinop- tionaler Bereich, der Namensraumbeschreibungen speichert, sofern welche im Projekt definiert sind.

Dokumentierer Der Bereich Dokumentierer speichert die verwende- ten Dokumentierer und ihre Einstellungen, wie z.B. Ausgabeverzeichnis, Ausgabedatei, Uberschriften¨ und sonstige Attribute.

Beispiel einer .ndoc-Datei

KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 28

Beschreibung des Namensraum ClassLibrary1 in Prosa.

Sofern eine gesamte Projektmappe uber¨ die Projektmappendatei (.sln)ge- laden wurde, ist der voreingestellte Dateiname eines NDoc-Dokumentations- Projekts das Verzeichnis und der Name der Projektmappe. Dies kann aber im Speichern unter“ Dialog ge¨andert werden. ” 3.2.3 Laden von Assemblies Assemblies k¨onnen uber¨ zwei verschiedene Arten geladen werden: Zum Einen uber¨ das Offnen¨ einer Projektmappe und die darin enthaltenen Projekte, de- ren Ausgabedateien in Abh¨angigkeit von der Konfiguration ermittelt werden und zum Anderen uber¨ das einzelne Offnen¨ von .dll-bzw..exe-Dateien und den dazugeh¨orenden .xml-Kommentardateien.

3.2.4 MSDN-Dokumentierer Im Zuge dieser Arbeit wird der MSDN-Dokumentierer erweitert und auf aktuelle Versionen des .net Frameworks und der MSDN-Bibliothek ange- passt. Deshalb wird hier dieser Dokumentierer genauer beschrieben. Wie alle anderen Dokumentierer wird auch der MSDN-Dokumentierer als eige- ner Thread im Hintergrund gestartet. Der Ablauf im Erstellungsprozess des MSDN-Dokumentierers wird in sieben Phasen eingeteilt.

Initialisierung In der Initialisierungsphase wird zun¨achst definiert, welcher Zeichensatz bei der Ausgabe in Dateien verwendet wird. Der so genannte Workspace“ b e- ” KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 29 schreibt die Arbeits- und Ausgabeverzeichnisse. Er wird erstellt oder bei Bedarf von Resten fruherer¨ Durchl¨aufe gereinigt. Eingebundene Ressourcen wie Bilder und Stylesheet-Dateien werden extrahiert und in den Workspace geschrieben. Optional ben¨otigte zus¨atzliche Dateien werden ebenfalls in den Workspace kopiert.

Zusammenfuhrung¨ der XML-Dokumentation Eine tempor¨are Datei im XML-Format wird mittels Reflection und den In- formationen der XML-Kommentare erstellt. Nach der Erstellung werden Korrekturen bei den generischen URLs durchgefuhrt.¨ Die XML-Datei ist die Grundlage fur¨ die gesamte weitere Verarbeitung.

Generierung der Dateizuordnung Ein Container mit allen sp¨ater ben¨otigten Dateinamen, der HTML-Dateien der einzelnen Typen und Elemente, wird auf Basis der zuvor erstellten XML- Datei befullt.¨

Laden der XSLT-Dateien Die eingebundenen XSL-Transformations-Dateien werden extrahiert und fur¨ die weitere Verarbeitung im Speicher gehalten.

Erstellung der HTML-Seiten Die zuvor definierten HTML-Dateien werden mit Hilfe von XSL-Transfor- mationen erzeugt und in den Workspace geschrieben. Drei Dateien fur¨ die Erstellung der kompilierten HTML-Hilfe-Datei werden ebenfalls erstellt (In- haltsverzeichnis = .hhc-Datei, Auflistung der enthaltenen Dateien .hhp und der Index = .hhk-Datei).

Erstellung der HTML-Inhalts-Datei Weitere optional ben¨otigte Ressourcen werden extrahiert und die beiden Dateien index.html und contents.html werden erstellt. Die Datei in- dex.html definiert die Rahmen fur¨ das Betrachten der Hilfe und die Datei contents.html repr¨asentiert die Navigationsleiste auf der linken Seite des fertigen Hilfedokuments.

Kompilieren der HTML-Hilfe-Datei Mit Hilfe des Microsoft HTML-Help-Compilers, der als externes Programm aufgerufen wird, wird die kompilierte HTML-Datei (.chm) erstellt. Am Ende der Verarbeitung wird der Workspace gereinigt, indem nicht mehr ben¨otigte Dateien gel¨oscht werden. KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 30

3.3 Alternativen zu NDoc

Es gibt einige kommerzielle und nicht kommerzielle Alternativen zu NDoc, die sich sehr stark im Funktionsumfang, in der Bedienung und im Entwick- lungsstadium unterscheiden.

Sandcastle URL: http://www.codeplex.com/Sandcastle

Lizenz: Microsoft Public License (Ms-PL)

Aktuelle Version: Sandcastle January 2008 Release

Entwickler: Anand Raman

Firma: Microsoft

Beschreibung: Sandcastle ist eine Sammlung von Kommandozeilen Werk- zeugen, Konfigurationsdateien, Erstellungskomponenten und XSL-Transfor- mations-Dateien, die gemeinsam aus einer XML-basierten Dokumentation eine Dokumentation im MSDN-Stil erzeugen. Sandcastle funktioniert mit und ohne eigene Kommentare und unterstutzt¨ generische Typen und das .net Framework 2.0. Die zwei Hauptkomponenten sind MrefBuilder und Build- Assembler. Der MrefBuilder extrahiert mit Hilfe von Reflection die Meta- daten und der Build-Assembler fuhrt¨ die Syntaxgenerierung, Transformatio- nen etc. durch. Sandcastle wird intern fur¨ .net Framework-Dokumentationen verwendet.

Sandcastle Help File Builder URL: http://codeplex.com/SHFB

Lizenz: Microsoft Public License (Ms-PL)

Aktuelle Version: 1.6.0.4 Production

Beschreibung: Sandcastle Help File Builder kurz SHFB ist eine von NDoc inspirierte, grafische Benutzeroberfl¨ache fur¨ Sandcastle, das nur uber¨ eine Kommandozeilen-Schnittstelle verfugt.¨ Projektmappen und Assemblies k¨onnen ge¨offnet, Einstellungen vorgenommen und der Erstellungsprozess an Sandcastle weitergegeben werden. KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 31

NDoc 2.0 Alpha URL: http://www.kynosarges.de/NDoc.html

Lizenz: GNU General Public License (GPL)

Aktuelle Version: Alpha 3

Beschreibung: NDoc 2.0 ist die Weiterentwicklung von NDoc von Don Kackman und Kevin Downs. Die Entwicklung wurde im Juni 2006 abge- brochen. Die letzte Version ist die Alpha 3 Version, von der offiziell kein Sourcecode verfugbar¨ ist.

NDoc 2005 URL: http://sourceforge.net/projects/ndoc05/

Lizenz: GNU General Public License (GPL)

Aktuelle Version: Beta Version (April 2006)

Beschreibung: NDoc 2005 ist eine Abspaltung von NDoc. Es enth¨alt eine Unterstutzung¨ von Visual Studio 2005 und .net 2.0. Dieses Projekt kam nie weiter als bis zur Beta Version und seit April 2006 wurden keine Neuerungen mehr get¨atigt.

NDoc 3 URL: http://sourceforge.net/projects/ndoc3/ alternative URL: http://ndoc3.blogspot.com/

Lizenz: GNU General Public License (GPL)

Aktuelle Version: Noch keine Version downloadbar. Pre Alpha Status

Beschreibung: NDoc 3 ist eine Erweiterung von NDoc bis einschließlich C# 3.0. Der Autor hat bereits eine Alpha Version angekundigt.¨

Doxygen URL: http://www.stack.nl/˜dimitri/doxygen

Lizenz: GNU General Public License (GPL) KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 32

Aktuelle Version: 1.5.6

Entwickler: Dimitri van Heesch

Beschreibung: Doxygen ist ein Dokumentationssystem fur¨ C++, C, Ja- va, Objective-C, Python, IDL, Fortran, VHDL, PHP, C# und teilweise D. Im Vergleich zu ¨ahnlichen Produkten verwendet Doxygen kein Reflection, sondern parst den Quellcode. Verweise zu .net-Systemklassen werden nicht unterstutzt.¨

Doc-to-Help 2008 URL: http://www.componentone.com

Lizenz: Kommerziell

Aktuelle Version: 2008

Firma: ComponentOne

Beschreibung: Doc-to-Help ist ein Tool, mit dem es m¨oglich ist, verschie- denste Dokumentationen zu erstellen. Fur¨ die Erstellung von Dokumenta- tionen von .net-Projekten wird im Hintergrund Sandcastle verwendet.

Document! X 2008 URL: http://www.innovasys.com/products/documentx.aspx

Lizenz: Kommerziell

Aktuelle Version: 2008

Firma: Innovasys

Beschreibung: Document! X ist eine Applikation mit der man Doku- mentationen erstellen kann. Unterstutzt¨ werden .net, COM, VB 6.0, Access, XSD, SQL etc.

Nevron .NET Vision URL: http://www.nevron.com/Products.Nevron.NETVision.Overview.as- px KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 33

Lizenz: Kommerziell

Aktuelle Version: Q4 2007

Firma: Nevron

Beschreibung: Nevron .NET Vision ist ein Werkzeug, das Abl¨aufe, Schnitt- stellen, Daten etc. aus .net-Anwendungen und -Assemblies extrahiert und visualisiert.

TeeGofer v2 URL: http://www.steema.com

Lizenz: Kommerziell

Aktuelle Version: 2

Firma: Steema

Beschreibung: TeeGofer ist ein Tool, das NDoc sehr ¨ahnlich ist und mittels Reflection und der vom Compiler erstellten XML-Datei eine Doku- mentation erstellt.

NDocProc URL: http://www.lshift.net/˜tonyg/ndocproc/doc/index.html

Lizenz: Open-Source

Aktuelle Version: 2008-01-21

Entwickler: Tony Garnock-Jones

Firma: LShift Ltd.

Beschreibung: NDocProc ist ein Kommandozeilenwerkzeug, welches auf Basis von .net-Assemblies und XML-Dokumentationen HTML und XML basierende Dokumentationen erstellt.

DocMounter URL: http://www.10tec.com/home/products/devtools/docmounter/index.- aspx KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 34

Lizenz: GNU General Public License Version 2 (GPL2)

Aktuelle Version: 1.01

Firma: 10Tec

Beschreibung: DocMounter basiert zum Teil auf NDoc. Einige Module sind weiterentwickelt worden. Generische Typen werden weitgehend nicht unterstutzt.¨

VSdocman URL: http://www.helixoft.com/vsdocman/overview.html

Lizenz: Kommerziell

Aktuelle Version: 3.5

Firma: Helixoft

Beschreibung: VSdocman ist eine kommerzielle Quellcodedokumentati- onsapplikation, die NDoc sehr ¨ahnlich ist.

TwinText URL: http://www.ptlogica.com/TwinText/overview.htm

Lizenz: Kommerziell

Aktuelle Version: 2008

Firma: PTLogica

Beschreibung: TwinText ist ein kommerzielles Dokumentationswerk- zeug, welches fur¨ sehr viele verschiedene Sprachen/Umgebungen verwen- det werden kann: Ada, ASP, Assembler, ActionScript, Basic, C, C++, C#, Cobol, ColdFusion, Delphi, Fortran, IDL, Java, JavaScript, Mathematica, Pascal, Perl, PHP, Python, Ruby, SQL, Synergy/DBL, Tcl/Tk, VBA, VB- Script, Verilog, VHDL, Visual Basic und VB .NET. In den Quelldateien mussen¨ eigene Bereiche definiert werden.

Doc-O-Matic URL: http://www.doc-o-matic.com/ KAPITEL 3. ANALYSE DER IST-SITUATION VON NDOC 35

Lizenz: Kommerziell

Aktuelle Version: 6.2

Firma: toolsfactory software inc.

Beschreibung: Doc-O-Matic ist ein Dokumentationswerkzeug, welches fur¨ Quellcodedokumentationen, Onlinehilfen und Benutzerhandbucher¨ ver- wendet werden kann und eine Vielzahl an Programmiersprachen unterstutzt:¨ C/C++, C++/CLI, C#, Delphi, Java, IDL, VB.NET, JavaScript, MAT- LAB, ASP.NET und JSP. Kapitel 4

Anforderungen an die Erweiterungen von NDoc

Der folgende Abschnitt beinhaltet eine systematische und vollst¨andige Auf- listung aller Anforderungen an die Erweiterungen von NDoc. Die ersten drei Abschnitte beschreiben die drei zu implementierenden Anforderungen. Die letzten beiden Abschnitte beschreiben die Anforderungen, die in den ersten drei Abschnitten berucksichtigt¨ werden sollen.

4.1 Umgang mit aktuellen Visual Studio-Dateien

Es gibt mehrere M¨oglichkeiten, Assemblies in NDoc zu laden. Die bequems- te Methode ist das Laden einer Visual Studio-Projektmappe. Beim Laden einer Projektmappe werden alle sich in der Projektmappe befindenden Pro- jekte erfasst. Des Weiteren werden alle definierten Konfigurationen ausge- lesen. Der Benutzer wird in einem kleinen Dialogfenster (siehe Abschnitt 4.1) gefragt, welche Konfiguration er gerne verwenden m¨ochte, da abh¨angig von der Konfiguration verschiedene Ausgabedateien von Visual Studio bzw. dem C#-Compiler erstellt werden. Abh¨angig von der vom Benutzer gew¨ahl- ten Konfiguration wird das entsprechende Assembly und falls vorhanden, die entprechende XML-Dokumentationsdatei geladen. In Visual Studio gibt es in Bezug auf die Speicherung der Metadaten der Projektmappe und der Projekte ab der Version 2005 einige Anderungen.¨ Die beiden markantesten Anderungen¨ sind ein anderer Aufbau der Projekt- dateien und ein wesentlich gr¨oßerer Einfluss der Zielplattformen. Bei der Ausgangsversion von NDoc wurde der Benutzer entsprechend der Art der Speicherung von Visual Studio .net 2002 und Visual Studio .net 2003 nur nach der Konfiguration gefragt, da diese die einzige Unterscheidungsm¨oglich- keit zwischen verschiedenen Ubersetzungen¨ war. Seit der Version 2005 kann es fur¨ eine Konfiguration noch verschiedene Zielplattformen geben. NDoc soll Projektmappendateien und Projektdateien von Visual Studio

36 KAPITEL 4. ANFORDERUNGEN AN DIE ERWEITERUNGEN 37

Abbildung 4.1: Dialogfenster zur Auswahl der Konfigurations- und Platt- formkombination

2005 und Visual Studio 2008 ¨offnen k¨onnen. Des Weiteren soll NDoc mit der neuen Rolle der einzelnen Plattformen in den Projekten umgehen k¨onnen und dem Benutzer eine sinnvolle Auswahlm¨oglichkeit der entsprechenden Konfigurations- und Plattformkombinationen erm¨oglichen.

4.2 Umgang mit generischen Typen

Der fur¨ NDoc relevanteste Unterschied von .net Framework 2.0 bzw. C# 2.0 zu seinen Vorg¨angern ist die M¨oglichkeit, generische Typen zu verwen- den. Dadurch bekommen Typendefinitionen, Methodenrumpfe,¨ Eigenschaf- ten, Variablen etc. bei generischer Verwendung ein v¨ollig anderes Aussehen, das von NDoc berucksichtigt¨ werden muss. Im Zuge dieser Arbeit wird der MSDN-Dokumentierer bezuglich¨ der An- forderungen von .net 2.0 erweitert und den folgenden Anforderungen ange- passt. In der ubersetzten¨ Dokumentation in Form einer kompilierten HTML- Datei (.chm) sollen alle Elemente, die entsprechend der Syntax von C# 2.0 generische Typen unterstutzen,¨ entsprechend angezeigt werden. Bei Definitionen, in denen eine konkrete Auspr¨agung verwendet wird, sollen die Typen, die bei der Programmubersetzung¨ eingesetzt werden, auch angezeigt werden.

Beispiel public IDictionary>> dict1; Die Dokumentation enth¨alt Verweise auf die verwendeten Typen der .net-- Klassenbibliothek. NDoc soll Verweise auf generische Typen der .net-Klas- KAPITEL 4. ANFORDERUNGEN AN DIE ERWEITERUNGEN 38 senbibliothek auf einer lokal installierten MSDN-Bibliotheks-Version, als auch auf die online MSDN-Bibliotheks-Version von Microsoft unterstutzen.¨

4.3 Integration in Visual Studio 2008

Viele moderne Werkzeuge, die Entwickler bei der Erstellung des Quelltexts, Refaktorierung, Dokumentation, Visualisierung, Anpassung auf spezielle Ge- gebenheiten etc. helfen, integrieren sich in eine Entwicklungsumgebung. Zwei der am h¨aufigst verwendeten Entwicklungsumgebungen, fur¨ die es eine Viel- zahl an Add-Ins gibt, sind Eclipse in der Java-Welt und Visual Studio in der Microsoft-.net-Welt. NDoc soll dahingehend integriert werden, dass es erm¨oglicht wird, uber¨ das Menu¨ in Visual Studio 2008 NDoc aufzurufen. Die NDoc-relevanten- Daten der aktuell geladenen Projektmappe und der darin enthaltenen Pro- jekte sollen an die gewohnte NDoc-Oberfl¨ache weitergegeben werden. Be- zug nehmend auf die verfugbaren¨ Konfigurationen und Plattformen, soll es m¨oglich sein, dass zum Einen die aktuelle projektmappenweite Konfigurati- on und Plattform verwendet wird und zum Anderen das Dialogfenster, wie es vom Laden der Projektmappendateien (siehe Abschnitt 4.1) bekannt ist, fur¨ die Auswahl der Konfigurations- und Plattformkombination erscheint. Durch diese Integration soll es dem C#-Entwickler m¨oglich sein, die Dokumentation einer Projektmappe direkt aus Visual Studio 2008 zu star- ten und anschließend die Dokumentationserstellung mittels der gewohnten NDoc-Benutzeroberfl¨ache anzustoßen.

4.4 Kompatibilit¨at

Alle vorgenommenen Erweiterungen an NDoc sollen die bestehende Funktio- nalit¨at nicht beeintr¨achtigen. Es soll nach wie vor m¨oglich sein, Projektmap- pen von Visual Studio .net 2002 und Visual Studio .net 2003 zu importieren. Assemblies, die fur¨ .net 1.0 und 1.1 ubersetzt¨ wurden, sollen nach wie vor zu einem NDoc-Projekt hinzugefugt¨ werden k¨onnen. Um Fehlerquellen m¨oglichst gering zu halten, soll bei der Implementie- rung darauf geachtet werden, m¨oglichst viel Quelltext wieder zu verwenden. Gespeicherte NDoc-Projekte in Form von .ndoc-Dateien sollen weiterhin in der Formatversion 1.3 gespeichert und geladen werden. Dadurch ist es m¨oglich, ¨altere gespeicherte Projekte in der erweiterten Version von NDoc zu ¨offnen und zu verwenden. KAPITEL 4. ANFORDERUNGEN AN DIE ERWEITERUNGEN 39

4.5 Erweiterbarkeit

4.5.1 Anderungen¨ von Projekten und Projektmappen Bei der Adaption des Projekts VisualStudio der Projektmappe NDoc soll schon im Design berucksichtigt¨ werden, dass zu einem sp¨ateren Zeitpunkt weitere Projektmappen- und Projektdateiversionen gelesen werden k¨onnen. Bei zukunftigen¨ Versionen von Visual Studio besteht die M¨oglichkeit, dass das Dateiformat ver¨andert wird. Durch die lose Kopplung ist eine sehr gute Erweiterbarkeit gegeben. Außerhalb des Projekts Visual Studio soll nichts ver¨andert werden mussen.¨ Die Logik fur¨ verschiedene Dateiversionen soll gekapselt und in ein objek- torientiertes Design einfließen, sodass bei Erweiterungen nur ein minimaler Anteil des bestehenden Quelltexts ver¨andert werden muss. Ein m¨oglichst hoher Grad an Wiederverwendbarkeit und Integrierbarkeit verringert auch die Fehleranf¨alligkeit nach Erweiterungen. Nicht berucksichtigt¨ werden k¨onnen eventuelle zukunftige¨ Metainfor- mationen, die fur¨ das Auslesen der Projektmappeninformationen und der Projektinformationen relevant sind. Je nach Art solcher Metainformatio- nen k¨onnen sie in der Klasse, die die Logik zum Auslesen einer zukunftigen¨ Version kapselt, intern verarbeitet werden. Sollten diese Metainformationen außerhalb der Klasse von Relevanz sein, musste¨ die Schnittstelle dahinge- hend ver¨andert werden, die Metainformationen nach außen zu tragen. Dies h¨atte zur Folge, dass alle Klassen, die diese Schnittstelle implementieren, angepasst werden mussen¨ und der Quelltext, der mit dieser Schnittstelle arbeitet, auch erweitert werden muss. Ein Beispiel w¨are ein weiteres Dialog- fenster, das dem Benutzer eine zus¨atzliche Auswahl erm¨oglicht.

4.5.2 Syntaktische Anderungen¨ Syntaktische Erweiterungen, die auch Schnittstellen von Methoden, Eigen- schaften, Delegationen und alle anderen fur¨ NDoc-relevanten Quelltextbe- reiche betreffen, sind von zukunftigen¨ Versionen der Sprache C# bis dato noch nicht absehbar. Da das Ausmaß solcher Erweiterungen aus der jetzigen Sicht nicht absch¨atzbar ist, w¨aren konkrete Uberlegungen¨ in diese Richtung rein spekulativ. Bei m¨oglichen zukunftigen¨ Erweiterungen mussen¨ konkrete Anpassungen in der ReflectionEngine fur¨ das Zwischenspeichern der Informationen in der tempor¨aren XML-Datei vorgenommen werden und die Dokumentierer, die diese Erweiterungen unterstutzen¨ sollen, mussen¨ dann dementsprechend mit diesen Informationen aus der XML-Datei umgehen k¨onnen, um eine korrekte Dokumentation im jeweiligen Format erstellen zu k¨onnen. Viele Anderungen¨ in der Syntax von C# haben keine Auswirkungen auf NDoc, da sie den Quellcode innerhalb von Klassenmitgliedern betreffen. Bei- spiele sind viele syntaktische Neuerungen der Programmiersprache C# 3.0. KAPITEL 4. ANFORDERUNGEN AN DIE ERWEITERUNGEN 40

Alle Abfragen auf Basis von LINQ, lokale Variablendefinitionen mit Hilfe des Schusselworts¨ var oder die neue Syntax von Eigenschaften. All diese Erweiterungen sind lokale Erweiterungen, die fur¨ die CLR in der Version 2.0 ubersetzt¨ werden und somit keine Anderungen¨ bei der Ermittlung von De- finitionen von Klassen, Methoden, Eigenschaften, Delegationen etc, mittels Reflectionnachsichziehen.

4.5.3 Sonstige Erweiterungen Beim Auslesen von Projektmappen unterstutzt¨ NDoc nur .net-Projekte der Programmiersprache C#. Es soll m¨oglich sein, auch in Zukunft das NDoc- Projekt VisualStudio dahingehend zu ¨andern, dass andere Projekte aus- gelesen werden k¨onnen. M¨ogliche andere Projekte sind Projekte der Pro- grammiersprachen Visual Basic.net oder managed C++. Diese Anderungen¨ sollen, ohne die Struktur ¨andern zu mussen,¨ hinzufugbar¨ sein. Duch den bereits in der Basisversion vorhandenen modularen Aufbau von Dokumentierern ist es ohne weiteres m¨oglich, neue Dokumentierer hin- zuzufugen,¨ bzw. vorhandene zu ¨andern. Kapitel 5

Konzept

In diesem Kapitel wird die Konzeption der NDoc-Erweiterung beschrieben. Das Konzept ist in drei Teile gem¨aß der drei prim¨aren Anforderungen aus Kapitel 4 gegliedert.

5.1 Anpassungen an die Anderungen¨ der Visual Studio-Dateien

Das NDoc-Projekt VisualStudio parst Projektmappendateien und Projekt- dateien, um die entsprechenden Metadaten fur¨ die weitere Verarbeitung von NDoc zu extrahieren. Analysiert werden dabei die einzelnen Konfigurationen und Plattformen. Abh¨angig von der verwendeten Visual Studio-Version sind in den Projekten Einstellungen pro Konfiguration oder pro Konfiguration und Plattform gespeichert. Visual Studio .net 2002 und Visual Studio .net 2003 unterteilen nicht globale Einstellungen nach Konfigurationen. Visual Studio 2005 und Visual Studio 2008 unterteilen nicht globale Einstellungen nach Konfigurationen und Plattformen, da jede Konfiguration in mehrere Plattformen ubersetzt¨ werden kann. Diese Abh¨angigkeit von Konfiguration und Plattform ist ein großer Unterschied der Dateien von Visual Studio .net 2002 und Visual Studio .net 2003 zu Visual Studio 2005 und Visual Studio 2008. Die wichtigsten Informationen fur¨ NDoc sind die Positionen und die Na- men der ubersetzten¨ Ausgabedateien und der XML-Dokumentationsdateien zur entsprechenden Konfiguration bzw. Konfigurations- und Plattformkom- bination. Entsprechend der Schreibweise in den Projektmappendateien und Projektdateien werden im Dialogfenster (siehe Abschnitt 4.1) dem Benutzer beim Laden einer Visual Studio 2005- oder Visual Studio 2008 Projektmap- pe, Kombinationen von Konfigurationen und Plattformen, getrennt durch einen senkrechten Strich, zur Auswahl angezeigt. Durch den Einsatz des Entwurfsmusters Fabrikmethode (siehe [Gam- ma et al., 2004])kanndie¨altere Funktionalit¨at fur¨ das Offnen¨ der alten

41 KAPITEL 5. KONZEPT 42

Abbildung 5.1: Entwurfsmuster Fabrikmethode (Quelle: [Gamma et al., 2004])

Dateiversionen von Visual Studio .net 2002 und Visual Studio .net 2003 weitgehend wieder verwendet und die neue Funktionalit¨at fur¨ das Offnen¨ der Dateien von Visual Studio 2005 und Visual Studio 2008 gekapselt wer- den. Die Abbildung 5.1 zeigt das Entwurfsmuster Fabrikmethode. Im Pro- jekt VisualStudio wird eine vereinfachte und parametrisierte Variante des Musters angewendet, in dem anhand vom Dateikopf der Projektmappenda- tei entschieden wird, um welche Dateiversion es sich beim Offnen¨ handelt. Das entsprechende Objekt wird erstellt oder ein Fehler geliefert, wenn die Datei nicht korrekt ist. Da sich die Logik, die entscheidet, um welche Pro- jektmappendatei es sich handelt, in der Fabrikmethode im NDoc-Projekt VisualStudio befindet, braucht sich der restliche Teil von NDoc nicht um die Versionsproblematik zu kummern.¨ Dadurch beschr¨ankensichdieAnde-¨ rungen von NDoc bezuglich¨ der neuen Projektmappendateien und Projekt- dateien fast ausschließlich auf das Projekt Visual Studio. Durch diese Vor- gehensweise wird die Koh¨asion erh¨oht und die Kopplung verringert. In der Fabrik hingegen wird eine niedrige Koh¨asion und eine hohe Kopplung kon- zentriert, was sich aber auf Grund der Uberschaubarkeit¨ der Fabrik nicht negativ auswirkt. Der Komplexit¨atszuwachs durch die Einbeziehung einer weiteren Schicht in Form der parametrisierten Fabrikmethode ist auf Grund der besseren Erweiterbarkeit und Wartbarkeit vernachl¨assigbar.

5.1.1 Projektmappendateien In der Projektmappendatei werden die einzelnen Projekte, Konfiguratio- nen und Plattfomen gespeichert. Die Dateiversionen von Visual Studio .net 2002 und Visual Studio .net 2003 sind sehr ¨ahnlich und fur¨ die Verwen- dung in NDoc als ident zu betrachten. Ab der Version 2005 von Visual Studio sind wesentliche Anderungen¨ in Bezug auf die unterstutzten¨ Platt- formen in der Projektmappendatei durchgefuhrt¨ worden. Die Dateien von Visual Studio 2005 und Visual Studio 2008 sind ebenfalls sehr ¨ahnlich und k¨onnen ebenfalls fur¨ die Verwendung in NDoc als ident betrachtet wer- den. Die Abbildungen 5.2 und 5.3 zeigen die Projektmappendatei einer KAPITEL 5. KONZEPT 43

Abbildung 5.2: Projektmappendatei Visual Studio .net 2003

Abbildung 5.3: Projektmappendatei Visual Studio 2008

Beispielanwendung mit hervorgehobenen Unterschieden als Visual Studio .net 2003-Projektmappendatei (Abbildung 5.2) und als Visual Studio 2008- Projektmappendatei (Abbildung 5.3). Die in Abbildung 5.3 gezeigte Visual Studio 2008-Projektmappendatei wurde von der IDE beim Laden automa- tisch konvertiert. Der Bereich preSolution umfasst in der Visual Studio .net 2003-Projektmappendatei eine Aufz¨ahlung von Konfigurationen und in der Visual Studio 2008-Projektmappendatei eine Aufz¨ahlung von Konfigurations- und Plattformkombinationen. Kommt in der Visual Studio 2008-Projekt- mappendatei (Abbildung 5.4) noch eine Plattform hinzu, wird die Aufz¨ahlung viel l¨anger. Dies betrifft auch die Verweise auf die einzelnen Projekte im postSolution-Bereich. Folgende Informationen werden aus der Projektmappendatei (.sln)ex- KAPITEL 5. KONZEPT 44

Abbildung 5.4: Projektmappendatei Visual Studio 2008 mit 2. Plattform

trahiert:

Der Name der Projektmappe wird nicht in der Projektmappendatei definiert, sondern entspricht dem Namen der Projektmappendatei oh- ne Dateierweiterung.

Die Nummer der zu Grunde liegenden Visual Studio Version wird er- mittelt.

Alle enthaltenen globalen Konfigurations- und Plattformkombinatio- nen werden gespeichert.

Alle in der Projektmappe enthaltenen Projekte werden durchgeparst.

– die Position der Projekte im Dateisystem, – die Anzahl der in der Projektmappe enthalteten Projekte, – die Art der einzelnen Projekte (C#-Projekt, VB-Projekt etc.), – Namen der einzelnen Projekte, – welches Projekt welche Konfigurations- und Plattformkonfigura- tion unterstutzt¨

Die eindeutige Identifizierung der Projekte erfolgt mit Hilfe einer GU- ID. KAPITEL 5. KONZEPT 45

Abbildung 5.5: Konfigurationen und Plattformen in einer Projektmappe

Abbildung 5.5 zeigt einen Uberblick¨ uber¨ die Projektmappen, weiters Konfi- gurations- und Plattformkombinationen und die Konfigurations- und Platt- formkombinationen, die zus¨atzlich noch einmal fur¨ jedes Projekt einzeln in der Projektmappendatei definiert sind. In der Projektdatei sind dann jeweils fur¨ die Konfigurationen zus¨atzliche Metainformationen gespeichert.

5.1.2 Projektdateien Visual Studio unterstutzt¨ verschiedene Arten von Projektdateien: C#-Pro- jekte (.csproj-Dateien), Visual Basic.net-Projekte (.vbproj-Dateien), Vi- sual C++-Dateien (.vcproj-Dateien), Setup-Projekte (.vdproj-Dateien) etc. Der Aufbau dieser einzelnen Projektdateien ist sehr unterschiedlich. Da NDoc nur das Laden von C#-Projekten unterstutzt,¨ werden in dieser Ar- beit prim¨ar C#-Projekte behandelt. Um eine m¨ogliche zukunftige¨ Erweite- rung zu erleichtern, werden mehrere Projekttypen im Projekt VisualStudio erkannt, aber nur C#-Projekte verarbeitet. Die Art der Projekte werden anhand einer von Microsoft vorgegebenen GUID identifiziert. KAPITEL 5. KONZEPT 46

Folgende Projekte werden erkannt:

C#-Projekt: FAE04EC0-301F-11D3-BF4B-00C04F79EFBC

Visual Basic-Projekt: F184B08F-C81C-45F6-A57F-5ABD9991F28F

C++-Projekt: 8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942

Setup-Projekt: 54435603-DBB4-11D2-8724-00A0C9A8B90C

WebSeiten-Projekt: E24C65DC-7377-472B-9ABA-BC803B73C61A

Projektmappe: 66A26720-8FB5-11D2-AA7E-00C04F688DDE

Visual J#-Projekt: E6FDF86B-F3D1-11D4-8576-0002A516ECE8 Die C#-Projektdateien sind in Visual Studio .net 2002 und Visual Stu- dio .net 2003 sehr ¨ahnlich und werden in NDoc gleich behandelt. Ebenso sind C#-Projektdateien in Visual Studio 2005 und Visual Studio 2008 sehr ¨ahnlich und werden in NDoc gleich behandelt. Die Anderung¨ zwischen Vi- sual Studio .net 2003 und Visual Studio 2005 ist sehr groß. Eine genauere Er¨orterung der Unterschiede wurde¨ den Rahmen dieser Arbeit sprengen. Wesentlichste Anderung¨ ist, wie bei den Projektmappendateien, die Unter- scheidung nach einer Konfigurations- und Plattformkombination. Alle C#- Projektdateien basieren auf XML. Die beiden neueren Versionen werden in Eigenschaftsgruppen unterteilt. Eine enth¨alt projektglobale Einstellungen und die anderen Eigenschaftsgruppen enthalten jeweils Einstellungen fur¨ eine Konfigurations- und Plattformkombination. Folgende Informationen werden aus der C#-Projektdatei (.csproj)ex- trahiert:

der Name des Assemblies,

der Ausgabetyp (Der Ausgabetyp kann eine Klassenbibliothek (.dll- Datei) oder ein ausfuhrbares¨ Programm (.exe-Datei) sein.),

Position der ubersetzten¨ Ausgabedatei im Dateisystem,

Position der XML-Dokumentationdatei im Dateisystem,

der Wurzelnamensraum (rootnamespace) des Assemblies

Erweiterbarkeit Fur¨ eine zukunftige¨ Erweiterung mussen¨ eine neue Pro- jektmappen-Klasse, die von der abstrakten Basisklasse Solution abgeleitet ist, eine neue Projekt-Klasse, die von der abstrakten Basisklasse Project abgeleitet ist und eine neue Projektkonfigurations-Klasse, die von der ab- strakten Basisklasse ProjectConfig abgeleitet ist, implementiert werden. Die Fabrikmethoden in der Klasse VisualStudioFactory mussen¨ dahin- gehend erweitert werden, dass sie ein neues Dateiformat erkennen und die entsprechenden Objekte erstellen k¨onnen. KAPITEL 5. KONZEPT 47

Abbildung 5.6: ReflectionEngine – MSDN-Dokumentierer

5.2 Anpassung an generische Typen

Die Erweiterungen an der NDoc Version 1.3.1, die von Richard Jonas durch- gefuhrt¨ wurden, erm¨oglichen bereits eine Verwendung von generischen Ty- pen. Es bleibt jedoch genug Raum fur¨ Verbesserungen. Die Projekte Core und Msdn sind von den Ver¨anderungen bezuglich¨ der Anpassungen an generische Typen prim¨ar betroffen. Das Projekt Msdn bein- haltet den MSDN-Dokumentierer und das Projekt Core beinhaltet unter anderem die so genannte ReflectionEngine und die abstrakten Basisklas- sen fur¨ die Dokumentierer. Die ReflectionEngine extrahiert die Metadaten aus den Assemblies und schreibt diese gemeinsam mit den Kommentaren der XML-Kommentardateiineineneuetempor¨are XML-Datei. Diese tempor¨are XML-Datei ist Basis fur¨ weitere Verarbeitungen. Abbildung 5.6 zeigt die Struktur des MSDN-Dokumentierers. Die ab- strakte Basisklasse BaseDocumenter implementiert die Schnittstelle IDocu- menter. Die Klasse BaseDocumenter stellt grundlegende Funktionalit¨aten fur¨ Dokumentierer zur Verfugung.¨ Die abstrakte Basisklasse BaseReflect- ionDocumenter ist von der Klasse BaseDocumenter abgeleitet und ist unter anderem fur¨ die Erstellung der tempor¨aren XML-Datei, die alle von NDoc verwendeten Metadaten enth¨alt, zust¨andig. Fur¨ diesen Zweck erstellt sie ein Objekt der ReflectionEngine. Die Klasse MsdnDocumenter ist, wie alle anderen Dokumentierer, von der Basisklasse BaseReflectionDocumenter abgeleitet und kann dadurch auf Funktionalit¨aten, die von der Basisklasse zur Verfugung¨ gestellt werden, zugreifen. Fur¨ die konkreten Auspr¨agungen der generischen Typen bei Variablen etc. muss eine Ver¨anderung in der ReflectionEngine durchgefuhrt¨ werden, KAPITEL 5. KONZEPT 48

Abbildung 5.7: Beispiel: online MSDN-Link – nicht generischer Typ

sodass bei der Extraktion der Metadaten diese Information mitgespeichert wird. Zus¨atzlich muss der XSL-Transformationscode fur¨ die korrekte Dar- stellung des Datentyps adaptiert werden. Die Korrektur der Anzeige des Datentyps bei Variablen erfordert eine Ver¨anderung des XSL-Transformations-Codes. Verweise auf nicht generische Typen der online MSDN-Bibliothek von Microsoft k¨onnen auf eine sehr einfache Art und Weise realisiert werden. Der Beginn der URL besteht aus folgender Zeichenkette: http://msdn.mi- crosoft.com/en-us/. An diese Zeichenkette wird der Typ samt Namens- raum, getrennt durch Punkte, angeh¨angt. Die Dateierweiterung .aspx ver- vollst¨andigt die URL. Die Abbildung 5.7 zeigt die Erstellung des Links an- hand der nicht generischen Klasse ArrayList. Fur¨ die Erstellung von Links auf generische Typen kann diese Vorge- hensweise nicht angewendet werden, da bei diesen Links nicht der Name des Typs verwendet wird, sondern eine nicht sprechende Zeichenkette. Diese Zeichenkette wird ebenfalls an den Pr¨afix http://msdn.microsoft.com/- en-us/ angeh¨angt. Die Ermittlung dieser Zeichenkette fur¨ einen bestimmten Typ erfolgt uber¨ ein Webservice, das Microsoft zur Verfugung¨ stellt. Erreich- bar ist das Webservice unter folgender Adresse: http://services.msdn.mi- crosoft.com/ContentServices/ContentService.asmx Die Abbildung 5.8 zeigt die Erstellung des Links mit Hilfe des Webservices anhand der Schnitt- stelle IList<>. KAPITEL 5. KONZEPT 49

Abbildung 5.8: Beispiel: online MSDN-Link – generischer Typ

5.3 Aufbau eines Visual Studio Add-Ins

In diesem Abschnitt werden nur die fur¨ das Visual Studio Add-In von NDoc relevanten Bereiche beschrieben. Eine detailliertere Beschreibung im Um- gang und zur Erstellung von Add-Ins fur¨ Visual Studio wird in [Skibo et al., 2006] geboten. Ein Visual Studio Add-In ist eine dll-Datei, die in der Visual Studio-IDE oder in der Marko-IDE l¨auft. Die Add-In-dll-Datei kann ein .net-Assembly oder eine COM-Komponente sein, die eine ¨offentliche Klasse enth¨alt, welche die Schnittstelle Extensibility.IDTExtensibility2 implementiert. Die Schnittstelle Extensibility.IDTExtensibility2 definiert folgende Me- thoden:

void OnAddInsUpdate (ref Array custom)

void OnBeginShutdown (ref Array custom)

void OnConnection ( Object Application, ext_ConnectMode ConnectMode, Object AddInInst, ref Array custom)

void OnDisconnection ( KAPITEL 5. KONZEPT 50

Abbildung 5.9: Ablauf der Ereignisse der Schnittstelle Extensibility.IDTExtensibility2 (Quelle: [Skibo et al., 2006])

ext_DisconnectMode RemoveMode, ref Array custom)

void OnStartupComplete (ref Array custom)

Abbildung 5.9 zeigt die Reihenfolge der Ereignisse des Add-Ins. Diese Er- eignisse beziehen sich auf die Schnittstelle Extensibility.IDTExtensibil- ity2 und beschreiben nur die grundlegenden Ereignisse, die ein Add-In un- terstutzen¨ muss. Weitere Ereignisse, wie z.B. Ereignisse, die uber¨ die grafi- sche Benutzeroberfl¨ache ausgel¨ost werden oder Ereignisse vom Texteditor, werden in diesem Ablauf nicht berucksichtigt.¨ Beim Laden des Add-Ins wird, wie Abbildung 5.9 zeigt, als erstes die Me- thode OnConnection aufgerufen. Mit dieser Methode ( Sie gewinnt m¨uhelos ” denerstenPreisf¨ur die wichtigste Add-In-Methode.“ [Skibo et al., 2006]) ubergibt¨ Visual Studio dem Add-In vier Parameter. Der wichtigste davon ist Object Application, der vom Add-In vom Datentyp Object auf den Da- tentyp EnvDTE80.EnvDTE2-Objekt konvertiert wird. Das Application Objekt KAPITEL 5. KONZEPT 51 vom Typ DTE2 erm¨oglicht es dem Add-In auf das gesamte Automatisierungs- objektmodell von Visual Studio zuzugreifen. Uber¨ dieses Automatisierungs- objektmodell kann das NDoc-Add-In die Informationen uber¨ die aktuelle Projektmappe und die darin enthaltenen Projekte ermitteln, aufbereiten und der eigentlichen NDoc-Applikation ubergeben.¨ Die Schnittstelle EnvDTE.IDTCommandTarget definiert folgende Me- thoden:

void Exec( string commandName, vsCommandExecOption executeOption, ref object varIn, ref object varOut, ref bool handled)

void QueryStatus( string commandName, vsCommandStatusTextWanted neededText, ref vsCommandStatus status, ref object commandText)

Diese beiden Methoden dienen der Interaktion mit benutzerdefinierten Be- fehlen. Das Add-In kann eine oder mehrere Befehlsleistenelemente, Symbol- leistenelemente oder Kontextmenueintr¨ ¨age registrieren. Die Methode Exec wird aufgerufen, wenn ein Befehl ausgefuhrt¨ werden soll. Da bei allen Befeh- len, um die sich das Add-In kummert,¨ Exec aufgerufen wird, muss anhand der ubergebenen¨ Parameter unterschieden werden, welcher Befehl abgearbei- tet werden soll. Die Methode QueryStatus wird von Visual Studio fur¨ jeden Befehl aufgerufen, um zu uberpr¨ ufen,¨ ob der Befehl gerade zur Verfugung¨ steht oder nicht. Ein Befehl der z.B. Informationen uber¨ Projekte anzeigt, wird wenn gerade keine Projekte in Visual Studio geladen sind, nicht zur Verfugung¨ stehen. Zur Registrierung eines Add-Ins bedarf es einer XML- Datei mit der Erweiterung .addin. Diese Datei beinhaltet den Link auf die dll-Datei, die das Add-In beinhaltet und Metainformationen zum Add-In. Die Position der .addin-Datei kann in den Visual Studio-Optionen angege- ben werden, damit sie von der IDE gefunden wird. KAPITEL 5. KONZEPT 52

Beispiel einer .addin-Datei

Microsoft Visual Studio 9.0 NDoc Visual Studio Add-In NDocVisualStudioAddIn.dll NDocVisualStudioAddIn.Connect Kapitel 6

Implementierung

Das folgende Kapitel umfasst die wichtigsten Teile der Implementierung der NDoc-Erweiterung. Durch die beschriebenen Details kann der Leser die Rea- lisierung der vorgestellten Konzepte nachvollziehen. Die Implementierung ist in drei Teile gem¨aß der drei prim¨aren Anforderungen aus Kapitel 4 geglie- dert. Jeder dieser Teile beinhaltet die zu Grunde liegende Architektur und die Codierung.

6.1 Visual Studio-Projektmappen und -Projekte

6.1.1 Architektur Das VisualStudio-Projekt der Ausgangsversion von NDoc ist sehr einfach aufgebaut (siehe Abbildung 6.1). Es besteht aus drei Klassen: Solution, Project und ProjectConfig. Die Klasse Solution bildet eine Projektmappe ab. Sie liest die Projektmappendatei (.sln) ein, parst den Inhalt und er- stellt fur¨ jedes Projekt ein Objekt der Klasse Project. Die Klasse Project bildet ein C#-Projekt ab und erstellt bei Bedarf ein Objekt der Klasse ProjectConfig, das wiederum eine konkrete Konfiguration abbildet. Durch diese Vorgehensweise werden die Informationen uber¨ die Projektmappe, die Projekte und die Konfigurationen sehr sch¨on gekapselt. Die Klasse Solution muss in der ursprunglichen¨ Version immer nur eine bestimmte Art von Projektmappendatei ¨offnen und dabei keine Versionsun- terscheidung treffen. Aus dieser Klasse Solution wurde eine Schnittstelle ISolution extrahiert (siehe Abbildung 6.2). Die neue abstrakte Basisklasse Solution, die die Schnittstelle ISolution implementiert, definiert versi- onsubergreifende¨ und gleichbleibende Aufgaben und Variablen auf Projekt- mappenebene. Die beiden Klassen Solution0203 und Solution0508 erwei- tern jeweils die abstrakte Basisklasse Solution fur¨ die jeweiligen Versionen der Visual Studio-Projektmappendateien. Da auf Grund von loser Kopplung die Entscheidung, welche Klasse bei welcher Projektmappendatei erzeugt werden soll, zentral an einer Stelle im

53 KAPITEL 6. IMPLEMENTIERUNG 54

Abbildung 6.1: Alte Architektur des Projekts VisualStudio

Abbildung 6.2: Neue Architektur des Projekts VisualStudio

Projekt VisualStudio erfolgen soll, enth¨alt die Klasse VisualStudioFactory die Fabrikmethode CreateSolution. Diese Fabrikmethode liest den Beginn der Projektmappendatei aus, stellt die Version fest und erstellt das entspre- chende Objekt. Aus der Klasse Project der ursprunglichen¨ Version wurde ebenfalls eine Schnittstelle (IProject) extrahiert. Die hier eingefuhrte¨ abstrakte Basis- klasse Project vereinigt versionsubergreifende¨ und gleichbleibende Aufga- ben und Variablen auf Projektebene. Die beiden Klassen Project0203 und Project0508 erweitern jeweils die abstrakte Basisklasse Project fur¨ die jeweiligen Versionen der Visual Studio-Projektdateien. Die dritte erstellte Schnittstelle ist IProjectConfig,diedie¨offentlichen Mitglieder der ursprunglichen¨ Klasse ProjectConfig extrahiert. Auf Grund KAPITEL 6. IMPLEMENTIERUNG 55 sehr unterschiedlicher Konfigurationen gibt die abstrakte Basisklasse Pro- jectConfig nur die Mitgliederdefinitionen der Schnittstelle IProjectCon- fig weiter, ohne selbst versionsunabh¨angige Aufgaben und Variablen zu de- finieren, wurde aber auf Grund eventueller zukunftiger¨ Erweiterungen nicht weggelassen. Die Klassen ProjectConfig0203 und ProjectConfig0508 er- weitern die abstrakte Basisklasse ProjectConfig fur¨ die entsprechenden Konfigurationen bzw. Konfigurations-Plattformkombinationen der jeweili- gen Visual Studio-Versionen. Alle Verwender des Projekts VisualStudio k¨onnen gegen Schnittstellen implementieren und die Fabrikmethode VisualStudioFactory verwenden und sind durch diese Vorgehensweise nur sehr lose an die verschiedenen Im- plementierungen gekoppelt. Durch diese Vorgehensweise mussen¨ bei Erwei- terungen zu einem sp¨ateres Zeitpunkt nur wenig oder gar keine Anderungen¨ durchgefuhrt¨ werden.

6.1.2 Codierung Bei der Codierung stehen die Wiederverwendung von Quellcode, die zukunf-¨ tige Erweiterbarkeit und ein sauberes Design im Vordergrund. Die Solution-Klasse der ursprunglichen¨ Version wurde in die Klasse Solution0203 umbenannt. Versionsubergreifende¨ Aufgaben und Variablen wurden in die neue abstrakte Basisklasse Solution eingefugt.¨ Die Klasse Solution0508 ist von der abstrakten Basisklasse Solution abgeleitet und wurde entsprechend der Besonderheiten der Projektmappendateien von Vi- sual Studio 2005 und Visual Studio 2008 implementiert. Die Project-Klasse der ursprunglichen¨ Version wurde in die Klasse Pro- ject0203 umbenannt. Versionsubergreifende¨ Aufgaben und Variablen wur- den in die neue abstrakte Basisklasse Project eingefugt.¨ Die Klasse Pro- ject0508 ist von der abstrakten Basisklasse Project abgeleitet und wurde entsprechend der Besonderheiten der C#-Projektdateien von Visual Studio 2005 und Visual Studio 2008 implementiert. Die ProjectConfig-Klasse der ursprunglichen¨ Version wurde in die Klas- se ProjectConfig0203 umbenannt. Da die beiden Versionen ProjectCon- fig0203 und ProjectConfig0508 sehr unterschiedlich sind, gibt es keine versionsubergreifenden¨ Aufgaben und Variablen, die in die abstrakte Basis- klasse Project eingefugt¨ werden konnten. Die Klasse ProjectConfig0508 ist von der abstrakten Basisklasse ProjectConfig abgeleitet und wurde ent- sprechend der Besonderheiten der Konfigurations- und Plattformkombina- tionen von C#-Projekten von Visual Studio 2005 und Visual Studio 2008 implementiert. Durch diese Vorgehensweise kann ein sehr hoher Anteil des alten Quell- codes wiederverwendet werden. Durch die Wiederverwendung von bereits verwendetem und getestetem Code ist die Fehlerwahrscheinlichkeit bei der Verarbeitung von Projektmappen von Visual Studio .net 2002 und Visual KAPITEL 6. IMPLEMENTIERUNG 56

Studio .net 2003 wesentlich geringer. Projektmappenintern werden GUIDs zur Identifizierung der Projekte verwendet. Diese GUIDs werden auch intern im NDoc-Projekt Visual Stu- dio verwendet, um bei Namensgleichheit keine Verwechslungen entstehen zu lassen. Neu eingefuhrt¨ wurden die beiden Enumerationen ProjectType und IDE- Type. ProjectType kapselt die verschiedenen Projekttypen, die Visual Stu- dio unterstutzt.¨ IDEType kapselt die vier verschiedenen unterstutzten¨ Visual Studio Versionen (.net 2002, .net 2003, 2005 und 2008). Das Projekt VisualStudio wird intern vom Projekt Gui verwendet. Im Projekt Gui mussten nur wenige Anpassungen durchgefuhrt¨ werden. Fur¨ die Implementierung gegen die Schnittstellen mussten Variablendeklarationen von der Verwendung konkreter Objekte auf die Schnittstellen umgestellt werden. Fur¨ die Erzeugung der entsprechenden Objekte bedient sich die Benutzeroberfl¨ache jetzt der Fabrikmethode, die in VisualStudio definiert ist.

6.2 Visual Studio Add-In

6.2.1 Architektur Im Menupunkt¨ Tools wird ein Untermenupunkt¨ mit dem Namen NDoc er- stellt. Dieser Untermenupunkt¨ enth¨alt zwei Punkte: Das Aufrufen der NDoc- Oberfl¨ache mit der aktuell in Visual Studio geladenen Projektmappe mit der aktuellen Konfigurations- und Plattformkombination und das Aufrufen der NDoc-Oberfl¨ache mit der aktuell in Visual Studio geladenen Projektmappe, wobei die Konfigurations- und Plattformkombination in einem Dialogfenster (siehe Abbildung 4.1) vom Entwickler ausgew¨ahlt werden kann. Die drei Klassen, in denen die fur¨ NDoc relevanten Informationen fur¨ die Weitergabe gekapselt werden, implementieren jeweils eine der drei Schnitt- stellen, die im Projekt VisualStudio definiert sind. Wie in Abbildung 6.3 veranschaulicht, implementiert die Klasse SolutionPlugin die Schnittstel- le ISolution, die Klasse ProjectPlugin implementiert die Schnittstelle IProject und die Klasse ProjectConfigPlugin implementiert die Schnitt- stelle IProjectConfig. Damit kann in anderen Projekten, die auf die Infor- mation zugreifen, sauber gegen Schnittstellen implementiert werden. Jeffrey Richter schreibt in [Cwalina und Abrams, 2007]: Mir gef¨allt, ” was das Windows-Forms-Team gemacht hat: Sie definieren eine Schnittstelle namens System.ComponentModel.IComponent,dienat¨urlich jeder Typ im- plementieren kann. Aber das Windows-Forms-Team stellte auch die Klasse System.Component.Component bereit, welche die Schnittstelle IComponent implementiert. Somit konnte ein Typ entweder von Component abgeleitet und damit die gesamte Implementierung sozusagen gratis erhalten, als auch von einer beliebigen Basisklasse ableiten und das Interface IComponent ma- KAPITEL 6. IMPLEMENTIERUNG 57

Abbildung 6.3: Architektur des NDoc Visual Studio-Add-Ins

nuell implementieren. Wenn sowohl eine Schnittstelle, als auch eine Basis- klasse bereitsteht, k¨onnen Programmierer ausw¨ahlen, was f¨ur sie am n¨utz- lichsten ist.“ Das entspricht auch der im NDoc-Projekt VisualStudio angewandten Architektur, da die beiden Klassen Solution0203 und Solution0508 von der abstrakten Basisklasse Solution abgeleitet sind. Dadurch k¨onnen diese beiden Klassen allgemeine, bereits implementierte Funktionalit¨at erben und verwenden. Im Projekt NDocVisualStudioAddIn implementiert die Klasse SolutionPlugin die Schnittstelle ISolution direkt, da in diesem Fall die Funktionalit¨at der Klasse Solution keinen Sinn macht, da die Metainforma- tionen in einer anderen Form vorliegen. Die Schnittstelle und die Klassen, die die Projekte kapseln, sind nach dem selben Schema aufgebaut. Bei der Kapselung der Projektkonfigurationen ist zwar keine Funktionalit¨at in der Basisklasse verankert, weil der Aufbau keine gemeinsame Logik zul¨asst, an- sonsten ist hier auch ein analoger Aufbau implementiert.

6.2.2 Codierung Entsprechend der Vorgaben uber¨ die Erstellung von Add-Ins (siehe Ab- schnitt 5.3) wird eine Klasse Connect erstellt, welche die beiden Schnittstel- len IDTExtensibility2 und IDTCommandTarget implementiert. Die Klasse Connect des Add-Ins wurde unter Verwendung des in Visual Studio zur Verfugung¨ stehenden Assistenten erstellt. Die so erstellte Grundstruktur wurde, mit dem in den Schnittstellen definierten Methoden den Anforde- rungen entsprechend, erweitert. Zu Beginn erfolgt die Installation der Menupunkte,¨ die beim Verbin- den des Add-Ins in der von Visual Studio aufgerufenen OnConnect Me- thode durchgefuhrt¨ wird. Um eine Mehrfachinstallation der Menupunkte¨ KAPITEL 6. IMPLEMENTIERUNG 58 zu vermeiden, muss immer zuvor ermittelt werden, ob die Menupunkte¨ bereits installiert sind. Der Abfragestatus der beiden Menupunkte¨ retour- niert die Methode QueryStatus der Entwicklungsumgebung. Die Ereignis- behandlungsroutinen, die beim Bet¨atigen der entsprechenden Menupunkte¨ die jeweiligen Aktionen setzen, beinhalten die eigentliche Logik des Add- Ins. Beim Aktivieren einer der beiden Menupunkte¨ werden die Objekte der drei Klassen erstellt. Diese drei Objekte bekommen jeweils eine Referenz auf das Automatisierungsobjektmodell von Visual Studio. Die Extraktion an sich erfolgt in den drei Objekten auf den jeweiligen, von den implemen- tierten Schnittstellen vorgegebenen Ebenen: Projektmappenebene, Projek- tebene und Konfigurations- und Plattformkombinationsebene.

6.3 MSDN-Dokumentierer

6.3.1 Architektur Die Architektur des MSDN-Dokumentierers entspricht weitgehend dem in Abschnitt 3.2.4 beschriebenen Ablauf. Der Dokumentationserstellungspro- zess bleibt, wie in der Originalversion, in sieben Phasen unterteilt. Ande-¨ rungen ergeben sich nur im Detail. Fur¨ die Ermittlung der Verweise auf die online Version der MSDN-Biblio- thek wird das von Microsoft zur Verfugung¨ gestellte Webservice verwendet. Nicht generische Typen verfugen¨ neben dem im Beispiel in der Abbildung 5.7 gezeigten sprechenden Verweis auch alternativ uber¨ einen nicht spre- chenden Verweis, der ebenfalls vom Webservice erstellt werden kann. Diese vom Webservice generierten Verweise fur¨ nicht generische Typen werden jedoch nicht verwendet, da bei einer Erstellung der Dokumentation ohne Verbindung zum Internet wenigstens Verweise auf nicht generische Typen der .net-Klassenbibliothek unterstutzt¨ werden. Ein Verzicht auf Webservice- Anfragen, wenn sie nicht unbedingt ben¨otigt werden, erh¨oht die Performanz der Dokumentationserstellung und spart Netzwerkressourcen ein. Die Ver¨anderungen am XSL-Transformationscode, den dazugeh¨origen C#-Methoden und die Anpassungen in den beiden Projekten Core und Msdn ziehen keine Anderung¨ an der zu Grunde liegenden Architektur nach sich, sondern nur punktuelle Adaptionen.

6.3.2 Codierung Die Implementierung umfasst keine gr¨oßeren strukturellen Anderungen.¨ Bei den Anpassungen wurden durchwegs bestehende Klassen und Methoden er- weitert, beziehungsweise erg¨anzt. KAPITEL 6. IMPLEMENTIERUNG 59

Anzeigen der konkreten Auspr¨agungen generischer Typen Fur¨ die Anzeige der konkreten Auspr¨agungen bei generischen Typen muss- ten verschiedene Anderungen¨ durchgefuhrt¨ werden. Die erste Anderung¨ ist die Anpassung der ReflectionEngine. Beim Ermit- teln der Metadaten mit Hilfe von Reflection werden generische Typen, die in einer konkreten Auspr¨agung vorliegen, syntaktisch aufbereitet. Dadurch liegen die Datentypen in einem Format vor, wie sie im syntaktisch korrekten Quelltext stehen. Diese Daten werden in die tempor¨are XML-Datei, die die Basis fur¨ weitere Verarbeitungen darstellt, gespeichert. Diese syntaktischen Aufbereitungen wurden weitgehend mit Stringoperationen gel¨ost. Fur¨ die Erstellung der HTML-Datei mussten kleine Eingriffe im XSL- Transformationscode und in den dazugeh¨origen C#-Routinen vorgenommen werden, damit die Darstellung der C#-Syntax entspricht. Folgende Beispiele zeigen den Unterschied anhand einer Methode, die einen generischen Ruckgabewert¨ hat und sowohl generische als auch einen nicht generischen Parameter in ihrer Schnittstelle hat.

Beispiel vor der Anpassung an konkrete Typen public IDictionary method1( IDictionary param1, IList param2, Int32 param3 );

Beispiel nach der Anpassung an konkrete Typen public IDictionary>> method1( IDictionary>> param1, IList param2, Int32 param3 );

Anpassung der Datentypen von Klassenvariablen Bei der Anzeige der Datentypen bei Klassenvariablen handelt es sich um einen kleinen Fehler im XSL-Transformationscode, der ausgebessert wurde. Das folgende Beispiel zeigt die ursprungliche¨ und die korrigierte Ausgabe am Beispiel einer ¨offentlichen Klassenvariablen mit dem Datentyp IList und dem Namen arrList1. KAPITEL 6. IMPLEMENTIERUNG 60

Beispiel public arrList1 arrList1; public IList arrList1;

Links auf die MSDN Fur¨ die Verweise auf Klassen der .net-Klassenbibliothek mussten Ver¨ande- rungen in den XSL-Transformationen durchgefuhrt¨ werden. Des weiteren wurden einige C#-Hilfsmethoden erstellt, die unter anderem die Unterschei- dung zwischen Verweise auf die lokale MSDN-Bibliothek oder Verweise auf die online Version der MSDL-Bibliothek bewerkstelligen. Diese Hilfsmetho- den befinden sich im NDoc-Projekt Msdn im Namensraum NDoc.Documen- ter.Msdn in der Klasse MsdnXsltUtilities, die bei den XSL-Transforma- tionen eine wichtige Rolle spielt. Je nach MSDN-Bibliotheks-Version werden von den erstellten Hilfsmethoden die entsprechenden Daten geliefert.

Online Fur¨ das Ermitteln der Verweise auf generische Typen der online MSDN-Bibliothek wird das von Microsoft zur Verfugung¨ gestellte Webser- vice verwendet. Fur¨ die Verwendung dieses Webservices wurde mittels dem in Visual Studio 2008 zur Verfugung¨ stehenden Assistenten eine Webreferenz erstellt. Diese Webreferenz erzeugt gem¨aß den von der Webserviceschnitt- stelle erhalteten Metadaten eine Proxy-Klasse. Durch Verwendung dieses Proxys kann auf eine sehr einfache Art auf die Funktionalit¨at des Webser- vices zugegriffen werden. Im Quelltextabschnitt, der fur¨ die Erstellung der Verweise zust¨andig ist, wird gepruft,¨ ob es sich um einen generischen Typ handelt oder nicht. Bei einem nicht generischen Typ wird der Verweis auf die konventionelle Weise, wie in Abschnitt 5.2 beschrieben, zusammengebaut. Bei einem generischen Typ wird das Webservice fur¨ die Endung des Verweises zu Rate gezogen.

Lokal Verweise auf die lokal installierte MSDN-Bibliothek wurden kaum ver¨andert. Hier wurden die Anpassungen von Richard Jonas, die bereits die MSDN-Version 8 mit der Verwendung von generischen Typen unterstutzt,¨ weitgehend ubernommen.¨ Kapitel 7

Evaluierung

Im folgenden Kapitel wird ein Vergleich der gesteckten mit den erreichten Zielen dargestellt, daruber¨ hinaus wird die Vorgehensweise beim Testen der Software vorgestellt.

7.1 Erreichte Ziele

Im Kapitel 4 wurden jene Anforderungen zusammengefasst, die an die Erwei- terung von NDoc gestellt wurden. Im folgenden Abschnitt wird verglichen, inwieweit die Anforderungen mit dem Ergebnis ubereinstimmen.¨

Umgang mit aktuellen Visual Studio-Dateien Der Umgang mit Visual Studio-Dateien wurde in NDoc integriert. Konkret kann NDoc nach der Erweiterung zus¨atzlich Visual Studio 2005- und Visual Studio 2008-Projektmappendateien ¨offnen. NDoc kann auf die Metainformationen von Projekten in Projektdatei- en, die in Projektmappendateien verwiesen sind, zugreifen. Diese Projekte mussen¨ C#-Projekte sein. VB.net, managed C++ oder andere .net-Spra- chen werden nicht unterstutzt.¨ NDoc unterscheidet bei Projekten der Visual Studio-Versionen .net 2002 und .net 2003 zwischen einzelnen Projektkonfigurationen und bei Visual Stu- dio Versionen 2005 und 2008 zwischen Kombinationen von Konfigurationen und Plattformen.

Umgang mit generischen Typen Generische Typen werden bei der Verwendung des Dokumentierers MSDN unterstutzt¨ und entsprechend der Syntax von C# in der erstellten Doku- mentation in Form einer .chm-Datei angezeigt. Bei konkreten Auspr¨agungen in Definitionen wird der Datentyp ange- zeigt, der beim Kompilieren des Assemblies eingesetzt wird. Dies funktio-

61 KAPITEL 7. EVALUIERUNG 62 niert auch bei verschachtelten generischen Definitionen. Der HTML-Verweis zeigt aber nur auf den ¨außeren Typ. Verweise auf Typen der .net-Klassenbibliothek in der Dokumentation, die in Form von kompilierten HTML-Dateien (.chm) vorliegen, zeigen je nach Konfiguration auf eine lokal installierte MSDN-Bibliothek oder auf die online Version. Verweise auf die online MSDN-Bibliothek werden sowohl mit generischen Typen durch Abfrage des Webservices von Microsoft, als auch die aktuellen Klassen der Klassenbibliothek des .net Frameworks 3.0 und 3.5 unterstutzt.¨ In Kombination mit der offline MSDN-Bibliothek wird das Anzeigen von generischen Typen unterstutzt,¨ Verweise auf die aktuelle MSDN-Version mit den Klassen der Klassenbibliothek des .net Frameworks 3.0 und 3.5 jedoch nicht.

Integration in Visual Studio 2008 In der Projektmappe NDoc wurde das Projekt NDocVisualStudioAddIn hinzugefugt.¨ Dieses Projekt realisiert ein kleines Add-In fur¨ Visual Studio. Entwickler k¨onnen uber¨ das Tools-Menu¨ in Visual Studio eine NDoc- Instanz starten, die die aktuell in Visual Studio geladene Projektmappe enth¨alt. Es gibt zwei verschiedene M¨oglichkeiten: Entweder wird die aktuelle Konfigurations- und Plattformkombination ubernommen,¨ oder der Entwick- ler wird nach der gewunschten¨ Kombination in einem Dialogfenster (siehe Abbildung 4.1) gefragt.

Kompatibilit¨at Durch den modularen Aufbau k¨onnen in der erweiterten NDoc-Version Do- kumentationen auf Basis von Projektmappen und Assemblies von allen Vi- sual Studio-Versionen, die eine Entwicklung auf Basis des .net Frameworks erlauben, erstellt werden.

Erweiterbarkeit Anderungen¨ im Aufbau von Projekten und Projektmappen Auf Grund des objektorientierten Designs und der Verwendung des Entwurfs- musters Fabrikmethode ist das Hinzufugen¨ einer Unterstutzung¨ fur¨ zukunf-¨ tige Dateiversionen von Projektmappen und Projekten ohne gr¨oßere Ande-¨ rungen m¨oglich. Das schlechteste Szenario w¨are, wenn zus¨atzliche fur¨ NDoc relevante Metainformationen hinzukommen wurden,¨ die in den Schnittstel- len nicht berucksichtigt¨ werden.

Syntaktische Anderungen¨ Zukunftige¨ fur¨ NDoc relevante syntaktische Anderungen¨ der Programmiersprache C# sind bis dato nicht absehbar. KAPITEL 7. EVALUIERUNG 63

Anderungen¨ mussen¨ in der ReflectionEngine und in den einzelnen Doku- mentierern durchgefuhrt¨ werden. Auf Grund der Vielf¨alltigkeit, in der solche Anderungen¨ auftreten k¨onnten, kann in der erweiterten Version von NDoc keine Rucksicht¨ auf zukunftige¨ syntaktische Anderungen¨ genommen werden.

Sonstige Erweiterungen Durch den modularen Aufbau des NDoc-Pro- jekts VisualStudio ist eine Unterstutzung¨ von Projektdateien anderer in Visual Studio unterstutzter¨ .net-Sprachen ohne große strukturelle Anderun-¨ gen m¨oglich. Ein Hinzufugen¨ weiterer Dokumentierer ist schon in der Ausgangsversion von NDoc m¨oglich. In der erweiterten Version von NDoc sollte ein eventuell hinzugefugter¨ Dokumentierer, falls er fur¨ Projekte, die auf .net Framework 2.0 und aktuellerer Versionen basieren, generische Typen unterstutzen.¨

7.2 Testbeschreibung

7.2.1 Interne Tests Im Zuge der internen Tests wurde eine Testprojektmappe erstellt. Die- se Testprojektmappe enth¨alt mehrere Projekte. Es sind benutzerdefinierte Konfigurationen und mehrere Plattformen definiert. Die einzelnen Projekte sind C#-Projekte. In den einzelnen Projekten sind verschiedene Typen und Typmitglieder definiert: generische Klassen, eine generische Delegation, ei- ne Wertvariable, die den Wert null annehmen kann, generische Methoden, generische Eigenschaften und generische Variablen. Aus dieser Test-Projektmappe wurde beim Testen mit der erweiterten NDoc-Version unter Verwendung des MSDN-Dokumentierers eine Doku- mentation erstellt. Zu Testzwecken wurden auch Projektmappen ¨alterer Visual Studio-Ver- sionen ge¨offnet und daraus Dokumentationen erstellt. Diese Projektmappen sind sehr simpel aufgebaut und entsprechen weitgehend den vom Assistenten in Visual Studio erstellten Projektmappen plus einiger kleinerer Erweiterun- gen, wie zus¨atzliche Klassenbibliotheken oder eine ver¨anderte Konfigurati- onseinstellung.

7.2.2 Externe Tests - Verarbeitung des Testprojektes Vom Auftraggeber wurde ein Projekt aus der Praxis zur Verfugung¨ gestellt. Dieses Projekt verwendet und definiert generische Typen. Des Weiteren wer- den Klassen aus der .net-Klassenbibliothek 3.5 verwendet. Vom Auftraggeber wurde definiert, dass eine erfolgreiche Dokumentation des Projekts mit der erweiterten NDoc-Version als OK-Kriterium gilt. In einer virtualisierten Umgebung wurde ein Windows-System mit in- stalliertem Visual Studio 2008 fur¨ das Testen des Add-Ins eingerichtet. Es KAPITEL 7. EVALUIERUNG 64 wurde eine kleine Test-Projektmappe erstellt, die mit verschiedenen Konfi- gurationen und Plattformen konfiguriert wurde.

7.3 Testergebnisse

7.3.1 Interne Tests Die erweiterte NDoc-Version konnte aus der Test-Projektmappe unter Ver- wendung des MSDN-Dokumentierers eine Dokumentation in Form einer .chm-Datei erstellen, die den Anforderungen entspricht. Die generischen Typen werden ordnungsgem¨aß und entsprechend der Syntax von C# angezeigt. Bei konkreten Auspr¨agungen generischer Typen wird der richtige Datentyp eingesetzt und Wertetypen, die den Wert null unterstutzen,¨ werden berucksichtigt.¨ Das Laden von Projektmappen ¨alterer Visual Studio-Versionen funktio- niert erfolgreich. Verweise auf die MSDN-Bibliothek funktionieren bei generischen Typen bei der online und bei der lokalen Version. Verweise auf Typen der Klassen- bibliothek der Version 3.0 und 3.5 funktionieren in der online Version der MSDN-Bibliothek. In der virtuellen Maschine wurde das Add-In erfolgreich getestet. Das Exportieren der aktuellen Projektmappe in der aktuellen Konfigurations- und Plattformkombination, als auch das manuelle Ausw¨ahlen der Kombina- tion seitens des Benutzers wurde erfolgreich unter verschiedenen Einstellun- gen der Projektmappe getestet. Weitere vom Assistenten von Visual Studio erstellte Projektmappen wurden ebenfalls erfolgreich geladen.

7.3.2 Externe Tests Das vom Auftraggeber zur Verfugung¨ gestellte Projekt wurde ordnungs- gem¨aß von NDoc verarbeitet. Die erstellte kompilierte HTML-Datei ent- spricht den Vorgaben, die an die Dokumentation gestellt wurden:

eine ordnungsgem¨aße Darstellung der verwendeten generischen Typen,

korrekte Verweise auf generische Typen in der MSDN-Bibliothek,

korrekte Verweise auf Typen des .net-Frameworks 3.0 und 3.5 auf die online MSDN-Bibliothek,

korrektes Laden der Projektmappe, die in der Version von Visual Stu- dio 2008 vorlag Kapitel 8

Resumee¨

Das folgende Kapitel stellt den Abschluss dieser Arbeit dar. Hier werden noch einmal die wichtigsten Aspekte und Erkenntnisse zusammengefasst. Es wird ein kurzer Uberblick¨ uber¨ die erzielten Ergebnisse gegeben. Ebenso wird ein Ausblick auf die Ver¨offentlichung der Anwendung und denkbare Erweiterungen und Verbesserungen erl¨autert.

8.1 Zusammenfassung

Ziel dieser Arbeit war es, die drei in Kapitel 4 beschriebenen Erweiterun- gen des Dokumentationswerkzeuges NDoc umzusetzen: Umgang mit gene- rischen Typen bei Dokumentationserstellungen mit dem MSDN-Dokumen- tierer, Unterstutzung¨ von Projektmappendateien und Projektdateien von Visual Studio 2005 und Visual Studio 2008 und ein kleines Add-In fur¨ Vi- sual Studio 2008, das die aktuell in Visual Studio geladene Projektmappe an NDoc weitergibt. Zus¨atzlich sollte die Kompatibilit¨at zu bestehenden NDoc-Projekten und -Projektmappen von Visual Studio .net 2002 und Vi- sual Studio .net 2003 gew¨ahrleistet sein. Um dieses Ziel erreichen zu k¨onnen, musste zun¨achst der Aufbau der Ausgangsversion von NDoc untersucht werden. Die Erweiterungen wurden anschließend bestm¨oglich in die bestehende Architektur integriert, bezie- hungsweise die bestehende Architektur an die Anforderungen adaptiert. Die erweiterte Version von NDoc kann verwendet werden, um Doku- mentationen im MSDN-Stil von .net-Anwendungen und .net-Bibliotheken zu erstellen. Diese Anwendungen und Bibliotheken k¨onnen fur¨ alle .net- Frameworkversionen ubersetzt¨ werden.

65 KAPITEL 8. RESUMEE¨ 66

8.2 Ver¨offentlichung des Ergebnisses

Die ursprunglich¨ geplante Vorgehensweise bestand darin, dass die erweiter- te NDoc-Version zu dem bestehenden NDoc-Projekt auf SourceForge hinzu- gefugt¨ wird. Um auf der Plattform Sourceforge in einem Projekt Anderungen¨ durchfuhren¨ zu k¨onnen, muss man vom jeweiligen Projektadministrator die entsprechenden Rechte bekommen. Ein E-Mail an Kevin Downs und Don Kackman blieb aber leider bislang unbeantwortet. Auf Grund dessen wurde ein neues Projekt auf dem Portal Sourcefor- ge fur¨ die erweiterte Version von NDoc angelegt. Der Projektname lau- tet: NDoc-Enhanced“ und der entsprechende Unixname: ndoc-e. Erreichbar ” ist das Projekt unter dem Verweis: http://sourceforge.net/projects/- ndoc-e/. Dort ist die erweiterte Version von NDoc sowohl als Quelltext als auch als kompilierte Bin¨ardateien unter der GNU General Public License (GPL) herunterladbar.

8.3 Ausblick

Bestehende Dokumentierer erweitern Eine der denkbaren Erweiterungen, die in eine zukunftige¨ Version von NDoc integriert werden k¨onnte, ist die Aktualisierung der in dieser Arbeit nicht erweiterten Dokumentierer, um generische Typen zu unterstutzen.¨

Neue Dokumentierer hinzufugen¨ Eine weitere m¨ogliche zukunftige¨ Erweiterung ist die Implementierung wei- terer Dokumentierer, zum Beispiel unter der Verwendung des von Microsoft im Juni 2008 zur Verfugung¨ gestellten Open-XML-Formats SDK. Damit w¨are ein Dokumentierer m¨oglich, der eine Dokumentation im Office Open- XML-Format fur¨ Microsoft Office 2007 erstellt.

Das Offenen¨ von anderen Projekten im Zuge eines Projektmap- penladevorgangs Das Offnen¨ von Projekten mit anderen Programmiersprachen als C#, im Zuge des Importierens einer Projektmappe ist ein Punkt, der ebenfalls in einer zukunftigen¨ NDoc-Version integriert werden k¨onnte. Durch den modu- laren Aufbau des NDoc-Projekts VisualStudio ist die Architektur bereits fur¨ dahin gehende Erweiterungen ausgelegt. Denkbar w¨are etwa die Unterstutzung¨ von Visual Basic .net, J#, mana- ged C++ oder andere durch Erweiterungen in Visual Studio entwickelbare Sprachen auf .net-Framework-Basis. KAPITEL 8. RESUMEE¨ 67

Lokale MSDN-Bibliothek der Version 9 Die Unterstutzung¨ von Verweisen von Typen der .net-Klassenbibliothek auf die MSDN-Version 9 ist ein Bereich, der in zukunftige¨ Versionen von NDoc Einzug halten kann. Dadurch wurden¨ dann auch bei lokaler Verlinkung Klas- sen der .net-Frameworkversionen 3.0 und 3.5 unterstutzt.¨ Anhang A

E-Mail von Kevin Downs

From: Kevin Downs

Sent: Wednesday, July 26, 2006 1:32 PM

Subject: NDoc 2.0 - R.I.P. I have decided to discontinue work on NDoc 2.0 and no longer participate in any open-source development work.

The development and release of NDoc 1.3 was a huge amount of work, and by all accounts widely appreciated. Unfortunately, despite the almost ubiquitous use of NDoc, there has been no support for the project from the .Net developer community either financially or by development contri- butions. Since 1.3 was released, there have been the grand total of eleven donations to the project. In fact, were it not for Oleg Tkachenko’s kind do- nation of a MS MVP MSDN subscription, I would not even have a copy of VS2005 to work with! To put this into perspective, if only roughly 1-in-10 of the those who downloaded NDoc had donated the minimum allowable

amount of °5 then I could have worked on NDoc 2.0 full-time and it could have been released months ago! Now, I am not suggesting that this should have occurred, or that anyone owes me anything for the work I have done, rather I am trying to demonstrate that if the community values open-source projects then it should do *something* to support them. MS has for years acknowledged community contributions via the MVP program but there is absolutely no support for community projects. Once ’Sandcastle’ is released, it is my belief that it will become the de- facto standard and that NDoc will slowly become a stagnant side-water. This will happen regardless of technical considerations, even if Sandcastle were to be less feature-complete. It’s just an inevitable result of MS’s ’not- invented-here’ mentality, one only has to look at Nant and NUnit to see the effects of MS ’competition’. This is not, however, my only reason for stopping development work - I

68 ANHANG A. E-MAIL VON KEVIN DOWNS 69 have a big enough ego to think I could still produce a better product than them :-) As some of you are aware, there are some in the community who believe that a .Net 2.0 compatible release was theirs by-right and that I should be moving faster - despite the fact that I am but one man working in his spare time... This came to head in the last week; I have been subjected to an auto- mated mail-bomb attack on both my public mail addresses and the ndoc2 mailing list address. These mails have been extremely offensive and resulted in my ISP temporarily suspending my account because of the traffic volu- me. This incident has been reported to the local authorities, although I am highly doubtful they will be able to do anything about it. This has was the ’last-straw’ and has convinced me that I should with- draw from the community; I’m not prepared to have myself and my family threatened by some lunatic!

Kevin

P.S. If anyone wants to take over as admin on the SourceForge NDoc project - contact me. If not, I’ll be removing myself in 14 days. Literaturverzeichnis

[Cwalina und Abrams, 2007] Krzysztof Cwalina und Brad Abrams. Richt- linien f¨ur das Framework-Design. Addison-Wesley Verlag, Martin-Kollar- Straße 10-12, D-81829 Munchen/Germany,¨ 2007.

[Gamma et al., 2004] Erich Gamma, Richard Helm, Ralph Johnson, und John Vlissides. Entwurfsmuster. Addison-Wesley Verlag, Martin-Kollar- Straße 10-12, D-81829 Munchen/Germany,¨ 2004.

[Hauser, 2006] Tobias Hauser. XML Standards. Entwickler Press, Frankfurt, 2006, 2006.

[Kackman et al., 2005] Don Kackman, Jean-Claude Manoli, und Kevin Downs. NDoc Online. http://ndoc.sourceforge.net/, 2005.

[Kuhnel,¨ 2006] Andreas Kuhnel.¨ Visual C# 2005. Galileo Press, Rhein- werkallee 4, 53227 Bonn, 2006.

[Mangano, 2006] Sal Mangano. XSLT Kochbuch. O’Reilly Verlag, Baltha- sarstr. 81, D-50670 K¨oln, 2006.

[Mic, 2008] Microsoft MSDN Library, http://msdn.microsoft.com/en-us/- library/b2s063f7.aspx. XML Documentation, 2008.

[Mon, 2008] Mono Webseite. http://www.mono-project.com, 2008.

[Richter, 2006] Jeffrey Richter. Microsoft .NET Framework-Programmie- rung in C#. Microsoft Press Deutschand, Konrad-Zuse-Str. 1, D-85716 Unterschleißheim, 2. Auflage, 2006.

[Schafer, 2002] J. Andrew Schafer. C#: Xml comments let you build do- cumentation directly from your visual studio .net source files. MSDN Magazine, June 2002.

[Skibo et al., 2006] Graig Skibo, Marc Young, und Brian Johnson. Arbeiten mit Microsoft Visual Studio 2005. Microsoft Press Deutschland, Konrad- Zuse-Str. 1, D-85716 Unterschleißheim, 2006.

70 LITERATURVERZEICHNIS 71

[XPa, 2008] XPath Tutorial. http://www.w3schools.com/xpath/default.- asp, 2008.