Recipe 3.26 Writing Code that Is Compatible with the Widest Range of Managed Languages

Problem

You need to make sure your C# code will interoperate with all other managed languages that are CLS-compliant consumers, such as VB.NET.

Solution

Mark the assembly with the CLSCompliantAttribute:

[assembly: CLSCompliantAttribute(true)]

Discussion

By default, your C# assemblies created with VS.NET are not marked with the CLSCompliantAttribute. This does not mean that the assembly will not work in the managed environment. It means that this assembly may use elements that are not recognized by other Common Language Specification (CLS)-compliant languages. For example, unsigned numeric types are not recognized by all managed languages, but they can be used in the C# language. The problem occurs when C# returns an unsigned data type, such as uint, either through a return value or a parameter to a calling component in another language that does not recognize unsigned data types—VB.NET is one example.

CLS compliance is enforced only on types/members marked public or protected. This makes sense because components written in other languages will only be able to use the public or protected types/members of components written in C#.

Marking your assembly as CLS-compliant means that any CLS-compliant language will be able to seamlessly interoperate with your code; that is, it enables CLS-compliance checking. It should also be noted that if you have types and/or members within those types that are not CLS-compliant, a compiler error will be generated. This makes it much easier on developers to catch problems before they manifest themselves, especially in an environment where multiple managed languages are being used on a single project. Marking your entire assembly to be CLS-compliant is done with the following line of code:

[assembly: CLSCompliantAttribute(true)]

Sometimes you just can't be 100% CLS-compliant, but you don't want to have to throw away the benefit of compiler checking for the 99.9% of your methods that are CLS-compliant just so you can expose one method that is not. To mark these types or members as not being CLS-compliant, use the following attribute:

[CLSCompliantAttribute(false)]

By passing a value of false to this constructor's isCompliant parameter, any type/member marked as such will not cause any compiler errors due to non-CLS-compliant code.

Many types/members in the FCL are not CLS-compliant. This is not a problem when using C# to interact with the FCL. However, this is a problem for other languages. To solve this dilemma, the authors of the FCL usually included a CLS-compliant type/member where possible to mirror the non-CLS-compliant type/member.

The following is a list of some of the things that can be done to make code non-CLS- compliant when using the C# language:

• Two identifiers with the same name that differ only by case

• Using unsigned data types (byte, ushort, uint, ulong)

• Use of the UIntPtr type

• Boxed value types

• The use of operator overloading

• An array of non-CLS-compliant types, such as unsigned data types

• An enumeration type having a non-CLS-compliant underlying data type

See Also

See the "CLSCompliantAttribute Class" topic in the MSDN documentation.