Обработка XML-файла (Руководство по программированию на C#)
Обновлен: Ноябрь 2007
Компилятор создает строку идентификатора для каждой конструкции в коде, отмеченной для создания документации. (Сведения о создании тегов в коде см. в разделе Рекомендуемые теги для комментариев документации.) Строка идентификатора однозначно определяет конструкцию. Программы обработки XML-файлов могут использовать строку идентификатора для идентификации соответствующего элемента метаданных или отражений .NET Framework, к которому применяется документация.
XML-файл не является иерархическим представлением кода; он содержит список с созданным идентификатором для каждого элемента.
Компилятор следует приведенным ниже правилам при формировании строк идентификаторов:
Отсутствие пробела в строке.
Первая часть строки идентификатора определяет тип идентифицируемого члена в виде одного символа с последующим двоеточием. Используются следующие типы элементов.
Символ
Описание
N
пространство имен
Нельзя добавлять комментарии документации к пространству имен, но можно создать CREF-ссылки на них, если они поддерживаются.
T
тип: класс, интерфейс, структура, перечисление, делегат
F
поле
P
свойство (включая индексаторы или другие индексированные свойства)
M
метод (включая такие специальные методы как конструкторы, операторы и так далее)
E
событие
!
строка ошибки
Остальная часть строки содержит сведения об ошибке. Компилятор C# создает сведения об ошибках для ссылок, которые не могут быть разрешены.
Вторая часть строки – это полное имя элемента, начиная с корневого пространства имен. Имя элемента, включающий его тип и пространство имен разделяются точками. Если имя элемента содержит точки, они заменяются решетками (#). Предполагается, что элемент не имеет символов решетки непосредственно в имени. Например, полное имя конструктора String будет "System.String.#ctor".
Для свойств и методов при наличии аргументов метода, список аргументов следует заключить в скобки. Если аргументов нет, скобки отсутствуют. Несколько аргументов разделяются запятыми. Кодировка каждого аргумента следует непосредственно из того, как он кодируется в подписи .NET Framework.
Базовые типы. Обычные типы (ELEMENT_TYPE_CLASS или ELEMENT_TYPE_VALUETYPE) представлены полным именем типа.
Встроенные типы (например, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF и ELEMENT_TYPE_VOID) представлены полным именем соответствующего полного типа. Например, System.Int32 или System.TypedReference.
ELEMENT_TYPE_PTR представлен символом звездочки (“*”) после измененного типа.
ELEMENT_TYPE_BYREF представлен символом “@” после измененного типа.
ELEMENT_TYPE_PINNED представлен символом “^” после измененного типа. Компилятор C# не создает этот тип.
ELEMENT_TYPE_CMOD_REQ представлен символом “|” и полным именем класса модификатора после измененного типа. Компилятор C# не создает этот тип.
ELEMENT_TYPE_CMOD_OPT представлен символом “!” и полным именем класса модификатора после измененного типа.
ELEMENT_TYPE_SZARRAY представлен символом “[]” после типа элемента массива.
ELEMENT_TYPE_GENERICARRAY представлен символом “[?]” после типа элемента массива. Компилятор C# не создает этот тип.
ELEMENT_TYPE_ARRAY представлен [нижняя граница:size,нижняя граница:size], где число запятых это ранг - 1, а нижние границы и размер каждой размерности (если они известны) представлены десятичными числами. Если нижняя граница или размер не указаны, они просто опускаются. Если нижняя граница и размер для определенной размерности опущены, “:” также опускается. Например, двухмерный массив с 1 в качестве нижних границ и незаданными размерами – [1:,1:].
ELEMENT_TYPE_FNPTR представлен "=FUNC:type(подпись)", где type – возвращаемый тип, а подпись – аргументы метода. Если аргументы отсутствуют, скобки опускаются. Компилятор C# не создает этот тип.
Следующие компоненты подписи не представляются, так как они никогда не используются для разграничения перегруженных методов:
соглашение при вызове
возвращаемый тип
ELEMENT_TYPE_SENTINEL
Только для операторов преобразования (op_Implicit и op_Explicit) возвращаемое значение кодируется в виде “~” с последующим возвращаемым типом как закодировано выше.
Для универсальных типов после имени типа будет следовать символ “`”, а затем число, указывающее количество параметров универсальных типов. Например:
<member name="T:SampleClass`2"> является тегом для типа, определенного как public class SampleClass<T, U>.
Для методов, принимающих в качестве параметров универсальные типы, параметры универсальных типов указываются в виде чисел, которым предшествуют символы “`” (например, `0,`1). Каждое число, представляющее нулевую нотацию массива для универсальных параметров типа.
Примеры
В следующих примерах показано как создаются строки идентификаторов для класса и его членов.
///
///
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"
}
}
См. также
Задачи
Основные понятия
Руководство по программированию в C#
Ссылки
/doc (комментарии документации процесса) (параметры компилятора C#)
Комментарии XML-документации (Руководство по программированию в C#)