top of page

Subscribe to get best practices, tutorials, and many other cool things directly to your email inbox

  • Writer's pictureAhmed Tarek

Invariance, Covariance, and Contravariance in .NET C#

Updated: Dec 27, 2023

Have hard time understanding it? Let me simplify it for you.


Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Christina@wocintechchat.com on Unsplash

If it is so hard on you to understand what Invariance, Covariance, and Contravariance in .NET C# means, don’t feel ashamed of it, you are not alone.


It happened to me and many other developers. I even know experienced developers who either don’t know about them and are using them but still can’t understand them well enough.


From where I see it, this is happening because every time I come across an article talking about Invariance, Covariance, and Contravariance, I find it focused on some technical terminologies rather than being concerned about the reason why we have them in the first place and what we would have missed if they didn’t exist.


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Olga Thelavart on Unsplash, modified by Ahmed Tarek

2021–11–04

I noticed that understanding Invariance, Covariance, and Contravariance would help you understand other topics and making the right design decisions. You can know more about this on my story A Best Practice for Designing Interfaces in .NET C#; Is it enough to define IMyInterface<T>? do I need IMyInterface as well?

 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Tadas Sar on Unsplash

Microsoft’s Definition


If you check Microsoft’s documentation for the Invariance, Covariance, and Contravariance in .NET C#, you would find this definition:


In C#, covariance and contravariance enable implicit reference conversion for array types, delegate types, and generic type arguments. Covariance preserves assignment compatibility and contravariance reverses it.

Do you get it? do you like it?


You can search the internet and you will find tons of resources about this topic. You will come across definitions, history, when introduced, code samples,… and many others and this is not what you would find in this story. I promise you that what you would see here is different….


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Rhys Kentish on Unsplash

What are they actually?


Basically, what Microsoft did is that they added a small addition to the way you define your generic template type place holder, the famous <T>.


What you used to do when defining a generic interface is to follow the pattern:

public interface IMyInterface<T> {…}

After having Covariance and Contravariance introduced, you can now follow the pattern:

public interface IMyInterface<out T> {…}

or

public interface IMyInterface<in T> {…}

Do you recognize the extra out and in ?


Have you seen them somewhere else?


May be on the famous .NET

public interface IEnumerable<out T>?

or the famous .NET

public interface IComparable<in T>?

Microsoft introduced a new concept so that the compiler -at design time- would make sure that the types of objects you use and pass around generic members would not throw runtime exceptions caused by wrong type expectations.


Still not clear, right? Just bear with me... Let’s assume that the compiler doesn’t apply any design time restrictions and see what would happen.


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Rick Monteiro on Unsplash

What if the compiler doesn’t apply any design time restrictions?


To be able to work on an appropriate example, let’s define the following:



Looking into the code above, you will notice that:

  1. Class A has F1() defined.

  2. Class B has F1() and F2() defined.

  3. Class C has F1(), F2() , and F3() defined.

  4. The interface IReaderWriter has Read() which returns an object of type TEntity and Write(TEntity entity) which expects a parameter of type TEntity.


Then let’s define a TestReadWriter() method as follows:



Calling TestReadWriter() when passing in an instance of IReaderWriter<B>


This should work fine as we are not violating any rules. TestReadWriter() is already expecting a parameter of type IReaderWriter<B>.


Calling TestReadWriter() when passing in an instance of IReaderWriter<A>


Keeping in mind the assumption that the compiler doesn’t apply any design time restrictions, this means that:

  1. param.Read() would return an instance of class A, not B

    1. So, the var b would actually be of type A, not B

    2. This would lead to the b.F2() line to fail as the var b -which is actually of type A- does not have F2() defined

  2. param.Write() line in the code above would be expecting to receive a parameter of type A, not B

    1. So, calling param.Write() while passing in a parameter of type B would both work fine


Therefore, since in the point #1 we are expecting a runtime failure, then we can’t call TestReadWriter() with passing in an instance of IReaderWriter<A>.


Calling TestReadWriter() when passing in an instance of IReaderWriter<C>


Keeping in mind the assumption that the compiler doesn’t apply any design time restrictions, this means that:

  1. param.Read() would return an instance of class C, not B

    1. So, the var b would actually be of type C, not B

    2. This would lead to the b.F2() line to work fine as the var b would have F2()

  2. param.Write() line in the code above would be expecting to receive a parameter of type C, not B

    1. So, calling param.Write() while passing in a parameter of type B would fail because simply you can’t replace C with its parent B


Therefore, since in the point #2 we are expecting a runtime failure, then we can’t call TestReadWriter() with passing in an instance of IReaderWriter<C>.


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Markus Winkler on Unsplash

Now, let’s analyze what we have discovered up to this moment:

  1. Calling TestReadWriter(IReaderWriter<B> param) when passing in an instance of IReaderWriter<B> is always fine.

  2. Calling TestReadWriter(IReaderWriter<B> param) when passing in an instance of IReaderWriter<A> would be fine if we don’t have the param.Read() call.

  3. Calling TestReadWriter(IReaderWriter<B> param) when passing in an instance of IReaderWriter<C> would be fine if we don’t have the param.Write() call.

  4. However, since we always have a mix between param.Read() and param.Write(), we would always have to stick to calling TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<B>, nothing else.

  5. Unless…….


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Hal Gatewood on Unsplash

The Alternative


What if we make sure that the IReaderWriter<TEntity> interface defines either TEntity Read() or void Write(TEntity entity), not both of them at the same time.


Therefore, if we drop the TEntity Read(), we would be able to call TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<A> or IReaderWriter<B>.


Similarly, if we drop the void Write(TEntity entity), we would be able to call TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<B> or IReaderWriter<C>.


This would be better for us as it would be less restrictive, right?


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Photo by Agence Olloweb on Unsplash

Time for some Facts


  1. In the real world, the compiler -in design time- would never allow calling TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<A>. You would get a compilation error.

  2. Also, the compiler -in design time- would not allow calling TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<C>. You would get a compilation error.

  3. From point #1 and #2, this is called Invariance.

  4. Even if you drop the TEntity Read() from the IReaderWriter<TEntity> interface, the compiler -in design time- would not allow you to call TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<A>. You would get a compilation error. This is because the compiler would not -implicitly by itself- look into the members defined into the interface and see if it is going to always work at runtime or not. You will need to do this by yourself through <in TEntity>. This acts as a promise from you to the compiler that all members in the interface would either don’t depend on TEntity or deal with it as an input, not an output. This is called Contravariance.

  5. Similarly, even if you drop the void Write(TEntity entity) from the IReaderWriter<TEntity> interface, the compiler -in design time- would not allow you to call TestReadWriter(IReaderWriter<B> param) with passing in an instance of IReaderWriter<C>. You would get a compilation error. This is because the compiler would not -implicitly by itself- look into the members defined into the interface and see if it is going to always work at runtime or not. You will need to do this by yourself through <out TEntity>. This acts as a promise from you to the compiler that all members in the interface would either don’t depend on TEntity or deal with it as an output, not an input. This is called Covariance.

  6. Therefore, adding <out > or <in > makes the compiler less restrictive to serve our needs, not more restrictive as some developers would think.


 

Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Image by Harish Sharma from Pixabay

Summary


At this point, you should already understand the full story of Invariance, Covariance, and Contravariance. However, as a quick recap, you can deal with the following as a cheat sheet:

  1. Mix between input and output generic type => Invariance => the most restrictive => can’t replace with parents or children.

  2. Added <in > => only input => Contravariance => itself or replace with parents.

  3. Added <out > => only output => Covariance => itself or replace with children.


Simple explanation of DotNet (.NET) CSharp (C#) Invariance, Covariance, Contravariance Cheat Sheet. Best Practice Code Coding Programming Software Development Architecture Engineering
Image by Ahmed Tarek

Finally, I will drop here some code for you to check. It would help you practice more.




That’s it, hope you found reading this article as interesting as I found writing it.





Recent Posts

See All

Subscribe to get best practices, tutorials, and many other cool things directly to your email inbox

bottom of page