What is contravariance in C# generics? Explain the in modifier, why an IComparer<object> or Action<object> can be used where IComparer<string> or Action<string> is expected, which BCL types are contravariant, and the gotcha with combining variant delegates.

1. Why input positions allow contravariance

Think of a consumer of T as a function T → void. If you can accept any Animal, you can accept a Dog because every Dog is an Animal — the substitution is safe in the input direction. Formally, function types are contravariant in parameter types and covariant in return types, matching Liskov's rule: an override may accept more general parameters and return more specific results.

2. Validity rules

An in T may appear in:

• method parameter types,
• set-only properties (rare),
• as a type argument to a contravariant parameter of an output (e.g. returning Action<T>? No — returning Action<T> puts T in an input-of-output position, which is contravariant, so allowed),
• as a type argument to a covariant parameter of an input (e.g. parameter IEnumerable<T> — input of output-only type: contravariant position — allowed).

It may not appear as a return type, in ref/out parameters, or in invariant generic types.

The compiler reports CS1961 for violations.

3. Runtime representation

As with covariance, the CLR performs no conversion: IComparer<object> and IComparer<string> reference the same object; the runtime's cast logic allows the assignment because IComparer<in T> is contravariant and string is assignable to object. Only reference types participate.

4. The multicast delegate issue in detail

Delegate.Combine(a, b) checks a.GetType() == b.GetType(). With variance, a variable typed Action<string> can hold an object whose runtime type is Action<object>. Events using field-like syntax call Delegate.Combine in add, so the exception happens on +=. It's documented behaviour and a known design wart of delegate variance (variance was added in C# 4, after multicast semantics were fixed).

Workaround helper:

static Action<T> Exact<T>(Action<T> handler) => handler.GetType() == typeof(Action<T>) ? handler : new Action<T>(handler.Invoke);

5. DI and contravariant handlers

Microsoft.Extensions.DependencyInjection does not resolve services using variance: requesting IEnumerable<IHandler<OrderPlaced>> won't include an IHandler<IDomainEvent> registration automatically. Some containers (Autofac with ContravariantRegistrationSource) support it. With MS DI, register the general handler for each concrete event, or write a dispatcher that also resolves handlers for base types/interfaces.

6. Comparers as a design example

Comparer<T>.Create(Comparison<T>) and IComparer<in T> let you write one comparer for a base type and reuse it for derived collections. StringComparer implements IComparer<string?> and IEqualityComparer<string?> — because those interfaces are contravariant, StringComparer.Ordinal can be used for collections of any... well, only string-related usage, since string is sealed.

Try it yourself

1. Assign IComparer<object> to IComparer<string> and sort a list of strings.
2. Reproduce the Delegate.Combine exception with variant Action<T> delegates and fix it with a wrapper.
3. Declare interface ISink<in T> { T Last { get; } } and read the compiler error.
4. Register an IHandler<IDomainEvent> in MS DI and check whether it's resolved for IHandler<OrderPlaced>.

namespace Generics.Contravariance;

public interface IDomainEvent { DateTimeOffset OccurredAt { get; } }
public sealed record OrderPlaced(Guid OrderId, DateTimeOffset OccurredAt) : IDomainEvent;
public sealed record OrderShipped(Guid OrderId, DateTimeOffset OccurredAt) : IDomainEvent;

public interface IEventHandler<in TEvent>
{
    void Handle(TEvent @event);
}

public sealed class AuditHandler : IEventHandler<IDomainEvent>
{
    public void Handle(IDomainEvent @event) => Console.WriteLine($"AUDIT {@event.GetType().Name} at {@event.OccurredAt:O}");
}

public sealed class ByOccurredAt : IComparer<IDomainEvent>
{
    public int Compare(IDomainEvent? x, IDomainEvent? y) => Nullable.Compare(x?.OccurredAt, y?.OccurredAt);
}

public static class Program
{
    public static void Main()
    {
        IEventHandler<OrderPlaced> placedHandler = new AuditHandler(); // contravariant conversion
        placedHandler.Handle(new OrderPlaced(Guid.NewGuid(), DateTimeOffset.UtcNow));

        List<OrderShipped> shipped =
        [
            new(Guid.NewGuid(), DateTimeOffset.UtcNow),
            new(Guid.NewGuid(), DateTimeOffset.UtcNow.AddMinutes(-5)),
        ];
        shipped.Sort(new ByOccurredAt()); // IComparer<IDomainEvent> used as IComparer<OrderShipped>

        Action<object> logAnything = o => Console.WriteLine($"log: {o}");
        Action<string> logText = logAnything;              // contravariance
        logText("hello");

        try
        {
            logText += s => Console.WriteLine(s.Length);  // run-time types differ
        }
        catch (ArgumentException ex)
        {
            Console.WriteLine($"Combine failed: {ex.Message}");
        }

        Action<string> safe = s => logAnything(s);         // adapter has run-time type Action<string>
        safe += s => Console.WriteLine(s.Length);
        safe("works");
    }
}