C#中如何使用ModuleInitializer实现模块初始化

在C#开发中，ModuleInitializer特性用于标记模块初始化方法，这些方法会在包含它的模块被加载时自动执行，非常适合处理全局的初始化逻辑，避免手动调用的繁琐和遗漏。

ModuleInitializer的基本定义

ModuleInitializer是System.Runtime.CompilerServices命名空间下的一个特性，它只能应用在静态方法上，并且对方法的签名有严格要求。被标记的方法会在模块加载阶段自动触发，执行顺序由运行时决定，通常早于任何其他用户代码的执行。

方法签名要求

• 方法必须是静态方法
• 方法没有参数
• 方法返回值为void
• 方法不能是泛型方法
• 方法不能包含in、ref、out参数修饰符

基础使用示例

下面是一个最简单的ModuleInitializer使用示例，我们在模块加载时输出一条初始化日志：

using System;
using System.Runtime.CompilerServices;

public class ModuleInitDemo
{
    // 标记该方法为模块初始化方法
    [ModuleInitializer]
    internal static void Init()
    {
        Console.WriteLine("模块初始化方法已执行，当前时间：" + DateTime.Now);
    }
}

class Program
{
    static void Main()
    {
        Console.WriteLine("主程序开始执行");
    }
}

运行上述代码后，会先输出模块初始化的内容，再输出主程序的执行内容，说明初始化方法确实在程序入口之前执行了。

常见使用场景

全局配置预加载

很多项目需要从配置文件或者环境变量中加载全局配置，使用ModuleInitializer可以在模块加载时就完成配置加载，后续其他代码可以直接使用配置，不需要重复加载。

using System;
using System.Runtime.CompilerServices;
using System.IO;

public static class GlobalConfig
{
    public static string AppName { get; private set; }
    public static string LogPath { get; private set; }

    [ModuleInitializer]
    internal static void LoadConfig()
    {
        // 模拟加载配置文件
        string configContent = File.ReadAllText("app.config");
        // 解析配置内容，这里简化逻辑
        AppName = "示例应用";
        LogPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "logs");
        if (!Directory.Exists(LogPath))
        {
            Directory.CreateDirectory(LogPath);
        }
        Console.WriteLine("全局配置加载完成");
    }
}

静态资源注册

如果项目中有需要预注册的静态资源，比如自定义的序列化器、全局的事件处理器等，也可以在模块初始化阶段完成注册，避免后续使用时的空引用问题。

using System;
using System.Runtime.CompilerServices;
using System.Collections.Generic;

public static class ResourceRegistry
{
    public static Dictionary<string, object> RegisteredResources { get; private set; }

    [ModuleInitializer]
    internal static void RegisterResources()
    {
        RegisteredResources = new Dictionary<string, object>();
        // 注册默认资源
        RegisteredResources.Add("DefaultLogger", new object());
        RegisteredResources.Add("DefaultCache", new object());
        Console.WriteLine("静态资源注册完成，已注册资源数量：" + RegisteredResources.Count);
    }
}

使用注意事项

• 同一个模块中可以有多个被ModuleInitializer标记的方法，它们的执行顺序不固定，不要依赖执行顺序来编写逻辑
• 初始化方法中不要抛出未处理的异常，否则可能导致模块加载失败，整个程序无法启动
• ModuleInitializer是在模块级别生效的，如果一个程序集包含多个模块，每个模块的初始化方法会分别在对应模块加载时执行
• 该特性从C# 9.0开始支持，使用低版本C#的项目无法使用这个特性

与其他初始化方式的对比

我们常用的静态构造函数也可以实现类似的初始化逻辑，但是两者有本质区别：

如果需要在整个模块加载时就执行初始化逻辑，优先选择ModuleInitializer；如果只需要某个类型使用前初始化，静态构造函数更合适。

总结

ModuleInitializer是C#中一个非常实用的高级特性，它简化了模块级别的初始化逻辑编写，不需要我们手动管理初始化方法的调用时机。在实际开发中，我们可以根据需求合理使用这个特性，处理全局配置加载、静态资源注册等场景，提升代码的简洁性和可维护性。使用时需要注意方法签名的限制，以及避免初始化逻辑中出现未处理的异常，确保模块能够正常加载。

C#_ModuleInitializer模块初始化器特性静态方法程序集初始化修改时间：2026-06-14 05:06:34