# core

**Repository Path**: relative/core

## Basic Information

- **Project Name**: core
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Core 框架

.NET 双目标（netstandard2.0 / net8.0）通用能力框架：一套契约 + 多实现，**同一组 dll 同时支持 ASP.NET Core 后端、WinForms、WPF 与控制台宿主**（无 net8.0-windows 工程；平台差异经能力表运行期门控）。

覆盖：加密/认证、缓存、消息、数据访问、格式化（含 Excel）、工业通讯（Modbus / OPC UA / MQTT / 多品牌 PLC）、系统工具。

详细专题文档见 [`docs/README.md`](docs/README.md)。  
**编译产物 / 如何引用 / 整体示例** → [`docs/getting-started.md`](docs/getting-started.md)。  
接口变更须同步文档（Skill：`.cursor/skills/core-docs-sync`）。

---

## 1. 环境与构建

| 项 | 要求 |
|---|---|
| SDK | .NET 8 SDK（可还原/编译 netstandard2.0 + net8.0） |
| IDE | Visual Studio 2022 / Rider / VS Code + C# |
| 外部依赖（可选） | Redis / RabbitMQ / Kafka 等集成测试缺省**自动跳过**，无服务也可跑通单元/仿真用例 |

```bash
# 还原 + 编译整仓（分模块各自编译；门面 ILRepack 合一产出 Core.dll）
dotnet restore Core.sln
dotnet build Core.sln -c Release

# 跑全部测试（推荐日常自检）
dotnet test Core.sln -c Release --no-build
# 或边编边测：
dotnet test Core.sln -c Release
```

合一包产物：`src/facade/Core.Facade/bin/Release/net8.0/Core.dll`（另有 `netstandard2.0`）。详见 [getting-started.md](docs/getting-started.md)。

---

## 2. 引用与入口

最小引用：**工程 `Core.Facade`（产出 `Core.dll`）**；契约/实现已由 ILRepack 合并进该文件，也可继续显式引用 `Core.Contracts.*` 做编译期类型。

```csharp
using Core.Facade;
using Core.Contracts.Formats;
using Core.Contracts.Comms.Protocols;

// 无配置依赖：直接 Get
var json  = Facade.Get<IJsonSerializer>();
var excel = Facade.Get<IExcelService>();          // 或 Facade.Formats.Excel()
var log   = Facade.Get<ILoggerFactory>().CreateLogger("app");

// 依赖端点 / 多 provider：分组工厂
await using var cache = Facade.Cache.InMemory();
await using var db    = Facade.Db.Sqlite("Data Source=app.db");
var modbus = Facade.Modbus.Tcp("192.168.1.50", 502, unitId: 1);

// 诊断：能力不可用时拿原因，而非裸异常
if (!Facade.TryGet<IDataAccess>(out _, out var reason))
    log.Log(LogLevel.Warning, "数据访问未装配：{Reason}", reason);
```

| 方式 | 适用场景 |
|---|---|
| `Facade.Get<T>()` | 无配置依赖的单默认能力（见 `docs/architecture.md` 矩阵） |
| `Facade.Cache / Db / Plc / Modbus / …` | 多 provider、需端点或外部服务 |
| `new XxxService()` | 单元测试、或宿主自有组合根 |

**部署**：① 全部 `Core.*.dll` 与门面同目录（或 `Facade.Configure` 指定 `ProbingPaths`）；② NuGet meta 包 + `DisableAutoScan`。详见下文「部署物布局」。

---

## 3. 常用能力怎么用（速览）

更细的 API ↔ 测试对照见对应专题文档。

### 3.1 Excel

```csharp
var excel = Facade.Formats.Excel();
var sheets = new (string, IReadOnlyList<IReadOnlyDictionary<string, object?>>)[]
{
    ("People", new List<IReadOnlyDictionary<string, object?>>
    {
        new Dictionary<string, object?> { ["Name"] = "alice", ["Age"] = 30 }
    })
};
await excel.WriteSheetsAsync(Path.Combine(AppContext.BaseDirectory, "test-output", "people.xlsx"), sheets);
var book = await excel.ReadWorkbookAsync(Path.Combine(AppContext.BaseDirectory, "test-output", "people.xlsx"));
```

完整 API、公式/路径/Sheet 操作：[`docs/excel.md`](docs/excel.md)  
对应测试：`ExcelTests.*`（见 §5）。

### 3.2 PLC（统一设备层，含仿真）

```csharp
await using var sim = Facade.Plc.Simulator(PlcVendor.Inovance, "inv://line1");
await sim.StartAsync();
sim.Seed("D100", (ushort)10);

IPlcDevice plc = sim.CreateDevice(); // 真机：Facade.Plc.Create(PlcVendor.Inovance, "inv://host")
await plc.ConnectAsync();

ushort d = await plc.ReadAsync<ushort>("D100");
await plc.WriteAsync("M0", true);
plc.RegisterTag(new PlcTag("Speed", "D100", PlcValueType.UInt16));
await plc.WriteTagAsync("Speed", (ushort)99);
```

厂商寻址与能力表：[`docs/protocols.md`](docs/protocols.md)、规格 [`docs/plc-spec.md`](docs/plc-spec.md)  
门面入口：[`docs/facade.md`](docs/facade.md)

### 3.3 Modbus / OPC UA / MQTT

```csharp
// Modbus TCP
var mb = Facade.Modbus.Tcp("127.0.0.1", 502, unit: 1);
await mb.ConnectAsync();

// OPC UA
var server = Facade.OpcUa.Server();
var ua = Facade.OpcUa.Client(server);

// MQTT 点协议（内存 broker 便于自测）
var broker = Facade.Mqtt.Broker("mqtt://inproc/demo");
var mqtt = Facade.Mqtt.Client(broker);
```

### 3.4 屏幕/窗口捕获 → 保存到本地（仅 Windows）

默认落盘：`{AppContext.BaseDirectory}/capture-output/`（**不写** Temp/AppData）。跑测试时即：

`tests/Core.Tests.Utilities.Capture/bin/<Config>/net8.0/capture-output/`

```csharp
if (!Facade.Capabilities.IsSupported("utilities.capture"))
    return; // 非 Windows 或未装配

var capture = Facade.Utilities.Capture();
var outDir = Path.Combine(AppContext.BaseDirectory, "capture-output");

// 主屏（也可省略 OutputDirectory，效果相同）
var result = await capture.CaptureAsync(
    new CaptureTarget(CaptureTargetKind.PrimaryScreen),
    new CaptureOptions(CaptureOutput.Png, OutputDirectory: outDir));
// 查看 result.FilePath

// 当前本程序主窗口
var hwnd = System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle;
await capture.CaptureAsync(
    new CaptureTarget(CaptureTargetKind.Window, WindowHandle: hwnd),
    new CaptureOptions(CaptureOutput.Png, OutputDirectory: outDir));

// 按其它软件窗口标题（包含匹配）
await capture.CaptureAsync(
    new CaptureTarget(CaptureTargetKind.Window, WindowTitle: "记事本"),
    new CaptureOptions(CaptureOutput.Png, OutputDirectory: outDir));
```

WinForms 用 `this.Handle` / `FindForm().Handle`；WPF 用 `WindowInteropHelper`；详解见 [`docs/capture.md`](docs/capture.md)。

### 3.5 缓存 / 库 / 认证（示例）

```csharp
await using var cache = Facade.Cache.InMemory();
await using var db = Facade.Db.Sqlite("Data Source=:memory:");
var tokenSvc = Facade.Token.Jwt(new TokenOptions("issuer", "audience", secret32Bytes!));
var protector = Facade.Auth.LoginProtector(Facade.Cache.InMemory());
```

完整工厂列表见 [`docs/facade.md`](docs/facade.md)。

---

## 4. 如何跑测试（按模块）

测试工程在 `tests/`。外部服务（Redis/RabbitMQ/Kafka 等）未启动时，集成用例会**自动跳过**，不影响本地绿测。

### 4.1 整仓 / 单工程

```bash
# 全部
dotnet test Core.sln -c Release

# 单工程
dotnet test tests/Core.Tests.Comms.Protocols -c Release
dotnet test tests/Core.Tests.Formats -c Release
dotnet test tests/Core.Tests.Facade -c Release
```

### 4.2 按类 / 关键字过滤（常用）

PowerShell / bash 均可（注意引号）：

```bash
# —— 工业协议 ——
dotnet test tests/Core.Tests.Comms.Protocols --filter "FullyQualifiedName~Plc"
dotnet test tests/Core.Tests.Comms.Protocols --filter "FullyQualifiedName~Mqtt"
dotnet test tests/Core.Tests.Comms.Protocols --filter "FullyQualifiedName~Modbus"
dotnet test tests/Core.Tests.Comms.Protocols --filter "FullyQualifiedName~OpcUa"
# 单用例示例
dotnet test tests/Core.Tests.Comms.Protocols --filter "FullyQualifiedName~AllVendors_Connect_Diagnostics"

# —— Excel ——
dotnet test tests/Core.Tests.Formats --filter "FullyQualifiedName~ExcelTests"
dotnet test tests/Core.Tests.Formats --filter "FullyQualifiedName~ExcelTests.SetCell_Rename_Clear_Copy"

# —— Facade ——
dotnet test tests/Core.Tests.Facade --filter "FullyQualifiedName~GroupFactoryTests"
dotnet test tests/Core.Tests.Facade --filter "FullyQualifiedName~Get_FormatsServices"

# —— 其它 ——
dotnet test tests/Core.Tests.Data --filter "FullyQualifiedName~DataAccessTests"
dotnet test tests/Core.Tests.Cache --filter "FullyQualifiedName~InMemory"
dotnet test tests/Core.Tests.Auth --filter "FullyQualifiedName~JwtRefresh"
```

### 4.3 能力 ↔ 测试工程对照

| 能力 | 文档 | 测试工程 | 典型 filter |
|---|---|---|---|
| 门面 Get / 工厂 | [facade.md](docs/facade.md) | `Core.Tests.Facade` | `~GroupFactoryTests` / `~AssemblyResolution` |
| Excel | [excel.md](docs/excel.md) | `Core.Tests.Formats` | `~ExcelTests` |
| JSON/CSV/XML/INI/YAML | architecture / module-matrix | `Core.Tests.Formats` | `~CsvTests` / `~JsonTests` / … |
| PDF | — | `Core.Tests.Formats.Pdf` | `~PdfTests` |
| PLC / MQTT / Modbus / OPC UA | [protocols.md](docs/protocols.md) | `Core.Tests.Comms.Protocols` | `~Plc` / `~Mqtt` / `~Modbus` / `~OpcUa` |
| TCP/UDP/HTTP 传输 | — | `Core.Tests.Comms.Transport` | `~Tcp` / `~Udp` / `~Http` |
| 数据访问 | — | `Core.Tests.Data` | `~DataAccessTests` |
| 缓存 | — | `Core.Tests.Cache` | `~InMemory` / `~Redis`（需 Redis） |
| 消息 | — | `Core.Tests.Messaging` | `~ZeroMq` / `~ExternalBroker`（需 broker） |
| 认证 / JWT / TOTP | — | `Core.Tests.Auth` | `~JwtRefresh` / `~Totp` |
| 验证码 | — | `Core.Tests.Auth.Captcha` | `~CaptchaTests`（Windows） |
| 工具 / 进程 | — | `Core.Tests.Utilities` | `~ProcessService`；临时文件在 `test-output/tmp` |
| 屏幕/窗口捕获 | [capture.md](docs/capture.md) | `Core.Tests.Utilities.Capture` | `~CaptureTests`（Windows） |
| 公共 / 日志 / 压缩 | — | `Core.Tests.Common` | `~Security` / `~Logging` |

用例级「API ↔ 方法名」表以专题文档为准（Excel / protocols 最完整）。

### 4.4 IDE 中跑

- **Visual Studio / Rider**：打开 `Core.sln` → 测试资源管理器 → 按工程或类名筛选。
- **过滤技巧**：类名如 `ExcelTests`、`PlcDeviceSuiteTests`、`MqttProtocolTests`、`ModbusTcpSlaveTests`、`OpcUaSkeletonTests`。

---

## 5. 部署物布局

**a. 目录扫描（默认）**：全部 `Core.*.dll` 与门面同目录（或 `Facade.Configure(o => o.ProbingPaths = [...])`）。启动时扫描并按 `CanLoad(运行时)` 门控注册。

**b. NuGet meta 包**：宿主引用 `Core.Facade` meta 包，`DisableAutoScan = true`，配合 DI 显式装配。

---

## 6. 宿主支持

| 宿主 | 支持 | 说明 |
|---|---|---|
| ASP.NET Core / Worker（net8.0） | ✅ | 全能力 |
| 控制台（net8.0） | ✅ | 全能力 |
| WinForms / WPF（net48 或 net8.0-windows 引用本库） | ✅ | + 桌面捕获/验证码 Available |
| Linux 容器/服务 | ✅ | 屏幕捕获、GDI 验证码 Unavailable；其余全能力 |

```csharp
if (Facade.Capabilities.IsSupported("utilities.capture"))
{
    var outDir = Path.Combine(AppContext.BaseDirectory, "capture-output");
    var result = await Facade.Utilities.Capture().CaptureAsync(
        new CaptureTarget(CaptureTargetKind.PrimaryScreen),
        new CaptureOptions(CaptureOutput.Png, OutputDirectory: outDir));
    // result.FilePath 在执行目录/capture-output 下
}
```

---

## 7. 仓库结构

```
src/contracts/      契约（接口+record，零实现）
src/common|logging|formats|data|cache|messaging|auth|comms|utilities/
src/facade/         Core.Facade 统一门面
tests/              对应测试工程（外部集成缺省跳过）
docs/               文档中心（用法 + API↔用例）
.cursor/            skills/core-docs-sync（接口变更强制同步文档）
AI_DEV_PLAN/        开发计划与进度
```

文档入口：[`docs/README.md`](docs/README.md)

---

## License / 版本策略

- 框架代码：MIT。第三方组件许可：NPOI、PDFsharp、PdfPig、MQTTnet、Confluent.Kafka、RabbitMQ.Client、YamlDotNet、Newtonsoft.Json、Dapper、Microsoft.Data.*、System.Drawing.Common（仅 Windows）等，以各包许可为准。
- 版本：`主.次.补`——契约破坏升主版本；Wave 内增能力升次版本；补丁仅修复。契约冻结点见 `AI_DEV_PLAN/00_foundation.md`。