Verarbeiten der XML-Datei (C# Programmierhandbuch)Processing the XML File (C# Programming Guide)

Für jedes Konstrukt, das zum Generieren von Dokumentation gekennzeichnet ist, wird vom Compiler eine ID-Zeichenfolge generiert.The compiler generates an ID string for each construct in your code that is tagged to generate documentation. (Weitere Informationen darüber, wie Code mit Tags versehen werden kann, finden Sie unter Empfohlene Tags für Dokumentationskommentare.) Das Konstrukt wird über die ID-Zeichenfolge eindeutig identifiziert.(For information about how to tag your code, see Recommended Tags for Documentation Comments.) The ID string uniquely identifies the construct. Programme, die die XML-Datei verarbeiten, können mithilfe der ID-Zeichenfolge das entsprechende .NET Framework-Metadaten-/Reflektionselement identifizieren, für das die Dokumentation gilt.Programs that process the XML file can use the ID string to identify the corresponding .NET Framework metadata/reflection item that the documentation applies to.

Die XML-Datei enthält keine hierarchische Darstellung des Codes. Es handelt sich um eine flache Liste mit einer generierten ID für jedes Element.The XML file is not a hierarchical representation of your code; it is a flat list that has a generated ID for each element.

Der Compiler beachtet beim Generieren der ID-Zeichenfolgen die folgenden Regeln:The compiler observes the following rules when it generates the ID strings:

  • Die Zeichenfolge darf keinen Leerraum enthalten.No whitespace is in the string.

  • Der erste Teil der ID-Zeichenfolge kennzeichnet die Art des zu identifizierenden Members durch ein einzelnes Zeichen, gefolgt von einem Doppelpunkt.The first part of the ID string identifies the kind of member being identified, by way of a single character followed by a colon. Die folgenden Membertypen werden verwendet:The following member types are used:

    ZeichenCharacter BeschreibungDescription
    NN namespacenamespace

    Einem Namespace können keine Dokumentationskommentare hinzugefügt werden. Falls unterstützt, können jedoch cref-Verweise hinzugefügt werden.You cannot add documentation comments to a namespace, but you can make cref references to them, where supported.
    TT Typ: Klasse, Schnittstelle, Struktur, Enumeration, Delegattype: class, interface, struct, enum, delegate
    FF Feldfield
    PP Eigenschaft (einschließlich von Indexern oder anderen indizierten Eigenschaften)property (including indexers or other indexed properties)
    MM Methode (einschließlich spezieller Methoden wie Konstruktoren, Operatoren usw.)method (including such special methods as constructors, operators, and so forth)
    EE eventevent
    !! Fehlerzeichenfolgeerror string

    Der verbleibende Teil der Zeichenfolge enthält Fehlerinformationen.The rest of the string provides information about the error. Vom C#-Compiler werden Fehlerinformationen für Links erstellt, die nicht aufgelöst werden können.The C# compiler generates error information for links that cannot be resolved.
  • Beim zweiten Teil der Zeichenfolge handelt es sich um den vollqualifizierten Namen eines Elements, beginnend mit dem Namespace-Stammverzeichnis.The second part of the string is the fully qualified name of the item, starting at the root of the namespace. Der Name des Elements, der oder die einschließenden Typen und der Namespace sind durch Punkte getrennt.The name of the item, its enclosing type(s), and namespace are separated by periods. Wenn der Name des Elements selbst Punkte enthält, werden sie durch ein Rautezeichen (#) ersetzt.If the name of the item itself has periods, they are replaced by the hash-sign ('#'). Es wird vorausgesetzt, dass kein Element direkt im Namen ein Rautezeichen enthält.It is assumed that no item has a hash-sign directly in its name. Der vollqualifizierte Name des String-Konstruktors würde beispielsweise „System.String.#ctor“ lauten.For example, the fully qualified name of the String constructor would be "System.String.#ctor".

  • Wenn es sich bei Eigenschaften und Methoden um Argumente der Methode handelt, folgt die in Klammern eingeschlossene Argumentliste.For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. Wenn keine Argumente vorhanden sind, werden keine Klammern verwendet.If there are no arguments, no parentheses are present. Die Argumente werden durch Kommas voneinander getrennt.The arguments are separated by commas. Die Codierung jedes Arguments erfolgt genauso wie die Codierung in einer .NET Framework-Signatur:The encoding of each argument follows directly how it is encoded in a .NET Framework signature:

    • Basistypen.Base types. Reguläre Typen (ELEMENT_TYPE_CLASS oder ELEMENT_TYPE_VALUETYPE) werden als vollqualifizierter Name des Typs dargestellt.Regular types (ELEMENT_TYPE_CLASS or ELEMENT_TYPE_VALUETYPE) are represented as the fully qualified name of the type.

    • Systeminterne Typen (z.B. ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREFIntrinsic types (for example, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. und ELEMENT_TYPE_VOID) werden als vollqualifizierter Name des entsprechenden vollständigen Typs dargestellt.and ELEMENT_TYPE_VOID) are represented as the fully qualified name of the corresponding full type. Als Beispiel sei hier System.Int32 oder System.TypedReference genannt.For example, System.Int32 or System.TypedReference.

    • ELEMENT_TYPE_PTR wird als * dargestellt, das auf den geänderten Typ folgt.ELEMENT_TYPE_PTR is represented as a '*' following the modified type.

    • ELEMENT_TYPE_BYREF wird als @ dargestellt, das auf den geänderten Typ folgt.ELEMENT_TYPE_BYREF is represented as a '@' following the modified type.

    • ELEMENT_TYPE_PINNED wird als ^ dargestellt, das auf den geänderten Typ folgt.ELEMENT_TYPE_PINNED is represented as a '^' following the modified type. Dies wird nie vom C#-Compiler generiert.The C# compiler never generates this.

    • ELEMENT_TYPE_CMOD_REQ wird als | und vollqualifizierter Name der Modifiziererklasse dargestellt, das bzw. der auf den geänderten Typ folgt.ELEMENT_TYPE_CMOD_REQ is represented as a '|' and the fully qualified name of the modifier class, following the modified type. Dies wird nie vom C#-Compiler generiert.The C# compiler never generates this.

    • ELEMENT_TYPE_CMOD_OPT wird als ! mit nachstehendem vollqualifizierten Namen der Modifiziererklasse dargestellt, das auf den geänderten Typ folgt.ELEMENT_TYPE_CMOD_OPT is represented as a '!' and the fully qualified name of the modifier class, following the modified type.

    • ELEMENT_TYPE_SZARRAY wird als [] dargestellt, das auf den Elementtyp des Arrays folgt.ELEMENT_TYPE_SZARRAY is represented as "[]" following the element type of the array.

    • ELEMENT_TYPE_GENERICARRAY wird als [?] dargestellt, das auf den Elementtyp des Arrays folgt.ELEMENT_TYPE_GENERICARRAY is represented as "[?]" following the element type of the array. Dies wird nie vom C#-Compiler generiert.The C# compiler never generates this.

    • ELEMENT_TYPE_ARRAY wird als [lowerbound:size,lowerbound:size] dargestellt, wobei die Anzahl von Kommas als Rang minus 1 berechnet wird und die untere Grenze sowie die Größe jeder Dimension – sofern bekannt – dezimal dargestellt werden.ELEMENT_TYPE_ARRAY is represented as [lowerbound:size,lowerbound:size] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. Wenn die untere Grenze oder die Größe nicht angegeben ist, wird sie einfach ausgelassen.If a lower bound or size is not specified, it is simply omitted. Wenn die untere Grenze und die Größe für eine bestimmte Dimension ausgelassen werden, kann der Doppelpunkt (:) ebenfalls ausgelassen werden.If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. [1:,1:] ist beispielsweise ein zweidimensionales Array mit 1 als unterer Grenze und nicht angegebenen Größen.For example, a 2-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:].

    • ELEMENT_TYPE_FNPTR wird als „=FUNC:type(signature)“ dargestellt, wobei type den Rückgabetyp angibt und es sich bei signature um die Argumente der Methode handelt.ELEMENT_TYPE_FNPTR is represented as "=FUNC:type(signature)", where type is the return type, and signature is the arguments of the method. Sind keine Argumente vorhanden, werden keine Klammern verwendet.If there are no arguments, the parentheses are omitted. Dies wird nie vom C#-Compiler generiert.The C# compiler never generates this.

    Die folgenden Signaturkomponenten werden nicht dargestellt, weil sie nicht zur Unterscheidung überladener Methoden verwendet werden:The following signature components are not represented because they are never used for differentiating overloaded methods:

    • Aufrufkonventioncalling convention

    • Rückgabetypreturn type

    • ELEMENT_TYPE_SENTINELELEMENT_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.For conversion operators only (op_Implicit and op_Explicit), the return value of the method is encoded as a '~' followed by the return type, as encoded above.

  • Bei generischen Typen folgt auf den Namen des Typs ein Graviszeichen und dann eine Zahl, mit der die Anzahl generischer Typparameter angegeben wird.For generic types, the name of the type will be followed by a back tick and then a number that indicates the number of generic type parameters. Beispiel:For example,

    <member name="T:SampleClass2">is the tag for a type that is defined aspublic class SampleClass<T, U>`.<member name="T:SampleClass2">is the tag for a type that is defined aspublic class SampleClass<T, U>`.

    Bei Methoden, die generische Typen als Parameter verwenden, werden die generischen Parameter des Typs als Zahlen mit vorangestelltem Graviszeichen angegeben (z.B. `0,1).</span><span class="sxs-lookup"><span data-stu-id="1661c-169">For methods taking generic types as parameters, the generic type parameters are specified as numbers prefaced with back ticks (for example \0,`1). Jede Zahl stellt eine bei 0 beginnende Arraynotation für die generischen Parameter des Typs dar.Each number representing a zero-based array notation for the type's generic parameters.

BeispieleExamples

Die folgenden Beispiele zeigen, wie die ID-Zeichenfolgen für eine Klasse und ihre Member generiert werden würden:The following examples show how the ID strings for a class and its members would be generated:

namespace N
{
    /// <summary>
    /// Enter description here for class X. 
    /// ID string generated is "T:N.X". 
    /// </summary>
    public unsafe class X
    {
        /// <summary>
        /// Enter description here for the first constructor.
        /// ID string generated is "M:N.X.#ctor".
        /// </summary>
        public X() { }


        /// <summary>
        /// Enter description here for the second constructor.
        /// ID string generated is "M:N.X.#ctor(System.Int32)".
        /// </summary>
        /// <param name="i">Describe parameter.</param>
        public X(int i) { }


        /// <summary>
        /// Enter description here for field q.
        /// ID string generated is "F:N.X.q".
        /// </summary>
        public string q;


        /// <summary>
        /// Enter description for constant PI.
        /// ID string generated is "F:N.X.PI".
        /// </summary>
        public const double PI = 3.14;


        /// <summary>
        /// Enter description for method f.
        /// ID string generated is "M:N.X.f".
        /// </summary>
        /// <returns>Describe return value.</returns>
        public int f() { return 1; }


        /// <summary>
        /// Enter description for method bb.
        /// ID string generated is "M:N.X.bb(System.String,System.Int32@,System.Void*)".
        /// </summary>
        /// <param name="s">Describe parameter.</param>
        /// <param name="y">Describe parameter.</param>
        /// <param name="z">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public int bb(string s, ref int y, void* z) { return 1; }


        /// <summary>
        /// Enter description for method gg.
        /// ID string generated is "M:N.X.gg(System.Int16[],System.Int32[0:,0:])". 
        /// </summary>
        /// <param name="array1">Describe parameter.</param>
        /// <param name="array">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public int gg(short[] array1, int[,] array) { return 0; }


        /// <summary>
        /// Enter description for operator.
        /// ID string generated is "M:N.X.op_Addition(N.X,N.X)". 
        /// </summary>
        /// <param name="x">Describe parameter.</param>
        /// <param name="xx">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public static X operator +(X x, X xx) { return x; }


        /// <summary>
        /// Enter description for property.
        /// ID string generated is "P:N.X.prop".
        /// </summary>
        public int prop { get { return 1; } set { } }


        /// <summary>
        /// Enter description for event.
        /// ID string generated is "E:N.X.d".
        /// </summary>
        public event D d;


        /// <summary>
        /// Enter description for property.
        /// ID string generated is "P:N.X.Item(System.String)".
        /// </summary>
        /// <param name="s">Describe parameter.</param>
        /// <returns></returns>
        public int this[string s] { get { return 1; } }


        /// <summary>
        /// Enter description for class Nested.
        /// ID string generated is "T:N.X.Nested".
        /// </summary>
        public class Nested { }


        /// <summary>
        /// Enter description for delegate.
        /// ID string generated is "T:N.X.D". 
        /// </summary>
        /// <param name="i">Describe parameter.</param>
        public delegate void D(int i);


        /// <summary>
        /// Enter description for operator.
        /// ID string generated is "M:N.X.op_Explicit(N.X)~System.Int32".
        /// </summary>
        /// <param name="x">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public static explicit operator int(X x) { return 1; }

    }
}

Siehe auchSee Also

C#-ProgrammierhandbuchC# Programming Guide
/ doc (C#-Compileroptionen)/doc (C# Compiler Options)
XML-DokumentationskommentareXML Documentation Comments