Rheinwerk Computing < openbook > Rheinwerk Computing - Professionelle Bücher. Auch für Einsteiger.
Professionelle Bücher. Auch für Einsteiger.

Inhaltsverzeichnis
Vorwort zur 6. Auflage
1 Allgemeine Einführung in .NET
2 Grundlagen der Sprache C#
3 Das Klassendesign
4 Vererbung, Polymorphie und Interfaces
5 Delegates und Ereignisse
6 Strukturen und Enumerationen
7 Fehlerbehandlung und Debugging
8 Auflistungsklassen (Collections)
9 Generics – Generische Datentypen
10 Weitere C#-Sprachfeatures
11 LINQ
12 Arbeiten mit Dateien und Streams
13 Binäre Serialisierung
14 XML
15 Multithreading und die Task Parallel Library (TPL)
16 Einige wichtige .NET-Klassen
17 Projektmanagement und Visual Studio 2012
18 Einführung in die WPF und XAML
19 WPF-Layout-Container
20 Fenster in der WPF
21 WPF-Steuerelemente
22 Elementbindungen
23 Konzepte von WPF
24 Datenbindung
25 Weitere Möglichkeiten der Datenbindung
26 Dependency Properties
27 Ereignisse in der WPF
28 WPF-Commands
29 Benutzerdefinierte Controls
30 2D-Grafik
31 ADO.NET – Verbindungsorientierte Objekte
32 ADO.NET – Das Command-Objekt
33 ADO.NET – Der SqlDataAdapter
34 ADO.NET – Daten im lokalen Speicher
35 ADO.NET – Aktualisieren der Datenbank
36 Stark typisierte DataSets
37 Einführung in das ADO.NET Entity Framework
38 Datenabfragen des Entity Data Models (EDM)
39 Entitätsaktualisierung und Zustandsverwaltung
40 Konflikte behandeln
41 Plain Old CLR Objects (POCOs)
Stichwort

Download:
- Beispiele, ca. 62,4 MB

Jetzt Buch bestellen
Ihre Meinung?

Spacer
Visual C# 2012 von Andreas Kühnel
Das umfassende Handbuch
Buch: Visual C# 2012

Visual C# 2012
Rheinwerk Computing
1402 S., 6., aktualisierte und erweiterte Auflage 2013, geb., mit DVD
49,90 Euro, ISBN 978-3-8362-1997-6
Pfeil 17 Projektmanagement und Visual Studio 2012
Pfeil 17.1 Der Projekttyp »Klassenbibliothek«
Pfeil 17.1.1 Mehrere Projekte in einer Projektmappe verwalten
Pfeil 17.1.2 Die Zugriffsmodifizierer »public« und »internal«
Pfeil 17.1.3 Friend Assemblys
Pfeil 17.1.4 Einbinden einer Klassenbibliothek
Pfeil 17.2 Assemblys
Pfeil 17.2.1 Ein Überblick über das Konzept der Assemblys
Pfeil 17.2.2 Allgemeine Beschreibung privater und globaler Assemblys
Pfeil 17.2.3 Die Struktur einer Assembly
Pfeil 17.2.4 Globale Assemblys
Pfeil 17.3 Konfigurationsdateien
Pfeil 17.3.1 Die verschiedenen Konfigurationsdateien
Pfeil 17.3.2 Die Struktur einer Anwendungskonfigurationsdatei
Pfeil 17.3.3 Eine Anwendungskonfigurationsdatei mit Visual Studio 2012 bereitstellen
Pfeil 17.3.4 Einträge der Anwendungskonfigurationsdatei auswerten
Pfeil 17.3.5 Editierbare, anwendungsbezogene Einträge mit <appSettings>
Pfeil 17.4 Versionsumleitung in einer Konfigurationsdatei
Pfeil 17.4.1 Die Herausgeberrichtliniendatei
Pfeil 17.5 XML-Dokumentation
Pfeil 17.5.1 Das Prinzip der XML-Dokumentation
Pfeil 17.5.2 Die XML-Kommentartags
Pfeil 17.5.3 Generieren der XML-Dokumentationsdatei
Pfeil 17.6 Der Klassendesigner (Class Designer)
Pfeil 17.6.1 Ein typisches Klassendiagramm
Pfeil 17.6.2 Hinzufügen und Ansicht von Klassendiagrammen
Pfeil 17.6.3 Die Toolbox des Klassendesigners
Pfeil 17.6.4 Das Fenster »Klassendetails«
Pfeil 17.6.5 Klassendiagramme als Bilder exportieren
Pfeil 17.7 Refactoring
Pfeil 17.7.1 Methode extrahieren
Pfeil 17.7.2 Bezeichner umbenennen
Pfeil 17.7.3 Felder einkapseln
Pfeil 17.8 Code-Snippets (Codeausschnitte)
Pfeil 17.8.1 Codeausschnitte einfügen
Pfeil 17.8.2 Die Anatomie eines Codeausschnitts
Pfeil 17.9 »ClickOnce«-Verteilung
Pfeil 17.9.1 Allgemeine Beschreibung
Pfeil 17.9.2 Erstellen einer ClickOnce-Anwendung
Pfeil 17.9.3 Die Installation einer ClickOnce-Anwendung

Rheinwerk Computing - Zum Seitenanfang

17.5 XML-DokumentationZur nächsten Überschrift

In C# lässt sich der Programmcode bereits innerhalb des Code-Editors dokumentieren. Dazu werden XML-Tags in spezielle Kommentarfelder des Quellcodes eingefügt, die unmittelbar vor dem Codeblock stehen, auf den sie sich beziehen. Auf diese Weise können Typen wie Klassen, Enumerationen, Delegates, Schnittstellen und Strukturen sowie deren Eigenschaften, Felder, Methoden, Ereignisse usw. beschrieben werden.

Der Clou bei der XML-Dokumentation ist, den Code mit zusätzlichen Informationen zu versorgen, die sowohl in der IntelleSense-Hilfe als auch im Objektkatalog nachzulesen sind. Darüber hinaus lässt sich die XML-Dokumentation auch in XML-Dateien veröffentlichen. Die XML-Dokumentationsdateien ersetzen sicherlich nicht eine konventionelle und aufwendige Dokumentation, können aber dennoch zumindest bei der Entwicklung hilfreich sein.


Rheinwerk Computing - Zum Seitenanfang

17.5.1 Das Prinzip der XML-DokumentationZur nächsten ÜberschriftZur vorigen Überschrift

Nehmen wir zu Demonstrationszwecken die Methode GetArea der Klasse Circle, die wir dokumentieren möchten:

public static double GetFlaeche(int radius) {
return Math.PI * Math.Pow(radius, 2);
}

XML-Dokumentationen werden dem Element vorangestellt, das dokumentiert werden soll. Eingeleitet werden die Kommentarfelder mit drei Schrägstrichen. Wenn Sie den Cursor vor das zu dokumentierende Element positionieren und die drei einleitenden Schrägstriche in den Code vor eine Klassendefinition schreiben, wird der folgende XML-Kommentar automatisch ergänzt:

/// <summary>
///
/// </summary>
/// <param name="radius"></param>
/// <returns></returns>

Zwischen dem ein- und ausleitenden <summary>-Tag können Sie eine Beschreibung eintragen, die später vom zu generierenden XML-Dokument übernommen wird. Zudem wird die Beschreibung in der IntelliSense-Hilfe und im Objektkatalog angezeigt. Die Beschreibung zwischen <summary> und </summary> sollte kurz gehalten werden. Für ausführlichere Beschreibungen steht Ihnen mit <remarks> ein geeigneteres Tag zur Verfügung.

Sie können sehen, dass über <summary> hinaus noch weitere vordefinierte XML-Dokumentationstags angeboten werden. Das Attribut name des <param>-Tags enthält den Bezeichner des Parameters. Zwischen dem ein- und ausleitenden Tag dürfen Sie auch eine spezifische Beschreibung eintragen. Diese wird vom späteren XML-Dokument übernommen und im Objektkatalog angezeigt, allerdings nicht in IntelliSense. <returns> dient zur Beschreibung des Rückgabewertes. Für dieses Tag gilt hinsichtlich der Anzeige dasselbe wie für <param>.

Sehen wir uns an dieser Stelle einmal einen etwas aufwendigeren XML-Kommentar sowie dessen Auswirkungen an.

/// <summary>
/// Berechnet die Fläche eines beliebigen Kreises
/// </summary>
/// <param name="radius">Geben Sie hier den Radius des zu
berechnenden Kreises an
/// </param>
/// <returns>Liefert die Kreisfläche</returns>
/// <remarks>Die Methode ist 'static' definiert.
/// <para>Sie müssen diese Methode auf den Klassenbezeichner aufrufen.
/// </para>
/// </remarks>
public static double GetFlaeche(double radius)
{
return Math.PI * Math.Pow(radius, 2);
}

Mit dem Objektkatalog, der über das Menü Ansicht geöffnet wird, können Sie Objekte (Namespaces, Klassen, Strukturen, Schnittstellen, Typen, Enumerationen usw.) und ihre Member (Eigenschaften, Methoden, Ereignisse, Variablen, Konstanten, Enumerationselemente) aus verschiedenen Komponenten suchen und überprüfen. Bei diesen Komponenten kann es sich um Projekte in der Projektmappe, um referenzierte Komponenten innerhalb dieser Projekte und um externe Komponenten handeln.

Schauen Sie sich im Objektkatalog nun die Ausgabe zu der Methode GetArea an (siehe Abbildung 17.9).

Abbildung

Abbildung 17.9 Ausgabe des XML-Kommentars im Objektkatalog

Ich glaube, dass Sie auch ohne eine langatmige Beschreibung erkennen können, welche Bereiche den einzelnen Tags zugeordnet werden. Im Code-Editor hingegen wird nur die Beschreibung angezeigt, die hinter <summary> angegeben ist (siehe Abbildung 17.10).

Abbildung

Abbildung 17.10 Anzeige der XML-Dokumentinformationen im Code-Editor


Rheinwerk Computing - Zum Seitenanfang

17.5.2 Die XML-KommentartagsZur nächsten ÜberschriftZur vorigen Überschrift

Ich habe Ihnen bisher einige, aber nicht alle Tags vorgestellt, die zur XML-Dokumentation dienen. In Tabelle 17.5 stelle ich Ihnen alle der Übersicht halber vor.

Tabelle 17.5 Die vordefinierten XML-Dokumentationstags

XML-Dokumentationstag Beschreibung

<c>

Kennzeichnet, dass dieser Text in einer Beschreibung als Code erscheinen soll.

<code>

Kennzeichnet, dass mehrere Zeilen als Code dargestellt werden sollen.

<example>

Kennzeichnet ein Beispiel zur Verwendung einer Klasse oder Methode.

<exception>

Wird zur Dokumentation der Ausnahmen verwendet, die von einer Klasse ausgelöst werden können.

<include>

Mit diesem Tag kann auf Kommentare in anderen Dateien verwiesen werden, die die Typen und Member im Quellcode beschreiben.

<list>

Kennzeichnet eine Liste von Elementen.

<para>

Dieses Tag ist für die Verwendung innerhalb eines Tags, wie beispielsweise <summary>, <remarks> und <returns> vorgesehen und ermöglicht die Strukturierung des Textes.

<param>

Dieses Tag sollte im Kommentar für eine Methodendeklaration verwendet werden, um einen der Parameter der Methode zu beschreiben. Der Text wird in IntelliSense und im Objektkatalog über Codekommentare angezeigt.

<paramref>

Ein Verweis auf einen anderen Parameter.

<permission>

Wird zur Beschreibung der Zugriffsberechtigungen für einen Member verwendet.

<remarks>

Eine Beschreibung des Elements, die <summary> ergänzt. Die Informationen werden im Objektkatalog angezeigt.

<returns>

Dokumentiert den Rückgabewert einer Methode.

<see>

Wird zum Querverweis auf verwandte Elemente verwendet.

<seealso>

Eine Verknüpfung zum »Siehe auch«-Abschnitt der Dokumentation.

<summary>

Eine kurze Beschreibung des Elements, die in IntelliSense und im Objektkatalog angezeigt wird.

<typeparam>

Dieses Tag sollte in dem Kommentar für einen generischen Typ oder eine Methodendeklaration zum Beschreiben eines Typparameters verwendet werden. Fügen Sie für jeden Typparameter des generischen Typs oder der Methode ein Tag hinzu.

<typeparamref>

Der Name des Typparameters.

<value>

Beschreibt den Wert einer Eigenschaft.


Rheinwerk Computing - Zum Seitenanfang

17.5.3 Generieren der XML-DokumentationsdateiZur vorigen Überschrift

Die Typen und deren Member mit XML-Kommentar zu versehen reicht zwar schon aus, um im Objektkatalog oder in der IntelliSense-Hilfe den Benutzer mit grundlegenden Informationen zu versorgen, aber damit wird nicht sofort ein XML-Dokument erzeugt, das sich beispielsweise zu einer Integration in eine Hilfe eignet und durchaus auch noch weitere Informationen bereitstellen kann.

Um aus den XML-Kommentaren eine XML-Dokumentationsdatei zu erzeugen, müssen Sie das Projekteigenschaftsfenster öffnen. Doppelklicken Sie dazu auf den Knoten Properties. Am rechten Rand sind mehrere Laschen gruppiert; klicken Sie hier auf Erstellen (siehe Abbildung 17.11). Auf der nun angezeigten Registerkarte setzen Sie ein Häkchen neben XML-Dokumentationsdatei. Damit ist alles Notwendige erledigt. Die Vorgabe des Ausgabeordners und den Bezeichner der XML-Dokumentationsdatei können Sie im Bedarfsfall auch ändern.

Abbildung

Abbildung 17.11 Das Erzeugen eines XML-Dokumentationsdokuments einstellen

Wir sollten auch einen Blick in das erzeugte Dokument werfen. Das gesamte Dokument wird in <doc>-Tags eingefasst. <doc> umfasst neben der Bekanntgabe des Dokumentationsnamens in <assembly> im Bereich <members> auch alle Tags, die wir im Code-Editor aufgeführt haben.

<?xml version="1.0"?>
<doc>
<assembly>
<name>CircleApplication6</name>
</assembly>
<members>
<member name="M:CircleApplication.Circle.GetFlaeche(System.Double)">
<summary> Berechnet die Fläche eines beliebigen Kreises
</summary>
<param name="radius">Geben Sie hier den Radius des zu berechnenden Kreises an
</param>
<returns>Liefert die Kreisfläche</returns>
<remarks>Die Methode ist 'static' definiert.
<para>Sie müssen diese Methode auf den Klassenbezeichner aufrufen.
</para>
</remarks>
</member>
</members>
</doc>

Listing 17.5 Inhalt der XML-Dokumentationsdatei



Ihre Meinung

Wie hat Ihnen das Openbook gefallen? Wir freuen uns immer über Ihre Rückmeldung. Schreiben Sie uns gerne Ihr Feedback als E-Mail an kommunikation@rheinwerk-verlag.de.

<< zurück
  Zum Rheinwerk-Shop
Zum Rheinwerk-Shop: Visual C# 2012

Visual C# 2012
Jetzt Buch bestellen


 Ihre Meinung?
Wie hat Ihnen das Openbook gefallen?
Ihre Meinung

 Buchempfehlungen
Zum Rheinwerk-Shop: Professionell entwickeln mit Visual C# 2012






 Professionell
 entwickeln mit
 Visual C# 2012


Zum Rheinwerk-Shop: Windows Presentation Foundation






 Windows Presentation
 Foundation


Zum Rheinwerk-Shop: Schrödinger programmiert C++






 Schrödinger
 programmiert C++


Zum Rheinwerk-Shop: C++ Handbuch






 C++ Handbuch


Zum Rheinwerk-Shop: C/C++






 C/C++


 Lieferung
Versandkostenfrei bestellen in Deutschland, Österreich und der Schweiz
InfoInfo





Copyright © Rheinwerk Verlag GmbH 2013
Für Ihren privaten Gebrauch dürfen Sie die Online-Version natürlich ausdrucken. Ansonsten unterliegt das Openbook denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt.
Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Nutzungsbestimmungen | Datenschutz | Impressum

Rheinwerk Verlag GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, service@rheinwerk-verlag.de

Cookie-Einstellungen ändern