Am 14. September 2017 haben wir eine überarbeitete Fassung unserer Datenschutzrichtlinie veröffentlicht. Wenn Sie video2brain.com weiterhin nutzen, erklären Sie sich mit diesem überarbeiteten Dokument einverstanden. Bitte lesen Sie es deshalb sorgfältig durch.

Visual Studio 2013 Grundkurs

XML-Kommentare

LinkedIn Learning kostenlos und unverbindlich testen!

Jetzt testen Alle Abonnements anzeigen
Die Dokumentation von benutzerdefinierten Typen erfolgt durch die Erstellung von XML-Kommentaren. Die hierbei erstellten Informationen können an verschiedenen Stellen ausgewertet werden.
07:49

Transkript

Wenn wir objektorientierte Systeme entwickeln und C#-Code schreiben ist Dokumentation ein sehr sehr wichtiger Bestandteil der eigentlichen Entwicklerarbeit. Die Dokumentation kann auf viele verschiedene Arten erfolgen. Ich kann in Word separat eine Dokumentation meiner Klassenstruktur machen oder ich kann es auch in irgendwelchen anderen Varianten machen mit normalen Kommentaren oder eben ich lasse mir Dokumentation zu meinen System generieren. Das funktioniert natürlich nicht alles voll automatisch, sondern ich muss gewisse Hinweise geben, aber mit den XML-Kommentaren die wir uns jetzt anschauen, lässt sich da schon eine ganze Menge automatisieren. Was sind XML-Kommentare? XML-Kommentare sind, ja, die etwas intelligenteren Brüder unser ganz normalen Kommentare, die leiten wir ja normalerweise mit "//" ein und so ein XML-Kommentar leiten wir mit "///" ein. Das heißt, mit einem XML-Kommentar kann ich jetzt zum Beispiel meine Klasse hier oben dokumentieren. Und ich schreibe jetzt mal "///" und man sieht automatisch Visual Sudio vervollständigt das Ganze und ich kann jetzt hier, ja, mehr oder weniger XML-Darstellung meine Klasse, meine Hauptklasse kommentieren. Also, "Dies ist die Class1. Sie hat eigentlich keinen Zweck". So, das wäre also jetzt hier, wenn auch vielleicht mit einem Rechtschreibfehler eine rudimentäre Dokumentation meiner Klasse. Jetzt haben wir natürlich in der Klasse weitere Elemente, wie zum Beispiel hier das Property und auch hier ist es so, dass ich mit /// ein entsprechendes XML-Kommentar setzen kann. Ich kann das jetzt hier sagen, okay, "Liest und setzt das Alter der (Class1) Klasse 1". So, das wäre also auch ein Kommentar. Methoden ebenfalls, dort sieht dann auch ähnlich aus, wie oben in unserem Property, "Macht eigentlich gar nix...". Aber ein bisschen spannender wird es dann zum Beispiel hier bei DoBar . Ich mache jetzt hier einfach mal einen Kommentar. Man sieht jetzt kommt ein bisschen mehr. Warum kommt ein bisschen mehr? Na ja, zum einen haben wir jetzt hier einen Rückgabetyp, das hatten wir hier oben nicht und wir haben zwei Parameter. Und ich kann jetzt hier hingehen, wir können erstmal schreiben, okay, "Die Methode macht auch nichts..." Und dann kann ich jeden einzelnen Parameter an der Stelle hier kommentieren. Das heißt, ich kann hier sagen "Das ist Parameter z1, der Bruder von z2". Und "z2 ist der böse Bruder von z1". Also irgendwelche sinnvolleren Kommentare natürlich an der Stelle und hier hinten kann ich dann sagen was wird überhaupt von der Methode zurückgegeben? Na ja, "Die zumme aus z1 und z2". Oder wobei das wäre jetzt vielleicht zu nah an der Implementierung. Man konnte auch einfach sagen "Die Summe der Berechnung". So, damit hätte ich jetzt diese Methode kommentiert. Was bringt mir das Ganze jetzt an der Stelle? Wen wir jetzt hier die Class1 und wir gehen mal innerhalb unsere Projektmappe in die entsprechende Program.cs und legen uns von Class1 mal ein Objekt an. In den Fall, wo ich jetzt hier Class 1 anlegen möchte sieht man in IntelliSense diese XML-Kommentar, den ich eben hinzugefügt habe, wird jetzt hier direkt in den IntelliSense angezeigt. Das heißt, ich sehe jetzt hier "Diese ist Class1. Sie hat eigentlich keinen Zweck" Okay, sehr gut, erstellen wir mal ein Objekt, und rufen mal von Class1 entsprechend unsere Methode DoFoo auf. Man sieht, "Macht eigentlich gar nix..." DoBar, "Die Methode auch nichts" und ich öffne jetzt hier mal die entsprechenden Parameter und dort sehe ich jetzt, okay, der Parameter z1 und unten wird mir der Parameter z1 beschrieben, "Das ist der Parameter z1, der Bruder von z2". Also schreiben wir für z1 mal 5 und sobald wir das Komma machen, swicht auch IntelliSense unten die Beschreibung um und jetzt sehe ich die Beschreibung für z1. Also gehen wir jetzt hier mal eine 5.6 an, machen ein Semikolon und jetzt ist die Frage, was gibt die Methode überhaupt zurück? Also hover ich über diese Methode drüber und lasse mir jetzt hier den Rückgabewert anzeigen, da komme ich so direkt nicht ran, also catche ich diesen Wert mal eben kurz. Wir suchen uns also jetzt die Information mal an einer anderen Stelle, und zwar schauen wir uns jetzt mal den Objektkatalog an. Diese Information, die wir im Hintergrund beschrieben haben können natürlich jetzt nicht nur von den IntelliSense ausgelesen werden, sondern auch von unserem Objektkatalog. Und wir sind ja immer noch die Information schuldig, was genau kommt in der Methode zurück. Dazu gehen wir jetzt mal hier hin und jetzt suchen wir mal unsere Class1. Und die taucht natürlich auch hier im Objektkatalog auf. Und wir sehen das jetzt hier, das ist genau unsere Methode und hier unten in dieser, ja, in dieser textuellen Hilfe sehen wir jetzt, okay, "Zusammenfassung", das war Summary was wir eben angegeben haben, sehen wir das wir im XML-Kommentar eben kommentiert haben. Das Gleiche gilt natürlich jetzt hier auch für DoBar. Das ist die Zusammenfassung hier, "die Methode auch nichts" also die macht nichts, dann hier die Parameterbeschreibung, "z1, z2" und Rückgabewert ist dann "die Summe der Berechnung". Das wie gesagt sind XML-Kommentare. Das kann man noch ein bisschen erweitern. Ich könnte jetzt hier sagen, okay, es gibt hier noch eine ganze Menge weitere Elemente. Wenn ich an der Stelle hier mal ein XML-Tag öffne, sieht man hier gibt man eine ganze Menge: permission, remarks, also, value, exception, nehmen wir mal Exception an der Stelle und sagen, okay, also diese Methode hier ist in der Lage ein "ArgumentNullException" zu schmeißen, ich vermute mal, dass ich da noch "System" vorschreiben muss, also "System.ArgumentNullException" und jetzt kann ich hier in diesem Element schreiben, wann sie ausgelöst wird, na ja, "Wenn das Argument null ist...". So, nachdem ich das Ganze jetzt hier kodiert habe, schauen wir uns das nochmal im Objektkatalog an. Die Frage ist, wann das Ganze aktualisiert? Ich gehe einmal vor, wieder zurück, gehe auf meine Methode und dann wird mir hier unten unter Ausnahmen angezeigt, okay, diese Methode ist in der Lage eine ArgumentNullException auszulösen wenn das Argument null ist und ich klicke dahin, lande ich dann auch bei der entsprechenden Exception. Das heißt, man kann seinen Code, seine komplette Schnittstelle an der Stelle mit diesem XML-Kommentaren dokumentiert. Wir haben jetzt gesehen diese XML-Kommentare können ausgelesen werden. Einmal vom Objektkatalog, auch von IntelliSense, aber im Prinzip können aber jedes x-beliebige Tool was XML versteht diese Kommentare auslesen, da gibt es eine ganze Menge. Wenn Sie also später auf Basis von Ihren Assemblies eine Dokumentation generieren möchten im XML-Format, im HTML-Format im PDF-Format oder was auch immer, bieten sich solche Tools wie zum Beispiel N-Dog oder [unverständlich] an und damit können Sie dann auf Basis von diesem XML-Dokumenten entsprechend Ihre Dokumentation generieren. Wie kommt man an diese XML-Kommentare in meinen Typen? Nun als aller erstes muss ich hier auf meine Projektmappe gehen zu der ich die entsprechende XML-Kommentare generieren lassen möchte, gehe dann auf "Eigenschaften" und unter dem Punkt "Erstellen" gibt es ganz am Ende die Möglichkeit eine XML-Dokumentationsdatei anzuhaken hier, wenn ich das weglasse wird Sie nicht generiert, wenn ich sie hinzufüge wird Sie generiert. Hier sieht man auch den entsprechenden Namen und nachdem das aktiviert habe kompiliere ich Anwendung mit "Erstellen" ein einziges Mal und danach kann ich über Ordner in Datei Explorer öffnen, hier an dieser Stelle in mein bin-Ordner reingehen, Debug, und hier befindet sich dann meine XML-Datei, die dann entsprechend mit dem Editor öffnen könnten und hier sehe ich dann, dass ist eine reine XML-Beschreibung meiner kompletten dokumentierten Klassenstruktur innerhalb der Anwendung und aus dieser dokumentierten Klassenstruktur hier kann ich dann entsprechend mit irgendeinem Tool was XML versteht mir eine Dokumentation bauen. Wir haben und in diesem Video angeschaut wie man mit Hilfe von XML-Kommentaren eigene Datentypen und Member in diesen Datentypen kommentieren kann. Das ganze funktioniert mit drei hintereinander folgenden Slashes generiert Visual Studio so ein Grundgerüst und dieses Grundgerüst kann dann ausformuliert werden. Man kann aber noch weitere Elemente in diesem Grundgerüst hinzufügen zum Beispiel für Parameter, Rückgabewerte oder Exceptions. Wenn ich das Ganze gemacht habe, kann ich an verschiedenen Stellen innerhalb von Visual Studio diese XML-Kommentare auswerten, wie zum Beispiel Objektkatalog oder im IntelliSense selber. Wenn ich ein eigenes Tool schreiben möchte, kann ich in den Projekteinstellungen hinterlegen, dass entsprechend eine XML-Dokumentation erzeugt werden sollen und mit setzen des Hackens landet dann die entsprechende XML-Dokumentation in meinem Ausgabeordner und wenn man ihn öffnet, sieht man, dass man eine ganz normale XML-Datei bekommt, die man mit jedem Programm oder mit jeder x-beliebigen Programmiersprache verarbeiten und aufbereiten könnte.

Derzeit sind keine Feedbacks vorhanden...
 

Dieser Online-Kurs ist als Download und als Streaming-Video verfügbar. Die gute Nachricht: Sie müssen sich nicht entscheiden - sobald Sie das Training erwerben, erhalten Sie Zugang zu beiden Optionen!

Der Download ermöglicht Ihnen die Offline-Nutzung des Trainings und bietet die Vorteile einer benutzerfreundlichen Abspielumgebung. Wenn Sie an verschiedenen Computern arbeiten, oder nicht den ganzen Kurs auf einmal herunterladen möchten, loggen Sie sich auf dieser Seite ein, um alle Videos des Trainings als Streaming-Video anzusehen.

Wir hoffen, dass Sie viel Freude und Erfolg mit diesem Video-Training haben werden. Falls Sie irgendwelche Fragen haben, zögern Sie nicht uns zu kontaktieren!