API Proposal: FromServiceKeyAttribute(object) to support nullable (for unkeyed) and to use current service key

[stephentoub]

Background and motivation

Note that issue #99084 is also addressed by the API changes below, which allows a constructor parameter to be resolved using the key that resolved the current service. Please see that other issue for details. This is achieved here by using the empty constructor on the attribute. The rest of this description is about allowing null.

Keyed services was added in v8 along with FromKeyedServices(object key) to be applied to a constructor argument so that a literal key, such as a string, can be specified as the key for that parameter. That key was marked non-nullable and now there is case to have that nullable.

At the time keyed services was implemented, [FromKeyedServices] was not considered useful for the pre-existing "unkeyed" services model (which uses the parameter's Type as the key) since every parameter by default is considered injectable and also do not need any extra "key" information since the parameter Type is used as the key. Note that although every parameter by default is required to be injected when using DI, there are ways to get around that by using a factory approach specified during registration or by using ActivatorUtilities.CreateInstance().

However, per the discussion in this issue, [FromKeyedServices] is also used in some systems (outside of the standard DI implementation) as a way to flag parameters that are to be injected but are unkeyed. This can be accomplished today by specifying null for the key and that approach is consistent with other (non-attribute) keyed service APIs called at runtime that take a null key to indicate that they are unkeyed.

By making [FromKeyedServices(object key)] non-nullable we can avoid compiler warnings of using [FromKeyedServices(null)] and avoid the workaround of [FromKeyedServices(null!)].

This is a compile-time breaking change for nullable-enabled consumers of FromServiceKeyAttribute.Key.

API Proposal

namespace Microsoft.Extensions.DependencyInjection;

[AttributeUsage(AttributeTargets.Parameter)]
public sealed class FromKeyedServicesAttribute : Attribute
{
-    public FromKeyedServicesAttribute(object key);
    
    // A null key means no key.
+    public FromKeyedServicesAttribute(object? key);

    // Use "inherit key" mode. Key will be null.
+    public FromKeyedServicesAttribute();

-   public object Key { get; }
+   public object? Key { get; }

    // Support a way to determine which of the 3 modes we are in.
+   public ServiceKeyLookupMode LookupMode { get; }
}

// A light-weight alternative is to add a bool "InheritKey" instead of an enum. The Key property would be null when true.
+ public enum ServiceKeyLookupMode
+ {
+    NoKey,
+    ExplicitKey,
+    InheritKey
+ }

API Usage

public class MyType1
{
    // Declare we need to inject `IMyService` with the appropriate registered type.
    // For our DI implementation, this attribute is a no-op, since a null key means no key.
    public MyType1([FromKeyedServices(null)] IMyService someService)
    {
    }
}

public class MyType2
{
    // The 'IMyService' is resolved by using the same key that was used to find this class ('MyType2').
    public MyType2([FromKeyedServices] IMyService someService)
    {
    }
}

Alternative Designs

Add a new attribute, such as the [FromServices] that already exists in AspNetCore.Mvc so we would need a different name.

Original PR Description

FromKeyedServicesAttribute is annotated to prohibit null keys:

runtime/src/libraries/Microsoft.Extensions.DependencyInjection.Abstractions/src/FromKeyedServicesAttribute.cs

Lines 11 to 24 in 4ca1691

	[AttributeUsage(AttributeTargets.Parameter)]
	public class FromKeyedServicesAttribute : Attribute
	{
	/// <summary>
	/// Creates a new <see cref="FromKeyedServicesAttribute"/> instance.
	/// </summary>
	/// <param name="key">The key of the keyed service to bind to.</param>
	public FromKeyedServicesAttribute(object key) => Key = key;
	/// <summary>
	/// The key of the keyed service to bind to.
	/// </summary>
	public object Key { get; }
	}

but IKeyedServiceProvider's GetService and GetRequiredService methods allow null keys:

runtime/src/libraries/Microsoft.Extensions.DependencyInjection.Abstractions/src/IKeyedServiceProvider.cs

Lines 21 to 31 in 4ca1691

	object? GetKeyedService(Type serviceType, object? serviceKey);
	/// <summary>
	/// Gets service of type <paramref name="serviceType"/> from the <see cref="IServiceProvider"/> implementing
	/// this interface.
	/// </summary>
	/// <param name="serviceType">An object that specifies the type of service object to get.</param>
	/// <param name="serviceKey">The <see cref="ServiceDescriptor.ServiceKey"/> of the service.</param>
	/// <returns>A service object of type <paramref name="serviceType"/>.
	/// Throws an exception if the <see cref="IServiceProvider"/> cannot create the object.</returns>
	object GetRequiredKeyedService(Type serviceType, object? serviceKey);

Is this inconsistency by design? Should the ctor parameter and Keys property on FromKeyedServicesAttribute be modified to be nullable?

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-dependencyinjection
See info in area-owners.md if you want to be subscribed.

[KalleOlaviNiemitalo]

Why would one use [FromKeyedServices(null)] rather than omit the attribute altogether (or use [Microsoft.AspNetCore.Mvc.FromServices])? It's strange code that IMO deserves a warning; a nullability warning works for that.

[stephentoub]

Why would one use [FromKeyedServices(null)] rather than omit the attribute altogether

If you want an object registered with a null key, which is possible to do:

runtime/src/libraries/Microsoft.Extensions.DependencyInjection.Abstractions/src/ServiceCollectionServiceExtensions.Keyed.cs

Line 539 in 04330b6

object? serviceKey,

or use [Microsoft.AspNetCore.Mvc.FromServices]

You may not be in an MVC context.

[KalleOlaviNiemitalo]

Registering a service without a key is the same as registering with a null key. If a parameter of a constructor has no attributes, then M.E.DI injects a service registered in either of those ways.

I mentioned Microsoft.AspNetCore.Mvc.FromServicesAttribute because ASP.NET Core can inject parameter values from sources other than DI services. If you wanted to use [FromKeyedServices(null)] to prevent ASP.NET Core from using those other sources, then [FromServices] serves that need. If the app is not using ASP.NET Core, then the attribute is not necessary.

[steveharter]

Registering a service without a key is the same as registering with a null key.

Correct - a null key in the keyed service APIs means use unkeyed which really mean use System.Type as the key (the service Type). For better or worse, these keyed service APIs that allow a null key were intended as a convenience so that one method can be used for both keyed and unkeyed.

[steveharter]

Closing - runtime APIs like AddKeyedSingleton(key) can use null as the key to be the equivalent of calling AddSingleton() but [FromKeyedServices] only makes sense with keyed services since it is a design-time literal value for the key. A forced null like [FromKeyedServices(null!)] should be a noop since it's saying use "unkeyed" services:

    internal class Program
    {
        static void Main(string[] args)
        {
            ServiceCollection services = new ();
            services.AddKeyedSingleton<IMyService, MyKeyedService>("A");
            
            services.AddSingleton<IOtherService, MyService>();
            // Same result:
            //services.AddKeyedSingleton<IOtherService, MyService>(null);

            ServiceProvider provider = services.BuildServiceProvider();
            IMyService service = provider.GetRequiredKeyedService<IMyService>("A");
            Console.WriteLine(service.GetType().Name); // MyKeyedService
            Console.WriteLine(service.OtherService.GetType().Name); // MyService
        }
    }

    public interface IMyService
    {
        IOtherService OtherService { get; }
    }

    public interface IOtherService { }

    public class MyKeyedService : IMyService
    {
        public IOtherService OtherService { get; }
        public MyKeyedService([FromKeyedServices(null!)] IOtherService other)
        // Same result:
        //public MyKeyedService(IOtherService other)
        {
            OtherService = other;
        }
    }

    public class MyService : IOtherService
    {
        public MyService() { }
    }
}

[stephentoub]

these keyed service APIs that allow a null key were intended as a convenience so that one method can be used for both keyed and unkeyed.

Which is exactly what led me to this, because [FromKeyedServices] exists in the DI library and there's no [FromServices] in the DI library; it'd be nice if [FromKeyedServices] could be used regardless of whether you want keyed or unkeyed. [FromServices] only exists in an ASP.NET specific library/namespace.

[stephentoub]

A forced null like [FromKeyedServices(null!)] should be a noop since it's saying use "unkeyed" services:

This is assuming a specific model of interaction, via ActivatorUtilities.CreateInstance. That doesn't apply to other systems that are trying to satisfy parameters to methods from DI, as is done in Semantic Kernel, Microsoft.Extensions.AI, etc.

[KalleOlaviNiemitalo]

Where does Microsoft.Extensions.AI recognize FromKeyedServicesAttribute? I see you had a pull request dotnet/extensions#5956 for that, but it was not merged.

[stephentoub]

Where does Microsoft.Extensions.AI recognize FromKeyedServicesAttribute? I see you had a pull request dotnet/extensions#5956 for that, but it was not merged.

It doesn't, currently. dotnet/extensions#6141 is another attempt at it. And part of the hang-up there is the lack of a [FromServices], which wouldn't be necessary if [FromKeyedServices(null)] just worked like the rest of the keyed support works. The attribute is the strange outlier here with regards to whether null is allowed; everything else supports it.