Verarbeiten der XML-Datei (C#-Programmierhandbuch)
Aktualisiert: November 2007
Für jedes Konstrukt, das zum Generieren von Dokumentation gekennzeichnet ist, wird vom Compiler eine ID-Zeichenfolge generiert. (Weitere Informationen darüber, wie Code mit Tags versehen werden kann, finden Sie unter Empfohlene Tags für Dokumentationskommentare.) Das Konstrukt wird von der ID-Zeichenfolge eindeutig identifiziert. Programme, von denen die XML-Datei verarbeitet wird, können die ID-Zeichenfolge einsetzen, um das entsprechende .NET Framework-Metadaten-/Reflektionselement zu identifizieren, auf das die Dokumentation angewendet werden kann.
Die XML-Datei enthält keine hierarchische Darstellung des Codes. Es handelt sich um eine unstrukturierte Liste mit einer generierten ID für jedes Element.
Die folgenden Regeln werden vom Compiler beim Generieren der ID-Zeichenfolgen beachtet:
Die Zeichenfolge darf keinen Leerraum enthalten.
Der erste Teil der ID-Zeichenfolge kennzeichnet die Art des zu identifizierenden Members durch ein einzelnes Zeichen, gefolgt von einem Doppelpunkt. Die folgenden Membertypen werden verwendet:
Zeichen
Beschreibung
N
Namespace
Einem Namespace können keine Dokumentationskommentare hinzugefügt werden. Falls unterstützt, können jedoch cref-Verweise hinzugefügt werden.
T
Typ: Klasse, Schnittstelle, Struktur, Auflistung, Delegat
F
Feld
P
Eigenschaft, einschließlich Indexern oder anderer indizierter Eigenschaften.
M
Methode (einschließlich spezieller Methoden wie Konstruktoren, Operatoren usw.)
E
Ereignis
!
Fehlerzeichenfolge
Der verbleibende Teil der Zeichenfolge enthält Fehlerinformationen. Vom C#-Compiler werden Fehlerinformationen für Links, die nicht aufgelöst werden können, erstellt.
Beim zweiten Teil der Zeichenfolge handelt es sich um den vollqualifizierten Namen eines Elements, beginnend mit dem Namespace-Stammverzeichnis. Der Name des Elements, der bzw. die einschließende(n) Typ(en) und der Namespace sind durch Punkte getrennt. Wenn der Name des Elements selbst Punkte enthält, werden sie durch ein Nummernzeichen (#) ersetzt. Es wird vorausgesetzt, dass kein Element direkt im Namen ein Nummernzeichen enthält. Der vollqualifizierte Name des String-Konstruktors würde beispielsweise "System.String.#ctor" lauten.
Wenn es sich bei Eigenschaften und Methoden um Argumente der Methode handelt, folgt die in Klammern eingeschlossene Argumentliste. Wenn keine Argumente vorhanden sind, werden keine Klammern verwendet. Die Argumente werden durch Kommas voneinander getrennt. Die Codierung jedes Arguments erfolgt genauso wie die Codierung in einer .NET Framework-Signatur:
Basistypen. Reguläre Typen, ELEMENT_TYPE_CLASS oder ELEMENT_TYPE_VALUETYPE, werden als vollqualifizierter Name des Typs repräsentiert.
Immanente Typen, z. B. ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRINGELEMENT_TYPE_TYPEDBYREF und ELEMENT_TYPE_VOID, werden als vollqualifizierter Name des entsprechenden vollständigen Typs repräsentiert. Als Beispiel sei hier System.Int32 oder System.TypedReference aufgeführt.
ELEMENT_TYPE_PTR wird als *, das auf den geänderten Typ folgt, repräsentiert.
ELEMENT_TYPE_PTR wird als @, das auf den geänderten Typ folgt, repräsentiert.
ELEMENT_TYPE_PTR wird als ^, das auf den geänderten Typ folgt, repräsentiert. Dies wird nie vom C#-Compiler generiert.
ELEMENT_TYPE_CMOD_REQ wird als '|' mit nachstehendem vollqualifizierten Namen der Modifiziererklasse repräsentiert, das auf den geänderten Typ folgt. Dies wird nie vom C#-Compiler generiert.
ELEMENT_TYPE_CMOD_OPT wird als ! mit nachstehendem vollqualifizierten Namen der Modifiziererklasse, die auf den geänderten Typ folgen, repräsentiert.
ELEMENT_TYPE_SZARRAY wird als [], das auf den Elementtyp des Arrays folgt, repräsentiert.
ELEMENT_TYPE_GENERICARRAY wird als [?], das auf den Elementtyp des Arrays folgt, repräsentiert. Dies wird nie vom C#-Compiler generiert.
ELEMENT_TYPE_ARRAY wird als [lowerbound:size,lowerbound:size] repräsentiert, wobei die Anzahl der Kommas durch Rang - 1 berechnet wird und die untere Grenze sowie die Größe jeder Dimension, sofern bekannt, dezimal repräsentiert werden. Wenn die untere Grenze oder die Größe nicht angegeben ist, wird sie einfach ausgelassen. Wenn die untere Grenze und die Größe für eine bestimmte Dimension ausgelassen werden, kann der : ebenfalls ausgelassen werden. [1:,1:] ist beispielsweise ein zweidimensionales Array mit 1 als unterer Grenze und nicht angegebenen Größen.
ELEMENT_TYPE_FNPTR wird als "=FUNC:type(signature)" repräsentiert, wobei type den Rückgabetyp darstellt und es sich bei signature um die Argumente der Methode handelt. Sind keine Argumente vorhanden, werden keine Klammern verwendet. Dies wird nie vom C#-Compiler generiert.
Die folgenden Signaturkomponenten werden nicht repräsentiert, weil sie nicht zur Unterscheidung überladener Methoden verwendet werden:
Aufrufkonvention
Rückgabetyp
ELEMENT_TYPE_SENTINEL
Nur für Konvertierungsoperatoren, op_Implicit und op_Explicit, wird der Rückgabewert der Methode als "~" gefolgt vom Rückgabewert codiert, wie weiter oben gezeigt.
Bei generischen Typen folgt auf den Namen des Typs ein Graviszeichen und dann eine Zahl, die die Anzahl der generischen Typparameter angibt. Beispiel:
<member name="T:SampleClass`2"> ist das Tag für einen Typ, der als public class SampleClass<T, U> definiert wird.
Bei Methoden, die generische Typen als Parameter verwenden, werden die generischen Parameter des Typs als Zahlen mit vorangestelltem Graviszeichen angegeben (z. B. `0,`1). Jede Zahl stellt eine bei 0 beginnende Arraynotation für die generischen Parameter des Typs dar.
Beispiele
In den folgenden Beispielen wird eine mögliche Generierung von ID-Zeichenfolgen für eine Klasse und ihre Member gezeigt:
///
///
namespace N // "N:N"
{
///
///
public unsafe class X // "T:N.X"
{
public X(){}
//----------------------------
// The result of the above is:
// "M:N.X.#ctor"
/// <param name="i"></param>
public X(int i){}
//----------------------------
// The result of the above is:
// "M:N.X.#ctor(System.Int32)"
~X(){}
//----------------------------
// The result of the above is:
// "M:N.X.Finalize", destructor's representation in metadata
public string q;
//----------------------------
// The result of the above is:
// "F:N.X.q"
/// <returns></returns>
public const double PI = 3.14;
//----------------------------
// The result of the above is:
// "F:N.X.PI"
/// <param name="s"></param>
/// <param name="y"></param>
/// <param name="z"></param>
/// <returns></returns>
public int f(){return 1;}
//----------------------------
// The result of the above is:
// "M:N.X.f"
/// <param name="array1"></param>
/// <param name="array"></param>
/// <returns></returns>
public int bb(string s, ref int y, void * z){return 1;}
//----------------------------
// The result of the above is:
// "M:N.X.bb(System.String,System.Int32@,=System.Void*)"
/// <param name="x"></param>
/// <param name="xx"></param>
/// <returns></returns>
public int gg(short[] array1, int[,] array){return 0;}
//----------------------------
// The result of the above is:
// "M:N.X.gg(System.Int16[], System.Int32[0:,0:])"
public static X operator+(X x, X xx){return x;}
//----------------------------
// The result of the above is:
// "M:N.X.op_Addition(N.X,N.X)"
public int prop {get{return 1;} set{}}
//----------------------------
// The result of the above is:
// "P:N.X.prop"
public event D d;
//----------------------------
// The result of the above is:
// "E:N.X.d"
public int this[string s]{get{return 1;}}
//----------------------------
// The result of the above is:
// "P:N.X.Item(System.String)"
public class Nested{}
//----------------------------
// The result of the above is:
// "T:N.X.Nested"
public delegate void D(int i);
//----------------------------
// The result of the above is:
// "T:N.X.D"
/// <param name="x"></param>
/// <returns></returns>
public static explicit operator int(X x){return 1;}
//----------------------------
// The result of the above is:
// "M:N.X.op_Explicit(N.X)~System.Int32"
}
}
Siehe auch
Aufgaben
Beispiel für die XML-Dokumentation
Konzepte
Referenz
/doc (Dokumentationskommentare verarbeiten) (C#-Compileroptionen)