Introduction
Asmex is a viewer for the internals of .NET assembly files. While the world is not
particularly short of .NET assembly viewers, Asmex has some unique features and the source
might prove useful in various contexts. Asmex's features include:
- Extract resources from assemblies
- View raw metadata tables
- Open assemblies as files or as Global Assembly Cache entries
- View disassembly (by cheating and spawning ILDASM)
- View PE file structures
- Browse types, namespaces, method parameters etc
Rationale
Asmex was an educational project; the idea was to make an application that involved
knowledge of the very lowest possible level of .NET, yet also took advantage of the clean
GUI model of WinForms. It is used in our company for
training and debugging purposes.
In terms of low-level .NET, Asmex contains code to read raw metadata tables and such-like.
I was generally impressed by the efficient and ingenious way .NET metadata is stored.
The elegance (relative to MFC) of the WinForms model is demonstrated by fitting the
heterogeneous data obtained by reflection and binary file parsing into a common tree format
for display. Again, I was impressed by how much less work this was than the MFC equivalent.
A generic object properties viewer (taken from another project) is also shoehorned into
Asmex -- it uses .NET's interesting Attribute functionality to provide a properties list for
each item in the tree.
Asmex was not intended to win prizes for canonically correct design, and that is
why the data is held in classes derived from the GUI tree node. Sorry :)
This article will discuss the (hopefully) more reusable and interesting areas of the Asmex
source code.
PE File Reader / .NET Metadata Reader
The FileViewer namespace contains the most useful part of ASMEX. A very short
and vague description of the structures dealt with in FileViewer follows. If
you are an expert on Microsoft executable formats, you will want to skip it. Otherwise, you
might find it too vague, in which case you can either look at Asmex's source or ask me about
it. I love talking about file formats. Incidentally, if there is any demand for a
brief overview of PE/.NET file formats and .NET type, resource and metadata concepts, I would
love an excuse to write one.
Background -- PE Files
Almost every Windows executable, DLL or EXE, is a Portable Executable (PE) format file.
Although there is little in the PE format that lends itself to .NET, in the current
implementation of .NET all assemblies are contained in special PE format files, which have
some traditional bits left out and quite a lot of new bits put in.
Very generally, a PE file consists of a PE header, which contains a list of Data Directory
entries, and a number of Sections which are defined just after the PE header. Not all the
Data Directories have meaning in a .NET file, and not many Sections are present either.
Nevertheless, those that remain are still important -- in particular, the last Data Directory
entry points to the start of .NET information.
Background -- .NET PE Files
The real starting point of a PE file, from the .NET point of view, is the COR20
Header, which tells the .NET runtime where to find the metadata. The COR20 header, like the
PE header, specifies some Data Directories, as well as the entry point for the assembly.
Most of these Data Directories point to things like fixup information which is not useful for
examining the assembly, but one of them points to the start of the Metadata Streams.
Background -- Metadata streams
.NET holds metadata in streams (usually four of them). Each of these streams has a
different format:
- The #Blob Stream holds binary data, which includes method signatures; also strings
in UCS-2.
- The #US Stream stores strings in UCS-2.
- The #GUID Stream contains a list of all the GUIDs that are used in the assembly,
end-to-end. GUIDs are referenced by 1-based indexes, rather than offsets, just to make life
harder.
- The #String Stream holds UTF-8 strings which contain the names of types, methods
etc. that are in the code.
- The #~ Stream contains the Metadata Tables.
- The #- Stream is used instead of #~, under rare circumstances. I think it
contains uncompressed tables.
Background -- Metadata tables
Metadata tables are just regions of data, lying end-to-end inside the file. There is a
fixed, known number of tables, and each table has a fixed, known range of tables that it's
tokens (see below) can refer to. Tables do not actually contain things like strings, method
signatures, etc.; rather, they contain either:
- Tokens that refer to a row in another table
- Numbers that refer to an entry in one of the streams
In general, the structure of the tables is such that you must know the properties of the
particular column you are looking at in order to interpret the numbers found in it. This
leads to a remarkably small data size, considering how rich .NET metadata is. (It's a pity
that this is then stuck into the not-very-efficient PE format). Asmex unpacks the tables,
looks up the strings etc for each row, and presents them in a relatively
friendly format.
Todo: UCS-2 strings are shown in hex form.
Background -- Types
There are two types which it is very important to understand when looking at .NET files
at a binary level:
- RVAs -- These are a PE concept, and MOST pointers within a PE file are in this
format. An RVA is the Relative Virtual Address of an item -- the address it will have
relative to the base address at which the PE file is loaded, AFTER the file is loaded into
memory. This is not the same as the offset within the PE file. Asmex converts between
RVAs and actual file offsets in the
ModHeaders.Rva2Offset method.
- Coded Tokens -- These are a .NET concept, and represent an entry in a metadata
table. They are fairly complex and functions to interpret them are provided in the
MDTables class. Generally, they specify both the table and the row within the
table of a particular data item. Todo: a CodedToken class that supports all coded
token operations.
The Classes
Generally, each class in FileViewer represents some chunk of the information
described above. Where possible, each class describes an actual physical range of bytes in
the file, and is therefore inherited from Region, which is an abstract base
class with 'start' and 'length' properties. Even
though the information about where a given structure is physically located is not that useful
in Asmex's treeview, we keep track of it in case we ever want to create a visual PE file
examiner or a PE file emitter.
There are also some classes that do not represent a particular range of bytes, but
encapsulate other information; these include the Metadata table related classes
Table and TableCell, and also the classes related to PE import and
relocation tables.
Each class takes a BinaryReader in its constructor. This reader is assumed
to refer to the assembly file and to be 'wound' to the right offset. In some cases, it was
necessary to adjust the reader's offset by hand, because some arithmetic is required in
converting RVAs and so on.
These classes should serve as documentation for a wide range of PE and .NET structures.
For comprehensive documentation, please see the Bibliography below.
Reflection Tree
A simple system for representing hierarchical data obtained from the PE file parser or by
reflection. Each item is represented by a BaseNode-derived class, which holds a
reference to a data object. Each node then GenerateChildren method
to populate the items below it, creating new data objects of various types as necessary.
The logic for viewing .NET types by reflection is contained in these tree node classes. This
logic is not very complicated and has been described in many places already, so there's no
need to go through it here.
It is easy to add new data items to Asmex by deriving a new node class, and modifying the
GenerateChildren method of another node so that your new node is sometimes
generated. You can also override your node's GetMenu method to add context
menu operations for that node type.
This design is not a work of genius, but it does the job of presenting the data in a
unified way and generating nodes only on demand. In MFC it would probably have been
necessary to build a large tree infrastructure and connect it to a CTreeCtrl by
some horrible tangle of messages.
Property Viewer
The ObjViewer namespace contains a few classes that define a generic
property-viewer control. ObjViewer is a UserControl that presents a list of
name-value pairs for any given object. Of course, the properties available on
an object don't necessarily add up to a freindly view of the object, so you can use the
ObjViewerAttribute attribute to modify the properties of a target object --
for instance, to specify that a property be shown in hex or not shown at all.
GAC Browser
The GACPicker class allows the user to select an assembly from the Global
Assembly Cache. It does this by looking at the filesystem representation of the GAC, since
there appears to be no actual API in the current .NET environment.
Ridiculous Star-Wars Writing
The HintDlg class presents hints in preposterous Star-Wars style perspective
scrolling text. It uses GraphicsPath.Warp to apply a pseudo-perspective
transformation to the text. Annoying, but I felt it had to be done.
Bibliography
For PE/.NET file format information, I would suggest reading sections 21-24 of
ECMA-335 Partition II, available all
over the web. Inside Microsoft
.NET IL Assembler is also a good book, despite the occasional inaccuracy.
If you want to go further and understand the actual CIL instructions in your assembly,
Compiling for the .NET Common Language Runtime is an excellent book.
If you want to examine your binary files in comfort, may I humbly plug my own
AXE program.
