Where an attribute is stored
An attribute written in source as [Obsolete("use X", true)] becomes one row of the CustomAttribute table with three columns.
Parent is a coded index (HasCustomAttribute) naming what the attribute is on: a type, method, field, parameter, property, event, generic parameter, the assembly or the module, and
a few other rows. Type is a coded index (CustomAttributeType) naming the attribute’s constructor, a MethodDef of this assembly or a MemberRef to another one; the type of the attribute is the type that
constructor belongs to. Value is an index into the #Blob heap.
The blob alone does not say what its bytes are: the constructor’s signature gives the types of the fixed arguments, and the blob has to be read with it. That is why an attribute is decoded only with the metadata at hand.
The value blob
Prologtwo bytes,01 00(the value 0x0001)alwaysFixed argumentsone value for each parameter of the constructor, in order, each written as its type saysfrom the signatureNumNamed2 bytes: how many named arguments followu16Named argumentseach: 0x53 (a field) or 0x54 (a property), the type of the value, the name, the valueby name
An attribute with no arguments is the four bytes 01 00 00 00. The values are written in little-endian, with no padding between them.
How a value is written
| Type | Bytes |
|---|---|
bool | 1 byte, 0 or 1 |
char | 2 bytes, a UTF-16 code unit |
sbyte byte short ushort int uint long ulong | 1, 1, 2, 2, 4, 4, 8, 8 bytes |
float double | 4 and 8 bytes, IEEE 754 |
string | a SerString: the single byte FF for null, otherwise a compressed length (as in signatures) and that many bytes of UTF-8; the empty string is the single byte 00 |
System.Type | a SerString holding the name of the type: the full name, and for a type that is not in the attribute’s own assembly or mscorlib, the assembly name after a comma (System.String, System.Runtime, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a); generic arguments in brackets |
| an enum | the value in the enum’s underlying type (see below) |
object | a boxed value: first the type of the value (as for a named argument below), then the value |
| an array | 4 bytes: the number of elements, or FF FF FF FF for a null array; then the elements, each as its element type says (for object[] each is boxed) |
A named argument gives the type of its value in the blob, since there is no signature to look it up in: the byte of the element type (02 bool, 03 char, 04 to 0D the integer and
floating point types, 0E string), 50 for a Type, 51 for a boxed object, 1D followed by the element type for an array, and 55 followed by a SerString with the name of the type for an enum. Any other byte in that place (in a boxed value, an array element or the declared type of a named argument) is not defined: the explorer stops at it with the error “The serialization type 0x99 at 2 is not defined” (the offset in the blob), keeps the arguments it read before, and does not guess a length.
The size of an enum is not in the blob
An enum value is written in the size of the enum’s underlying type (1, 2, 4 or 8 bytes, signed or not) but the blob names only the enum. To read it a decoder has to find the enum and look at its value__ field. For an enum of the same
assembly that is a lookup in the Field table. For an enum of another assembly it needs that assembly: Microsoft’s reader asks its caller (a GetUnderlyingEnumType callback).
The explorer reads the assembly’s own enums from their value__ field. For enums of the framework it has a table of those whose underlying type is not int, made from the shared framework of .NET 10 by listing every
public enum whose underlying type is not Int32 (about 50 of them: for example EventKeywords is a long, TarEntryType a byte, SecurityRuleSet a byte). An enum it cannot find is assumed to be an int
and the cell says so. Over every assembly of the .NET 10 SDK this assumption was used 57,134 times and the independent reader, which resolves each enum in the running .NET, agreed on every value.
What the explorer shows
- In the CustomAttribute table the Value column of each row is decoded:
AllArgs(true, 'x', -128, …, Level.High, new[] { 1, 2, 3 }, IntField = -1). Enum values are named when the enum is in the same assembly or is one of 32 framework enums the explorer knows (AttributeTargets,LayoutKind,DynamicallyAccessedMemberTypes, …; checked against the runtime’s reflection), and a combination of flags is written asBits.One | Bits.Twothe wayEnum.ToStringwould; any other enum, or a value no member has, is written as a number,(Colour)9. A generic attribute (C# 11,[GA<int>(5)]) has a constructor that belongs to aTypeSpecrow, an instantiation such asGA<int>, and a constructor parameter of type!0; the type arguments of the instantiation fill the parameters, and the attribute is writtenGA<int>(5).Typevalues astypeof(…); a blob that cannot be read is said so with the reason, and the row has a problem. - The Types listing writes the attributes above each declaration: the assembly and module attributes at the top, then those of types, fields, properties, events and methods, with the attributes of parameters and return values under their method (option Custom attributes).
- The Custom attributes section lists all of them with what each is on.
Decoding is checked against System.Reflection.Metadata’s CustomAttributeDecoder: the same text is written from both readers for every attribute row of a test library built to carry every kind of argument (90 attributes), of every assembly of the .NET 10 SDK
(2,621 files, 1,029,017 attributes), and of 700 distinct assemblies found on this machine (212,336 attributes, from .NET Framework 1.0 on): no differences.
Not described
Known, not yet covered
- Reference: declarative security (
DeclSecuritypermission sets in XML and the binary form) and the marshalling descriptors ofFieldMarshalare other blob formats of ECMA-335, not described here yet. - Viewer: the explorer shows attributes by their constructor’s type name and does not interpret what particular attributes mean (
Nullable,CompilerGenerated,Extensionare shown like any other, so nullable annotations and record types are not reconstructed in the type listing). An enum of another assembly that is not in the framework table is assumed to be anintand shown as a number. An array of arrays as the type of a named argument (SZARRAY SZARRAY) is reported as an error, as the independent reader does; ECMA-335 gives a single-dimension array of one element type (the paraphrase of the independent decoder’s source, not a re-reading of the specification text).
Unknown
- Reference: how each runtime treats a blob that is malformed in ways other than those the independent reader refuses (a blob with trailing bytes, a missing named-argument count): the explorer reads a blob that ends after the fixed arguments as having no named arguments, which no document confirms.
Links
Reference
- ECMA-335 – partition II section 23.3: custom attributes
- CustomAttributeDecoder – Microsoft’s decoder, the independent reader these pages were checked against