.NET 依赖项注入

.NET 支持依赖关系注入 (DI) 软件设计模式，这是一种在类及其依赖项之间实现控制反转 (IoC) 的技术。 .NET 中的依赖关系注入是框架的内置部分，与配置、日志记录和选项模式一样。

依赖项是指另一个对象所依赖的对象。 使用其他类所依赖的 Write 方法检查以下 MessageWriter 类：

public class MessageWriter
{
    public void Write(string message)
    {
        Console.WriteLine($"MessageWriter.Write(message: \"{message}\")");
    }
}

类可以创建 MessageWriter 类的实例，以便利用其 Write 方法。 在以下示例中，MessageWriter 类是 Worker 类的依赖项：

public class Worker : BackgroundService
{
    private readonly MessageWriter _messageWriter = new();

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            _messageWriter.Write($"Worker running at: {DateTimeOffset.Now}");
            await Task.Delay(1_000, stoppingToken);
        }
    }
}

该类创建并直接依赖于 MessageWriter 类。 硬编码的依赖项（如前面的示例）会产生问题，应避免使用，原因如下：

• 要用不同的实现替换 MessageWriter，必须修改 Worker 类。
• 如果 MessageWriter 具有依赖项，则必须由 Worker 类对其进行配置。 在具有多个依赖于 MessageWriter 的类的大型项目中，配置代码将分散在整个应用中。
• 这种实现很难进行单元测试。 应用需使用模拟或存根 MessageWriter 类，而该类不能使用此方法。

依赖关系注入通过以下方式解决了这些问题：

• 使用接口或基类将依赖关系实现抽象化。
• 在服务容器中注册依赖关系。 .NET 提供了一个内置的服务容器 IServiceProvider。 服务通常在应用启动时注册，并追加到 IServiceCollection。 添加所有服务后，可以使用 BuildServiceProvider 创建服务容器。
• 将服务注入到使用它的类的构造函数中。 框架负责创建依赖关系的实例，并在不再需要时将其释放。

例如，IMessageWriter 接口定义 Write 方法：

namespace DependencyInjection.Example;

public interface IMessageWriter
{
    void Write(string message);
}

此接口由具体类型 MessageWriter 实现：

namespace DependencyInjection.Example;

public class MessageWriter : IMessageWriter
{
    public void Write(string message)
    {
        Console.WriteLine($"MessageWriter.Write(message: \"{message}\")");
    }
}

示例代码使用具体类型 MessageWriter 注册 IMessageWriter 服务。 AddSingleton 方法使用单一实例生存期（应用的生存期）注册服务。 本文后面将介绍服务生存期。

using DependencyInjection.Example;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddHostedService<Worker>();
builder.Services.AddSingleton<IMessageWriter, MessageWriter>();

using IHost host = builder.Build();

host.Run();

在上面的代码中，示例应用：

• 创建主机应用生成器实例。

• 通过注册以下内容来配置服务：

  • Worker 作为托管服务。 有关详细信息，请参阅 .NET 中的辅助角色服务。
  • IMessageWriter接口作为具有MessageWriter类相应实现的单一实例服务。

• 生成主机并运行它。

主机包含依赖关系注入服务提供程序。 它还包含自动实例化 Worker 并提供相应的 IMessageWriter 实现作为参数所需的所有其他相关服务。

namespace DependencyInjection.Example;

public sealed class Worker(IMessageWriter messageWriter) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            messageWriter.Write($"Worker running at: {DateTimeOffset.Now}");
            await Task.Delay(1_000, stoppingToken);
        }
    }
}

通过使用 DI 模式，辅助角色服务：

• 不使用具体类型 MessageWriter，只使用实现它的 IMessageWriter 接口。 这样可以轻松地更改辅助角色服务使用的实现，而无需修改辅助角色服务。
• 不要创建 MessageWriter 的实例。 该实例由 DI 容器创建。

可以通过使用内置日志记录 API 来改善 IMessageWriter 接口的实现：

namespace DependencyInjection.Example;

public class LoggingMessageWriter(
    ILogger<LoggingMessageWriter> logger) : IMessageWriter
{
    public void Write(string message) =>
        logger.LogInformation("Info: {Msg}", message);
}

更新的 AddSingleton 方法注册新的 IMessageWriter 实现：

builder.Services.AddSingleton<IMessageWriter, LoggingMessageWriter>();

HostApplicationBuilder (builder)类型是Microsoft.Extensions.Hosting NuGet 包的一部分。

LoggingMessageWriter 依赖于 ILogger<TCategoryName>，并在构造函数中对其进行请求。 ILogger<TCategoryName> 是ILogger<TCategoryName>。

以链式方式使用依赖关系注入并不罕见。 每个请求的依赖关系相应地请求其自己的依赖关系。 容器解析图中的依赖关系并返回完全解析的服务。 必须被解析的依赖关系的集合通常被称为“依赖关系树”、“依赖关系图”或“对象图”。

容器通过利用（泛型）开放类型解析 ILogger<TCategoryName>，而无需注册每个（泛型）构造类型。

在依赖项注入术语中，服务：

• 通常是向其他对象提供服务的对象，如 IMessageWriter 服务。
• 与 Web 服务无关，尽管服务可能使用 Web 服务。

框架提供可靠的日志记录系统。 编写上述示例中的 IMessageWriter 实现来演示基本的 DI，而不是来实现日志记录。 大多数应用都不需要编写记录器。 下面的代码展示了如何使用默认日志记录，只需要将Worker注册为托管服务AddHostedService：

public sealed class Worker(ILogger<Worker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);

            await Task.Delay(1_000, stoppingToken);
        }
    }
}

使用前面的代码时，无需更新 Program.cs，因为框架提供日志记录。

多个构造函数发现规则

当某个类型定义多个构造函数时，服务提供程序具有用于确定要使用哪个构造函数的逻辑。 选择最多参数的构造函数，其中的类型是可 DI 解析的类型。 请考虑以下 C# 示例服务：

public class ExampleService
{
    public ExampleService()
    {
    }

    public ExampleService(ILogger<ExampleService> logger)
    {
        // omitted for brevity
    }

    public ExampleService(FooService fooService, BarService barService)
    {
        // omitted for brevity
    }
}

在前面的代码中，假定已添加日志记录，并且可以从服务提供程序解析，但 FooService 和 BarService 类型不可解析。 使用 ILogger<ExampleService> 参数的构造函数用于解析 ExampleService 实例。 即使有定义多个参数的构造函数，FooService 和 BarService 类型也不能进行 DI 解析。

如果发现构造函数时存在歧义，将引发异常。 请考虑以下 C# 示例服务：

public class ExampleService
{
    public ExampleService()
    {
    }

    public ExampleService(ILogger<ExampleService> logger)
    {
        // omitted for brevity
    }

    public ExampleService(IOptions<ExampleOptions> options)
    {
        // omitted for brevity
    }
}

警告

具有不明确的可 DI 解析的类型参数的 ExampleService 代码将引发异常。 不要执行此操作，它旨在显示“不明确的可 DI 解析类型”的含义。

在前面的示例中，有三个构造函数。 第一个构造函数是无参数的，不需要服务提供商提供的服务。 假设日志记录和选项都已添加到 DI 容器，并且是可 DI 解析的服务。 当 DI 容器尝试解析 ExampleService 类型时，将引发异常，因为这两个构造函数不明确。

可通过定义一个接受 DI 可解析的类型的构造函数来避免歧义：

public class ExampleService
{
    public ExampleService()
    {
    }

    public ExampleService(
        ILogger<ExampleService> logger,
        IOptions<ExampleOptions> options)
    {
        // omitted for brevity
    }
}

使用扩展方法注册服务组

Microsoft 扩展使用一种约定来注册一组相关服务。 约定使用单个 Add{GROUP_NAME} 扩展方法来注册该框架功能所需的所有服务。 例如，AddOptions 扩展方法会注册使用选项所需的所有服务。

框架提供的服务

使用任何可用的主机或应用生成器模式时，会应用默认值，并由框架注册服务。 请考虑一些最常用的主机和应用生成器模式：

• Host.CreateDefaultBuilder()
• Host.CreateApplicationBuilder()
• WebHost.CreateDefaultBuilder()
• WebApplication.CreateBuilder()
• WebAssemblyHostBuilder.CreateDefault
• MauiApp.CreateBuilder

从这些 API 中的任何一个创建生成器后， IServiceCollection具有框架定义的服务，具体取决于主机的配置方式。 对于基于 .NET 模板的应用，该框架会注册数百个服务。

下表列出了框架注册的这些服务的一小部分：

服务类型	生存期
Microsoft.Extensions.DependencyInjection.IServiceScopeFactory	单例
IHostApplicationLifetime	单例
Microsoft.Extensions.Logging.ILogger<TCategoryName>	单例
Microsoft.Extensions.Logging.ILoggerFactory	单例
Microsoft.Extensions.ObjectPool.ObjectPoolProvider	单例
Microsoft.Extensions.Options.IConfigureOptions<TOptions>	暂时
Microsoft.Extensions.Options.IOptions<TOptions>	单例
System.Diagnostics.DiagnosticListener	单例
System.Diagnostics.DiagnosticSource	单例

服务生存期

可以使用以下任一生存期注册服务：

• 暂时
• 作用域（Scoped）
• 单例

下列各部分描述了上述每个生存期。 为每个注册的服务选择适当的生存期。

暂时

暂时生存期服务是每次从服务容器进行请求时创建的。 若要将服务注册为暂时性，请调用 AddTransient。

在处理请求的应用中，在请求结束时会释放暂时服务。 此生存期会产生每个请求的分配，因为每次都会解析和构建服务。 有关详细信息，请参阅依赖项注入指南：暂时性实例和共享实例的 IDisposable 指南。

范围内

对于 Web 应用，指定了作用域的生存期指明了每个客户端请求（连接）创建一次服务。 向 AddScoped 注册范围内服务。

在处理请求的应用中，在请求结束时会释放有作用域的服务。

使用 Entity Framework Core 时，默认情况下 AddDbContext 扩展方法使用范围内生存期来注册 DbContext 类型。

注意

不要从单一实例解析限定范围的服务，并小心不要间接地这样做，例如通过暂时性服务。 当处理后续请求时，它可能会导致服务处于不正确的状态。 可以：

• 从范围内或暂时性服务解析单一实例服务。
• 从其他范围内或暂时性服务解析范围内服务。

默认情况下在开发环境中，从具有较长生存期的其他服务解析服务将引发异常。 有关详细信息，请参阅作用域验证。

单例

创建单例生命周期服务的情况如下：

• 在首次请求它们时进行创建；或者
• 在向容器直接提供实现实例时由开发人员进行创建。 很少用到此方法。

来自依赖关系注入容器的服务实现的每一个后续请求都使用同一个实例。 如果应用需要单一实例行为，则允许服务容器管理服务的生存期。 不要实现单一实例设计模式，或提供代码来释放单一实例。 服务永远不应由解析容器服务的代码释放。 如果类型或工厂注册为单一实例，则容器自动释放单一实例。

向 AddSingleton 注册单一实例服务。 单一实例服务必须是线程安全的，并且通常在无状态服务中使用。

在处理请求的应用中，当应用关闭并释放 ServiceProvider 时，会释放单一实例服务。 由于应用关闭之前不释放内存，因此请考虑单一实例服务的内存使用。

服务注册方法

框架提供了适用于特定场景的服务注册扩展方法：

方法	自动 对象 释放	多种 实现	传递参数
Add{LIFETIME}<{SERVICE}, {IMPLEMENTATION}>() 示例： services.AddSingleton<IMyDep, MyDep>();	是	是	否
Add{LIFETIME}<{SERVICE}>(sp => new {IMPLEMENTATION}) 示例： services.AddSingleton<IMyDep>(sp => new MyDep()); services.AddSingleton<IMyDep>(sp => new MyDep(99));	是	是	是
Add{LIFETIME}<{IMPLEMENTATION}>() 示例： services.AddSingleton<MyDep>();	是	否	否
AddSingleton<{SERVICE}>(new {IMPLEMENTATION}) 示例： services.AddSingleton<IMyDep>(new MyDep()); services.AddSingleton<IMyDep>(new MyDep(99));	否	是	是
AddSingleton(new {IMPLEMENTATION}) 示例： services.AddSingleton(new MyDep()); services.AddSingleton(new MyDep(99));	否	No	是

要详细了解释放类型，请参阅服务释放部分。

仅使用实现类型注册服务等效于使用相同的实现和服务类型注册该服务。 例如，考虑以下代码：

services.AddSingleton<ExampleService>();

这相当于将服务注册到相同类型的服务和实现：

services.AddSingleton<ExampleService, ExampleService>();

这种等效性就是无法使用未采用显式服务类型的方法来注册服务的多个实现的原因。 这些方法可以注册服务的多个实例，但它们都具有相同的实现类型 。

上述任何服务注册方法都可用于注册同一服务类型的多个服务实例。 下面的示例以 IMessageWriter 作为服务类型调用 AddSingleton 两次。 第二次对 AddSingleton 的调用在解析为 IMessageWriter 时替代上一次调用，在通过 IEnumerable<IMessageWriter> 解析多个服务时添加到上一次调用。 通过 IEnumerable<{SERVICE}> 解析服务时，服务按其注册顺序显示。

using ConsoleDI.IEnumerableExample;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IMessageWriter, ConsoleMessageWriter>();
builder.Services.AddSingleton<IMessageWriter, LoggingMessageWriter>();
builder.Services.AddSingleton<ExampleService>();

using IHost host = builder.Build();

_ = host.Services.GetService<ExampleService>();

await host.RunAsync();

前面的示例源代码注册了 IMessageWriter 的两个实现。

using System.Diagnostics;

namespace ConsoleDI.IEnumerableExample;

public sealed class ExampleService
{
    public ExampleService(
        IMessageWriter messageWriter,
        IEnumerable<IMessageWriter> messageWriters)
    {
        Trace.Assert(messageWriter is LoggingMessageWriter);

        var dependencyArray = messageWriters.ToArray();
        Trace.Assert(dependencyArray[0] is ConsoleMessageWriter);
        Trace.Assert(dependencyArray[1] is LoggingMessageWriter);
    }
}

ExampleService 定义两个构造函数参数：一个是 IMessageWriter，另一个是 IEnumerable<IMessageWriter>。 第一个 IMessageWriter 是已注册的最后一个实现，而 IEnumerable<IMessageWriter> 表示所有已注册的实现。

框架还提供 TryAdd{LIFETIME} 扩展方法，只有当尚未注册某个实现时，才注册该服务。

在下面的示例中，对 AddSingleton 的调用会将 ConsoleMessageWriter 注册为 IMessageWriter的实现。 对 TryAddSingleton 的调用没有任何作用，因为 IMessageWriter 已有一个已注册的实现：

services.AddSingleton<IMessageWriter, ConsoleMessageWriter>();
services.TryAddSingleton<IMessageWriter, LoggingMessageWriter>();

TryAddSingleton 不起作用，因为已添加它并且“try”将失败。 ExampleService 将断言以下内容：

public class ExampleService
{
    public ExampleService(
        IMessageWriter messageWriter,
        IEnumerable<IMessageWriter> messageWriters)
    {
        Trace.Assert(messageWriter is ConsoleMessageWriter);
        Trace.Assert(messageWriters.Single() is ConsoleMessageWriter);
    }
}

有关详细信息，请参阅：

• TryAdd
• TryAddTransient
• TryAddScoped
• TryAddSingleton

TryAddEnumerable(ServiceDescriptor) 方法仅会在没有同一类型实现的情况下才注册该服务。 多个服务通过 IEnumerable<{SERVICE}> 解析。 注册服务时，如果还没有添加相同类型的实例，就添加一个实例。 库作者使用 TryAddEnumerable 来避免在容器中注册一个实现的多个副本。

在下面的示例中，对 TryAddEnumerable 的第一次调用会将 MessageWriter 注册为 IMessageWriter1的实现。 第二次调用向 IMessageWriter2 注册 MessageWriter。 第三次调用没有任何作用，因为 IMessageWriter1 已有一个 MessageWriter 的已注册的实现：

public interface IMessageWriter1 { }
public interface IMessageWriter2 { }

public class MessageWriter : IMessageWriter1, IMessageWriter2
{
}

services.TryAddEnumerable(ServiceDescriptor.Singleton<IMessageWriter1, MessageWriter>());
services.TryAddEnumerable(ServiceDescriptor.Singleton<IMessageWriter2, MessageWriter>());
services.TryAddEnumerable(ServiceDescriptor.Singleton<IMessageWriter1, MessageWriter>());

服务注册通常与顺序无关，除了注册同一类型的多个实现时。

IServiceCollection 是 ServiceDescriptor 对象的集合。 以下示例演示如何通过创建和添加 ServiceDescriptor 来注册服务：

string secretKey = Configuration["SecretKey"];
var descriptor = new ServiceDescriptor(
    typeof(IMessageWriter),
    _ => new DefaultMessageWriter(secretKey),
    ServiceLifetime.Transient);

services.Add(descriptor);

内置 Add{LIFETIME} 方法使用同一种方式。 相关示例请参阅 AddScoped 源代码。

构造函数注入行为

服务可使用以下方式来解析：

• IServiceProvider
• %>
  • 创建未在容器中注册的对象。
  • 用于某些框架功能。

构造函数可以接受非依赖关系注入提供的参数，但参数必须分配默认值。

当服务由 IServiceProvider 或 ActivatorUtilities 解析时，构造函数注入需要 public 构造函数。

当服务由 ActivatorUtilities 解析时，构造函数注入要求只存在一个适用的构造函数。 支持构造函数重载，但其参数可以全部通过依赖注入来实现的重载只能存在一个。

作用域验证

如果应用在Development环境中运行，并调用CreateApplicatioBuilder以生成主机，默认服务提供程序会执行检查，以确认以下内容：

• 没有从根服务提供程序解析到范围内服务。
• 未将范围内服务注入单一实例。

调用 BuildServiceProvider 时创建根服务提供程序。 在启动提供程序和应用时，根服务提供程序的生存期对应于应用的生存期，并在关闭应用时释放。

有作用域的服务由创建它们的容器释放。 如果范围内服务创建于根容器，则该服务的生存期实际上提升至单一实例，因为根容器只会在应用关闭时将其释放。 验证服务作用域，将在调用 BuildServiceProvider 时收集这类情况。

范围场景

IServiceScopeFactory 始终注册为单一实例，但 IServiceProvider 可能因包含类的生存期而异。 例如，如果从某个范围解析服务，而这些服务中的任意一种采用 IServiceProvider，该服务将是区分范围的实例。

若要在 IHostedService 的实现（例如 BackgroundService）中实现范围服务，请不要通过构造函数注入来注入服务依赖项。 请改为注入 IServiceScopeFactory，创建范围，然后从该范围解析依赖项以使用适当的服务生存期。

namespace WorkerScope.Example;

public sealed class Worker(
    ILogger<Worker> logger,
    IServiceScopeFactory serviceScopeFactory)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using (IServiceScope scope = serviceScopeFactory.CreateScope())
            {
                try
                {
                    logger.LogInformation(
                        "Starting scoped work, provider hash: {hash}.",
                        scope.ServiceProvider.GetHashCode());

                    var store = scope.ServiceProvider.GetRequiredService<IObjectStore>();
                    var next = await store.GetNextAsync();
                    logger.LogInformation("{next}", next);

                    var processor = scope.ServiceProvider.GetRequiredService<IObjectProcessor>();
                    await processor.ProcessAsync(next);
                    logger.LogInformation("Processing {name}.", next.Name);

                    var relay = scope.ServiceProvider.GetRequiredService<IObjectRelay>();
                    await relay.RelayAsync(next);
                    logger.LogInformation("Processed results have been relayed.");

                    var marked = await store.MarkAsync(next);
                    logger.LogInformation("Marked as processed: {next}", marked);
                }
                finally
                {
                    logger.LogInformation(
                        "Finished scoped work, provider hash: {hash}.{nl}",
                        scope.ServiceProvider.GetHashCode(), Environment.NewLine);
                }
            }
        }
    }
}

在上述代码中，当应用运行时，后台服务：

• 依赖于 IServiceScopeFactory。
• 创建 IServiceScope 用于解析其他服务。
• 解析区分范围内的服务以供使用。
• 处理要处理的对象，然后对其执行中继操作，最后将其标记为已处理。

在示例源代码中，可以看到 IHostedService 的实现如何从区分范围的服务生存期中获益。

键控服务

从 .NET 8 开始支持基于密钥的服务注册和查找，这意味着可以使用其他密钥注册多个服务，并使用此密钥进行查找。

例如，假设接口 IMessageWriter 有不同的实现：MemoryMessageWriter 和 QueueMessageWriter。

可以使用支持密钥作为参数的服务注册方法（前面所示）的重载来注册这些服务：

services.AddKeyedSingleton<IMessageWriter, MemoryMessageWriter>("memory");
services.AddKeyedSingleton<IMessageWriter, QueueMessageWriter>("queue");

key 不限于 string，只要类型正确地实现了 Equals，它就可以是所需的任何 object。

在使用 IMessageWriter 的类的构造函数中，添加 FromKeyedServicesAttribute 以指定要解析的服务的密钥：

public class ExampleService
{
    public ExampleService(
        [FromKeyedServices("queue")] IMessageWriter writer)
    {
        // Omitted for brevity...
    }
}

另请参阅

• 了解 .NET 中的依赖项注入基础知识
• 在 .NET 中使用依赖关系注入
• 依赖关系注入指南
• ASP.NET Core 中的依赖关系注入
• 用于 DI 应用开发的 NDC 会议模式
• 显式依赖关系原则
• 控制反转容器和依赖关系注入模式 (Martin Fowler)
• 应在 github.com/dotnet/extensions 存储库中创建 DI bug