Traitement du fichier XML (Guide de programmation C#)
Mise à jour : novembre 2007
Le compilateur génère une chaîne d'identification pour chaque construction de votre code qui est placée entre balises de manière à générer de la documentation. (Pour plus d'informations sur l'ajout de balises à votre code, consultez Balises recommandées pour commentaires de documentation.) La chaîne d'identification identifie de manière unique la construction. Les programmes qui traitent le fichier XML peuvent utiliser la chaîne d'identification pour identifier l'élément de métadonnées/réflexion du .NET Framework correspondant auquel s'applique la documentation.
Le fichier XML n'est pas une représentation hiérarchique de votre code, mais une simple liste comportant un identificateur généré pour chaque élément.
Lorsqu'il génère les chaînes d'identification, le compilateur respecte les règles suivantes :
La chaîne ne doit contenir aucun espace.
La première partie de la chaîne d'identification identifie le type de membre à l'aide d'un caractère unique suivi de deux-points. Les types de membres suivants sont utilisés :
Caractère
Description
N
espace de noms
Vous ne pouvez pas ajouter de commentaires de documentation à un espace de noms, mais vous pouvez ajouter des références cref à ces commentaires, lorsqu'elles sont prises en charge.
T
type : classe, interface, struct, enum, délégué
F
champ
P
propriété (y compris les indexeurs ou autres propriétés indexées)
M
méthode (y compris des méthodes spéciales telles que les constructeurs, les opérateurs, etc.)
E
événement
!
chaîne d'erreur
Le reste de la chaîne fournit des informations sur l'erreur. Le compilateur C# génère des informations sur l'erreur pour les liens impossibles à résoudre.
La deuxième partie de la chaîne est composée du nom complet de l'élément, à partir de la racine de l'espace de noms. Le nom de l'élément, ses types englobants et l'espace de noms sont séparés par des points. Si le nom de l'élément lui-même comporte des points, ils sont remplacés par un dièse ('#'). Par principe, aucun nom d'élément ne doit contenir de signe dièse à l'origine. Par exemple, le nom complet du constructeur String est "System.String.#ctor".
Pour les propriétés et méthodes, s'il existe des arguments pour la méthode, la liste des arguments figure à la suite entre parenthèses. En l'absence d'arguments, aucune parenthèse n'est mentionnée. Les arguments sont séparés par des virgules. Le codage de chaque argument correspond directement à son codage dans une signature .NET Framework :
Types de base. Les types réguliers (ELEMENT_TYPE_CLASS ou ELEMENT_TYPE_VALUETYPE) sont représentés par le nom complet du type.
Les types intrinsèques (par exemple, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. et ELEMENT_TYPE_VOID) sont représentés par le nom qualifié complet du type correspondant. Exemple : System.Int32 ou System.TypedReference.
ELEMENT_TYPE_PTR est représenté par un '*' à la suite du type modifié.
ELEMENT_TYPE_BYREF est représenté par un '@' à la suite du type modifié.
ELEMENT_TYPE_PINNED est représenté par un '^' à la suite du type modifié. Le compilateur C# ne génère jamais ceci.
ELEMENT_TYPE_CMOD_REQ est représenté par un '|' et le nom complet de la classe de modificateur, à la suite du type modifié. Le compilateur C# ne génère jamais ceci.
ELEMENT_TYPE_CMOD_OPT est représenté par un '!' et le nom complet de la classe de modificateur, à la suite du type modifié.
ELEMENT_TYPE_SZARRAY est représenté par "[]" à la suite du type d'élément du tableau.
ELEMENT_TYPE_GENERICARRAY est représenté par "[?]" à la suite du type d'élément du tableau. Le compilateur C# ne génère jamais ceci.
ELEMENT_TYPE_ARRAY est représenté par [limite_inférieure:size,limite_inférieure:size], où le nombre de virgules correspond au rang - 1, et les limite inférieure et taille de chaque dimension, lorsqu'elles sont connues, sont représentées sous forme décimale. Lorsqu'une limite inférieure ou une taille n'est pas spécifiée, elle est seulement omise. Si la limite inférieure et la taille d'une dimension particulière sont omises, le signe ':' est également omis. Par exemple, un tableau à 2 dimensions avec des limites inférieures égales à 1, mais sans tailles spécifiées est représenté par [1:,1:].
ELEMENT_TYPE_FNPTR est représenté sous la forme "=FUNC:type(signature)", où type est le type de retour et signature l'argument de la méthode. En l'absence d'arguments, les parenthèses sont omises. Le compilateur C# ne génère jamais ceci.
Les composants de signature suivants ne sont pas représentés parce qu'ils ne sont jamais utilisés pour différencier les méthodes surchargées :
convention d'appel
type de retour
ELEMENT_TYPE_SENTINEL
Uniquement pour les opérateurs de conversion (op_Implicit et op_Explicit), la valeur de retour de la méthode est codée sous la forme d'un '~' suivi du type de retour, conformément au codage effectué plus haut.
Pour les types génériques, le nom du type sera suivi du caractère ` puis d'un nombre qui indique le nombre de paramètres de type générique. Par exemple :
<member name="T:SampleClass`2"> est la balise d'un type défini comme public class SampleClass<T, U>.
Pour les méthodes qui prennent des types génériques comme paramètres, les paramètres de type générique sont spécifiés comme des nombres précédés de caractères ` (par exemple `0, `1). Chaque nombre représente une notation de tableau de base zéro pour les paramètres génériques du type.
Exemples
Les exemples ci-dessous illustrent la manière dont les chaînes d'identification doivent être générées pour une classe et ses membres :
///
///
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"
}
}
Voir aussi
Tâches
Concepts
Référence
/doc (Traiter les commentaires de documentation) (Options du compilateur C#)
Commentaires de documentation XML (Guide de programmation C#)