CodeWF.NetWrapper 2.1.2.10

CodeWF.NetWeaver

CodeWF.NetWeaver 是网络数据包二进制序列化与反序列化核心库。 CodeWF.NetWrapper 构建在它之上，提供 TCP/UDP 帮助类、命令分发、远程文件系统管理、文件上传/下载和断点续传能力。

文档职责

• 本 README.md 是仓库入口：介绍项目组成、安装、基础用法、构建测试和常用 API。
• CodeWF.NetWeaver 设计原理与架构说明 面向维护者：解释协议结构、序列化实现、Socket 封装和文件传输设计。
• UpdateLog.md 记录版本更新。
• 文件服务简单流程.md 保留文件服务流程备忘。

仓库规范

• 当前版本：2.1.2.3，版本号统一维护在根目录 Directory.Build.props 的 <Version> 节点。
• NuGet 包项目支持 net8.0;net10.0；示例、测试与内部应用项目使用 net11.0 / net11.0-windows。
• 根目录 logo.svg、logo.png、logo.ico 是唯一图标源，子工程通过 MSBuild Link 引用。
• 使用 Directory.Packages.props 做中央包管理，并启用传递包 pin。

项目组成

安装

仅安装数据包序列化核心：

dotnet add package CodeWF.NetWeaver

需要 TCP/UDP 命令分发、文件传输或远程文件管理时，再安装封装层：

dotnet add package CodeWF.NetWrapper

Package Manager Console：

NuGet\Install-Package CodeWF.NetWeaver

构建与测试

dotnet restore CodeWF.NetWeaver.slnx
dotnet build CodeWF.NetWeaver.slnx -c Debug
dotnet test CodeWF.NetWeaver.slnx -c Debug --no-build

打包 NuGet 类库：

pack.bat

发布示例程序：

publish_all.bat

运行示例时先启动服务端，再启动客户端：

dotnet run --project src/SocketTest.Server/SocketTest.Server.csproj -f net11.0-windows
dotnet run --project src/SocketTest.Client/SocketTest.Client.csproj -f net11.0-windows

数据包模型

每个网络数据包由固定头部和对象正文组成：

Header
- BufferLen: int
- SystemId: long
- ObjectId: ushort
- ObjectVersion: byte
- UnixTimeMilliseconds: long

Body
- 序列化后的对象正文

通过 NetHead 为 DTO 标记协议对象 ID 和版本：

using CodeWF.NetWeaver.Base;

[NetHead(10, 1)]
public class ResponseProcessList : INetObject
{
    public int TaskId { get; set; }

    public int TotalSize { get; set; }

    public List<ProcessItem>? Processes { get; set; }
}

public record ProcessItem
{
    public int Pid { get; set; }

    public string? Name { get; set; }
}

基础用法

序列化：

var netObject = new ResponseProcessList
{
    TaskId = 3,
    TotalSize = 2,
    Processes =
    [
        new ProcessItem { Pid = 1, Name = "CodeWF.NetWeaver" },
        new ProcessItem { Pid = 2, Name = "CodeWF.NetWrapper" }
    ]
};

var buffer = netObject.Serialize(systemId: 32);
Console.WriteLine($"Packet bytes: {buffer.Length}");

反序列化：

var deserialized = buffer.Deserialize<ResponseProcessList>();
Console.WriteLine($"Process count: {deserialized.Processes?.Count ?? 0}");

SerializeHelper 支持标量、字符串、枚举、数组、List<T> / 集合接口、Dictionary<TKey,TValue> / 字典接口和嵌套对象。需要跳过字段时使用 NetIgnoreMemberAttribute。

CodeWF.NetWrapper

CodeWF.NetWrapper 负责 TCP/UDP 通信，并将原始数据包转换为强类型命令：

using CodeWF.EventBus;
using CodeWF.NetWrapper.Commands;
using CodeWF.NetWrapper.Helpers;

var server = new TcpSocketServer();
await server.StartAsync("Server", "0.0.0.0", 8888);

EventBus.Default.Subscribe<SocketCommand>(async (sender, command) =>
{
    // 非内置文件管理命令可在这里处理。
    await Task.CompletedTask;
});

文件管理与文件传输

客户端常用 API：

await client.BrowseFileSystemAsync(string.Empty);
await client.BrowseFileSystemAsync(@"D:\ServerFiles");
await client.CreateDirectoryAsync(@"D:\ServerFiles\uploads");
await client.DeletePathAsync(@"D:\ServerFiles\uploads\old.bin", isDirectory: false);
await client.UploadFileAsync(@"D:\local\demo.zip", @"D:\ServerFiles\uploads\demo.zip");
await client.DownloadFileAsync(@"D:\ServerFiles\uploads\demo.zip", @"D:\downloads");

服务端文件系统能力通过 IManagedFileSystem 抽象，默认使用物理文件系统：

var server = new TcpSocketServer();

server.FileTransferProgress += (sender, args) =>
{
    Console.WriteLine($"{args.FileName}: {args.Progress:F2}%");
};

当前实现要求服务端路径使用绝对路径；空路径用于浏览入口，服务端可返回磁盘列表。文件浏览响应按页返回目录条目，上传和下载都通过 TaskId 关联同一次传输流程。

传输行为：

• 文件块大小为 64 KB。
• 上传和下载支持断点续传。
• 完成后执行 SHA-256 校验。
• 客户端触发 FileTransferProgress 和 FileTransferOutcome 事件。
• 服务端触发 FileTransferProgress 事件。
• 传输拒绝、文件不存在、路径访问失败、哈希不一致等情况通过 FileTransferReject 表达。

文件管理 DTO

文件传输 DTO

测试

Wrapper 文件链路已有测试覆盖：

• 上传文件到服务端文件系统。
• 下载文件到指定本地目录。
• 拒绝不存在文件、文件大小冲突和哈希冲突等异常路径。

运行方式：

dotnet test src\CodeWF.NetWrapper.Tests\CodeWF.NetWrapper.Tests.csproj

第三方开源组件审计

检查范围包括 NuGet 元数据、恢复后的 project.assets.json、NuGet.org 信息以及上游源码/许可证链接。优先接受 MIT / Apache-2.0 / BSD。

当前关键依赖：

示例工程已移除 Semi.Avalonia.ProDataGrid 和 AvaloniaUI.DiagnosticsSupport，表格链路改用 MIT 的 ProDataGrid 与自研开源主题包。

Package Versioning Convention

Keep NuGet package versions and Central Package Management settings in Directory.Packages.props, including shared version properties such as AvaloniaVersion. Keep Directory.Build.props focused on build, compiler, and NuGet package metadata. When referenced, VC-LTL and YY-Thunks should use their latest prerelease versions for OS platform compatibility.