net9nlib 1.0.0

net9nlib

通用 .NET 9 类库，提供日志功能和单实例应用支持，支持 Windows、Linux、Mac 平台。

功能特性

• ✅ 日志功能: 基于 Microsoft.Extensions.Logging 的统一日志接口
  • 支持控制台、调试窗口和文件输出
  • 日志文件存储在程序运行目录，按日期自动创建子文件夹
  • 支持自定义日志名称和目录
• ✅ 配置文件管理: 提供简单的 JSON 配置文件读写功能
  • 配置文件存储在程序运行目录
  • 支持类型安全的配置读写
• ✅ 单实例应用: 确保应用程序在同一时间只能运行一个实例
• ✅ 跨平台支持: 支持 Windows、Linux、Mac 三大平台

安装

dotnet add package net9nlib

快速开始

日志功能

基础日志（仅控制台输出）

using net9nlib;

// 创建日志服务（仅控制台输出）
var logger = Net9nLib.CreateLoggerService("MyApp");

// 使用日志
logger.LogInformation("应用程序启动");
logger.LogWarning("这是一个警告");
logger.LogError("这是一个错误");
logger.LogError(exception, "发生异常: {Message}", exception.Message);

文件日志（推荐）

using net9nlib;
using Microsoft.Extensions.Logging;

// 创建带文件输出的日志服务
// 日志文件存储在程序运行目录的 logs 文件夹下，按日期创建子文件夹
// 日志文件格式：logs/yyyy-MM-dd/日志名_yyyy-MM-dd.log
var (logger, loggerFactory) = Net9nLib.CreateFileLoggerService(
    logName: "MyApp",              // 日志名称（用于日志文件名）
    categoryName: "MyApp",          // 日志类别名称
    enableConsole: true,            // 是否启用控制台输出
    enableDebug: true,              // 是否启用调试输出
    minimumLevel: LogLevel.Debug   // 最小日志级别
);

// 使用日志（会自动写入文件）
logger.LogInformation("应用程序启动");
logger.LogWarning("这是一个警告");
logger.LogError("这是一个错误");

// 注意：需要保持 loggerFactory 的引用，程序退出时调用 Dispose
loggerFactory.Dispose();

日志文件结构

程序运行目录/
├── logs/
│   ├── 2026-01-28/
│   │   └── MyApp_2026-01-28.log
│   ├── 2026-01-29/
│   │   └── MyApp_2026-01-29.log
│   └── ...

单实例应用

using net9nlib;

// 创建单实例服务
var singleInstance = Net9nLib.CreateSingleInstanceService();

// 尝试获取锁
if (!singleInstance.TryAcquireLock("MyUniqueAppName"))
{
    Console.WriteLine("应用程序已在运行，退出当前实例");
    return;
}

try
{
    // 应用程序主逻辑
    Console.WriteLine("应用程序正在运行...");
    // ...
}
finally
{
    // 释放资源
    singleInstance.Dispose();
}

配置文件管理

基础配置管理器（键值对方式）

using net9nlib;

// 创建配置文件管理器（配置文件存储在程序运行目录）
var config = Net9nLib.CreateConfigManager("MyApp");

// 读取配置（带默认值）
var appName = config.GetValue("AppName", "默认应用名称");
var maxRetries = config.GetValue("MaxRetries", 3);
var timeout = config.GetValue("Timeout", TimeSpan.FromSeconds(30));

// 设置配置
config.SetValue("AppName", "我的应用程序");
config.SetValue("MaxRetries", 5);
config.SetValue("Timeout", TimeSpan.FromMinutes(1));

// 保存配置到文件
config.SaveConfig();

// 获取配置文件路径
Console.WriteLine($"配置文件路径: {config.ConfigFilePath}");

实体配置管理器（双向绑定，推荐）

using net9nlib;

// 定义配置实体类
public class AppConfig
{
    public string AppName { get; set; } = "默认应用";
    public int MaxRetries { get; set; } = 3;
    public int TimeoutSeconds { get; set; } = 30;
    public bool EnableDebug { get; set; } = true;
    public List<string> ServerUrls { get; set; } = new();
}

// 创建实体配置管理器（支持双向绑定）
var entityConfig = Net9nLib.CreateEntityConfigManager<AppConfig>("MyApp");

// 自动从配置文件加载实体（如果文件不存在，使用默认值）
var config = entityConfig.Entity;
Console.WriteLine($"应用名称: {config.AppName}");

// 修改实体属性
config.AppName = "我的应用程序";
config.MaxRetries = 5;
config.ServerUrls.Add("http://example.com");

// 保存实体到配置文件（双向绑定）
entityConfig.Save();

// 重新加载配置（从文件读取）
var reloadedConfig = entityConfig.Reload();

// 重置为默认值
var defaultConfig = entityConfig.Reset();

实体双向绑定的优势：

• ✅ 类型安全：编译时检查，避免键名拼写错误
• ✅ 自动序列化：实体对象自动转换为 JSON
• ✅ 支持复杂对象：嵌套对象、集合等
• ✅ 代码简洁：直接操作对象属性，无需键值对
• ✅ 智能默认值：使用实体类的属性初始值

完整示例

using net9nlib;
using Microsoft.Extensions.Logging;

// 创建带文件输出的日志服务
var (logger, loggerFactory) = Net9nLib.CreateFileLoggerService(
    logName: "MyApp",
    categoryName: "MyApp"
);

// 创建配置文件管理器
var config = Net9nLib.CreateConfigManager("MyApp");

// 读取配置
var appName = config.GetValue("AppName", "默认应用");
logger.LogInformation("应用程序名称: {AppName}", appName);

// 创建单实例服务
var singleInstance = Net9nLib.CreateSingleInstanceService();

// 检查单实例
if (!singleInstance.TryAcquireLock("MyUniqueAppName"))
{
    logger.LogWarning("应用程序已在运行，退出当前实例");
    return;
}

logger.LogInformation("应用程序启动成功");

try
{
    // 应用程序主逻辑
    logger.LogInformation("应用程序正在运行...");
}
catch (Exception ex)
{
    logger.LogError(ex, "应用程序发生错误");
}
finally
{
    singleInstance.Dispose();
    loggerFactory.Dispose(); // 释放日志工厂
    logger.LogInformation("应用程序退出");
}

API 文档

ILoggerService

提供统一的日志记录接口：

• LogDebug(string message, params object[] args) - 记录调试信息
• LogInformation(string message, params object[] args) - 记录信息
• LogWarning(string message, params object[] args) - 记录警告
• LogError(string message, params object[] args) - 记录错误
• LogError(Exception exception, string message, params object[] args) - 记录错误（带异常）
• LogCritical(string message, params object[] args) - 记录严重错误
• LogCritical(Exception exception, string message, params object[] args) - 记录严重错误（带异常）

ISingleInstanceService

提供单实例应用支持：

• TryAcquireLock(string instanceName) - 尝试获取单实例锁
• IsLockAcquired - 是否已获取锁
• Dispose() - 释放资源

ConfigManager

提供基础配置文件管理功能（键值对方式）：

• GetValue<T>(string key, T defaultValue) - 获取配置值（带默认值）
• SetValue<T>(string key, T value) - 设置配置值
• GetAllValues() - 获取所有配置
• SaveConfig() - 保存配置到文件
• ConfigFilePath - 配置文件路径（只读）

EntityConfigManager<T>

提供实体双向绑定功能（推荐使用）：

• Entity - 获取当前绑定的实体对象（自动加载）
• Load() - 从配置文件加载实体
• Save() - 保存当前实体到配置文件
• Save(T entity) - 保存指定实体到配置文件
• Reload() - 重新加载实体（从文件读取）
• Reset() - 重置实体为默认值
• ConfigFilePath - 配置文件路径（只读）
• ConfigFileExists - 配置文件是否存在（只读）

使用要求：

• 实体类型 T 必须有无参构造函数（new() 约束）
• 实体属性必须是可序列化的（public 属性）

平台支持

• ✅ Windows (使用 Mutex)
• ✅ Linux (使用文件锁)
• ✅ macOS (使用文件锁)

许可证

MIT License

作者

aranwuyou