Generics

What it is and why it exists

A generic declaration leaves one or more types as parameters. Classes, structs, interfaces, delegates, and methods can declare a type parameter , conventionally named T, TKey, or TResult. Once a caller supplies type arguments, a constructed type such as List<string> or Dictionary<string, int> is fully specified.

Generics reuse type relationships, not merely lines of code. T Find<T>(IEnumerable<T> source) says that the result and the sequence element have the same type. Changing it to object Find(IEnumerable source) loses that relationship, forcing callers to cast and accept runtime failure.

Passing a value type through object usually causes boxing , followed by unboxing when the value comes back. List<int> stores and retrieves int elements directly, preserving compile-time checking without first converting every element to object. This doesn’t mean all generic code allocates nothing; it avoids this specific conversion path.

Generics appear throughout collections, LINQ, delegates, asynchronous APIs, dependency injection, and serialization libraries. In IEnumerable<Order>, the type between angle brackets isn’t documentation. It is part of the contract used by both the compiler and runtime.

Generics fit algorithms that apply to several types and depend on a small, explicit set of capabilities. If each type needs a different business flow, a stack of type tests and typeof(T) branches usually hides several implementations. Interfaces, polymorphism, or separate services state that design more clearly.

How it works

Declaration and construction are separate stages

Cache<TKey, TValue> declares two type parameters. Cache<string, Product> supplies two type arguments and forms a closed constructed type; arity, order, and constraints must all match. Cache<,> is an unbound generic type used only for metadata operations such as typeof and reflection. You can’t instantiate it directly.

When one type parameter occurs in several positions, the compiler keeps those positions equal. The following signature requires item, fallback, and the result to use one T. A caller can’t mix unrelated types in one call.

static T Choose<T>(bool useItem, T item, T fallback) =>
    useItem ? item : fallback;

A generic method owns its type parameters even when its containing type isn’t generic. For Choose(true, 10, 20), the compiler infers T as int from the arguments. Method type inference doesn’t infer T from the return value. If inference fails or its result violates a constraint, the caller must change the arguments or write the type argument explicitly.

Constraints expose capabilities

An unconstrained T supports only operations available to every type, such as assignment, object members, and EqualityComparer<T>.Default. A generic constraint in a where clause narrows the accepted types and lets the implementation use members guaranteed by that constraint.

Constraints are compile-time rules, not business validators. where T : class doesn’t stop older code, reflection, or callers with nullable analysis disabled from passing null. where T : new() doesn’t prove that the new object satisfies domain invariants. Public boundaries must still check actual values.

Multiple constraints follow a prescribed order: a primary constraint such as a reference-type, value-type, or unmanaged constraint comes first, followed by base-class or interface constraints, with new() near the end. The allows ref struct anti-constraint states that the implementation obeys ref struct safety rules. It comes after other constraints and prevents the implementation from assuming that T can be boxed or stored across await.

Equality, comparison, and operators need protocols

Using == with an unknown T doesn’t always compile and may not express the domain’s equality rule. Ordinary equality searches should use EqualityComparer<T>.Default; sorting can accept an IComparer<T>; add IComparable<T> only when the implementation calls CompareTo. Value types, reference types, and caller-supplied comparison policies then follow one explicit path.

C# interfaces can declare static abstract members. Generic math interfaces such as INumber<TSelf> therefore let constrained code use T.Zero and + without falling back to dynamic. This is a real capability constraint: callers can supply only types implementing the required static protocol.

Don’t add new(), class, or a broad interface just for convenience. Constraints become compatibility boundaries in a public API. A constraint the algorithm doesn’t use excludes otherwise valid types and may need to be removed later as a design correction.

Variance controls reference-conversion direction

Variance describes how existing reference conversions propagate through generic interfaces or delegates. IEnumerable<out T> is covariant, so IEnumerable<string> can be assigned to IEnumerable<object>. It only produces T through that interface, preventing the consumer from inserting an arbitrary object.

IComparer<in T> is contravariant. A comparer that handles any Animal can also compare two Dog values, so IComparer<Animal> can be used where IComparer<Dog> is required. The direction looks reversed because T flows only into the interface.

Only interface and delegate type parameters can declare out or in; generic classes remain invariant. Even when Dog derives from Animal, List<Dog> isn’t assignable to List<Animal>, because the receiver could then insert an Animal that isn’t a Dog. Variance conversions also apply only to reference-type arguments. They don’t convert IEnumerable<int> to IEnumerable<object>.

Examples

These four examples cover type relationships, static capabilities supplied by constraints, variance conversions, and runtime type identity. This environment has no .NET SDK or C# compiler, so each block carries the repository’s non-execution marker and no output is fabricated.

Preserve the result type in a search

This search method binds the element, target, and comparer to the same T. The caller gets string? inference from the string?[] argument and never converts elements to object.

EqualityComparer<T>.Default handles the two null operands in the example and follows the concrete type’s default equality rules. The method returns an index instead of default(T), so “not found” can’t be confused with a valid default value of the element type.

A real API must also decide whether items itself can be null. Nullable annotations express intent and produce warnings. Across reflection, deserialization, or code compiled without nullable analysis, a contract that rejects null still needs a runtime check.

Sum through static abstract members

INumber<T> guarantees that T.Zero and addition are available. The implementation neither branches on concrete numeric types nor defers operator binding to dynamic.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;
using System.Collections.Generic;
using System.Numerics;

int[] units = [2, 3, 5];
decimal[] prices = [1.25m, 2.50m, 4.00m];

Console.WriteLine(Sum(units));
Console.WriteLine(Sum(prices));

static T Sum<T>(IEnumerable<T> values) where T : INumber<T>
{
    T total = T.Zero;

    foreach (T value in values)
        total += value;

    return total;
}

# not executed here: the .NET SDK and C# compilers are unavailable

An empty sequence returns T.Zero, the additive identity deliberately chosen by this method. That result doesn’t automatically fit averages, maxima, or business validation for money. Those operations need their own empty-input contracts rather than copying sum’s behavior.

If the code only needs addition and zero, it can use narrower operator interfaces instead of all of INumber<T>. Constraints should follow the members the implementation actually calls, which makes the API available to more custom numeric types.

Separate producers from consumers

The producer only returns T, so it declares out T; the consumer only accepts T, so it declares in T. Assignment direction follows these interface positions without changing any concrete object’s runtime type.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;

IProducer<Dog> dogSource = new DogSource();
IProducer<Animal> animalSource = dogSource;

IConsumer<Animal> animalSink = new AnimalSink();
IConsumer<Dog> dogSink = animalSink;

Animal animal = animalSource.Create();
dogSink.Save(new Dog("Rex"));
Console.WriteLine(animal.Name);

public interface IProducer<out T>
{
    T Create();
}

public interface IConsumer<in T>
{
    void Save(T value);
}

public sealed class DogSource : IProducer<Dog>
{
    public Dog Create() => new("Milo");
}

public sealed class AnimalSink : IConsumer<Animal>
{
    public void Save(Animal value) =>
        Console.WriteLine($"saved: {value.Name}");
}

public record Animal(string Name);
public sealed record Dog(string Name) : Animal(Name);

# not executed here: the .NET SDK and C# compilers are unavailable

The static type of animalSource promises only an Animal, but the object remains a DogSource and the produced instance remains a Dog. dogSink can only be called with a Dog, while the underlying AnimalSink already knows how to handle that input.

An interface that both accepts and returns the same T usually can’t mark that parameter covariant or contravariant. Splitting reads and writes into narrow interfaces can enable safe variance conversions, but only when that split matches the domain contract.

Observe constructed types at runtime

The runtime retains generic type arguments. This example also shows that a generic static class has separate fields for each closed constructed type.

// # not executed here: the .NET SDK and C# compilers are unavailable
using System;
using System.Collections.Generic;

Type integers = typeof(List<int>);
Type strings = typeof(List<string>);

Console.WriteLine(integers == strings);
Console.WriteLine(integers.GetGenericTypeDefinition() == typeof(List<>));
Console.WriteLine(string.Join(", ", integers.GetGenericArguments()));

TypeSlot<int>.Label = "quantities";
TypeSlot<string>.Label = "names";

Console.WriteLine(TypeSlot<int>.Label);
Console.WriteLine(TypeSlot<string>.Label);

public static class TypeSlot<T>
{
    public static string Label { get; set; } = typeof(T).Name;
}

# not executed here: the .NET SDK and C# compilers are unavailable

List<int> and List<string> are distinct constructed types, but both have List<> as their generic type definition. Reflection code must distinguish a definition from a closed type before it chooses GetGenericArguments(), MakeGenericType(), or instance creation.

TypeSlot<int>.Label and TypeSlot<string>.Label don’t share storage. This behavior can cache metadata per type, but it still needs capacity and lifetime design. When untrusted dynamic input determines how many types appear, generic static fields aren’t an automatically bounded cache.

Pitfalls

Replacing a design problem with object or dynamic

Fix: write down the smallest protocol the algorithm needs. Use IEqualityComparer<T> for equality, IComparer<T> for ordering, and an interface with static abstract members for static operations. Use polymorphism or separate implementations for genuinely different business behavior instead of hiding it behind dynamic.

Treating default(T) as not found

Fix: return an index, a Boolean plus out T, a discriminated result type, or a nullable value when that fits the contract. The choice must account for value types, reference types, and the actual domain meaning.

Using new() as an object-creation contract

Fix: accept a Func<T> or domain factory, or constrain the parameter to an interface that represents the real creation protocol. Use new() only when an empty object is valid and the generic implementation truly owns creation.

Assuming every generic collection is covariant

Fix: inspect the actual interface declaration for out or in, and check that the type arguments are reference types. Read-only consumers can accept a covariant interface. Code that mutates elements must preserve the exact element type or explicitly copy into a new target collection.

Assuming nullable constraints checked the value

Fix: express type-level intent with constraints and protect real boundaries with runtime checks such as ArgumentNullException.ThrowIfNull. Test inputs arriving through reflection, deserialization, older assemblies, and nullable-disabled contexts.

Adding constraints the algorithm doesn’t use

Fix: map each constrained capability to an actual operation in the implementation. Remove constraints with no such operation. Put business data rules in parameter validation or domain types instead of pretending they are type constraints.

Further reading

• C# generics overview
• Constraints on type parameters
• Variance in generic interfaces
• Generics in the .NET runtime
• Constructed types in the C# language specification