配置类库依赖注入后Blazor WebAssembly卡在Loading页面

问题背景 #

构建了一个可复用的类库，在Blazor WebAssembly项目的Program.cs中配置该类库的依赖注入后，应用卡在了Loading...页面，移除相关配置则恢复正常。

类库核心代码如下：

public class ConfigurationSettings
{
    public string ConnectionString { get; set; }
    public string Token { get; set; }
    public string Issuer { get; set; }
    public string Audience { get; set; }
}

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddLibrary(this IServiceCollection services, Action<ConfigurationSettings> configure)
    {
        services.Configure(configure);        
        services.AddDbContext<ApplicationDbContext>((provider, options) =>
        {
            var myLibraryOptions = provider.GetRequiredService<IOptions<ConfigurationSettings>>().Value;
            options.UseSqlServer(myLibraryOptions.ConnectionString);
        });

        return services;
    }
}

Blazor WebAssembly项目中的配置代码：

builder.Services.AddLibrary(options =>
{
    options.ConnectionString = connectionString;

    IConfigurationSection configurationSettingsSection = builder.Configuration.GetSection("ConfigurationSettings");
    options.Token = configurationSettingsSection["Token"];
    options.Issuer = configurationSettingsSection["Issuer"];
    options.Audience = configurationSettingsSection["Audience"];
});
builder.Services.AddScoped<IAuthService, AuthService>();

核心排查点 #

1. Blazor WASM环境限制：Blazor WebAssembly运行在浏览器沙箱中，无法直接使用SqlServer数据库驱动——这类依赖包含原生代码，浏览器环境不支持，初始化DbContext时会抛出无法捕获的异常，导致应用启动卡住。
2. DI容器初始化失败：AddDbContext的配置委托中如果出现异常（比如配置值为空、驱动加载失败），会导致整个服务容器初始化中断，Blazor无法完成启动流程。
3. 配置读取异常：手动赋值配置项时，如果某个配置键不存在，会得到null值，后续初始化DbContext时可能引发空引用异常。

解决方案 #

1. 拆分类库的客户端/服务端逻辑 #

类库要支持多项目（包括Blazor WASM客户端），必须把数据访问逻辑和客户端可用的服务拆分：

// 服务端专用扩展方法，负责注册DbContext
public static class ServiceCollectionServerExtensions
{
    public static IServiceCollection AddLibraryServer(this IServiceCollection services, Action<ConfigurationSettings> configure)
    {
        services.Configure(configure);        
        services.AddDbContext<ApplicationDbContext>((provider, options) =>
        {
            var myLibraryOptions = provider.GetRequiredService<IOptions<ConfigurationSettings>>().Value;
            options.UseSqlServer(myLibraryOptions.ConnectionString);
        });

        return services;
    }
}

// 客户端专用扩展方法，只注册配置和无需数据库的服务
public static class ServiceCollectionClientExtensions
{
    public static IServiceCollection AddLibraryClient(this IServiceCollection services, Action<ConfigurationSettings> configure)
    {
        services.Configure(configure);
        // 在这里注册客户端可用的服务，比如AuthService等
        services.AddScoped<IAuthService, AuthService>();
        return services;
    }
}

2. 修正Blazor WASM的配置代码 #

在WASM客户端只调用客户端专用的扩展方法，避免注册DbContext：

// 直接绑定配置，替代手动赋值，减少错误
var configSection = builder.Configuration.GetSection("ConfigurationSettings");
var settings = configSection.Get<ConfigurationSettings>();
settings.ConnectionString = connectionString; // 补充额外的连接字符串（如果需要）

builder.Services.AddLibraryClient(options =>
{
    configSection.Bind(options);
    options.ConnectionString = connectionString;
});

3. 检查配置加载完整性 #

确保appsettings.json中的配置项齐全，避免空值：

{
  "ConfigurationSettings": {
    "Token": "your-token",
    "Issuer": "your-issuer",
    "Audience": "your-audience"
  }
}

4. 添加启动异常捕获（调试用） #

在Blazor WASM的Program.cs中添加全局异常捕获，方便定位问题：

try
{
    var builder = WebAssemblyHostBuilder.CreateDefault(args);
    builder.RootComponents.Add<App>("#app");
    builder.RootComponents.Add<HeadOutlet>("head::after");

    // 你的配置代码...

    await builder.Build().RunAsync();
}
catch (Exception ex)
{
    Console.WriteLine($"启动异常: {ex.Message}");
    Console.WriteLine(ex.StackTrace);
}

内容的提问来源于stack exchange，提问作者MarkBerry