Elaborazione del file XML (Guida per programmatori C#)

Il compilatore genera una stringa identificativa (ID) per ciascun costrutto del codice che contiene tag per la creazione della documentazione. Per informazioni sull'applicazione di tag al codice, vedere Tag consigliati per i commenti relativi alla documentazione. L'ID identifica in modo univoco il costrutto. Nei programmi in cui viene elaborato il file XML, l'ID può essere utilizzato per identificare i metadati o gli oggetti Reflection di .NET Framework a cui fa riferimento la documentazione.

Il file XML non è una rappresentazione gerarchica del codice, bensì un normale elenco contenente un ID generato per ciascun 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	Oggetto di descrizione
  N	Spazio dei nomi Non è possibile aggiungere commenti relativi alla documentazione a uno spazio dei nomi, ma è possibile creare riferimenti cref ad essi, se supportati.
  T	tipo: classe, interfaccia, struct, enum, delegato
  F	field
  P	proprietà (compresi gli indicizzatori o altre proprietà indicizzate)
  M	metodo (compresi i metodi speciali, ad esempio costruttori, operatori e così via)
  E	event
  !	stringa di errore Nella parte restante della stringa vengono fornite informazioni sull'errore. Il compilatore C# genera informazioni sugli errori per tutti i collegamenti che non è possibile risolvere.

• La seconda parte della stringa identifica il nome completo dell'elemento, a partire dalla radice dello spazio dei nomi. Il nome dell'elemento, i tipi che lo contengono 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 ('#'), in base al presupposto che nessun nome di elemento contiene direttamente il segno di cancelletto. Ad esempio, il nome completo del costruttore String è "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. ed 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. Non viene mai generato dal compilatore C#.

  • ELEMENT_TYPE_CMOD_REQ viene rappresentato con '|' seguito dal nome completo della classe di modificatori dopo il tipo modificato. Non viene mai generato dal compilatore C#.

  • 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. Non viene mai generato dal compilatore C#.

  • 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. Non viene mai generato dal compilatore C#.

  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.

• Limitatamente agli operatori di conversione (op_Implicit e op_Explicit), il valore restituito del metodo viene codificato come '~' seguito dal tipo restituito, codificato come descritto in precedenza.

• 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. Ad esempio,

  <member name="T:SampleClass`2"> è il tag per un tipo definito come public class SampleClass<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.

Esempi

Negli esempi seguenti viene illustrato come vengono generate le stringhe di ID per una classe e i relativi membri:

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; }

    }
}

Vedere anche

Riferimenti

/doc (opzioni del compilatore C#)

Commenti relativi alla documentazione XML (Guida per programmatori C#)

Concetti

Guida per programmatori C#