Metadata API Overview
The common language runtime (CLR) metadata API enables a component's metadata to be accessed without requiring the class to be loaded by the runtime. The API is designed specifically to maximize performance and minimize overhead. The metadata engine makes the data available but stops short of providing direct access to the in-memory data structures. In contrast, when a class is loaded at run time, the loader imports the metadata into its own data structures, which you can browse using the runtime's reflection services.
Metadata API Versus Reflection Services
The reflection services do much more work than the metadata API. For example, they automatically walk the inheritance hierarchy to obtain information about inherited methods and fields. The metadata API returns only the direct member declarations for a given class and requires the API client to make additional calls to walk the hierarchy and enumerate inherited methods. The reflection services approach exposes a higher-level view of metadata, whereas the metadata API approach puts the API client in complete control of walking the data structures.
Scope
At any given time you might have several distinct areas of memory that contain metadata. For example, you might have one area that maps all of the metadata from an existing module on disk. At the same time, you might be emitting metadata into a separate area that you will later save as a module into a file.
Note
The word module here means a file that contains metadata. Typically it will be an .obj, .exe, or .dll file that contains both metadata and Microsoft intermediate language (MSIL) code, but it can also be a file that contains only metadata.
Each separate area of metadata in memory is referred to as a scope. Each scope corresponds to one module. Modules are often saved as files on disk, but this is not required. For example, scripting tools frequently generate metadata that is never persisted into a file.
The term scope is used because it represents the region within which metadata tokens are defined. For example, a metadata token with value N identifies details about a class definition within a given scope. However, a metadata token with the same value N might correspond to a completely different set of details for a different scope.
To establish a metadata scope in memory, you call the CComPtrBase::CoCreateInstance method of the IMetaDataDispenser interface. This method creates a new scope or opens an existing set of metadata structures from a file or memory location. With each call to the IMetaDataDispenser::DefineScope or the IMetaDataDispenser::OpenScope method, the caller specifies which API to receive:
The IMetaDataEmit interface enables tools to write to a metadata scope.
The IMetaDataImport interface enables tools to read from a metadata scope.
Error Checking
The metadata API performs a minimum of semantic error checking. The metadata API methods assume that the tools and services that emit metadata are enforcing the object system rules that are outlined in the common type system, and that any additional checking by the metadata engine during development time is superfluous.