🤔 你是否遇到过这些困境？

在实际项目里，有一类问题几乎每个 C# 开发者都踩过坑——程序集加载时需要做一些全局性的初始化工作，但你不知道该把这段逻辑放在哪里。

比如注册全局的序列化器、初始化日志框架、预热缓存、设置默认编码……这些事情必须在任何业务代码执行之前完成，但又没有一个"天然"的入口。于是你开始在 Main() 里堆代码，或者在每个类的静态构造函数里写初始化，结果维护成本越来越高，初始化顺序也越来越难以控制。

C# 9.0 引入的 [ModuleInitializer] 特性，正是为了解决这个问题而生的。它提供了一种在程序集层面、任何用户代码执行之前自动触发初始化的机制，干净、优雅、无侵入。

读完本文，你将掌握：

• ModuleInitializer 的底层运行机制
• 它与静态构造函数、AppDomain 事件的本质区别
• 3 个可直接落地的实战场景与完整代码

---

1️⃣ 问题深度剖析：初始化的"无主之地"

传统方案的痛点

在 [ModuleInitializer] 出现之前，C# 开发者通常有以下几种选择来处理全局初始化：

方案一：在 Main() 中集中初始化

csharp
static void Main(string[] args)
{
    // 各种初始化逻辑堆在这里
    LogManager.Initialize();
    SerializerRegistry.RegisterDefaults();
    CacheWarmup.Run();
    // ... 然后才是真正的业务逻辑
}

这种方式最直接，但问题也最明显——它只适用于有 Main() 的可执行程序。类库项目根本没有入口点，你无法强制库的使用者在调用你的 API 之前先执行某段初始化代码。

方案二：静态构造函数（Static Constructor）

csharp
public static class MyLibrary
{
    static MyLibrary()
    {
        // 初始化逻辑
    }
}

静态构造函数的触发时机是"第一次访问该类型时"，这意味着它是懒触发的，无法保证在程序集加载后立即执行。如果初始化逻辑涉及跨类型的依赖，顺序就很难控制，线程安全问题也随之而来。

方案三：约定俗成的"Init"方法

csharp
// 要求使用者手动调用
MyLibrary.Initialize();

这是最脆弱的方案。一旦使用者忘记调用，程序可能在运行时才出现莫名其妙的错误，排查成本极高。

这三种方案都有一个共同的缺陷：初始化逻辑与调用者耦合，或者依赖运行时的某个特定时机，缺乏一种真正意义上"程序集自治"的初始化能力。

---

2️⃣ 核心要点提炼：ModuleInitializer 的底层机制

什么是 Module？

要理解 ModuleInitializer，首先要明白 .NET 里"模块（Module）"的概念。在 .NET 的 PE 文件结构中，一个程序集（Assembly）可以包含一个或多个模块（Module），通常情况下一个程序集就是一个模块。模块是 IL 代码的物理载体。

在 IL 层面，每个模块都可以有一个特殊的方法叫做 .cctor（模块级静态构造函数，也称 Module Initializer）。这个方法由 CLR 在模块被加载时自动调用，早于任何其他代码。

C# 9.0 的 [ModuleInitializer] 特性，正是将这个底层的 IL 机制暴露给了 C# 开发者。

使用规则与约束

[ModuleInitializer] 的使用有明确的编译器约束，必须满足以下条件：

• 方法必须是 static
• 方法必须没有参数，也没有返回值（void）
• 方法不能是泛型方法，也不能包含在泛型类中
• 方法必须可以从模块内部访问（internal 或 public 均可）
• 不能是 extern 方法

csharp
using System.Runtime.CompilerServices;

namespace AppModuleInitializer
{
    internal static class AppInitializer
    {
        [ModuleInitializer]
        internal static void Initialize()
        {
            // 这里的代码会在程序集加载后、任何其他代码执行前自动运行
            Console.WriteLine("模块初始化器已触发");
        }
    }

    internal class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello, World!");
        }
    }
}

执行时机与顺序

[ModuleInitializer] 的执行时机非常早，具体顺序如下：

1. CLR 加载程序集
2. 触发所有 [ModuleInitializer] 标记的方法（按编译顺序）
3. 触发各类型的静态构造函数（懒触发）
4. 执行 Main() 或其他入口代码

如果同一个程序集中存在多个 [ModuleInitializer] 方法，它们的执行顺序由编译器决定（通常按照源码中的定义顺序），不建议依赖多个初始化器之间的执行顺序。

---

3️⃣ 解决方案设计：三个落地场景

🚀 场景一：类库的自动注册机制

这是 [ModuleInitializer] 最典型的使用场景。假设你在开发一个序列化类库，希望在库被引用时自动注册默认的转换器，而不需要使用者手动调用任何初始化方法。

csharp
using System.Runtime.CompilerServices;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace AppModuleInitializer
{
    //  自定义 DateTimeOffset 转换器 
    /// <summary>
    /// 将 DateTimeOffset 序列化为 ISO 8601 字符串（含偏移量），
    /// 反序列化时支持带或不带偏移量的格式。
    /// </summary>
    public class DateTimeOffsetConverter : JsonConverter<DateTimeOffset>
    {
        private const string Format = "yyyy-MM-ddTHH:mm:ss.fffzzz";

        public override DateTimeOffset Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options)
        {
            var str = reader.GetString()
                ?? throw new JsonException("Expected a non-null DateTimeOffset string.");

            return DateTimeOffset.Parse(str,
                System.Globalization.CultureInfo.InvariantCulture,
                System.Globalization.DateTimeStyles.RoundtripKind);
        }

        public override void Write(
            Utf8JsonWriter writer,
            DateTimeOffset value,
            JsonSerializerOptions options)
        {
            writer.WriteStringValue(value.ToString(Format,
                System.Globalization.CultureInfo.InvariantCulture));
        }
    }

    //  自定义 Guid 转换器 
    /// <summary>
    /// 将 Guid 序列化为小写无连字符的 32 位十六进制字符串，
    /// 反序列化时兼容标准格式（带/不带连字符、大小写均可）。
    /// </summary>
    public class GuidConverter : JsonConverter<Guid>
    {
        public override Guid Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options)
        {
            var str = reader.GetString()
                ?? throw new JsonException("Expected a non-null Guid string.");

            return Guid.Parse(str);
        }

        public override void Write(
            Utf8JsonWriter writer,
            Guid value,
            JsonSerializerOptions options)
        {
            // "N" → 小写无连字符，例如 "d3b07384d113edec49eaa6238ad5ff00"
            writer.WriteStringValue(value.ToString("N"));
        }
    }

    //  模块初始化器 
    internal static class LibraryInitializer
    {
        [ModuleInitializer]
        internal static void RegisterDefaults()
        {
            // 注册自定义的 JsonConverter
            SerializerRegistry.Register(new DateTimeOffsetConverter());
            SerializerRegistry.Register(new GuidConverter());

            // 设置全局默认选项
            SerializerRegistry.DefaultOptions = new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true,
                WriteIndented = false,
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
            };
        }
    }

    //  全局注册表 
    public static class SerializerRegistry
    {
        private static readonly List<JsonConverter> _converters = new();

        public static JsonSerializerOptions DefaultOptions { get; internal set; } = new();

        internal static void Register(JsonConverter converter)
            => _converters.Add(converter);

        /// <summary>
        /// 返回一个合并了默认选项与所有已注册 Converter 的新实例。
        /// </summary>
        public static JsonSerializerOptions GetOptions()
        {
            var options = new JsonSerializerOptions(DefaultOptions);
            foreach (var converter in _converters)
                options.Converters.Add(converter);
            return options;
        }
    }

    //  入口 
    internal class Program
    {
        static void Main(string[] args)
        {
            // 模块初始化器在 Main 之前已自动执行
            var options = SerializerRegistry.GetOptions();

            // 快速验证
            var dto = DateTimeOffset.UtcNow;
            var guid = Guid.NewGuid();

            string json = JsonSerializer.Serialize(new { Time = dto, Id = guid }, options);
            Console.WriteLine(json);
        }
    }
}

使用者引用这个库后，无需调用任何初始化方法，SerializerRegistry 就已经处于就绪状态。这种"零配置"体验在框架和基础库开发中非常有价值。

---

🔧 场景二：Source Generator 与代码生成配合

[ModuleInitializer] 与 Source Generator 的结合是一个非常强大的组合。Source Generator 可以在编译期扫描所有标记了某个特性的类型，然后生成一个 [ModuleInitializer] 方法来自动完成注册，彻底消除运行时反射扫描的开销。

下面展示一个不依赖 Source Generator、但模拟其效果的手动版本，帮助你理解这个模式：

csharp
// 假设这是 Source Generator 生成的代码（GeneratedRegistrations.g.cs）
using System.Runtime.CompilerServices;

namespace MyApp
{
    // 这个文件由编译器/生成器自动维护，开发者无需手动修改
    internal static partial class GeneratedRegistrations
    {
        [ModuleInitializer]
        internal static void AutoRegisterAll()
        {
            // 编译期扫描所有 [AutoRegister] 标记的类型并生成注册代码
            // 相比运行时反射，性能提升显著
            ServiceLocator.Register<IOrderService, OrderService>();
            ServiceLocator.Register<IUserService, UserService>();
            ServiceLocator.Register<IPaymentService, PaymentService>();
        }
    }

    // 轻量级服务定位器（仅作示意）
    public static class ServiceLocator
    {
        private static readonly Dictionary<Type, Func<object>> _factories = new();

        public static void Register<TInterface, TImpl>()
            where TImpl : TInterface, new()
        {
            _factories[typeof(TInterface)] = () => new TImpl();
        }

        public static T Resolve<T>() =>
            (T)_factories[typeof(T)]();
    }
}

Source Generator 这个我单独有一个系列写过，非常强大，好用。

---

🛡️ 场景三：诊断与环境验证

在一些对运行环境有严格要求的应用中（如工控软件、金融系统），可以用 [ModuleInitializer] 在程序集加载时立即进行环境检查，确保问题在最早的时机被发现，而不是等到某个功能被调用时才爆出难以定位的异常。

csharp
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace AppModuleInitializer
{
    //  诊断日志（轻量级静态实现）
    /// <summary>
    /// 极简结构化日志，输出到控制台并附带时间戳与级别标签。
    /// 可替换为 NLog / Serilog 等正式框架。
    /// </summary>
    public static class DiagnosticLog
    {
        // 是否输出 Debug 级别日志，可通过环境变量 APP_VERBOSE=1 开启
        public static bool VerboseEnabled { get; private set; } =
            Environment.GetEnvironmentVariable("APP_VERBOSE") == "1";

        public static void Debug(string message) =>
            WriteLog("DEBUG", ConsoleColor.Gray, message);

        public static void Info(string message) =>
            WriteLog("INFO ", ConsoleColor.Cyan, message);

        public static void Warn(string message) =>
            WriteLog("WARN ", ConsoleColor.Yellow, message);

        public static void Error(string message) =>
            WriteLog("ERROR", ConsoleColor.Red, message);

        private static void WriteLog(string level, ConsoleColor color, string message)
        {
            if (level == "DEBUG" && !VerboseEnabled) return;

            var timestamp = DateTimeOffset.Now.ToString("yyyy-MM-dd HH:mm:ss.fff zzz");
            var original = Console.ForegroundColor;

            Console.ForegroundColor = color;
            Console.WriteLine($"[{timestamp}] [{level}] {message}");
            Console.ForegroundColor = original;
        }
    }

    //  环境验证结果（供后续业务代码读取）
    /// <summary>
    /// 模块初始化完成后，将关键环境信息写入此静态上下文，
    /// 业务代码可直接读取，无需重复调用系统 API。
    /// </summary>
    public static class RuntimeContext
    {
        public static Version DotNetVersion { get; internal set; } = Environment.Version;
        public static string OSDescription { get; internal set; } = RuntimeInformation.OSDescription;
        public static bool IsWindows { get; internal set; }
        public static bool IsLinux { get; internal set; }
        public static bool IsMacOS { get; internal set; }
        public static string? DbConnectionStr { get; internal set; }
        public static bool DbConfigured => !string.IsNullOrWhiteSpace(DbConnectionStr);
    }

    //  模块初始化器：环境守卫 
    internal static class EnvironmentGuard
    {
        [ModuleInitializer]
        internal static void ValidateRuntime()
        {
            // 检查 .NET 运行时版本
            var version = Environment.Version;
            if (version.Major < 8)
            {
                throw new PlatformNotSupportedException(
                    $"此程序集要求 .NET 8 或更高版本，当前版本：{version}");
            }

            // 检查操作系统平台
            RuntimeContext.IsWindows = RuntimeInformation.IsOSPlatform(OSPlatform.Windows);
            RuntimeContext.IsLinux = RuntimeInformation.IsOSPlatform(OSPlatform.Linux);
            RuntimeContext.IsMacOS = RuntimeInformation.IsOSPlatform(OSPlatform.OSX);

            if (!RuntimeContext.IsWindows)
            {
                DiagnosticLog.Warn("当前平台非 Windows，部分硬件功能不可用");
            }

            // 检查必要的环境变量
            var connStr = Environment.GetEnvironmentVariable("APP_DB_CONNECTION");
            RuntimeContext.DbConnectionStr = connStr;

            if (!RuntimeContext.DbConfigured)
            {
                DiagnosticLog.Warn("未检测到 APP_DB_CONNECTION 环境变量，将使用默认配置");
            }

            // 写入版本 & OS 信息到上下文
            RuntimeContext.DotNetVersion = version;
            RuntimeContext.OSDescription = RuntimeInformation.OSDescription;

            DiagnosticLog.Info(
                $"环境验证通过 | Runtime: {version} | OS: {RuntimeInformation.OSDescription}");
        }
    }

    //  入口 
    internal class Program
    {
        static void Main(string[] args)
        {
            // [ModuleInitializer] 已在 Main 之前自动执行，此处直接读取结果
            DiagnosticLog.Info("应用程序启动");

            // 读取运行时上下文
            Console.WriteLine();
            Console.WriteLine("═══════════════════ 运行时环境摘要 ═══════════════════");
            Console.WriteLine($"  .NET 版本   : {RuntimeContext.DotNetVersion}");
            Console.WriteLine($"  操作系统    : {RuntimeContext.OSDescription}");
            Console.WriteLine($"  Windows     : {RuntimeContext.IsWindows}");
            Console.WriteLine($"  Linux       : {RuntimeContext.IsLinux}");
            Console.WriteLine($"  macOS       : {RuntimeContext.IsMacOS}");
            Console.WriteLine($"  DB 已配置   : {RuntimeContext.DbConfigured}");

            if (RuntimeContext.DbConfigured)
                Console.WriteLine($"  DB 连接串   : {MaskConnectionString(RuntimeContext.DbConnectionStr!)}");

            Console.WriteLine("═══════════════════════════════════════════════════════");
            Console.WriteLine();

            // 演示：根据平台分支执行不同逻辑
            if (RuntimeContext.IsWindows)
            {
                DiagnosticLog.Info("Windows 专属初始化完成（如注册 COM 组件等）");
            }
            else
            {
                DiagnosticLog.Info("跨平台模式运行，跳过 Windows 专属步骤");
            }

            // 演示：DB 未配置时降级到内存模式
            if (!RuntimeContext.DbConfigured)
            {
                DiagnosticLog.Warn("使用内存数据库作为降级方案");
                // InMemoryDatabase.Initialize();
            }

            DiagnosticLog.Info("主逻辑执行完毕，程序正常退出");
        }

        /// <summary>
        /// 将连接字符串中的密码段替换为 ***，避免明文输出到日志。
        /// 示例输入：Server=.;Database=App;Password=secret123;
        /// 示例输出：Server=.;Database=App;Password=***;
        /// </summary>
        private static string MaskConnectionString(string connStr)
        {
            return System.Text.RegularExpressions.Regex.Replace(
                connStr,
                @"(?i)(password|pwd)\s*=\s*[^;]+",
                "$1=***");
        }
    }
}

这种"快速失败（Fail Fast）"的设计哲学，能将潜在的配置问题从"运行时某个随机时刻"提前到"程序集加载时"，极大降低了问题排查的难度。

---

⚠️ 踩坑预警：这些地方要小心

陷阱一：初始化器中抛出未处理异常

[ModuleInitializer] 中抛出的异常会导致 TypeInitializationException 或直接的程序崩溃，且错误信息可能不够直观。建议在初始化器内部做好异常捕获，将致命错误与可恢复的警告分开处理。

陷阱二：在初始化器中访问未就绪的类型

由于 [ModuleInitializer] 执行时各类型的静态构造函数可能尚未运行，不要在初始化器中假设某个类型已经完成了自己的静态初始化。应尽量保持初始化器的逻辑简单、自包含。

陷阱三：测试项目的干扰

在单元测试项目中，如果测试程序集引用了包含 [ModuleInitializer] 的程序集，初始化器会在测试运行前自动触发。这通常是期望行为，但如果初始化器依赖外部资源（如数据库连接），可能导致测试环境下的意外失败。建议通过环境变量或编译条件来区分测试环境。

csharp
[ModuleInitializer]
internal static void Initialize()
{
    // 测试环境跳过外部资源初始化
    if (Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_TESTS") == "1")
        return;
    
    HeavyResourceInitializer.Run();
}

---

💡 三句话总结

• [ModuleInitializer] 是 CLR 模块级 .cctor 的 C# 语法糖，执行时机早于任何用户代码，是类库实现"零配置自动初始化"的最优解。
• 它不是静态构造函数的替代品，而是填补了"程序集加载时"这个初始化时机的空白，两者在触发时机和适用场景上有本质区别。
• 与 Source Generator 结合使用时威力倍增，可以在编译期完成类型扫描与注册，彻底消除启动时的反射开销。

---

💬 互动话题

在你的项目中，程序集级别的初始化逻辑通常是怎么处理的？是集中在 Main() 里、依赖 DI 容器的启动流程，还是已经在尝试 [ModuleInitializer]？

另外，如果你在类库开发中遇到过"使用者忘记调用初始化方法"导致的 Bug，欢迎在评论区聊聊当时的场景，这类问题往往比表面看起来更有意思。

---

#C# #dotnet #性能优化 #编程技巧 #程序集