7 Common Language Specification (CLS)

ANNOTATION

This section briefly introduces the CLS, the set of restrictions on the CTS (Common Type System) that ensure interoperability among languages. It is important to remember that the CLS rules apply only to items that are visible outside of their defining assembly, with public, family, or family-or-assembly accessibility.

The CLS rules themselves are presented in the context of the discussion of the CTS, primarily in Partition I, section 8. This context is very important to understanding each of the rules, although Partition I, section 11 is simply a list of the CLS rules, provided as a convenient reference. Partition I, section 10 provides the name and type rules for the CLS and is also very important for understanding the CLS.

There are expected to be three categories of implementers of the CLS: frameworks, consumers, and extenders. Each CLS rule in this standard is described in terms of how it affects implementers in each of these three categories. This section mainly describes these categories, discusses CLS compliance, and explains how to mark CLS compliance.

7.1 Introduction

The 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.

ANNOTATION

The Common Type System was designed for reach to allow as many programming languages as possible to support all of their types. Equally important was to ensure interoperation among languages, which meant that all complying languages and framework developers had to agree on a subset of the CTS for all publicly exposed types.

Framework developers need to ensure that all complying languages can fully use their libraries, and that those libraries are full-featured. The process of coming to an agreement was not an easy one, because the agreement required compromise from all parties. In most cases, languages had to add elements not previously supported and accept that some features that their programmers liked were not interoperable with other languages. Framework developers had to write libraries with a limited set of types, so all conforming languages could use the libraries.

Framework developers need to be language-agnostic because generally the goal is for the framework to be usable by any compliant language, and the restrictions described in the CLS ensure this. The other two categories described, consumers and extenders, are usually language-centered.

In general, language designers need to add features to their languages to adhere to the rules of the CLS, and to ensure language access to frameworks. Consumer languages have a small set of requirements because they will simply use the frameworks. Extender languages, however, must implement more of the CLS to allow them to extend existing frameworks. Section 7.2 below lists some of the requirements of each of these three.

7.2 Views of CLS Compliance

This section and its subsections contain only informative text.

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 Framework

A 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:

• Avoid the use of names commonly used as keywords in programming languages.

• Should not expect users of the framework to be able to author nested types.

• Should assume that implementations of methods of the same name and signature on different interfaces are independent.

• Should not rely on initialization of value types to be performed automatically based on specified initializer values.

7.2.2 CLS Consumer

A 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:

• Support calling any CLS-compliant method or delegate.

• Have a mechanism for calling methods that have names that are keywords in the language.

• Support calling distinct methods supported by a type that have the same name and signature, but implement different interfaces.

• Create an instance of any CLS-compliant type.

• Read and modify any CLS-compliant field.

• Access nested types.

• Access any CLS-compliant property. This does not require any special support other than the ability to call the getter and setter methods of the property.

• Access any CLS-compliant event. This does not require any special support other than the ability to call methods defined for the event.

The following is a list of things CLS consumer tools need not support:

• Creation of new types or interfaces.

• Initialization metadata (see Partition II) on fields and parameters other than static literal fields. Note that consumers may choose to use initialization metadata, but may also safely ignore such metadata on anything other than static literal fields.

7.2.3 CLS Extender

A 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:

• Define new CLS-compliant types that extend any (non-sealed) CLS-compliant base class.

• Have some mechanism for defining types with names that are keywords in the language.

• Provide independent implementations for all methods of all interfaces supported by a type. That is, it is not sufficient for an extender to require a single code body to implement all interface methods of the same name and signature.

• Implement any CLS-compliant interface.

• Place any CLS-compliant custom attribute on all appropriate elements of metadata.

Extenders need not support the following:

• Definition of new CLS-compliant interfaces

• Definition of nested types

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.

End informative text

7.3 CLS Compliance

ANNOTATION

Whenever no CLS rule is specified, the CTS specifications apply to the CLS with no change.

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

• have signatures composed only of CLS-compliant types, or

• are specifically marked as not CLS-compliant

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-Compliant

The 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:

• When an assembly does not carry an explicit System.CLSCompliantAttribute, it shall be assumed to carry System.CLSCompliantAttribute(false).

• By default, a type inherits the CLS-compliance attribute of its enclosing type (for nested types) or acquires the value attached to its assembly (for top-level types). It may be marked as either CLS-compliant or not CLS-compliant by attaching the System.CLSCompliantAttribute attribute.

• By default, other members (methods, fields, properties, and events) inherit the CLS compliance of their type. They may be marked as not CLS-compliant by attaching the attribute System.CLSCompliantAttribute(false).

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).