In this article, we will explore the role, significance, usage, and impact of invariance <T>, contravariance <in T> and covariance <out T> in our C# generics programming.

Generics in C# enable us to design flexible, reusable classes and methods, providing type safety without the need for excessive casting or the risk of runtime errors.

However, when working with generics, the direction of type flow (input or output) can significantly impact how we design and interact with our generic classes. This is where the in and out keywords come into play, enhancing our ability to work with variance in generic interfaces and delegates.

Support Code Maze on Patreon to get rid of ads and get the best discounts on our products!
Become a patron at Patreon!
To download the source code for this article, you can visit our GitHub repository.

Let’s delve deeper.

Understanding Variance in Generics

Variance in generics describes the capacity of a generic type or method to handle types in an adaptable manner. Thus, it lets us replace a type with its subclass or superclass, making our code more flexible. C# applies this concept mainly to interfaces and delegates, directing it via the in and out keywords.

To set the stage, let’s consider these two classes:

public class BaseMessage { }

public class SubMessage : BaseMessage { }

Here, we declare a parent class, BaseMessage, and its child class, SubMessage.

With these classes, let’s explore the distinctions between invariance, contravariance, and covariance in C# generics.

Invariance (<T>)

Invariance in C# generics enforces a strict type match, prohibiting the use of either a more general (base) or more specific (derived) type in place of the specified generic type. This principle ensures type safety by requiring exact type conformity in generic classes or methods.

Consider the IMessageEditor<TMessage> interface and its implementation:

public interface IMessageEditor<TMessage> where TMessage : BaseMessage, new()
{
    TMessage EditAndCopyOriginalMessage(TMessage message);
}

public class MessageEditor<TMessage> : IMessageEditor<TMessage> where TMessage : BaseMessage, new()
{
    public TMessage EditAndCopyOriginalMessage(TMessage message)
    {
        var newMessage = new TMessage();

        // copy from old to new and edit

        return newMessage;
    }
}

Here, the MessageEditor<TMessage> class demonstrates invariance by requiring the TMessage type match the specified type, as implemented by the EditAndCopyOriginalMessage() method. This method highlights invariance’s capability to allow for both input and output parameters within the generics paradigm.

Let’s initialize a new object instance of the MessageEditor<SubMessage> class:

var message = new SubMessage();

IMessageEditor<SubMessage> messageEditor = new MessageEditor<SubMessage>();
    
var editedCopy = messageEditor.EditAndCopyOriginalMessage(message);

Here, we see how invariance strictly enforces the generic type requirement by how the MessageEditor<TMessage> class interacts with the SubMessage type.

Also, deviating from invariance’s strict type rules leads to compile-time errors:

IMessageEditor<BaseMessage> messageEditor2 = new MessageEditor<SubMessage>(); // won't compile
IMessageEditor<SubMessage> messageEditor3 = new MessageEditor<BaseMessage>(); // won't compile

These two lines of code will result in an error because we are attempting to substitute types that are different from the specified types.

This example emphasizes invariance’s particularity in maintaining type integrity in generics.

Contravariance (<in T>)

The in keyword enables contravariance. It allows a method to accept arguments of a less derived type than specified by the generic type parameter. This might sound counterintuitive at first, but it’s beneficial for ensuring that functions can work on a broader range of data without sacrificing type safety or the need to resort to object types and manual type checking.

When we mark a generic type parameter with the in keyword, we’re informing the compiler of our intentions to only consume values of that type within the method or interface. We’re not producing or returning values of that type. This restriction enables C# to safely execute methods with a more generic (less derived) type than what we specified:

public interface IConsumer<in TMessage> where TMessage : BaseMessage, new()
{
    void Consume(TMessage message);
}

public class Consumer<TMessage> : IConsumer<TMessage> where TMessage : BaseMessage, new()
{
    public void Consume(TMessage message) =>
        Console.WriteLine($"Consumed {message.GetType().Name}");
}

IConsumer<SubMessage> consumer = new Consumer<BaseMessage>();

var subMessage = new SubMessage();
consumer.Consume(subMessage); // Output: Consumed SubMessage

In this scenario, we’ve defined an IConsumer<in TMessage> interface with a constraint that limits TMessage to types deriving from BaseMessage. By marking TMessage with the in keyword, we enable the Consumer<TMessage> class to handle any subtype of BaseMessage.

This flexibility allows the Consume() method to consume instances of the SubMessage class or any other types derived from BaseMessage, showcasing how contravariance enhances the adaptability of methods to work with a broader range of derived types.

Covariance (<out T>)

On the flip side, the out keyword introduces covariance, the reverse of contravariance. It allows a method to return a more specific type than the one specified by the generic type parameter.

This is particularly useful when we want our methods or interfaces to return more precise types than what we initially declared:

public interface IProducer<out TMessage> where TMessage : BaseMessage, new()
{
    TMessage Produce();
}

public class Producer<TMessage> : IProducer<TMessage> where TMessage : BaseMessage, new()
{
    public TMessage Produce()
    {
        var message = new TMessage();

        Console.WriteLine($"Produced {message.GetType()}");

        return message;
    }
}

IProducer<BaseMessage> producer = new Producer<SubMessage>();

var message = producer.Produce(); // Output: Produced SubMessage

Here, the IProducer<out TMessage> interface alongside its Producer<TMessage> implementation demonstrates the practical use of covariance through the out keyword. This application allows the Producer<SubMessage> instance to be regarded as an IProducer<BaseMessage>, showing how out permits returning more specific or derived types.

The Produce() method illustrates covariance in action by generating a SubMessage type, but treating it as a BaseMessage type at the interface level.

Conclusion

In this article, we’ve explained the distinct roles and applications of the <T>, <in T>, and <out T> modifiers in C# generics, underpinning the flexible and type-safe design of classes and methods.

We’ve discussed the nuances between invariance, contravariance, and covariance in C# generics and how they allow us to not only enforce type safety but also allow for a more adaptable and efficient coding practice.

Liked it? Take a second to support Code Maze on Patreon and get the ad free reading experience!
Become a patron at Patreon!