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