An assembly is the unit of deployment of .NET: one or more files (modules) described by a manifest in the metadata of one of them. The directives on this page write the manifest: who the assembly is, which assemblies it needs, which files and resources belong to it and which types it exports. ECMA-335 II.6 describes them; the grammar of ilasm (assemblyHead, assemblyRefHead, exptypeHead, manifestResHead) is the reference for the exact words.
.assembly extern mscorlib
{
.publickeytoken = (B7 7A 5C 56 19 34 E0 89)
.ver 4:0:0:0
}
.assembly Counter
{
.custom instance void [mscorlib]System.Reflection.AssemblyTitleAttribute::.ctor(string) = ( 01 00 07 43 6F 75 6E 74 65 72 00 00 )
.hash algorithm 0x00008004
.ver 1:0:0:0
}
.module Counter.exe.assembly
.assembly [flags] Name { declarations } names the assembly the module belongs to; a module has at most one. The flags are words between the directive and the name.
| Flag | Meaning |
|---|---|
retargetable | sets the Retargetable bit of the assembly flags (the identity may be redirected to another assembly at run time) |
windowsruntime | the assembly holds Windows Runtime types |
noplatform | no processor architecture is set |
legacy library | accepted, with no effect on the flags |
cil, x86, amd64, arm, arm64 | the processor architecture the assembly is for (cil is architecture-neutral) |
| Declaration | Meaning |
|---|---|
.hash algorithm n | the algorithm that computed the hashes of the other files of the assembly (0x8004 = 32772 is SHA-1, the value in the standard’s example); one algorithm for the whole assembly |
.publickey = ( bytes ) | the full public key of the publisher, for a strong-named assembly |
.ver a:b:c:d | major, minor, build and revision, each up to 65535; * is accepted for a part and is read as 0xFFFF, which ilasm replaces by 0 in the assembly it writes |
.locale "culture" or .locale = ( bytes ) | the culture the assembly is built for ("en-GB"); the standard’s word is .culture, which ilasm does not have |
.custom …, .permission …, .permissionset … | attributes and declarative security of the assembly (Custom attributes) |
| preprocessor lines | #define, #ifdef and the rest are allowed between the declarations |
.assembly extern
.assembly extern [flags] Name [as Alias] { … } declares an assembly this one refers to. The name must be the assembly’s own name (case-sensitive); the as clause lets the source use another name for it in […] scopes. The body can hold the same .ver, .locale, .publickey and .custom and, for a reference:
| Declaration | Meaning |
|---|---|
.publickeytoken = ( 8 bytes ) | the low 8 bytes of the SHA-1 hash of the publisher’s public key: the short form of the key, used to check that the referenced assembly was signed by the same publisher |
.hash = ( bytes ) | the hash of the referenced assembly’s file |
auto | sets the reference to be auto-detected (ilasm records the request; see Not described) |
A reference may carry either the full key or the token, or neither. The standard library of .NET is referenced as mscorlib (the .NET Framework), System.Runtime and the other facade assemblies (.NET Core and later), each with its own version and token.
.assembly extern System.Runtime
{
.publickeytoken = (B0 3F 5F 7F 11 D5 0A 3A)
.ver 10:0:0:0
}
.assembly extern MyComponents
{
.publickeytoken = (BB AA BB EE 11 22 33 00)
.hash = (2A 71 E9 47 F5 15 E6 07 35 E4 CB E3 B4 A1 D3 7F 7F A0 9C 24)
.ver 2:10:2002:0
}Modules and files
| Directive | Meaning |
|---|---|
.module [Name] | names this module, by a logical name that other modules and the manifest use (.module Counter.exe); the name may be left out. Attributes written right after it belong to the module |
.module extern Name | declares another module of the same assembly (the manifest module lists them; the name must match that module’s .module) |
.file [nometadata] Name [.hash = ( bytes )] [.entrypoint] | adds a file to the manifest: a module, or with nometadata any data file; the hash is checked when the file is read; .entrypoint says the entry point of the assembly is in that file |
Resources
.mresource [public | private] Name [as Alias] { … } adds a manifest resource: a named block of data, exported when public and visible only inside the assembly when private. Its body says where the data is.
| Item | Meaning |
|---|---|
.file Name at offset | the resource is in that file (declared with a top-level .file) at that byte offset (0 for a file that is not a module) |
.assembly extern Name | the resource is in another assembly |
.custom … | an attribute on the resource |
The text form never holds the bytes of a resource: for a resource embedded in the file, ildasm writes the data to a separate .resources file and lists only the .mresource declaration (the comment in its source reads “embedded resource – dump as .resources file”).
Exported types and type forwarders
A type defined in a module other than the manifest module must be listed in the manifest to be visible outside the assembly. .class extern [attributes] Name { … } does that, with public or nested public (and the others of the class accessibility words) as attributes and a body that says where the type is.
| Item | Meaning |
|---|---|
.file Name | the type is defined in that file |
.class extern Outer | the type is nested in that exported type |
.assembly extern Name | the type has moved to that assembly: a type forwarder, written with the attribute forwarder |
mdtoken(n), .class n | the implementation and the type definition given as metadata tokens or row numbers |
.custom … | an attribute on the exported type |
.class extern forwarder System.Collections.ArrayList
{
.assembly extern System.Collections.NonGeneric
}
.class extern public Foo
{
.file B.dll
}The top-level .export directive is the deprecated spelling of .class extern; inside a method, .export means something else (Marshalling and platform invoke).
Not described
Known, not yet covered
- Reference: strong-name signing (what the key and the hash cover, II.6.2.1.3) and the rules of version binding are in the standard and in the documentation of .NET; they are not repeated. The ilasm options that set the key (
/KEY), the assembly name (/ANAME) and the resource file are on the tooling page.
Unknown
- Reference: what the
autoword of.assembly externdoes: the grammar andAsmMan::SetAssemblyAutodetectrecord a flag, but where ilasm uses it was not found in the files read.