Всяка програма на С# се компилира до междинен език IL (Intermediate Language). Microsoft предоставя стандартен инструмент за разглеждане на този, генериран от компилаторите на С#, код. Това е инструментът Microsoft .NET Framework Disassembler (ILDASM). С тази деасемблираща програма можем да отворим всяко .NET асембли и да разгледаме неговите пространства от имена, класове, типове и код.
Инструментът ildasm.exe е стандартна част от Microsoft .NET Framework SDK. Обикновено .NET Framework SDK идва заедно с Visual Studio .NET и се намира в директория C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin. Нека илюстрираме как се използва той. За целта трябва да изпълним следните стъпки:
-
Стартираме командния интерпретатор cmd.exe:
Start | Programs | Accessories | Command Prompt
| -
Отиваме в директорията, където се намира компилираната програма, например, програмата от предходния пример Digits.exe:
cd "C:\DotNet-course-lectures\Lecture-2-Introduction-to-CSharp\Demo-3-Digits\bin\Debug"
| -
Извикваме от командната линия инструмента ILDASM (ildasm.exe) и му подаваме като параметър компилираната програма Digits.exe:
-
Навигирайки по дървото, което ILDASM показва за асемблито Digits.exe, можем да видим как изглежда MSIL кодът за конструктора на класа Digits и за метода му Main():
XML документация в C#
XML документацията в C# програмите представлява съвкупност от коментари, започващи с ///. Тя може да съдържа различни XML тагове – например, таг описващ връщана стойност на метод, таг за препратки към други методи и др. Като идея XML документацията прилича на JavaDoc в Java.
XML документацията значително улеснява поддръжката – документацията е част от кода, а не стои във външен файл. Поддържа се лесно и ползата от нея е видима още при разработката на приложението – Visual Studio .NET показва краткото описание на даден метод, ако той е документиран чрез вградената XML документация, при задействане на IntelliSense. C# компилаторът може да извлича XML документацията като XML файл за по-нататъшна обработка.
Ето пример за използване на XML документация:
///
/// The main entry point for the application.
///
///
The command line arguments
static void Main(string[] args)
{
// ...
}
/// Calculates the square of a number
///
The number to calculate
/// The calculated square
/// Thrown when the
/// result is too big to be stored in an int
///
public static int square(int num)
{
// ...
}
| Тагове в XML документацията
Ето по-важните тагове, използвани в XML документацията в C#:
-
… – кратко описание за какво се отнася даден тип, метод, свойство и т.н. Visual Studio .NET показва това описание при задействане на IntelliSense.
-
… – подробно описание на даден тип, метод, свойство и т.н. Visual Studio .NET показва това описание в областта Object Browser.
-
…
– описание на един от параметрите на даден метод.
-
… – описание на връщаната от даден метод стойност.
-
…> – описание на изключение, което може да възникне в даден метод.
-
– препратка към информация, свързана с текущото описание.
-
… – описание на свойство (property).
Извличане на XML документация от C# сорс код
Сега ще покажем как чрез C# компилатора може да се извлече документацията от C# файл в отделен XML файл. Нека имаме следната програма на C#, която използва XML документация:
MainClass.cs
|
using System;
namespace XMLCommentsDemo
{
///
/// MainClass is a sample illustrating how to use XML
/// documentation in C#.
///
class MainClass
{
/// Calculates the square of a number
///
The number to calculate
/// The calculated square
/// Thrown when the
/// result is too big to be stored in an int
///
public static int Square(int num)
{
checked
{
return num*num;
}
}
///
/// The main entry point for the application.
///
///
The command line arguments
static void Main(string[] args)
{
Console.WriteLine("3*3 = " + Square(3));
}
}
}
|
За да извлечем документацията от тази програма, трябва да изпълним следните стъпки:
-
Стартираме командния интерпретатор cmd.exe:
Start | Programs | Accessories | Command Prompt
| -
Отиваме в директорията, където се намира сорс кода на програмата. Нека тя е Demo-6-XML-Comments:
cd "C:\DotNet-course-lectures\Lecture-2-Introduction-to-CSharp\Demo-6-XML-Comments"
| -
Извикваме компилатора на C#, за да компилира файла MainClass.cs, като му задаваме опцията за извличане на XML документацията в отделен файл:
csc MainClass.cs /doc:MainClassComments.xml
| -
Отваряме получения .xml файл с Internet Explorer, за да разгледаме съдържанието му.
Ето как полученият XML файл:
MainClassComments.xml
|
MainClass
MainClass is a sample illustrating how to use XML
documentation in C#.
Calculates the square of a number
The number to calculate
The calculated square
Thrown when
the result is too big to be stored in an int
The main entry point for the application.
The command line arguments
| Генериране на HTML документация от VS.NET
Сега ще покажем как чрез Visual Studio .NET може да се генерира HTML документация за даден проект на C# по XML коментарите в неговия сорс код. Във вид на HTML документацията е много по-удобна за четене и разглеждане.
За целта трябва да изпълним следните стъпки:
-
Отваряме с Visual Studio .NET проект, в който сме използвали XML документиране, например проекта Demo-6-XML-Comments.sln, който съдържа кода от предходния пример.
-
От меню Tools избираме Build Comment Web Pages…. Указваме директория, където да се генерира HTML документацията, и натискаме бутона [OK]. Visual Studio .NET ще генерира в посочената директория съвкупност от HTML файлове, които документират нашия проект и съдържат XML коментарите от сорс кода му, подредени в подходящ за разглеждане вид.
-
Разглеждаме HTML документацията, която Visual Studio .NET е генерирал. Можем да навигираме по пространствата от имена, типовете от проекта и отделните му методи:
Сподели с приятели: |
