This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!
Metadata Extensibility
NGWS runtime metadata is extensible. There are three reasons this is important:
- The NGWS frameworks and runtime Common Language Specification (CLS) is a specification for conventions that languages and tools agree to support in a uniform way for better language integration. The CLS constrains parts of the VOS model, and the CLS introduces higher-level abstractions that are layered over the VOS. It is important that the metadata be able to capture these sorts of development-time abstractions that are used by tools even though they are not recognized or supported explicitly by the runtime.
- It should be possible to represent language-specific abstractions in metadata that are neither NGWS nor CLS language abstractions. For example, it should be possible, over time, to enable languages like C++ to not require separate header files or IDL files in order to use types, methods, and data members exported by compiled modules.
- It should be possible, in member signatures, to encode types and type modifiers that are used in language-specific overloading. For example, to allow C++ to distinguish int from long even on 32-bit machines where both map to the underlying type int32.
This extensibility comes in the following forms:
- Every metadata object can carry custom attributes, and the metadata APIs provide a way to declare, enumerate, and retrieve custom attributes. Custom attributes may be identified by a simple name, where the value encoding is opaque and known only to the specific tool, language, or service that defined it. Or, custom attributes may be identified by a type reference, where the structure of the attribute is self-describing (via data members declared on the type) and any tool including the NGWS frameworks Reflection services may browse the value encoding. Refer to the Metadata API Specification for details.
CLS Rule 32: CLS-compliant tools are only required to deal with a subset of the encodings of custom attributes. The only types that can appear in these encodings are: System.Type, System.String, System.Char, System.Boolean, System.Byte, System.Int16, System.Int32, System.Int64, System.Single, System.Double, and any enumeration type based on a CLS-compliant base type.
CLS (consumer): Must be able to read attributes encoded using the restricted scheme. Must be able to attach attributes based on existing attribute classes to any metadata that is emitted. Must implement the rules for the System.AttributeUsageAttribute.
CLS (extender): Must be able to author new classes and new attributes, as well as all requirements for CLS consumer.
CLS (framework): Must externally expose only attributes that are encoded within the CLS rules and following the conventions specified for System.AttributeUsageAttribute
- In addition to VOS type extensibility, it is possible to emit custom modifiers into member signatures. NGWS runtime will honor these modifiers for purposes of method overloading and hiding, as well as for binding, but will not enforce any of the language-specific semantics. These modifiers can reference the return type or any parameter of a method, or the type of a field. They come in two kinds: required modifiers that anyone using the member must understand in order to correctly use it, and optional modifiers that can be ignored if the modifier is not understood. Refer to the Type and Signature Encoding Specification for details.
CLS Rule 33: CLS-compliant tools shall not generate publicly visible required modifiers, and shall ignore optional modifiers they do not understand. They need not emit either kind of modifier, although they must be able to copy both kinds of modifiers should they exist in metadata that they import.
CLS (consumer): Must be able to read metadata containing optional modifiers and correctly copy signatures that include them. May ignore these modifiers in type matching and overload resolution. May ignore types that become ambiguous when the optional modifiers are ignored, or that use required modifiers.
CLS (extender): Must be able to author signatures that include optional modifiers.
CLS (framework): Must not use required modifiers in externally visible signatures unless they are marked as not CLS-compliant.