Resources inside an assembly
An assembly can carry files: pictures, text, strings for the user interface. Each is one row of the ManifestResource table with a name, flags (public 1 or private 2), and an Implementation. When the Implementation is empty the resource is embedded: its Offset is a position inside the block that the CLR header’s Resources directory points at, and there the resource is a 4-byte length followed by that many bytes. When the Implementation is a File row the resource is in another file of the assembly, and when it is an AssemblyRef row it is in another assembly.
The bytes of a resource can be anything. Compilers write each embedded file as it is, and for the localised strings of a project they compile the .resx (an XML file, described by Microsoft’s documentation and not here) into a binary .resources file
named Namespace.Name.resources and embed that. A resource named .g.resources is the same kind of file that WPF fills with its compiled pages. A satellite assembly (de/Name.resources.dll) is an assembly with no code whose only content is
the resources of one culture. The resources in the block usually start on 8-byte boundaries, with a few bytes of padding between them.
The .resources file
Magic, header version, header size0xBEEFCACE (the bytesCE CA EF BE), 1, and the length of the two names that follow12 bytesReader type, resource set typetwo names, each a length (7 bits at a time) and UTF-8: normallySystem.Resources.ResourceReader, mscorlib, …andSystem.Resources.RuntimeResourceSetthe headerResource set version, count, type count3 times 4 bytes: version 2 (the form used since .NET 2.0), the number of resources, the number of user types12 bytesType namesone name for each user type (a type that is not one of the built-in ones), as the header doesvariablePaddingthe lettersPADrepeated, to bring the next table to an 8-byte boundary of the file0 to 7 bytesName hashesthe 32-bit hash of each name, in ascending ordercount × 4Name offsetsfor each hash, where its name starts in the name sectioncount × 4Data section offsetwhere the values start in the file4 bytesNameseach: the length of the name in bytes (7 bits at a time), the name in UTF-16, and the 4-byte offset of its value in the data sectionvariableDatathe values: a type code (7 bits at a time), then the data of that typeto the end
The hash of a name is computed over its UTF-16 characters: start from 5381 and for each character multiply by 33 and exclusive-or the character, in 32 bits. The reader finds a name by binary search over the sorted hashes. The explorer checks that each hash is the hash of the name it belongs to.
Value types
The type code of a value is 0 to 0x10, 0x20 and 0x21 for the built-in types and 0x40 + n for the n-th user type of the type name table. Every other code (0x11 to 0x1F, 0x22 to 0x3F) is not defined, and a user type number with no name in the table is an error too: the explorer marks that one entry with the problem
(“has the type code 0x3f, which is not defined”), shows the others as they are, and ResourceReader refuses such a value as well (checked for each of the 109 codes, and against ResourceReader for a sample).
| Code | Type | Data |
|---|---|---|
| 0 | Null | nothing |
| 1 | String | a length (7 bits at a time) and UTF-8 |
| 2 | Boolean | 1 byte |
| 3 | Char | 2 bytes, a UTF-16 code unit |
| 4, 5 | Byte, SByte | 1 byte |
| 6, 7 | Int16, UInt16 | 2 bytes |
| 8, 9 | Int32, UInt32 | 4 bytes |
| 10, 11 | Int64, UInt64 | 8 bytes |
| 12, 13 | Single, Double | 4 and 8 bytes, IEEE 754 |
| 14 | Decimal | 16 bytes: low, middle and high 32 bits of the 96-bit number, then the flags (the scale in bits 16 to 23, the sign in bit 31) |
| 15 | DateTime | 8 bytes: DateTime.ToBinary(), the ticks since 0001-01-01 of 100 nanoseconds in the low 62 bits and the kind in the top two |
| 16 | TimeSpan | 8 bytes, ticks |
| 0x20 | ByteArray | a 4-byte length and the bytes |
| 0x21 | Stream | a 4-byte length and the bytes |
| 0x40 + n | user type n | the bytes of an object of that type, written by whatever serialised it (normally the binary formatter), up to the next value |
The end of a value is where the next one starts, so the explorer takes the data of a user-typed value as all the bytes up to there. It does not deserialise them: the type needs the code that wrote it.
What the explorer shows
- In an assembly the Managed resources block has one node for each embedded resource: its length and its bytes (a text file shows its first characters), or for a
.resourcesfile the whole structure below: header, type names, hashes, name offsets, names, and every value with its type code and decoded value. A byte array or stream value opens as a file of its own, named by its resource name. - The Manifest resources section lists every row; Resources in .resources files lists the name, type and value of every resource of the embedded files.
- A
.resourcesfile opens by itself, with the same structure as a node tree: a file named.resources, or any file that starts with the magic.
The reading is checked against System.Resources.ResourceReader (its GetResourceData gives each resource’s type name and bytes, and the enumerator its value): the same lines are written from both readers for the files made to cover every type (22 built-in values, user types, 300 names), and for the
manifest resources of the test library, its satellite assembly and 700 distinct assemblies found on this machine (257 manifest resources and 12,032 resource entries, some from .NET Framework 1.x). Differences: none.
Not described
Known, not yet covered
- Reference: version 1 resource sets (the .NET Framework 1.x form, where each value is a serialised object preceded by an index into the type names) are read from the description and real files made by .NET 1.x compilers: the names and the bytes of every value agree with
ResourceReader, whose own type names for these values differ from the type table and are not compared. No writer of today produces version 1. The.resxXML format is not described. - Viewer: values of user types (images, icons, settings objects) are shown as bytes, not deserialised; a bitmap or icon inside one is not opened.
Unknown
- Reference: how every writer of the past padded the file: the explorer accepts any padding before the hash table that is not longer than needed for the alignment.
Links
Reference
- Resources in .NET – Microsoft’s overview of resource files
- ResourceReader – the class that reads the format, the independent reader these pages were checked against
- ECMA-335 – partition II section 22.24: the ManifestResource table