SAEA.FileSocket 26.4.22.1

SAEA.FileSocket - 高性能文件传输组件 📁

English Version | 中文版

基于 SAEA.Sockets 的高性能文件传输组件，采用 IOCP 完成端口技术，支持大文件分块传输、断点续传、实时进度监控。

快速导航 🧭

30秒快速开始 ⚡

最快上手方式，只需3步即可实现文件传输：

Step 1: 安装 NuGet 包

dotnet add package SAEA.FileSocket

Step 2: 创建文件接收服务器（仅需6行代码）

using SAEA.FileSocket;

var fileTransfer = new FileTransfer(@"C:\ReceivedFiles", port: 39654);
fileTransfer.OnReceiveEnd += (path) => Console.WriteLine($"接收完成: {path}");
fileTransfer.Start();

Step 3: 发送文件

fileTransfer.SendFile(@"C:\Data\video.mp4", "192.168.1.100");

就这么简单！ 🎉 你已经实现了一个支持大文件、断点续传的高性能文件传输系统。

核心特性 🎯

架构设计 📐

组件架构图

┌─────────────────────────────────────────────────────────────┐
│                   SAEA.FileSocket 架构                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   FileTransfer                         │  │
│  │              (文件传输协调主类)                        │  │
│  └───────────────────────┬──────────────────────────────┘  │
│                          │                                  │
│           ┌──────────────┴──────────────┐                  │
│           │                             │                   │
│  ┌────────▼────────┐          ┌────────▼────────┐        │
│  │      Client     │          │      Server      │        │
│  │    (发送端)     │          │    (接收端)      │        │
│  └────────┬────────┘          └────────┬────────┘        │
│           │                             │                   │
│           │     ┌───────────────┐       │                   │
│           └────►│ FileMessage   │◄──────┘                  │
│                 │  (消息模型)   │                           │
│                 └───────┬───────┘                          │
│                         │                                   │
│              ┌──────────┴──────────┐                       │
│              │                     │                        │
│       ┌──────▼──────┐      ┌───────▼──────┐               │
│       │  Request    │      │   Chunk      │               │
│       │  (请求)     │      │   (数据块)   │               │
│       └─────────────┘      └──────────────┘               │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              SAEA.Sockets (IOCP底层)                 │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

文件传输流程图

文件传输完整流程:

发送端                                    接收端
  │                                         │
  │  1. SendFile(fileName, targetIp)        │
  │────────────────────────────────────────►│
  │                                         │
  │  2. 请求发送 (RequestMessage)            │
  │     ├── FileName                        │
  │     └── FileLength                      │
  │────────────────────────────────────────►│
  │                                         │
  │                              3. OnRequested 事件
  │                                 ├── 返回 true (允许)
  │                                 └── 返回 false (拒绝)
  │                                         │
  │  4. 允许接收 (AllowReceive)             │
  │◄────────────────────────────────────────│
  │                                         │
  │  5. 分块发送数据流                        │
  │     ┌─────────────────────────────────┐ │
  │     │ Chunk 1 (100KB)                 │ │
  │     │────────────────────────────────►│ │
  │     │ Chunk 2 (100KB)                 │ │
  │     │────────────────────────────────►│ │
  │     │ Chunk 3 (100KB)                 │ │
  │     │────────────────────────────────►│ │
  │     │ ...                             │ │
  │     │ Chunk N (剩余部分)              │ │
  │     │────────────────────────────────►│ │
  │     └─────────────────────────────────┘ │
  │                                         │
  │                              6. 写入文件 (File.WriteAllText)
  │                                         │
  │                              7. OnReceiveEnd 事件
  │                                 └── 触发接收完成回调
  │                                         │
  │  8. 发送完成回调                          │
  │◄────────────────────────────────────────│
  │                                         │

断点续传流程:

  │  SendFile(fileName, offset)             │
  │────────────────────────────────────────►│
  │  从 offset 位置继续发送                   │
  │  ├── 跳过已传输部分                       │
  │  └── 只发送剩余数据                       │
  │────────────────────────────────────────►│

传输协议详解

┌─────────────────────────────────────────────────────────────┐
│                    四阶段握手协议                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  阶段1: 请求 (RequestMessage)                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 消息类型: Request                                    │   │
│  │ 内容: FileName + FileLength                         │   │
│  │ 说明: 发送端请求发送文件                              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  阶段2: 响应 (ResponseMessage)                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ AllowReceive: 允许接收                               │   │
│  │ RefuseReceive: 拒绝接收                              │   │
│  │ 说明: 接收端决定是否接收                              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  阶段3: 数据流 (DataMessage)                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 分块大小: 默认 100KB                                  │   │
│  │ 发送方式: SendAsync 异步发送                          │   │
│  │ 说明: 分块传输文件内容                                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  阶段4: 完成 (Complete)                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 触发: OnReceiveEnd 事件                              │   │
│  │ 动作: 保存文件、清理资源                              │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

应用场景 💡

✅ 适合使用 SAEA.FileSocket 的场景

❌ 不适合的场景

性能对比 📊

传输性能数据

分块传输效率

💡 提示: 可根据网络环境和文件大小调整 bufferSize 参数优化传输效率。

与其他方案对比

常见问题 ❓

Q1: 如何实现断点续传？

A: 使用 offset 参数从指定位置继续传输：

// 记录已传输的位置
long lastOffset = GetLastOffset(fileName);

// 从断点继续发送
client.SendFile(fileName, lastOffset, (success) => 
{
    if (success)
        Console.WriteLine("续传成功");
});

// 接收端会从 offset 位置继续写入

Q2: 如何调整传输块大小？

A: 在构造函数中设置 bufferSize 参数：

// 小文件或网络不稳定：使用较小块
var fileTransfer = new FileTransfer(path, port, bufferSize: 50 * 1024);

// 大文件或高速网络：使用较大块
var fileTransfer = new FileTransfer(path, port, bufferSize: 1024 * 1024);  // 1MB

Q3: 如何监控传输进度？

A: 使用 OnDisplay 事件：

fileTransfer.OnDisplay += (info) => 
{
    Console.WriteLine(info);  // 包含发送/接收速度
};

fileTransfer.OnReceiveEnd += (filePath) => 
{
    Console.WriteLine($"接收完成: {filePath}");
};

Q4: 如何拒绝接收特定文件？

A: 使用 Server 类的 OnRequested 事件：

var server = new Server(port: 39654);

server.OnRequested += (ID, fileName, length) => 
{
    // 根据文件名或大小决定是否接收
    if (length > 1024 * 1024 * 1024)  // 超过 1GB
    {
        Console.WriteLine($"拒绝接收大文件: {fileName}");
        return false;  // 拒绝
    }
    return true;  // 允许
};

server.Start();

Q5: 支持同时传输多个文件吗？

A: 支持。创建多个 Client 实例或使用同一个 FileTransfer 发送多个文件：

// 方式1: 使用 FileTransfer 顺序发送
fileTransfer.SendFile(file1, targetIp);
fileTransfer.SendFile(file2, targetIp);

// 方式2: 创建多个 Client 并发发送
var client1 = new Client();
var client2 = new Client();
client1.Connect(ip, port);
client2.Connect(ip, port);
client1.SendFile(file1, callback);
client2.SendFile(file2, callback);

Q6: 传输中断后如何恢复？

A: FileSocket 支持断点续传，只需记录已传输的字节数：

// 1. 定期保存已传输位置
long savedOffset = GetTransferredBytes(fileName);
SaveProgress(fileName, savedOffset);

// 2. 中断后从保存位置恢复
long lastOffset = LoadProgress(fileName);
client.SendFile(fileName, lastOffset, callback);

Q7: 如何自定义接收路径？

A: 在 FileTransfer 或 Server 构造时指定：

// FileTransfer 方式
var fileTransfer = new FileTransfer(@"C:\CustomPath", port: 39654);

// Server 方式
var server = new Server(port: 39654, filePath: @"C:\CustomPath");

核心类 🔧

使用示例 📝

基础文件传输

using SAEA.FileSocket;

var fileTransfer = new FileTransfer(@"C:\ReceivedFiles", port: 39654);

fileTransfer.OnReceiveEnd += (filePath) => 
    Console.WriteLine($"文件接收完成: {filePath}");

fileTransfer.OnDisplay += (info) => 
    Console.WriteLine($"传输状态: {info}");

fileTransfer.Start();
fileTransfer.SendFile(@"C:\Data\document.pdf", "192.168.1.100");

Server 端自定义处理

using SAEA.FileSocket;

var server = new Server(port: 39654, bufferSize: 100 * 1024);

server.OnRequested += (ID, fileName, length) => 
{
    Console.WriteLine($"请求接收文件: {fileName}, 大小: {length / 1024 / 1024}MB");
    return true;
};

server.OnFile += (userToken, content) => 
{
    // 自定义处理接收的数据块
};

server.OnError += (ID, ex) => 
    Console.WriteLine($"传输错误: {ex.Message}");

server.Start();

Client 端发送（带回调）

using SAEA.FileSocket;

var client = new Client(bufferSize: 100 * 1024);

client.Connect("192.168.1.100", 39654);

client.SendFile(@"C:\Data\document.pdf", (success) => 
{
    if (success)
        Console.WriteLine("发送成功");
    else
        Console.WriteLine("发送失败");
});

// 断点续传
long offset = 1024 * 1024 * 100;
client.SendFile(@"C:\Data\large_file.dat", offset, (success) => 
    Console.WriteLine($"续传结果: {success}"));

自定义缓冲区大小

using SAEA.FileSocket;

// 小缓冲区：网络不稳定场景
var smallBuffer = new FileTransfer(path, port, bufferSize: 50 * 1024);

// 大缓冲区：高速网络大文件场景
var largeBuffer = new FileTransfer(path, port, bufferSize: 1024 * 1024);

分块传输机制

传输协议格式

FileSocket 使用四阶段握手协议：

┌──────────────┐     Request      ┌──────────────┐
│    发送端    │ ────────────────► │    接收端    │
│   (Client)   │                   │   (Server)   │
└──────────────┘                   └──────────────┘
       │                                  │
       │◄───── Allow/Refuse ─────────────│
       │                                  │
       │═══════ Data Chunks ═════════════►│
       │                                  │
       │◄───── Complete ──────────────────│

依赖项

更多资源

• GitHub 仓库
• NuGet 包
• 作者博客

许可证

Apache License 2.0