C# Reference ยท Classes and Object-Oriented Concepts
Covariance and contravariance in C#
Reference for C# variance: out for covariance, in for contravariance, which BCL types are variant, array covariance dangers and why List<T> stays invariant.
Variance describes how conversions between generic types follow conversions between their type arguments. If Cat derives from Animal, is IEnumerable<Cat> usable as IEnumerable<Animal>? Yes: that is covariance, declared with out. Is Action<Animal> usable as Action<Cat>? Yes, in the other direction: contravariance, declared with in. Most generic types are invariant and accept only the exact type.
Variance applies only to generic interfaces and delegates, only to reference-type arguments (an identity or reference conversion must exist), and only when the type parameter is used in a compatible position: out T may appear only in outputs (return values), in T only in inputs (parameters).
IEnumerable<Cat> cats = new List<Cat>(); IEnumerable<Animal> animals = cats; // covariant: OK
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
interface IProducer<out T> { T Get(); } // covariant interface IConsumer<in T> { void Put(T item); } // contravariant delegate TResult Func<in T, out TResult>(T arg); // both
| Kind | Keyword | Direction | Allowed use of T |
|---|---|---|---|
| Covariant | out |
Producer<Derived> converts to Producer<Base> |
Return types, out and read-only positions only |
| Contravariant | in |
Consumer<Base> converts to Consumer<Derived> |
Parameter types only |
| Invariant | none | Exact type required | Anywhere |
Errors: CS1961 when a variant parameter is used in a position that is not allowed (for example out T as a method parameter type).
Usage notes
- Variant BCL types: covariant
IEnumerable<out T>,IEnumerator<out T>,IReadOnlyList<out T>,IReadOnlyCollection<out T>,IQueryable<out T>,Func<..., out TResult>; contravariantIComparer<in T>,IEqualityComparer<in T>,IComparable<in T>,Action<in T>,Predicate<in T>; both forFunc<in T, out TResult>. - Invariant on purpose:
List<T>,IList<T>,ICollection<T>andDictionary<K,V>both read and writeT, so neither direction is safe. - Reference types only.
IEnumerable<int>does not convert toIEnumerable<object>, because boxing would change representation.IEnumerable<string>converts toIEnumerable<object>. - Class and struct types are always invariant. Only interfaces and delegates declare variance.
- Array covariance is a legacy hole.
Animal[] a = new Cat[1]compiles, but storing aDogthrowsArrayTypeMismatchException. PreferIReadOnlyList<T>for covariant views. - Covariant return types (C# 9) are different: an override can return a more derived type; this is about inheritance, not generics.
- Delegates combine. Contravariance on parameters and covariance on return types follow the "accept less, give more" rule.