CLS compliance means designing a .NET component’s public API around features shared by languages that support the Common Language Specification (CLS). It can help code written in one CLS-supporting language consume a library written in another, but it does not make every .NET feature available in every language or combine multiple languages’ source code into a single assembly.
What is the Common Language Specification?
The CLS is a set of rules for generated .NET assemblies. A component that follows those rules exposes features that code in any language supporting the CLS can consume. The formal rules are in ECMA-335, Partition I, Clauses 7 through 11, as identified by Microsoft’s overview of language independence and language-independent components.
CLS compliance establishes a common subset, not universal compatibility. Languages may support different features, and the CLS does not guarantee that every runtime- or language-specific feature can be represented by every consuming compiler.
Which parts of a library need to be CLS-compliant?
The rules concern the API contract: public types and members, members available to derived classes, and the types used in their signatures, including parameter and return types. Microsoft Learn puts it succinctly: “The rules for CLS compliance apply only to a component’s public interface, not to its private implementation.”
#1 Best Overall
For example, a class can keep a private UInt16 field while exposing a property with a CLS-compliant type such as Int16. The public signature is the concern; internal storage need not use the same type. Also ensure that a public signature does not expose a type less visible than the member itself, including a type used to construct a generic type.
What naming rules apply to public identifiers?
Public names must remain distinct under CLS identifier comparison, which is stricter than a case-sensitive comparison. Since some CLS-supporting languages are case-insensitive, a type or member cannot rely on names such as Name and name being distinct.
The rules also account for Unicode: identifier comparisons remove formatting codes and convert names to Unicode Normalization Form C. Consequently, identifiers that look the same or normalize to the same form can conflict. This is not an ASCII-only rule; check public names for collisions under the specified comparison rather than relying on how they appear in one editor.
Which .NET types are not CLS-compliant?
Microsoft’s overview names SByte, UInt16, UInt32, UInt64, and UIntPtr as examples of non-CLS-compliant intrinsic types. The following alternatives are suggestions, not interchangeable substitutes; choose according to the range and behavior the API needs.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute| Type in the public signature | Possible alternative | Design consideration |
|---|---|---|
SByte |
Int16 |
Int16 has a wider range but permits negative values; validate inputs if the API requires nonnegative values. |
UInt16 |
Int16 |
Int16 cannot represent the full UInt16 range. Choose a wider type or otherwise redesign the contract if preserving that range matters. |
UInt32 |
Int64 |
Int64 can represent every UInt32 value, though it also permits negative values. |
UInt64 |
Int64, BigInteger, or Double |
Int64 cannot represent the full unsigned range and may overflow; floating-point representation can lose integer precision. Select based on required range and exactness. |
UIntPtr |
IntPtr |
Check that signedness and the values the API must represent are appropriate for the intended use. |
The alternatives reflect types discussed in Microsoft’s language independence guidance. A type substitution can change range, valid inputs, overflow behavior, or precision, so document those semantics as part of the API contract.
How do I declare CLS compliance in a library?
Apply CLSCompliantAttribute at the assembly level to state the library’s intent. Types and members inherit the setting unless an attribute overrides it.
Rank #4
- Add
[assembly: CLSCompliant(true)]in an assembly-level source file. - Build and address compiler warnings about declarations that conflict with the stated compliance.
- Mark an intentional exception with
[CLSCompliant(false)]on the relevant public type or member. - When practical, provide a compliant alternative and document which API elements are exceptions.
The attribute communicates a claim; it does not convert an unsupported signature type into a compliant one. Compiler diagnostics can help identify declarations that do not match an assembly’s declared intent. For the exact attribute behavior and usage, see Microsoft’s language independence documentation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Does CLS compliance guarantee compatibility with every language?
No. It supports consumption of a shared API subset by languages that support the CLS. It does not guarantee access to all .NET or language-specific features, and a consuming compiler may reject a noncompliant element it cannot represent. The guarantee is about the component’s CLS-conforming surface, not compatibility with non-.NET languages or every possible toolchain.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Is CLS compliance the same as putting C# and Visual Basic code in one assembly?
No. Microsoft describes language independence as including both consuming types authored in one language from another language and combining source code written in multiple languages into one .NET assembly. CLS rules primarily address the first problem: making a component’s public API consumable across CLS-supporting languages. Multi-language compilation is a separate workflow.
Is the CLS analyzer CA1014 enabled by default?
Microsoft’s CA1014 documentation states that this rule is not enabled by default in .NET 10 and recommends explicitly indicating assembly compliance. That setting is specific to .NET 10 tooling; check the rule’s current documentation and the target SDK when configuring analyzers.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
