CodeWF.Toolkit.Core 1.0.0.16

CodeWF.Toolkit

一组无 UI 依赖的 .NET 基础设施库合集：工具扩展、文件与图片处理、日志、事件总线与网络通信，均以 CodeWF.Toolkit.* 前缀发布。

A collection of UI-independent .NET infrastructure libraries: tool extensions, file/image processing, logging, event bus and network communication, published with the CodeWF.Toolkit.* prefix. Runtime messages use embedded English and Simplified Chinese JSON resources from CodeWF.Toolkit.Lang.

适用场景 / Typical scenarios

包一览 / Packages

所有包均面向 net10.0。「依赖」列中的本仓包由包依赖自动带入，无需单独安装。

快速开始 / Quick start

国际化（CodeWF.Toolkit.Lang）

控制台、服务和基础库可直接使用 CodeWF.Toolkit.Lang，无需引入 Avalonia。JSON 保持现有格式：language、description、cultureName 为元数据，其余对象路径组成稳定资源键。NuGet 库使用 EmbeddedResource；Demo 和桌面应用将 JSON 复制到输出和发布目录的 I18n/，保持宿主资源可替换。

using CodeWF.Toolkit.Lang;
using CodeWF.Toolkit.Lang.Json;

var plugin = new JsonLangPlugin { ResourceFolder = Path.Combine(AppContext.BaseDirectory, "I18n") };
I18nManager.Instance.Register(plugin, new System.Globalization.CultureInfo("en-US"));
I18nManager.Instance.Culture = new System.Globalization.CultureInfo("zh-CN");
var text = I18nManager.Instance.GetResource("App.Title");

库自身使用 new JsonLocalizer(typeof(MyLibrary).Assembly) 读取嵌入 JSON，无需调用方先注册。它跟随全局语言或当前 UI 文化，按请求文化、父文化、默认 en-US 回退；应用可用同名键覆盖库文案。空翻译保留，缺失键返回键本身。JsonLangPlugin<TLanguage>、XmlLangPlugin<TLanguage>、ResxLangPlugin<TLanguage> 支持已有语言元数据子类，解析逻辑只维护一份。裁剪或 NativeAOT 应用使用显式程序集或 ResourceManager 注册，避免 RESX 约定扫描。

应用更新（CodeWF.Toolkit.Core）

IUpdateService 统一检查 GitHub Release、匹配当前 RID、下载、SHA-256 校验与系统安装分发。应用只维护界面状态，程序集 AssemblyInformationalVersion 同时用于显示和版本比较。

using CodeWF.Toolkit.Core.UpdateChecking;

using var updates = new UpdateService(new UpdateServiceOptions
{
    Owner = "dotnet9",
    Repository = "MyApp",
    ProductName = "MyApp"
});
var result = await updates.CheckAsync(cancellationToken: cancellationToken);
if (result is { Succeeded: true, Update: { AssetUrl: not null, ChecksumUrl: not null } update })
{
    var download = await updates.DownloadAsync(update, progress, cancellationToken);
    // 用户点击安装后调用；Windows 成功启动安装器后按 ShouldExitApplication 退出。
    var install = await updates.InstallAsync(download, cancellationToken);
}

无匹配资产或校验文件时，界面提供 UpdateInfo.PageUrl 作为发布页入口。检查失败通过 UpdateCheckResult 返回；下载失败和取消通过异常通知调用方，需由界面状态机处理。安装分发为 Windows EXE、Linux DEB、macOS DMG/PKG；便携 ZIP 只打开目录，启动失败返回手动处理。错误和日志从库的嵌入 JSON 读取，无需应用复制资源。

UpdateChecking 的资源由 Toolkit 维护。 安装 Core 包后，中英文 JSON 已嵌入程序集；无需提供 resolver、创建 JSON 或注册语言插件。未注册应用国际化时跟随 CultureInfo.CurrentUICulture；注册后跟随 I18nManager.Instance.Culture，不支持的语言回退到库内英文。

需要定制时，应用可在自己的国际化资源中只定义要替换的稳定键，使用既有 JsonLangPlugin 扫描输出目录。例如应用输出的 I18n/en-US.json 可写：

{
  "language": "English",
  "description": "MyApp overrides",
  "cultureName": "en-US",
  "Toolkit.Core.Update.AssetMissing": "No package is available for this application."
}

只有应用提供的键被覆盖，其余文案仍从 Core 内嵌资源读取。完整键表在 Core 中英文资源；覆盖带占位符的文案时保留 {0}、{1} 等格式参数。

库和 Demo 的 C# 资源键由 I18n/Language.tt 生成到 Language.g.cs，引用 I18n.ResourceKeys 强类型常量。修改 JSON 后执行 pwsh scripts/sync_localization_keys.ps1；CI 以 -Check 检查生成文件。普通构建直接使用已提交的生成代码，无需安装 T4。XAML 仍使用原有 I18n 绑定。

AssemblyExtensions.CompileTime() 优先读取 Core 包的 buildTransitive 构建目标写入的 UTC CodeWF.BuildTimestamp 元数据，支持 NativeAOT；旧程序集回退到 PE 时间或文件修改时间，并排除确定性构建的哈希时间戳。需要可重复构建时设置固定的 CodeWFBuildTimestamp（ISO 8601），或用 CodeWFGenerateBuildTimestamp=false 关闭自动生成；默认使用本次构建时间，会影响程序集的字节级可重复性。

各库的运行时错误、日志、枚举描述使用 Toolkit.<库名>.<语义> 键。中英文资源随各自 NuGet 包嵌入，中文数字转换所需字符表作为固定算法数据读取，不随界面语言改变。编译期 AOT/裁剪诊断保留英文常量，以符合 .NET 特性参数约束。

dotnet add package CodeWF.Toolkit.Core
dotnet add package CodeWF.Toolkit.EventBus
dotnet add package CodeWF.Toolkit.Logging

日志（CodeWF.Toolkit.Logging）

using CodeWF.Toolkit.Logging;

Logger.TryInitialize(new LoggerOptions
{
    MinimumLevel = LogLevel.Information,
    EnableConsole = true,
    File = new FileLogOptions
    {
        DirectoryPath = Path.Combine(AppContext.BaseDirectory, "logs"),
        MaxFileSizeBytes = 32 * 1024 * 1024,
        RetentionDays = 30,
    },
});

Logger.Info("服务已启动");
Logger.Error("处理失败", ex);
await Logger.ShutdownAsync();   // 退出前刷盘

需要把 MEL 生态的日志也收进来时，加装 CodeWF.Toolkit.Logging.Microsoft：builder.Logging.AddCodeWFLogger(options => { /* 同 LoggerOptions */ });

事件总线（CodeWF.Toolkit.EventBus）

using CodeWF.Toolkit.EventBus;

var bus = new EventBus();
bus.Subscribe<GreetCommand>(cmd => Console.WriteLine(cmd.Name));
await bus.PublishAsync(new GreetCommand("hi"));

var query = new TimeQuery();
bus.Subscribe(new TimeQueryHandler());   // 含 [EventHandler] 方法的处理器
bus.Query(query);

序列化往返（CodeWF.Toolkit.NetWeaver）

[NetHead(0x01, 1)]
public sealed class SamplePacket : INetObject
{
    [NetFieldOrder(0)] public int Id { get; set; }
    [NetFieldOrder(1)] public string Title { get; set; } = string.Empty;
}

var buffer = packet.Serialize(systemId: 0);
var restored = buffer.Deserialize<SamplePacket>();

TCP 收发（CodeWF.Toolkit.NetWrapper）

using CodeWF.Toolkit.NetWrapper.Helpers;

var server = new TcpSocketServer();
await server.StartAsync("demo-server", "127.0.0.1", 39561);

var client = new TcpSocketClient();
await client.ConnectAsync("demo-server", "127.0.0.1", 39561);
await client.SendCommandAsync(packet);

远程文件系统（浏览/上传/下载/断点续传）见 CodeWF.Toolkit.NetWrapper.FileSystem 的 TcpSocketClientFileSystemFeature。

文件与图片（CodeWF.Toolkit.Files / CodeWF.Toolkit.Image）

using CodeWF.Toolkit.Core.FileExtensions;   // SevenZipCompressor
using CodeWF.Toolkit.Files.Extensions;      // ToJson / ToYaml
using CodeWF.Toolkit.Image;                 // ImageHelper / QrCodeGenerator

var yaml = student.ToYaml(out var error);

var compressor = new SevenZipCompressor(httpClient);
compressor.Zip(sourceDirectory, "out.zip");
compressor.Decompress("out.zip", destinationDirectory);

await ImageHelper.MergeGenerateIcon("logo.png", "logo.ico", [24, 32, 48]);
QrCodeGenerator.GenerateQrCode("CodeWF", "https://codewf.com", "qr.png");

更新检查（CodeWF.Toolkit.Core）

using CodeWF.Toolkit.Core.UpdateChecking;

var checker = new UpdateChecker("dotnet9", "CodeWF.Toolkit");
var result = await checker.CheckAsync(new Version(1, 0, 0, 0));

与 CodeWF.Avalonia 的关系 / Relationship with CodeWF.Avalonia

• CodeWF.Avalonia.Log（日志查看控件与桌面通知）配套本仓的 CodeWF.Toolkit.Logging：控件订阅核心的 UI 日志事件流，日志回调在后台线程，界面侧自行调度到 UI 线程。
• 两个仓库各自带演示程序：本仓 demo/ 下是控制台演示与 Avalonia 图形演示台，CodeWF.Avalonia 仓的演示台展示的是控件与主题。
• UI 相关能力一律留在 CodeWF.Avalonia.*；本仓保持无 UI 依赖。

依赖与目标框架 / Dependencies and AOT

全部库项目面向 net10.0，Directory.Packages.props 集中管理版本。Native AOT/裁剪注意点：

CI 的 aot-smoke 作业会对控制台演示与 Avalonia 演示台做 PublishAot=true 发布并运行 --smoke。

包 → 源码 → 文档索引 / Source & docs index

演示 / Demos

Demo 保留 Ribbon + Dock，按核心扩展、系统与文件、数据与图像、事件与集成、协议与网络、日志与观测分类；每个主菜单对应一个帮助类，52 个页面按类名查找；CSV / Excel 提供真实表格回读，网络与文件系统提供可保持的会话和传输操作，组合示例集中到“综合示例”。详见 原生 Demo 文档。

核心扩展再按文本、数值、日期时间、类型与查询分组，密集命令使用双行排列，保留完整帮助类名。UI 从公开 NuGet 安装 CodeWF.Avalonia 包，单独克隆本仓即可构建；global.json 选择稳定版 .NET 10 SDK。

标题栏提供浅色、深色、跟随系统三态，搭配 .NET 紫、AI 极光、AI 赤陶、默认蓝、水生、沙漠、黄昏、夜空八套配色。颜色与模式独立选择，通过 NuGet 中的 StudioThemeController 跟随系统并同步文档属性面板。

The Ribbon and Dock demo groups APIs by function, with one helper class per primary menu entry. Composite workflows are in the final category. Its UI libraries come from NuGet; cloning CodeWF.Toolkit alone is sufficient to build the GUI and console demos.

# 控制台演示：依次跑日志、进程内总线、分布式总线、序列化，然后进入交互菜单
dotnet run --project demo/CodeWF.Toolkit.Demo
# 冒烟模式：跑完全部演示直接退出，退出码 0 表示通过（CI / AOT 冒烟使用）
dotnet run --project demo/CodeWF.Toolkit.Demo -- --smoke

# Avalonia 图形演示台：同款能力以界面方式逐页演示
dotnet run --project demo/CodeWF.Toolkit.Demo.Avalonia
# 冒烟模式：逐页构建后逐色板渲染一遍再退出，退出码 0 表示全部通过（CI / AOT 冒烟使用）
dotnet run --project demo/CodeWF.Toolkit.Demo.Avalonia -- --smoke

图形演示台的安装包由 GitHub Releases 提供（随 v* tag 构建）：Windows setup.exe / 便携 zip、Linux deb、macOS dmg，均附 .sha256 校验文件。控制台演示以源码运行，不作为安装包分发。

许可与贡献 / License and contributing

MIT。Issue 与 PR 都欢迎，提交前请确保 dotnet build CodeWF.Toolkit.slnx -c Release 与 dotnet test 通过。