Condividi tramite

Elaborazione di file di documentazione XML

  • Articolo

Il compilatore genera una stringa identificativa (ID) per ciascun costrutto del codice che contiene tag per la creazione della documentazione. Per altre informazioni, vedere Commenti sulla documentazione dei tag consigliati. La stringa ID identifica in modo univoco il costrutto. I programmi che elaborano il file XML possono usare la stringa ID per identificare i metadati o l'elemento di reflection .NET Framework corrispondente a cui si applica la documentazione.

Il file XML non è una rappresentazione gerarchica del codice, è un elenco flat con un ID generato per ogni elemento.

Per generare gli ID, il compilatore applica le regole seguenti:

  • Assenza di spazi vuoti nella stringa.

  • La prima parte della stringa ID specifica il tipo di membro, con un singolo carattere seguito dai due punti. Vengono usati i tipi di membri seguenti:

    Carattere Descrizione
    N Spazio dei nomi

    Non è possibile aggiungere commenti alla documentazione a uno spazio dei nomi, sono possibili riferimenti cref a uno spazio dei nomi.
    T Tipo: classe, interfaccia, struct, enumerazione, delegato
    D Typedef
    F Campo
    P Proprietà (inclusi indicizzatori o altre proprietà indicizzate)
    M Metodo (inclusi metodi speciali come costruttori, operatori e così via)
    E Event
    ! Stringa di errore

    Nella parte restante della stringa vengono fornite informazioni sull'errore. Il compilatore MSVC genera informazioni sull'errore 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, i tipi di inclusione e lo spazio dei nomi sono separati da punti. Se il nome dell'elemento stesso ha punti, questi vengono sostituiti dal segno hash ('#'). in base al presupposto che nessun nome di elemento contiene direttamente tale segno. 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 sono presenti argomenti, non verranno usate le parentesi. Gli argomenti sono separati da virgole. Ogni argomento viene codificato nello stesso modo in cui viene codificato in una firma di .NET Framework:

    • Tipi di base. I tipi regolari (ELEMENT_TYPE_CLASS o ELEMENT_TYPE_VALUETYPE) sono rappresentati come nome completo del tipo.

    • I tipi intrinseci , ad esempio , ELEMENT_TYPE_STRINGELEMENT_TYPE_I4ELEMENT_TYPE_OBJECT, 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 è rappresentato come '*' dopo il tipo modificato.

    • ELEMENT_TYPE_BYREF è rappresentato come '@' dopo il tipo modificato.

    • ELEMENT_TYPE_PINNED è rappresentato come '^' dopo il tipo modificato. Il compilatore MSVC non genera mai questo elemento.

    • ELEMENT_TYPE_CMOD_REQ è rappresentato come "|" e il nome completo della classe modificatore, seguendo il tipo modificato. Il compilatore MSVC non genera mai questo elemento.

    • ELEMENT_TYPE_CMOD_OPT è rappresentato come "!" e il nome completo della classe modificatore, seguendo il tipo modificato.

    • ELEMENT_TYPE_SZARRAY è rappresentato come "[]" dopo il tipo di elemento della matrice.

    • ELEMENT_TYPE_GENERICARRAY è rappresentato come "[?]" dopo il tipo di elemento della matrice. Il compilatore MSVC non genera mai questo elemento.

    • ELEMENT_TYPE_ARRAYè rappresentato come [dimensione inferiore limite:inferiore dimensione,] limite inferiore:dove il numero di virgole è il rango - 1 e il limite inferiore e le dimensioni di ogni dimensione, se noto, sono rappresentati in decimale. Se non viene specificato un limite o una dimensione inferiore, viene omesso. Se il limite inferiore e le dimensioni vengono omessi per una determinata dimensione, viene omesso anche ':'. Ad esempio, una matrice bidimensionale con 1 come limite inferiore e dimensioni non specificate viene rappresentata come [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 MSVC non genera mai questo elemento.

    I componenti di firma seguenti non sono rappresentati perché non vengono mai usati per differenziare i metodi di overload:

    • Convenzione di chiamata

    • Tipo restituito

    • ELEMENT_TYPE_SENTINEL

  • Solo per gli operatori di conversione, il valore restituito del metodo viene codificato come '~' seguito dal tipo restituito, come codificato 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:MyClass`2">

    L'esempio mostra un tipo definito come public class MyClass<T, U>.

    Per i metodi che accettano tipi generici come parametri, i parametri di tipo generico vengono specificati come numeri preceduti da segni di graduazione posteriore ( ad esempio '0, '1). Ogni numero rappresenta una posizione di matrice in base zero per i parametri generici del tipo.

Esempio

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

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

Vedi anche

Documentazione XML