Dieser Artikel wurde maschinell übersetzt.

table.one { table-layout:fixed; width : 900px; } table.two { table-layout:fixed;width:900px; margin-bottom: 10px; } .tdwidth{ width:100px; }

Basic Instincts

Dokumentieren Ihren Code mit XML-Kommentare

Lisa Feigenbaum

Dieser Artikel basiert teilweise auf einer Vorabversion von Visual Studio. Allen Informationen sind vorbehalten.

Inhalt

XML-Kommentar-Grundlagen
Anpassen von XML-Kommentare
Generieren die Dokumentation zu XML-Datei
Verbesserung von Visual Studio mit XML-Kommentare
Vorteile der kommentieren Teilnehmer sonst ist Code
Tricks von .NET-Framework
Generieren von Nicer-Dokumentation
XML-Kommentare in Visual Studio-2010

Eine einfache noch effektiver Möglichkeit dokumentieren Sie Ihren code suchen? XML-Kommentare bieten es sich um eine gute Lösung. XML-Kommentare für Visual Basic wurden zunächst in Visual Studio 2005 eingeführt. Sie können zum Erstellen einer Dokumentation-Datei für das Projekt verwendet werden, und ein Rich-Entwicklung Umgebung Erlebnis zu bieten selbst, Ihre Teamkollegen oder andere Personen, die mit Ihrem code.

In diesem Artikel wird ich Sie mehr über XML-Kommentare und diese Verwendung erläutert. Es werden Möglichkeiten untersuchen, in denen XML-Kommentaren die Codierung Umgebung anpassen und zum Erstellen von Dokumentationsdateien aus den Kommentaren im code verwendet werden können. Ich zeigt Sie einige zukünftige features von Visual Studio außerdem, die eine auch Erleichterung für das Arbeiten mit XML-Kommentare in Ihrem code erstellen.

XML-Kommentar-Grundlagen

XML-Kommentaren können zum Dokumentieren der fast alle Definitionen außer namespaces verwendet werden. Dies ist der beinhaltet, Typen (Klasse, Modul, Interface, Struktur, Aufzählen, delegieren), Felder (Dim), Eigenschaften (Eigenschaft), Ereignisse (Ereignis) sowie Methoden (Sub-Funktion, Declare,-Operator).

XML-Kommentare sind eingefügten inline, direkt in Ihren Quellcode. Dadurch leichter auf Sie während der code entwickelt sich auf dem neuesten Stand halten. Zum Einfügen eines XML-Kommentar Geben Sie drei einseitige Anführungszeichen einschließen (" ") direkt über die definition, wie folgt:

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Alternativ können Sie auch eingeben " "am Anfang des definition Zeilen- und betätigen Sie Enter. Visual Studio fügt ein Gerüst des XML-Kommentars zur füllen.

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Habe zum Zweck der diesem Artikel ich verwendet eine einfache Funktion mit einem parameter, um des XML-Kommentare Features zu demonstrieren. Das XML-Gerüst variiert entsprechend der definition. Das XML-Gerüst für eine Funktion enthält z. B. ein element zurückgegeben, während das Gerüst für eine Sub-nicht. Die Anzahl von param-tags für Methoden werden außerdem basierend auf die Anzahl von Parametern variieren.

Bitte beachten Sie, obwohl Visual Studio das entsprechende XML-Gerüst für die definition Fügt und einige Warnungen bereitgestellt werden, werden wenn der Kommentar der Synchronisierung erhält, aus, nicht automatisch den Kommentar für Sie korrigiert werden. Daher sicherstellen Sie um den Kommentar zu aktualisieren, wenn Sie auf die definition Änderungen vornehmen.

Wenn das XML-Gerüst eingefügt wird, können Sie über den Inhalt wells um Ihre Kommentare einzufügen Registerkarte. Visual Studio colorizes den XML-Inhalt als die tags. Sie können Elemente auch löschen, wenn Sie Sie z. B. das element hinweisen.

Schließlich können Sie Elemente hinzufügen, die nicht in der ursprünglichen XML-elementaren waren. Sie beginnen eine linke spitze Klammer (<) eingeben, wird eine Liste der häufig verwendete tags in einem Popup IntelliSense-Menü angezeigt wie in dargestellt Abbildung 1 .

Abbildung 1 XML-Bemerkungen in IntelliSense

Sie können eine beliebige gültige XML-zum XML-Kommentar hinzufügen. Eine Liste der häufig verwendete tags kann in diesem Artikel finden"XML-Tags für die Dokumentation zu Kommentare (Visual Basic) empfohlen.." Wenn der Kommentar zu viel Speicherplatz benötigt, können Sie es der Zusammenfassung mit Reduzieren der +/-Steuerelemente auf der linken Seite des code-editor, wie in dargestellt Abbildung 2 .

Abbildung 2 reduziert-XML-Kommentar

Anpassen von XML-Kommentare

Im vorherigen Beispiel versucht es eine Reihe von Änderungen, zu der ursprünglichen XML-elementaren. Entwickler, die in einer Unternehmensumgebung arbeiten müssen möglicherweise die Standard XML-Kommentaren entsprechend Ihrer bestimmten Unternehmen Richtlinien zu ändern. Bei diesen Szenarios helfen zu können, bietet Visual Basic eine Möglichkeit aus, um das Standard-XML-Gerüst anzupassen.

Erstellen Sie zunächst eine neue XML-Datei namens VBXMLDoc.xml, die die Standardvorlagen Kommentar enthält. Eine Beispieldatei ist im Codedownload für diesen Artikel enthalten. Speichern Sie VBXMLDoc.xml, auf den entsprechenden Speicherort auf Ihrer version von Windows und Visual Studio basieren werden, wie in Abbildung 3 dargestellt. <user>Ersetzen Sie in jedem Fall <benutzer> im Pfad durch Ihren eigenen Benutzernamen ein.

Visual Studio hat integrierte Standardeinstellungen für die XML-skeletons, die eingefügt haben, erhalten, wenn VBXMLDoc.xml beim Programmstart vorhanden ist, Visual Studio verwenden jedoch die XML-Definitionen aus dieser Datei stattdessen. Die version von VBXMLDoc.xml in den Codedownload bereitgestellten enthält die Standard-tags, die andernfalls von Visual Studio eingefügt werden, würde eine. Um die Standardeinstellungen zu ändern, suchen Sie den code Elementtyp, dem Sie interessiert sind, und bearbeiten Sie die XML-Elemente in der Datei.

Ein Beispiel ändern wir das XML-Gerüst, das für die Funktion eingefügt wird. Abbildung 4 zeigt die Standardeinstellung und die angepasste Einträge für eine Funktion. Das Template-element untergeordneten Elemente darstellen der XML-Elemente, die in der XML-Kommentar elementaren eingefügt werden soll. Die CompletionList des-Elemente repräsentieren die Vorschläge, die in IntelliSense angezeigt wird, bei der Eingabe einer linken spitze Klammer (<) über eine Funktion.

Abbildung 4 XML-Tags für-Funktion

Standard-XML-

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>

Benutzerdefinierte XML-

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <author/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <returns/>
    <summary/>
    <author/>
    <history/>
  </CompletionList>
</CodeElement>

Wie Sie im zweiten Teil der Abbildung 4 sehen können, vorgenommen ich einige einfache Anpassungen an. Zunächst entfernt ich das element hinweisen aus die Standard-Gerüst und IntelliSense. Auch, hinzugefügt ein author-Element die Standard-Gerüst und IntelliSense und IntelliSense ein Verlauf-element hinzugefügt.

Zu diesem Zeitpunkt müssen Sie schließen und öffnen Sie Visual Studio für die Änderungen in VBXMLDoc.xml, die kommissioniert erhalten, bis es erneut. Nach dem Neustart werden die XML-Kommentare, die automatisch eingefügt, über die Funktion ein author-Element anstelle von Anmerkungen gehören:

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Zwar es möglich ist, die Vorlage XML-Elemente hinzuzufügen, ist es nicht möglich, um XML-Werte zu addieren. Daher können Sie die IDE-einfügen <author> </author> der Standardeinstellung ist jedoch nicht möglich, die es das Einfügen von <author> Microsoft Corporation </author>.

Generieren die Dokumentation zu XML-Datei

Der Visual Basic-compiler generiert ein XML-Dokument für die assembly, mit allen XML-Kommentaren, die in den code definierten. Der compiler wird auch lösen Sie Symbole cref, Berechtigungen und Namenattribute, auch als Datei Verweise im enthalten Elemente.

Die generierte Datei anzeigen nicht die kommentierte Elemente hierarchisch. Vielmehr ist es eine flache Liste. Es enthält eine eindeutige ID-Zeichenfolge für jede definition, mit dem die Kommentare an Ihre Definitionen im code zugeordnet werden kann (siehe Abbildung 5 ). In diesem Fall ist die Zeichenfolge M:RegLib.helpers.RegKeyExists(System.String). M steht für Methode, RegLib.helpers Gibt den Pfad, RegKeyExists die Methodennamen, und System.String den Parametertyp.

Abbildung 5 generierte XML-Dokument Auszug

<?xml version="1.0" ?>
<doc>
<assembly>
<name>RegLib</name>
</assembly>
<members>
...
<member name="M:RegLib.Helpers.RegKeyExists(System.String)">
  <summary>Determines whether a specific registry key exists.</summary>
  <param name="regKey">Name or path of the registry key.</param>
  <returns>True if the registry key exists; otherwise, False.</returns>
  <author>Microsoft Corporation</author>
</member>
...
</members>
</doc>

Sie können Generieren der XML-Dokumentation Datei mit einer den Befehlszeilen-compiler oder über die Visual Studio-Schnittstelle. Wenn Sie mit der Befehlszeilen-compiler kompilieren, verwenden Sie die Optionen /doc " oder " Dokument +. Eine XML-Datei mit demselben Namen und den gleichen Pfad wie die assembly generiert. Um einen anderen Dateinamen zu anzugeben, verwenden Sie /doc:file.

Wenn Sie die Visual Studio-Schnittstelle verwenden, ist eine Einstellung, die steuert, ob die XML-Dokumentation-Datei erstellt wird. Um es zu festzulegen, doppelklicken Sie auf eigenes Projekt im Projektmappen-Explorer um den Projekt-Designer zu öffnen. Navigieren Sie zur Registerkarte kompilieren. Suchen ' Generieren von XML-Dokumentationsdatei " am Ende das Fenster, und stellen Sie sicher, es wird überprüft. Standardmäßig ist diese Einstellung auf. Erzeugt eine XML-Datei mithilfe dem gleichen Namen und Pfad als der assembly.

Mein Beispiel ist ein Bibliothek-Projekt für Klasse, das RegLib, aufgerufen, damit die assembly und XML Dokumentationsdatei RegLib.dll und RegLib.xml, bzw.. Der Pfad, in dem Sie erstellt werden, wird in das Textfeld "Generator Ausgabe Pfad" aufgeführt. Es muss ein expliziter build für diese Dateien zu produzierende vorhanden sein.

Microsoft verwendet XML-Kommentare, um Dokumentation für alle die Microsoft .NET-Framework-Assemblys zu generieren. Der XML-Dokumentation, die neben die DLL-Dateien befinden, die Sie dokumentieren, und diese Namen übereinstimmen.

Verbesserung von Visual Studio mit XML-Kommentare

Viele Funktionen von Visual Studio verwenden XML-Kommentare, um eine Erleichterung für das Arbeiten mit Elementen zu bereitzustellen. Da der Visual Basic-compiler immer im Hintergrund ausgeführt wird, können Visual Studio XML-Kommentaren nutzen, wie Sie erstellt wurden, ohne eine explizite Erstellung.

Die weitesten verbreitete Stelle, wo die XML-Kommentare verwendet werden, ist IntelliSense. Der Zusammenfassung Inhalt aus dem XML-Kommentar wird sich in der QuickInfo. Während die Methode verwendet wird, zeigt IntelliSense auch den param-Inhalt im So parameter Hilfe QuickInfo genannten (siehe Abbildung 6 ).

Abbildung 6- Parameter Hilfe QuickInfo, die mit XML-Kommentar

Untersuchen die Elemente in der Objektkatalog ist eine deutlich verbesserte Erfahrung mit XML-Kommentaren. Objektkatalog zeigt Zusammenfassung, param, Reklamation, Anmerkungen, typeparam und Ausnahme Kommentare, wenn Sie vorhanden sind (siehe Abbildung 7 ). Klasse-Designer, Klassenansicht und Test-Bench-Objekt verwenden auch XML-Kommentare, wenn Sie verfügbar sind.

Abbildung 7 -Objektbrowser, die mit XML-Kommentare

Vorteile der kommentieren Teilnehmer sonst ist Code

Zuvor gezeigt ich zum der Visual Studio-experience für eine Funktion anpassen, indem Sie dessen definition XML-Kommentare hinzufügen. Für Elemente in der referenzierten Assemblys definiert ist es jedoch nicht praktisch den gleichen Vorgang folgen, da Sie unbedingt Zugriff auf die Quelle nicht. Glücklicherweise ist gibt es ein anderen Prozess (auch auf XML-Kommentare), den Sie für referenzierte Elemente verwenden können!

Es gibt eine wichtiger Unterschied. Mitglieder in der aktuellen Projektmappe arbeiten features von Visual Studio gegen eine speicherresidente Darstellung von der XML-Kommentaren basierend auf der Datenquelle. In diesem Fall wird die XML-Dokumentation-Datei ist lediglich eine Ausgabe und auch muss für die Visual Studio-Funktionen arbeiten generiert werden. Andererseits, im Fall von referenzierten Assemblys, die XML-Dokumentationsdateien werden lesen als Eingaben, und wirken sich Verhalten in der Codierung-Umgebung.

Sehen wir uns ein Beispiel. ICH ein neues Projekt erstellen und verweisen die assembly, dass es frühere (RegLib.dll) erstellt. Die erzeugte XML-Dokumentation-Datei (RegLib.xml) muss neben der assembly sich und muss denselben Namen haben. Wenn ich die RegKeyExists-Methode aus dem aktuellen Projekt zugreifen, wird es in IntelliSense angezeigt. Jedoch kann ich die Darstellung ändern.

Ich öffnen Sie RegLib.xml, und ändern Sie den zusammengefassten Inhalt "legt fest, ob der Registrierungsschlüssel vorhanden ist." Die Aktualisierung sofort geschieht, und das nächste Mal, das wird das Element in der IntelliSense, zugegriffen, ich den neuen text in der QuickInfo (siehe sehen Abbildung 8 ).

Abbildung 8 IntelliSense-QuickInfo

Tricks von .NET-Framework

Das .NET Framework ist ein weiteres Beispiel Assemblys, die Sie aus Ihren Projekten verweisen. Berücksichtigen Sie die Microsoft.VisualBasic.dll, deren XML Dokumentationsdatei hier aufgeführt wird:

C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml 

Öffnen Sie die XML-Datei und untersuchen Sie die XML-Kommentare. Es gibt einige interessante XML-Elemente, die Sie in der es finden werden. Beispielsweise ermittelt die Filterpriority wie ein Element in einem Visual Basic IntelliSense angezeigt. Der Wert 1 bedeutet, die auf der Registerkarte Allgemeine angezeigt werden sollen, bedeutet 2, er sollte mehr in die Registerkarte Alle angezeigt und 3 bedeutet, dass es von IntelliSense vollständig ausgeblendet werden sollen. Dieses Element (filterpriority) ist auf 1, festgelegt, sodass es in Common angezeigt wird. Sie können auf einfache Weise den Wert filterpriority auf 2 ändern und speichern Sie die XML-Datei aus, sodass das Element auf der Registerkarte Alle angezeigt wird.

Beachten Sie, dass vor der Bearbeitung alle .NET Framework, XML-Dokumentationsdateien, es ratsam, die vorher eine Kopie erstellen. Sie müssen auch die Dateien in einer Anwendung zu öffnen, die Berechtigungen erhöhte hat. Visual Studio ist eine gute Möglichkeit, da Sie das Dateiformat beibehalten wird.

Sie können die Methode, die in diesem Abschnitt beschriebenen Elemente in eine referenzierte assembly beeinflussen, solange Sie Zugriff auf die XML-Dokumentationsdatei haben oder Sie eine erstellen falls diese nicht vorhanden ist. Um die filterpriority eines Elements in der aktuellen assembly definierten zu beeinflussen, verwenden Sie das System.ComponentModel.EditorBrowsable-Attribut.

Ein anderes interessantes element ist die PermissionSet. Gibt dieses element an unter welchen Bedingungen der Zugriff auf angehört. Der Inhalt des Elements bezieht sich auf der System.Security.Permissions.SecurityPermission-Typ.

Wir reduzieren Sie die aktuelle Berechtigungsstufe, und finden Sie unter welche Auswirkungen dies unsere Zugriff auf FileWidth hat. Erstellen einer Verwaltungskonsole oder der Windows-Anwendung. Klicken Sie auf Meine Programme im Projektmappen-Explorer um den Projekt-Designer zu öffnen. Wählen Sie die Registerkarte Sicherheit, und überprüfen Sie "Aktivieren der ClickOnce Sicherheitseinstellungen" und "Dies ist eine teilweise vertrauenswürdigen Anwendung."

Die erforderlichen Berechtigungen sind zu diesem Zeitpunkt nicht verfügbar, damit FileWidth und benachbarten Mitglieder, grayed und in IntelliSense nicht zugegriffen werden. Dieses VBA-feature ist es sich um IntelliSense in Zone bezeichnet. Die QuickInfo zeigt an, welche Berechtigungstyp erforderlich ist das Element verwenden.

Sie können Mitglied XML-Dokumentationsdateien PermissionSet Elemente hinzu, und geben Sie die entsprechende Berechtigung.

Generieren von Nicer-Dokumentation

Von der Visual Basic-compiler generierte XML ist lesbar, aber nicht die meisten benutzerfreundlicher. Eine Reihe von tools wurden erstellt, um nicer suchen Dokumentation zu erstellen, einfacher zu navigieren.

Das erste tool wird aufgerufen. Sandcastle, von Microsoft entwickelt wurde. Erfassen Sie nach der Installation Sandcastle die Assemblys, die Sie dokumentieren werden werden, Abhängigkeiten und die XML-Dokumentationsdateien. Kopieren Sie alle diese Materialien zum vSandcastle-Installationsordner (normalerweise im Files\Sandcastle\Examples\sandcastle).

Öffnen einer Eingabeaufforderung und wechseln Sie zu dem gleichen Verzeichnis und dann führen Sie diesen Befehl:

build_Sandcastle.bat prototype <your assembly name without the file extension>

Verzeichnisse und Dateien werden durch diesen Vorgang generiert.Öffnen Sie das .chm-Verzeichnis, und öffnen Sie die Dateierweiterung CHM-Datei in.Es sollte etwa wie die Hilfe in Abbildung 9 aus.

Abbildung 9 Sandcastle .chm Ausgabe

Das tool bietet eine Reihe von anderen außer Ausgabeformate. chm.Weitere Informationen und Weitere Ankündigungen auf Sandcastle achten Sie den blog unter  blogs.msdn.com/Sandcastle.

NDocist ein weiteres beliebtes tool, das Sie berücksichtigen können, verwenden, oder Sie konnte die leistungsfähigen XML-Funktionen in Visual Basic-9 verwenden, Ihre eigenen benutzerdefinierte tool schreiben!

XML-Kommentare in Visual Studio-2010

Vorwärts suchen, sind neue Möglichkeiten für die Anzeige, die Sie die mit XML-Kommentaren im code interagieren werden können.Der Visual Studio-2010-editor wird geschrieben mit Windows Presentation Foundation (WPF) und Rich-Visualisierungen ermöglicht.Der editor aktualisiert außerdem das beteiligten Verschieben in ein neues Komponente system, die verwaltete Erweiterbarkeit Framework (MEF), ist viel einfacher zu COM-add-ins mit Visual Studio zu registrieren.Abbildung 10 zeigt ein Beispiel für ein XML-Kommentar-viewer, die oben auf der neue editor und component model erstellt wurde.

Abbildung 10- XML-Kommentar-Funktion in Visual Studio-2010

Auf die Schaltfläche klicken in die Parameter der oberen rechten Ecke der Anzeige zwischen dem WPF-Steuerelement und der ursprünglichen XML-Code.Das Steuerelement von WPF bietet sicherlich eine viel klarere Ansicht.Es nutzt auch von WPF-Funktionen wie z. B. Farbverläufe und runden Kanten.WPF ermöglicht die Bilder oder videos zu zu enthalten.Das ist sicherlich einen umfassenden Bereich für Drittanbieter-add-ins in der Visual Studio-2010-Version nutzen.

Senden Sie Fragen und Kommentareinstinct@microsoft.com.

Lisa Feigenbaum ist der Microsoft-Programmmanager, für die Visual Basic-Community.Er ist 2004 ein Mitglied der Visual Basic-team seit.Bevor Sie Ihre derzeitige Rolle von Lisa wurde der Programm-Manager für die Visual Basic-Editor und Debugger, auffeatures wie IntelliSense, Bearbeitung und -fortgesetzt, und code Ausschnitte.Lisa finden Sie auf verschiedene USAund internationale Konferenzen und Benutzergruppen, sehen Sie sich Ihr Channel 9-webcasts, oder lesen Sie Ihre Beiträge auf den VB-Teamblogan  blogs.msdn.com/b/vbteam/.