---
URL: "/zh-CN/blog/2026-06/AssemblyLoadContext.html"
LLMS_URL: "/zh-CN/blog/2026-06/AssemblyLoadContext.md"
lastUpdated: true
commentabled: true
recommended: true
title: "自定义 ALC 中启动WebHost"
description: ".NET Core自定义 ALC 中启动WebHost的HostingStartup解析异常"
date:

pageClass: "blog-page-class"
cover: "/covers/dotnet.svg"
---

---
lastUpdated: true
commentabled: true
recommended: true
title: 自定义 ALC 中启动WebHost
description: .NET Core自定义 ALC 中启动WebHost的HostingStartup解析异常
date: 2026-06-15 10:35:00
pageClass: blog-page-class
cover: /covers/dotnet.svg
---

## 问题场景

在 .NET Core插件系统中，插件程序集通过自定义 `AssemblyLoadContext`（ALC）加载，与宿主程序的 Default ALC 保持隔离。当插件内部若需要自托管一个 Web 服务，调用 `Host.CreateDefaultBuilder()` 启动 WebHost 时，此时必然会出现一条致命异常：

异常被捕获，但应用仍能正常运行，所以看起来只是一条日志污染，但它却出现 `crit` 级别，难免让我们心生疑惑。

## 机制背景

### HostingStartup 是什么

`IHostingStartup` 是 ASP.NET Core 提供的启动扩展点。标记 `[assembly: HostingStartup]` 特性的程序集，会在构建 `IWebHostBuilder` 时被自动加载并执行，允许外部组件在启动阶段注入服务和中间件，无需修改应用代码、也不需要应用显式依赖这些组件。这是 Azure 等 PaaS 平台实现零侵入集成的核心机制。

_典型场景_：

#### 可观测性

— Application Insights 通过 `HostingStartup` 自动注入请求追踪、依赖遥测、性能计数器，应用完全无感知

#### 平台集成

— Azure AppService 的 `AzureAppServices.HostingStartup` 注入诊断日志、应用预热（Application Initialization）、ARR 亲和性 Cookie 等平台级中间件

#### 配置增强

— 在 `Configure()` 中读取远程配置中心数据，追加到 `IWebHostBuilder`，实现启动阶段的动态配置注入

### 程序集发现

#### 配置指定

— 环境变量 `ASPNETCORE_HOSTINGSTARTUPASSEMBLIES`，或配置键 `hostingStartupAssemblies`

#### 自动扫描

— 遍历 `deps.json` 中列出的程序集，检查是否标记了 `[assembly: HostingStartup]`

### 加载方式

`GenericWebHostBuilder.ExecuteHostingStartups()` 内部调用：

```cs
var assembly = Assembly.Load(new AssemblyName(assemblyName));
```

`Assembly.Load(AssemblyName)` 仅在Default ALC中查找，对自定义 ALC 完全无感知。

### 冲突链路

```mermaid
flowchart TD
    Start([应用程序启动]) --> DefaultALC[Default ALC<br/>(宿主 + ASP.NET Core 框架)]

    DefaultALC --> A[Host.CreateDefaultBuilder()]
    A --> B[GenericWebHostBuilder.ExecuteHostingStartups()]
    B --> C[Assembly.Load(new AssemblyName("TestLib"))]

    C --> D{在 Default ALC 中查找 TestLib}
    D -->|未找到| E[❌ FileNotFoundException]
    E --> F[catch {{ exceptions.Add(ex); }}]
    F --> G[收集异常，继续执行后续程序集]

    D -->|找到| H[正常加载]

    subgraph Custom ALC 边界
        I[Custom ALC]
        J[TestLib.dll 仅在此处加载]
        I --> J
    end

    G -.-> I

    style DefaultALC fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style Custom ALC fill:#fff3e0,stroke:#ff6f00,stroke-width:2px
    style E fill:#ffebee,stroke:#c62828
    style F fill:#e8f5e9,stroke:#2e7d32
```

### 源码分析

`GenericWebHostBuilder.ExecuteHostingStartups()` 的实际实现

```cs
private void ExecuteHostingStartups()
{
    var webHostOptions = new WebHostOptions(
        _config, Assembly.GetEntryAssembly()?.GetName().Name);

    if (webHostOptions.PreventHostingStartup)
        return;

    var exceptions = new List<Exception>();

    var assemblyNames = webHostOptions.HostingStartupAssemblies
        .Except(webHostOptions.HostingStartupExcludeAssemblies,
                StringComparer.OrdinalIgnoreCase)
        .Distinct(StringComparer.OrdinalIgnoreCase);

    // 1) 先 Except(excludeAssemblies)，再 Distinct 去重
    // 2) 逐个程序集独立 try/catch，异常不中断循环

    foreach (var assemblyName in assemblyNames)
    {
        try
        {
            var assembly = Assembly.Load(new AssemblyName(assemblyName));
            foreach (var attr in
                assembly.GetCustomAttributes<HostingStartupAttribute>())
            {
                var hostingStartup = (IHostingStartup)Activator
                    .CreateInstance(attr.HostingStartupType);
                hostingStartup.Configure(_hostingStartupWebHostBuilder);
            }
        }
        catch (Exception ex)
        {
            exceptions.Add(ex);  // 收集异常，继续处理后续程序集
        }
    }

    if (exceptions.Count > 0)
        _hostingStartupErrors = exceptions;
}
```

每个程序集包裹在独立的 `try/catch` 中，异常只影响当前程序集，循环继续执行后续程序集，不存在 `StartupFilter` 链断裂问题，`Except(excludeAssemblies)在Assembly.Load()` 之前执行，被排除的程序集根本不会进入加载循环，这是解决方案生效的根基。所有异常最终存入 `_hostingStartupErrors`，由 `GenericWebHostServiceOptions.HostingStartupExceptions` 对外暴露，日志组件据此输出 `crit` 级别日志。

## 异常复现

### 第一步：创建控制台宿主程序

新建 .NET 控制台项目 ConsoleApp。宿主需要两件事：启动WebHost，然后通过自定义 ALC 加载插件并调用其初始化方法。

```cs
using System.Reflection;
using System.Runtime.Loader;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;

// 1. 在 Default ALC 中启动第一个 WebHost
Console.WriteLine("[ConsoleApp] Starting first web host...");
var mainHost = Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseUrls("http://localhost:5001");
        webBuilder.Configure(app => app.Run(async ctx =>
            await ctx.Response.WriteAsync("Hello from main host!")));
    })
    .Build();
await mainHost.StartAsync();
Console.WriteLine("[ConsoleApp] First host listening on http://localhost:5001");

// 2. 通过自定义 ALC 加载插件程序集
var pluginPath = Path.Combine(
    AppContext.BaseDirectory, "Plugins", "TestLib.dll");
var alc = new CustomAssemblyLoadContext(pluginPath);
var asm = alc.LoadFromAssemblyPath(pluginPath);

// 验证隔离：TestLib 不在 Default ALC 中
Console.WriteLine($"[ConsoleApp] TestLib in Default ALC: " +
    $"{AssemblyLoadContext.Default.Assemblies.Any(a => a.GetName().Name == "TestLib")}");
// 输出: False

// 3. 调用插件初始化方法
asm.GetType("TestLib.Initializer")!
   .GetMethod("Initialize")!
   .Invoke(null, null);

Console.WriteLine("Press ENTER to shut down...");
Console.ReadLine();
await mainHost.StopAsync();

// 自定义 ALC：仅加载 Plugins 目录下的程序集，其余交给 Default ALC
internal sealed class CustomAssemblyLoadContext : AssemblyLoadContext
{
    private readonly AssemblyDependencyResolver _resolver;

    public CustomAssemblyLoadContext(string pluginDir) : base(isCollectible: true)
    {
        _resolver = new AssemblyDependencyResolver(pluginDir);
    }

    protected override Assembly? Load(AssemblyName assemblyName)
    {
        var path = _resolver.ResolveAssemblyToPath(assemblyName);
        return path is not null ? LoadFromAssemblyPath(path) : null;
    }
}
```

确保 `ConsoleApp.csproj` 中 `TestLib` 不作为项目引用。`TestLib.dll` 通过构建后事件拷贝到 `Plugins/` 子目录，使其脱离 Default ALC 的探查路径：

```xml
<Target Name="CopyTestLibToPlugins" AfterTargets="Build">
    <MakeDir Directories="$(OutputPath)Plugins" />
    <Copy SourceFiles="..\TestLib\bin\$(Configuration)\net10.0\TestLib.dll"
          DestinationFolder="$(OutputPath)Plugins" />
</Target>
```

### 第二步：创建测试插件类库

新建 .NET 类库项目 `TestLib`，引用 `Microsoft.AspNetCore.App` 框架。

```cs
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;

// 标记为 HostingStartup 程序集
[assembly: HostingStartup(typeof(TestLib.TestHostingStartup))]

namespace TestLib;

public class TestHostingStartup : IHostingStartup
{
    public void Configure(IWebHostBuilder builder)
    {
        // 观测点 1：记录 Configure 被调用，证明 TestLib 被成功加载为 HostingStartup
        Console.WriteLine("[TestLib.HostingStartup] Configure() invoked.");

        // 观测点 2：检查当前程序集归属的 ALC
        var currentAlc = AssemblyLoadContext.GetLoadContext(
            typeof(TestHostingStartup).Assembly);
        Console.WriteLine($"[TestLib.HostingStartup] Loaded in ALC: {currentAlc?.Name ?? "Default"}");
        Console.WriteLine($"[TestLib.HostingStartup] Is Default ALC: {currentAlc == AssemblyLoadContext.Default}");

        // 观测点 3：注册一个诊断中间件，验证 HostingStartup 注入是否生效
        builder.Configure(app =>
        {
            app.Use(async (ctx, next) =>
            {
                ctx.Response.Headers["X-HostingStartup"] = "TestLib-Injected";
                await next();
            });
        });

        Console.WriteLine("[TestLib.HostingStartup] Diagnostic middleware registered.");
    }
}
```

TestHostingStartup本身也是一个观测手段——如果 `Configure()` 被调用，说明 ASP.NET Core 在 Default ALC 中成功定位并加载了 TestLib；反之，如果只有 `FileNotFoundException`日志而 `Configure()` 从未触发，则证实了加载失败。

```cs
public static class Initializer
{
    public static void Initialize()
    {
        Console.WriteLine("[TestLib] Called from custom ALC context.");

        // 模拟被注入到环境变量的场景
        Environment.SetEnvironmentVariable(
            "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES", "TestLib");

        var host = Host.CreateDefaultBuilder()
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseUrls("http://localhost:5002");
                webBuilder.Configure(app => app.Run(async ctx =>
                    await ctx.Response.WriteAsync("Hello from inner host!")));
            })
            .Build();

        host.Start();
        Console.WriteLine("[TestLib] Inner host started on http://localhost:5002");
    }
}
```

### 第三步：启动控制台程序

TestLib in Default ALC: False —— 插件确实只存在于自定义 ALC；异常来自 `GenericWebHostBuilder.ExecuteHostingStartups()`→`Assembly.Load()`—— Default ALC 中找不到 TestLib

## 解决方案

在插件的 `ConfigureWebHostDefaults` 中，排除自身程序集：

```cs
Host.CreateDefaultBuilder()
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // 在 Assembly.Load 发生之前就排除 TestLib
        webBuilder.UseSetting(
            WebHostDefaults.HostingStartupExcludeAssembliesKey,
            "TestLib");

        webBuilder.UseUrls("http://localhost:5002");
        webBuilder.Configure(app => app.Run(async ctx =>
            await ctx.Response.WriteAsync("Hello from inner host!")));
    })
    .Build();
```

`WebHostOptions` 在构建待加载列表时先执行 `assemblies.Except(excludeAssemblies)`，再交给 `ExecuteHostingStartups`。排除发生在 `Assembly.Load()` 之前，加载尝试根本不会触发。

### 令人疑惑的API

直觉上我们可能想直接清空 `HostingStartupAssemblies`：

```cs
webBuilder.UseSetting(
    WebHostDefaults.HostingStartupAssembliesKey, "");  // 无效
```

但在 `WebHostBuilder` 内部，配置会按以下优先级合并：

```cs
AddInMemoryCollection(_settings)     ← UseSetting 写入（低优先级）
   .AddConfiguration(hostConfig)     ← 环境变量在此（高优先级）
```

`_settings` 中的空值被 `hostConfig` 中的环境变量覆盖，因此 `UseSetting` 无法清空由环境变量注入的值。而 `HostingStartupExcludeAssemblies` 没有对应的环境变量，`UseSetting` 写入的值不会被覆盖。

## 总结

`FileNotFoundException: Could not load file or assembly 'TestLib'` ——ASP.NET Core 尝试在 Default ALC 中加载 `TestLib` 作为 `HostingStartup` 程序集，但没找到。这个失败的后果仅仅是一条 crit 日志，以及 IHostingStartup.Configure() 不会被调用。循环中的其他程序集不受影响，`StartupFilter` 链不受影响，WebHost 正常启动。换句话说：_如果我们不依赖 `Configure()` 来做任何业务初始化，输出的致命异常日志对应用没有任何实质性影响_。

[ACLSolution](https://github.com/changweihua/ACLSolution)