NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Accessing Metadata

Metadata is emitted into and read from a NGWS runtime image using either a set of unmanaged APIs documented in the NGWS runtime Metadata API Specification or through the managed Reflection and Reflection Emit Services documented in the NGWS runtime Base Class Library Specification. The physical data structures persisted in a metadata binary are not manipulated directly by tools or compilers, and so they are not specified here or elsewhere in NGWS runtime documentation. Instead the APIs provide a layer of isolation between the underlying data structures and clients of those data structures. This abstraction enables the runtime to continue to optimize the in-memory and on-disk structures for compile-time and runtime scenarios without requiring updating all compilers as these structures are improved. It also enables a pluggable persistence format architecture that allows NGWS runtime binary representations, Unmanaged COM type libraries, and other formats to be imported into or from memory transparently. The primary design goals for these APIs include maximizing performance and minimizing overhead – the metadata engine stops just short of providing direct access to the in-memory data structures.

While the metadata data structures allow the full VOS Type Model to be expressed, the unmanaged metadata APIs do not check or enforce constraints expressed in the model. This is to reduce compile-time overhead. Instead, the emitting tools and compilers are expected to check the constraints and emit valid NGWS runtime metadata. The NGWS SDK contains a tool, PEVerify, that can be used to verify a NGWS runtime image, including the metadata, during development.

When a class is loaded at runtime, the NGWS runtime loader imports the metadata into its own in-memory data structures, which can be browsed via the NGWS frameworks Reflection services. The Reflection services do much more work for a browser or tool than the unmanaged metadata APIs do, such as automatically walking the inheritance hierarchy to obtain information about inherited methods and fields; the unmanaged metadata APIs return only the direct member declarations for a given class and expect the API client to make additional calls to walk the hierarchy and enumerate inherited methods. The former approach exposes a higher-level view of metadata, where the latter approach puts the API client in complete control of walking the data structures.