Elaborazione del file .Xml
Il compilatore genera una stringa identificativa (ID) per ciascun costrutto del codice che contiene tag per la creazione della documentazione.Per ulteriori informazioni, vedere Commenti della documentazione dei tag consigliati.L'ID identifica in modo univoco il costrutto.I programmi che elaborano il file xml possono utilizzare la stringa ID per identificare i metadati di .NET Framework o un elemento corrispondenti di reflection della documentazione si applica.
Il file xml non è una rappresentazione gerarchica del codice, è un semplice elenco con un ID generato per ogni elemento.
Per generare gli ID, il compilatore applica le regole descritte di seguito.
La stringa non deve contenere spazi vuoti.
La prima parte della stringa ID specifica il tipo di membro da identificare, con un singolo carattere seguito dai due punti.Vengono utilizzati i tipi di membri descritti di seguito.
Carattere
Descrizione
N
Spazio dei nomi
Non è possibile aggiungere i commenti della documentazione a uno spazio dei nomi, riferimenti cref in uno spazio dei nomi è possibile.
T
tipo: classe, interfaccia, struct, enum, delegato
D
typedef
F
campo
P
proprietà (compresi gli indicizzatori o altre proprietà indicizzate)
M
metodo (compresi i metodi speciali, ad esempio costruttori, operatori e così via)
E
evento
!
stringa di errore
Nella parte restante della stringa vengono fornite informazioni sull'errore.Il compilatore di Visual C++ genera informazioni sugli errori per i collegamenti che non possono essere risolti.
La seconda parte della stringa identifica il nome completo dell'elemento, a partire dalla radice dello spazio dei nomi.Il nome dell'elemento, il tipo di inclusione o tipi e lo spazio dei nomi sono separati da punti.Se il nome dell'elemento contiene dei punti, questi verranno sostituiti con il segno di cancelletto ('#'),Si presume che nessun elemento ha un segno hash direttamente nel nome.Ad esempio, il nome completo del costruttore di String sarebbe “System.String.#ctor„.
Per le proprietà e i metodi, se il metodo ha degli argomenti, verrà incluso di seguito l'elenco degli argomenti racchiuso tra parentesi.Se non vi sono argomenti, non si utilizzeranno le parentesi.Gli argomenti sono separati da virgole.La codifica di ciascun argomento è del tutto simile alla modalità di codifica utilizzata in una firma .NET Framework.
Tipi base.I tipi regolari (ELEMENT_TYPE_CLASS o ELEMENT_TYPE_VALUETYPE) vengono rappresentati con il nome completo del tipo.
Tipi intrinseci (ad esempio, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF.e ELEMENT_TYPE_VOID) sono rappresentati come nome completo del tipo completo corrispondente, ad esempio, System.Int32 o System.TypedReference.
ELEMENT_TYPE_PTR viene rappresentato con '*' dopo il tipo modificato.
ELEMENT_TYPE_BYREF viene rappresentato con '@' dopo il tipo modificato.
ELEMENT_TYPE_PINNED viene rappresentato con '^' dopo il tipo modificato.Il compilatore di Visual C++ non viene mai questo.
ELEMENT_TYPE_CMOD_REQ viene rappresentato con '|' seguito dal nome completo della classe di modificatori dopo il tipo modificato.Il compilatore di Visual C++ non viene mai questo.
ELEMENT_TYPE_CMOD_OPT viene rappresentato con '!' seguito dal nome completo della classe di modificatori dopo il tipo modificato.
ELEMENT_TYPE_SZARRAY viene rappresentato con "[]" dopo il tipo di elemento della matrice.
ELEMENT_TYPE_GENERICARRAY viene rappresentato con "[?]" dopo il tipo di elemento della matrice.Il compilatore di Visual C++ non viene mai questo.
ELEMENT_TYPE_ARRAY viene rappresentato con [limite inferiore:size,limite inferiore:size], dove il numero di virgole indica il numero di dimensioni - 1. I limiti inferiori e le dimensioni di ciascuna dimensione, qualora noti, vengono rappresentati con valori decimali.Se non è specificato alcun valore, il limite o la dimensione inferiore viene omessa.Se vengono omessi il limite inferiore e la dimensione per una dimensione specifica, anche ':' viene omesso.Ad esempio, una matrice a due dimensioni con limiti inferiori pari a 1 e dimensioni non specificate viene rappresentata con [1:,1:].
ELEMENT_TYPE_FNPTR viene rappresentato con "=FUNC:type(signature)", dove type rappresenta il tipo restituito e signature identifica gli argomenti del metodo.Se non vi sono argomenti, le parentesi vengono omesse.Il compilatore di Visual C++ non viene mai questo.
I seguenti componenti della firma non vengono rappresentati in quanto non vengono mai utilizzati per differenziare i metodi di overload:
convenzione di chiamata;
tipo restituito;
ELEMENT_TYPE_SENTINEL.
Per gli operatori di conversione solo, il valore restituito del metodo viene codificato come “~„ seguita dal tipo restituito, come in precedenza codificato.
Nel caso di tipi generici il nome del tipo verrà seguito da un apice inverso e quindi da un numero che indica il numero di parametri di tipo generici.Di seguito è riportato un esempio:
<member name="T:MyClass`2">Per un tipo definito come public class MyClass<T, U>.
Nel caso di metodi che accettano tipi generici come parametri, i parametri di tipo generici sono caratterizzati da numeri preceduti da apici inversi, ad esempio `0,`1.Ciascun numero rappresenta la notazione della matrice in base zero per i parametri generici del tipo.
Esempio
Negli esempi seguenti viene mostrato come le stringhe ID di classe e i relativi membri verranno generati.
// xml_id_strings.cpp
// compile with: /clr /doc /LD
///
namespace N {
// "N:N"
/// <see cref="System" />
// <see cref="N:System"/>
ref class X {
// "T:N.X"
protected:
///
!X(){}
// "M:N.X.Finalize", destructor's representation in metadata
public:
///
X() {}
// "M:N.X.#ctor"
///
static X() {}
// "M:N.X.#cctor"
///
X(int i) {}
// "M:N.X.#ctor(System.Int32)"
///
~X() {}
// "M:N.X.Dispose", Dispose function representation in metadata
///
System::String^ q;
// "F:N.X.q"
///
double PI;
// "F:N.X.PI"
///
int f() { return 1; }
// "M:N.X.f"
///
int bb(System::String ^ s, int % y, void * z) { return 1; }
// "M:N.X.bb(System.String,System.Int32@,System.Void*)"
///
int gg(array<short> ^ array1, array< int, 2 >^ IntArray) { return 0; }
// "M:N.X.gg(System.Int16[], System.Int32[0:,0:])"
///
static X^ operator+(X^ x, X^ xx) { return x; }
// "M:N.X.op_Addition(N.X,N.X)"
///
property int prop;
// "M:N.X.prop"
///
property int prop2 {
// "P:N.X.prop2"
///
int get() { return 0; }
// M:N.X.get_prop2
///
void set(int i) {}
// M:N.X.set_prop2(System.Int32)
}
///
delegate void D(int i);
// "T:N.X.D"
///
event D ^ d;
// "E:N.X.d"
///
ref class Nested {};
// "T:N.X.Nested"
///
static explicit operator System::Int32 (X x) { return 1; }
// "M:N.X.op_Explicit(N.X!System.Runtime.CompilerServices.IsByValue)~System.Int32"
};
}