7.1 IntroductionThe Common Language Specification (CLS) is a set of rules intended to promote language interoperability. These rules shall be followed in order to conform to the CLS. They are described in greater detail in subsequent chapters and are summarized in Partition I, section 11. CLS conformance is a characteristic of types that are generated for execution on a CLI implementation. Such types must conform to the CLI specification, in addition to the CLS rules. These additional rules apply only to types that are visible in assemblies other than those in which they are defined, and to the members (fields, methods, properties, events, and nested types) that are accessible outside the assembly (i.e., those that have an accessibility of public, family, or family-or-assembly). NOTE A library consisting of CLS-compliant code is herein referred to as a "framework." Compilers that generate code for the CLI may be designed to make use of such libraries, but not to be able to produce or extend such library code. These compilers are referred to as "consumers." Compilers that are designed to both produce and extend frameworks are referred to as "extenders." In the description of each CLS rule, additional informative text is provided to assist the reader in understanding the rule's implication for each of these situations.
7.2 Views of CLS Compliance
The CLS is a set of rules that apply to generated assemblies. Because the CLS is designed to support interoperability for libraries and the high-level programming languages used to write them, it is often useful to think of the CLS rules from the perspective of the high-level source code and tools, such as compilers, that are used in the process of generating assemblies. For this reason, informative notes are added to the description of CLS rules to assist the reader in understanding the rule's implications for several different classes of tools and users. The different viewpoints used in the description are called framework, consumer, and extender and are described here. 7.2.1 CLS FrameworkA library consisting of CLS-compliant code is herein referred to as a "framework." Frameworks (libraries) are designed for use by a wide range of programming languages and tools, including both CLS consumer and extender languages. By adhering to the rules of the CLS, authors of libraries ensure that the libraries will be usable by a larger class of tools than if they chose not to adhere to the CLS rules. The following are some additional guidelines that CLS-compliant frameworks should follow:
7.2.2 CLS ConsumerA CLS consumer is a language or tool that is designed to allow access to all of the features supplied by CLS-compliant frameworks (libraries), but not necessarily be able to produce them. The following is a partial list of things CLS consumer tools are expected to be able to do:
The following is a list of things CLS consumer tools need not support:
7.2.3 CLS ExtenderA CLS extender is a language or tool that is designed to allow programmers to both use and extend CLS-compliant frameworks. CLS extenders support a superset of the behavior supported by a CLS consumer; i.e., everything that applies to a CLS consumer also applies to CLS extenders. In addition to the requirements of a consumer, extenders are expected to be able to:
Extenders need not support the following:
The Common Language Specification is designed to be large enough that it is properly expressive and small enough that all languages can reasonably accommodate it.
7.3 CLS Compliance
As these rules are introduced in detail, they are described in a common format. For an example, see the first rule below. The first paragraph specifies the rule itself. This is then followed by an informative description of the implications of the rule from the three different viewpoints as described above. The CLS defines language interoperability rules, which apply only to "externally visible" items. The CLS unit of that language interoperability is the assembly that is, within a single assembly there are no restrictions as to the programming techniques that are used. Thus, the CLS rules apply only to items that are visible (see Partition I, section 8.5.3) outside of their defining assembly and have public, family, or family-or-assembly accessibility (see Partition I, section 8.5.3.2).
CLS Rule 1: CLS rules apply only to those parts of a type that are accessible or visible outside of the defining assembly. NOTE CLS (consumer): No impact. CLS (extender): When checking CLS compliance at compile time, be sure to apply the rules only to information that will be exposed outside the assembly. CLS (framework): CLS rules do not apply to internal implementation within an assembly. A type is CLS-compliant if all its publicly accessible parts (those classes, interfaces, methods, fields, properties, and events that are available to code executing in another assembly) either
Any construct that would make it impossible to rapidly verify code is excluded from the CLS. This allows all CLS-compliant languages to produce verifiable code if they so choose. 7.3.1 Marking Items as CLS-CompliantThe CLS specifies how to mark externally visible parts of an assembly to indicate whether or not they comply with the CLS requirements. This is done using the custom attribute mechanism (see Partition I, section 9.7 and Partition II). The class System.CLSCompliantAttribute (see the .NET Framework Standard Library Annotated Reference) indicates which types and type members are CLS-compliant. It also can be attached to an assembly, to specify the default value for all top-level types it contains. The constructor for System.CLSCompliantAttribute takes a Boolean argument indicating whether the item with which it is associated is or is not CLS-compliant. This allows any item (assembly, type, or type member) to be explicitly marked as CLS-compliant or not. The rules for determining CLS compliance are:
CLS Rule 2: Members of non-CLS-compliant types shall not be marked CLS-compliant. NOTE CLS (consumer): May ignore any member that is not CLS-compliant using the above rules. CLS (extender): Should encourage correct labeling of newly authored assemblies, classes, interfaces, and methods. Compile-time enforcement of the CLS rules is strongly encouraged. CLS (framework): Shall correctly label all publicly exposed members as to their CLS compliance. The rules specified here may be used to minimize the number of markers required (for example, label the entire assembly if all types and members are compliant or if there are only a few exceptions that need to be marked). |