[API Proposal]: Create Generalized Pattern for Collection Builder Types

Start by reading this proposal alongside #111715 and the existing CollectionBuilderAttribute mentioned in the issue. Compare the proposed generalized attribute with the current IEnumerable/IList special cases and determine the API design and compatibility requirements. Done means the generalized mechanism is sufficiently designed for a follow-up implementation proposal.

Background and motivation

Currently, as of .NET 9, there is no generic mechanism for defining collection builder types. This results in collection builders being special cased, currently IEnumerable<T> => T[] and IList<T> => List<T>. There may be others but these are the two most common scenarios.

This mechanism allows for situations like this:

public IEnumerable<T> EnumerateFoos<T>(IEnumerable<T> foos)
{
    if (foos is null)
    {
        return []; // returns an empty T[]
    }

    // Not empty, evaluate
}

#111715 proposes adding this capability for IAsyncEnumerable<T> but there is no mechanim that can be extended in a generic manner. Instead, they must be special typed just like arrays and lists. This proposal is to add a generic mechanism that can be used to decorate any current or future type.

That way we're not just continually fixing things by adding "just one more type" for each release.

• @CyrusNajmabadi https://github.com/dotnet/runtime/issues/111715#issuecomment-2629051395

API Proposal

[AttributeUsage(AttributeTargets.Class, AllowMultiple: true)]
internal sealed class CollectionBuilderForAttribute(Type enumerableType) : Attribute
{
}

I'm not entirely settled on the API design at this point but the idea is that this attribute becomes the primary driver for defining collection builders. This allows for a general, well-known, and documented solution to adding support for collection types moving forward. This should not resolve #111715 directly, but should provide a mechanism for a separate API proposal which implements the solution provided here.

API Usage

This should be a rough approximation of the special casing that List has for IList.

[CollectionBuilderFor(typeof(IList<>))]
public sealed class List<T> : IList<T>
{
    // Body omitted
}

Alternative Designs

We could stay our current course and set up a handler in the runtime/corelib, similar to how IEnumerable is handled by T[] and IList is handled by List. This is a lot of special casing for a feature that is repeated multiple times.

In .NET 10, we gain CollectionBuilderAttribute but this would not allow support to be backported to previous TFMs.

Risks

None that I'm aware of.