Übersetzung vorschlagen
 
Andere Vorschläge:

progress indicator
Keine anderen Vorschläge
MSDN Magazin > Home > Ausgaben > 2009 > MSDN Magazin Mai 2009 >  Dokumentieren Ihren Code mit XML-Kommentare
Inhalt anzeigen: Englisch mit deutscher ÜbersetzungInhalt anzeigen: Englisch mit deutscher Übersetzung
Dies sind maschinell übersetzte Inhalte, die von den Mitgliedern der Community bearbeitet werden können. Sie können die Übersetzung verbessern, indem Sie auf den jeweils zum Satz gehörenden Link "Bearbeiten" klicken.Mithilfe des Dropdown-Steuerelements "Inhalt anzeigen" links oben auf der Seite können Sie zudem bestimmen, ob nur der englische Originaltext, nur die deutsche Übersetzung oder beides nebeneinander angezeigt werden.
Basic Instincts
Documenting Your Code With XML Comments
Lisa Feigenbaum

This article is partly based on a prerelease version of Visual Studio. All information is subject to change.

Looking for an easy yet effective way to document your code? XML comments provide a great solution. XML comments for Visual Basic were first introduced in Visual Studio 2005. They can be used to create a documentation file for the project, and provide a rich development environment experience for yourself, your teammates, or other people using your code.
In this article, I will introduce you to XML comments and explain how to use them. I will explore ways in which XML comments can be used to customize your coding environment and to create documentation files from the comments in your code. I will also show you some future Visual Studio features that will create an even better experience for working with XML comments in your code.

XML Comment Basics
XML comments can be used to document almost all definitions except namespaces. This includes types (Class, Module, Interface, Structure, Enum, Delegate), fields (Dim), properties (Property), events (Event), and methods (Sub, Function, Declare, Operator).
XML comments are inserted inline, directly in your source code. This makes it easier to keep them up to date as the code evolves. To insert an XML comment, type three single-quotation marks ('") immediately above the definition, like this: 
'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...
Alternatively, you can also type '" at the start of the definition line and press Enter. Visual Studio will insert a skeleton of the XML comment for you to fill in. 
''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...
For the purpose of this article, I used a simple function with one parameter to demonstrate the XML comments feature. The XML skeleton varies according to the definition. For example, the XML skeleton for a Function includes a returns element, whereas the skeleton for a Sub does not. The number of param tags for methods will also vary based on the number of parameters.
Please note that although Visual Studio will insert the appropriate XML skeleton for the definition, and will provide some warnings if the comment gets out of sync, it will not automatically correct the comment for you. Therefore, make sure to update the comment as you make changes to the definition.
Once the XML skeleton is inserted, you can tab through the content wells to insert your comments. Visual Studio colorizes the XML content distinctly from the tags. You can also delete elements if you don't need them, such as the remarks element.
Finally, you can add elements that were not in the original XML skeleton. As you start typing a left angle bracket (<), a list of common tags will appear in an IntelliSense pop-up menu as shown in Figure 1.
Figure 1 XML Comment in IntelliSense
You can add any valid XML to the XML comment. A list of commonly used tags can be found in the article " Recommended XML Tags for Documentation Comments (Visual Basic) ." If the comment takes up too much space, you can collapse it to its summary using the +/- controls on the left-hand side of the code editor, as shown in Figure 2 .
Figure 2 Collapsed XML Comment

Customizing XML Comments
In the previous example, I made a number of changes to the original XML skeleton. Developers working in an enterprise environment might need to change the default XML comments to match their particular corporate guidelines. To help with these scenarios, Visual Basic provides a way to customize the default XML skeleton.
First, create a new XML file called VBXMLDoc.xml that includes your default comment templates. A sample file is included in the code download for this article. Save VBXMLDoc.xml to the appropriate location based on your version of Windows and Visual Studio as shown in Figure 3. In each case, replace <user> in the path with your own user name.
Figure 3 Where to Save VBXMLDoc.xml
Visual Studio 2005 Visual Studio 2008 Windows XP Windows Vista Path
X   X   C:\Documents and Settings\<user>\Application Data\Microsoft\Visual Studio\8.0
X     X C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\8.0
  X X   C:\Documents and Settings\<user>\Application Data\Microsoft\Visual Studio\9.0
  X   X C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\9.0
Visual Studio has built-in defaults for the XML skeletons that get inserted, but when VBXMLDoc.xml is present upon startup, Visual Studio will use the XML definitions from that file instead. The version of VBXMLDoc.xml provided in the code download contains the default tags that would otherwise be inserted by Visual Studio. To change the defaults, find the code element type you are interested in and edit the XML elements in the file.
As an example, let's change the XML skeleton that gets inserted for Function. Figure 4 shows the default and customized entries for a Function. The Template element's children represent the XML elements that will be inserted in the XML comment skeleton. The CompletionList element's children represent the suggestions that will appear in IntelliSense upon typing a left angle bracket (<) above a Function.
 Figure 4 XML Tags for Function
Default XML 
<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>
Customized 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>
As you can see in the second part of Figure 4, I made a few simple customizations. First, I removed the remarks element from both the default skeleton and IntelliSense. Also, I added an author element to both the default skeleton and IntelliSense, and I added a history element to IntelliSense.
At this point you will need to close and re-open Visual Studio for the changes in VBXMLDoc.xml to get picked up. After restarting, the XML comments automatically inserted above Function will include an author element instead of remarks: 
''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...
While it is possible to add XML elements to the template, it is not possible to add XML values. Thus, you can make the IDE insert <author></author> by default, but it is not possible to make it insert <author>Microsoft Corporation</author>.

Generating the XML Documentation File
The Visual Basic compiler generates an XML document for your assembly with all the XML comments defined in the code. The compiler will also resolve symbols used in cref, permission, and name attributes, as well as file references in include elements.
The generated file doesn't show your commented members hierarchically. Rather, it is a flat list. It includes a unique ID string for each definition that allows the comments to be mapped back to their definitions in code (see Figure 5). In this case, the string is M:RegLib.Helpers.RegKeyExists(System.String). M stands for method, RegLib.Helpers specifies the path, RegKeyExists is the method name, and System.String the parameter type.
 Figure 5 Generated XML Document Excerpt 
<?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>
You can generate the XML documentation file using either the command-line compiler or through the Visual Studio interface. If you are compiling with the command-line compiler, use options /doc or /doc+. That will generate an XML file by the same name and in the same path as the assembly. To specify a different file name, use /doc:file.
If you are using the Visual Studio interface, there's a setting that controls whether the XML documentation file is generated. To set it, double-click My Project in Solution Explorer to open the Project Designer. Navigate to the Compile tab. Find "Generate XML documentation file" at the bottom of the window, and make sure it is checked. By default this setting is on. It generates an XML file using the same name and path as the assembly.
My example is a class library project called RegLib, so the assembly and XML documentation file will be RegLib.dll and RegLib.xml, respectively. The path where they will be created is listed in the "Build output path" textbox. There must be an explicit build for these files to be produced.
Microsoft uses XML comments to generate documentation for all the Microsoft .NET Framework assemblies. The XML documentation files are placed beside the DLLs they document, and they match in name.

Enhancing Visual Studio with XML Comments
Many Visual Studio features use XML comments to provide a better experience for working with members. Because the Visual Basic compiler is always running in background, Visual Studio can consume XML comments as they are authored, without requiring an explicit build.
The most prevalent place where XML comments are used is IntelliSense. The summary content from the XML comment appears in the tooltip. As the method is used, IntelliSense also displays the param content in what is called a parameter help tooltip (see Figure 6).
Figure 6 Parameter Help Tooltip Using XML Comment
Exploring members in the Object Browser is a much improved experience with XML comments. Object Browser displays summary, param, return, remarks, typeparam, and exception comments when they exist (see Figure 7). Class Designer, Class View, and Object Test Bench also use XML comments when they are available.
Figure 7 Object Browser Using XML Comments

The Advantages of Commenting Someone Else's Code
Earlier I demonstrated how to customize the Visual Studio experience for a function by adding XML comments to its definition. For members defined in referenced assemblies, however, it is not practical to follow the same process since you don't necessarily have access to the source. Fortunately, there is a different process (also involving XML comments) that you can use for referenced members!
There is one key difference. For members in the current solution, Visual Studio features work against an in-memory representation of the XML comments based on the source. In that case, the XML documentation file is purely an output and doesn't even need to be generated for the Visual Studio features to work. On the other hand, in the case of referenced assemblies, the XML documentation files are read as inputs, and do influence behavior within the coding environment.
Let's look at an example. I'll create a new project and reference the assembly that I built earlier (RegLib.dll). The generated XML documentation file (RegLib.xml) must be placed beside the assembly and must have the same name. If I access the RegKeyExists method from the current project, it will appear in IntelliSense. However, I can alter its appearance.
I open RegLib.xml and change the summary content to "Determines whether the registry key exists." The update happens immediately, and the next time I access the member in IntelliSense, I see the new text in the tooltip (see Figure 8 ).
Figure 8 IntelliSense Tooltip

Tricks from the .NET Framework
The .NET Framework is another example of assemblies that you reference from your projects. Consider Microsoft.VisualBasic.dll, whose XML documentation file can be found here: 
C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml
Open the XML file and examine the XML comments. There are some interesting XML elements you'll find in there. For example, Filterpriority determines how a member appears in Visual Basic IntelliSense. A value of 1 means that it should appear in the Common tab, 2 means it should appear in the All tab, and 3 means it should be hidden from IntelliSense completely. This member's filterpriority is set to 1, so it will appear in Common. You could easily change the filterpriority value to 2 and save the XML file so the member appears in the All tab.
Note that, before editing any .NET Framework XML documentation files, it's a good idea to make a copy beforehand. You will also need to open the files in an application that has elevated privileges. Visual Studio is a good option since it will preserve the file format.
You can use the methodology described in this section to influence members in a referenced assembly, as long as you have access to its XML documentation file or you can create one if it doesn't exist. To influence the filterpriority of a member defined in the current assembly, use the System.ComponentModel.EditorBrowsable attribute.
Another interesting element is PermissionSet. This element specifies under what conditions the member is accessible. The content of the element refers to the System.Security.Permissions.SecurityPermission type.
Let's lower our current permission level and see what effect this has on our access to FileWidth. Create a Console or Windows Application. Click on My Program in Solution Explorer to open the Project Designer. Select the Security tab, then check "Enable ClickOnce Security Settings" and "This is a partial trust application."
At this point the required permissions are not available, so FileWidth and neighboring members become grayed out and inaccessible in IntelliSense. This Visual Basic feature is called IntelliSense-In-Zone. The tooltip indicates which permission type is required to use the member.
You can add PermissionSet elements to member XML documentation files and specify the appropriate permission.

Generating Nicer Documentation
The XML generated by the Visual Basic compiler is readable, but not the most user-friendly. A number of tools have been created to create nicer looking documentation that is easier to navigate.
The first tool is called Sandcastle , developed by Microsoft. After installing Sandcastle, collect the assemblies that you will be documenting, their dependencies, and their XML documentation files. Copy all of those materials to the vSandcastle installation folder (typically C:\Program Files\Sandcastle\Examples\sandcastle).
Open an elevated command prompt and navigate to the same directory, then run this command: 
build_Sandcastle.bat prototype <your assembly name without the file extension>
Directories and files will be generated by this operation. Open the .chm directory, and then open the .chm file inside. It should look something like the help in Figure 9.
Figure 9 Sandcastle .chm Output
The tool offers a number of other output formats other than .chm. For more information and further announcements on Sandcastle, please watch the blog at blogs.msdn.com/sandcastle .
NDoc is another popular tool you might consider using, or you could use the powerful XML features in Visual Basic 9 to write your own custom tool!

XML Comments in Visual Studio 2010
Looking forward, there are new possibilities for the way that you might interact with XML comments in code. The Visual Studio 2010 editor is rewritten using Windows Presentation Foundation (WPF) and allows for rich visualizations. The editor updates also involved moving to a new component system, the Managed Extensibility Framework (MEF), which makes it much easier to register add-ins with Visual Studio. Figure 10 shows an example of an XML comment viewer that was built on top of the new editor and component model.
Figure 10 XML Comment Viewer in Visual Studio 2010
Clicking on the button in the top-right corner switches the display between the WPF control and the original XML. The WPF control certainly provides a much clearer view. It also takes advantage of WPF capabilities such as gradients and round edges. WPF makes it possible to include images or videos, too! This will certainly be a rich area for third-party add-ins to take advantage of in the Visual Studio 2010 release.

Send your questions and comments to instinct@microsoft.com .

Lisa Feigenbaum is the Microsoft Program Manager for the Visual Basic Community. She has been a member of the Visual Basic team since 2004. Before her current role, Lisa was the Program Manager for the Visual Basic Editor and Debugger, working on features such as IntelliSense, edit-and-continue, and code snippets. You can find Lisa at various U.S. and international conferences and user groups, watch her Channel 9 webcasts, or read her posts on the VB team blog at http://blogs.msdn.com/vbteam .

Basic Instincts
Dokumentieren Ihren Code mit XML-Kommentare
Lisa Feigenbaum

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

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.
Abbildung 3 wo zum Speichern von VBXMLDoc.xml
Visual Studio 2005 Visual Studio 2008 Windows XP Windows Vista Pfad
X   X   <user>C:\Dokumente und Einstellungen\ <benutzer> \Application Data\Microsoft\Visual Studio\8.0
X     X C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\8.0
  X X   <user>C:\Dokumente und Einstellungen\ <benutzer> \Application Data\Microsoft\Visual Studio\9.0
  X   X C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\9.0
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 .
NDoc ist 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 Kommentare instinct@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, auf features wie IntelliSense, Bearbeitung und -fortgesetzt, und code Ausschnitte. Lisa finden Sie auf verschiedene USA und internationale Konferenzen und Benutzergruppen, sehen Sie sich Ihr Channel 9-webcasts, oder lesen Sie Ihre Beiträge auf den VB-Teamblog an http://blogs.msdn.com/vbteam .

 

Current Issue

 

 

 

Tip: Click the printer button in your browser toolbar to get the printer friendly version of this article.

 

Page view tracker