<include> (C#-Programmierhandbuch)

Syntax

<include file='filename' path='tagpath[@name="id"]' />  

Parameter

filename
Der Name der XML-Datei, die die Dokumentation enthält. Der Dateiname kann mit einem Pfad qualifiziert werden. filename muss in einfache Anführungszeichen (‚‘) eingeschlossen werden.

tagpath
Der Pfad der Tags in filename, der zum Tag name führt. Der Pfad muss in einfache Anführungszeichen (‚‘) eingeschlossen werden.

name
Der Namensbezeichner in dem Tag, das sich vor den Kommentaren befindet. name besitzt eine id.

id
Die ID für das Tag, das sich vor den Kommentaren befindet. Die ID muss in doppelte Anführungszeichen („“) eingeschlossen werden.

Hinweise

Mit dem <include>-Tag können Sie auf Kommentare in einer anderen Datei verweisen, die die Typen und Member in Ihrem Quellcode beschreiben. Dies ist eine Alternative zum direkten Platzieren von Dokumentationskommentaren in der Quellcodedatei. Durch das Ablegen der Dokumentation in einer separaten Datei können Sie die Quellcodeverwaltung unabhängig vom Quellcode auf die Dokumentation anwenden. Eine Person kann die Quellcodedatei auschecken, eine andere die Dokumentationsdatei.

Das <include>-Tag verwendet die XPath-Syntax von XML. Weitere Anpassungsmöglichkeiten der Verwendung von <include> finden Sie in der XPath-Dokumentation.

Beispiel

Dies ist ein Beispiel einer Mehrfachdatei. Die erste Datei, die <include> verwendet, wird unten aufgeführt:

// compile with: /doc:DocFileName.xml 

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
    static void Main()
    {
    }
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
    public void Test()
    {
    }
}

Die zweite Datei, xml_include_tag.doc, enthält die folgenden Dokumentationskommentare:

<MyDocs>  

<MyMembers name="test">  
<summary>  
The summary for this type.  
</summary>  
</MyMembers>  

<MyMembers name="test2">  
<summary>  
The summary for this other type.  
</summary>  
</MyMembers>  

</MyDocs>  

Programmausgabe

Die folgende Ausgabe wird generiert, wenn Sie die Klassen „Test“ und „Test2“ mit der folgenden Befehlszeile kompilieren: /doc:DocFileName.xml.. Geben Sie in Visual Studio im Bereich „Build“ des Projekt-Designers die Option XML-Dokumentkommentare an. Erkennt der C#-Compiler das <include>-Tag, sucht er statt in der aktuellen Quelldatei in „xml_include_tag.doc“ nach Dokumentationskommentaren. Der Compiler generiert dann DocFileName.xml. Dies ist die Datei, die von Dokumentationstools wie z.B. Sandcastle genutzt wird, um die endgültige Dokumentation zu erzeugen.

<?xml version="1.0"?>   
<doc>   
    <assembly>   
        <name>xml_include_tag</name>   
    </assembly>   
    <members>   
        <member name="T:Test">   
            <summary>   
The summary for this type.   
</summary>   
        </member>   
        <member name="T:Test2">   
            <summary>   
The summary for this other type.   
</summary>   
        </member>   
    </members>   
</doc>   

Siehe auch

C#-Programmierhandbuch
Empfohlene Tags für Dokumentationskommentare