StreamFrame.Protocols.Xml
1.1.0
There is a newer version of this package available.
See the version list below for details.
See the version list below for details.
dotnet add package StreamFrame.Protocols.Xml --version 1.1.0
NuGet\Install-Package StreamFrame.Protocols.Xml -Version 1.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="StreamFrame.Protocols.Xml" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="StreamFrame.Protocols.Xml" Version="1.1.0" />
<PackageReference Include="StreamFrame.Protocols.Xml" />
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add StreamFrame.Protocols.Xml --version 1.1.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: StreamFrame.Protocols.Xml, 1.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package StreamFrame.Protocols.Xml@1.1.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=StreamFrame.Protocols.Xml&version=1.1.0
#tool nuget:?package=StreamFrame.Protocols.Xml&version=1.1.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
StreamFrame
通用 socket 通讯框架：把"帧边界判定"与"帧内数据编解码"插件化，适用于通过 socket 进行数据互换的场景（设备通讯、物流 WMS 对接等）。把场景间的共性（连接管理、重连、读写、粘包/半包、消息分发）收敛到框架核心，把差异性（framing、codec）抽象成可插拔的驱动。
为什么用它
| 传统手写 | StreamFrame | |
|---|---|---|
| 接一种新设备/协议 | 重写连接、切帧、编解码 | 只写一个 ICodec<T> 驱动 |
| 帧边界（长度前缀 / STX-ETX / 自定义） | 各写各的 | 内置两种 + 可插拔 |
| 粘包/半包 | 手写缓冲拼接 | Pipelines 自动处理 |
| 重连 / 状态机 | 手写 | 内置自动重连 |
| 发送性能 | 多次拷贝 | 可选流式零拷贝 |
安装
dotnet add package StreamFrame
XML 报文驱动（可选）：
dotnet add package StreamFrame.Protocols.Xml
快速上手
一条连接 = 一个帧定界策略（framing）+ 一个编解码器（codec）+ 地址/端口/模式。framing 与 codec 均连接级固定，一条连接只流通一种消息类型、一种帧格式。
using System.Net;
using System.Xml.Linq;
using StreamFrame;
using StreamFrame.Abstractions;
using StreamFrame.Protocols.Xml;
// 服务端（被动监听）
var server = new StreamConnection<XDocument>(
new LengthPrefixFrameCodec(), // 4 字节大端长度头；也可用 StxEtxFrameCodec
new XmlDocumentCodec(), // 换成自己的 ICodec<T> 即可支持自定义协议
IPAddress.Any, 5100, isActive: false);
server.Start(ct);
await foreach (var doc in server.GetMessages(ct))
{
var id = doc.Root?.Element("Id")?.Value;
await server.SendAsync(XDocument.Parse($"<Reply><Echo>{id}</Echo></Reply>"), ct);
}
// 客户端（主动连接）
var client = new StreamConnection<XDocument>(
new LengthPrefixFrameCodec(),
new XmlDocumentCodec(),
IPAddress.Parse("127.0.0.1"), 5100, isActive: true);
client.Start(ct);
await client.SendAsync(XDocument.Parse("<Message><Id>1</Id></Message>"), ct);
概念
帧定界（IFrameCodec）— 怎么从字节流里切出一帧
| 实现 | 定界方式 | 适用 |
|---|---|---|
LengthPrefixFrameCodec |
4 字节大端长度头 + 负载 | 通用，二进制安全 |
StxEtxFrameCodec |
STX 0x02 … ETX 0x03 包裹 |
XML / 纯文本等已知安全的负载 |
两种默认实现都支持流式单缓冲编码（可选，消除发送侧 memcpy）。想自定义帧格式时实现 IFrameCodec 即可。
编解码（ICodec<T>）— 怎么解析/写入帧内数据
public interface ICodec<TMessage>
{
TMessage Decode(in ReadOnlySequence<byte> frame, CancellationToken ct = default);
void Encode(TMessage message, IBufferWriter<byte> writer, CancellationToken ct = default);
}
接新设备 = 写一个驱动：实现 ICodec<TMessage> + 定义业务消息类，选一个帧策略，其余全部复用。官方示例见 StreamFrame.Protocols.Xml。
连接（IStreamConnection<T>）— 传输层
- 客户端/服务端双模式：
isActive: true主动连远端，false被动监听 - 自动重连：
Connecting → Connected → Retry状态机 - 事件：
ConnectionChanged状态变化、RawBytesReceived/Sent原始字节（HEX 调试） - 发送背压：有界发送队列，队列满时
SendAsync自动等待
依赖
测试与示例
dotnet build StreamFrame.slnx
dotnet test
dotnet run --project samples/StreamFrame.Demo
项目结构
src/StreamFrame/ # 核心库（无业务依赖）
src/StreamFrame.Protocols.Xml/ # XML 报文驱动（示例 codec）
test/StreamFrame.Tests/ # xUnit 单测
samples/StreamFrame.Demo/ # 控制台端到端 demo
许可
MIT
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
net8.0
- StreamFrame (>= 1.1.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.