Although purely an implementation artifact, the phrase metadata token is found throughout the NGWS frameworks and runtime specifications. The File Format Specification talks about metadata tokens embedded in various sections of a NGWS PE/COFF image. Metadata tokens are embedded in IL and native code to encode method invocations and field accesses at call sites; the token is used by various runtime services to retrieve information from metadata about the reference and the type on which it was scoped in order to resolve the reference. While metadata tokens are primarily of used with the unmanaged Metadata APIs, some of them can also be used with the managed APIs, as shown in the following table.
Logically, a metadata token is a typed identifier of a metadata object (type declaration, member declaration, etc.): With each call to emit a declaration into metadata, a token is returned. Given a token, its type can be determined, and using the appropriate IMetaDataImport method the metadata engine can retrieve the specific metadata attributes that had been persisted for that metadata object. However, it’s important to understand that a metadata token is not a persistent identifier. Rather it is scoped to a specific metadata binary. Physically, a metadata token is an index into a metadata data structure, so access is fast and direct.
Compilers and tools emit metadata by calling the unmanaged emit APIs or managed Reflection Emit classes during compilation and link or, with RAD tools, as a part of building components or applications. The APIs work over in-memory data structures that, at save time, are compressed and persisted as a binary format into the target of the compilation unit (“.obj OBJ file”), executable file (“.EXE file”), shared library (“.DLL file”), or stand-alone metadata binary file.
When multiple compilation units are linked to form an .EXE or .DLL, the unmanaged APIs provide a method used to merge the metadata sections from each compilation unit into a single integrated metadata binary. When two scopes are merged, tokens from the import scope are remapped into tokens in the target emit scope. When a metadata scope is saved, there are various format optimizations that can result in token remaps, which must be handled by the application.
A list of token types and a more detailed explanation of how to manage metadata tokens are provided in the NGWS runtime Metadata API Specification.