Vane.Dispatch 1.1.0

dotnet add package Vane.Dispatch --version 1.1.0
                    
NuGet\Install-Package Vane.Dispatch -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="Vane.Dispatch" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Vane.Dispatch" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Vane.Dispatch" />
                    
Project file
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 Vane.Dispatch --version 1.1.0
                    
#r "nuget: Vane.Dispatch, 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 Vane.Dispatch@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=Vane.Dispatch&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Vane.Dispatch&version=1.1.0
                    
Install as a Cake Tool

Vane.Dispatch

一个容器无关、高性能、AOT 友好的 .NET 服务分发引擎。前身 Ndf 已在公司内部多个项目中长期生产验证,现正式开源。

Vane.Dispatch 是一个微内核:按特性(Attribute)将调用路由到控制器操作,绑定请求模型,执行过滤器管线,并基于接口生成代理。它只依赖一个最小的 ServiceResolver 委托,与任何 DI 容器、任何通信层都零耦合。你可以自己提供解析器(或任意 IServiceProvider)、自己的控制器、自己的线格式。

所有公开类型统一归属 Vane.Dispatch 命名空间;通过 GlobalUsings.cs 汇总全局 using,源码内不含散落的 using 指令。

特性

  • 容器无关 —— 只依赖 BCL(双目标 net8.0 / net10.0)。通过 ServiceResolver 委托解析控制器,或用任意 IServiceProvider 作为适配。
  • 特性路由 —— 类级 [Route](声明可分发 + 组名 + 默认自动绑定)、方法级 [Route](操作契约名 / 别名)、[NoAutoBind](关闭自动绑定推断),查表大小写不敏感,支持重复操作检测。
  • 模型绑定 —— Body / Route / Header / Query / Services 值提供器与类型转换,支持 [FromBody] / [FromRoute] / [FromHeader] / [FromQuery] / [FromServices]。
  • 过滤器管线 —— 全局与操作级过滤器;OnExecuted 对标 MVC 三态恒运行(成功 / 异常 / 取消均执行,上下文携带 Exception / Canceled / ExceptionHandled);IExceptionFilter 统一处理操作异常,可置 ExceptionHandled 免除失败判定。内置 DataAnnotations 校验(含 IValidatableObject),用 UseValidation() 一键启用(对标 MVC 默认自动校验)。
  • 格式化器 —— 内置 JSON 与原始字节,另提供扁平二进制 FlatBinaryFormatter(需手动注册),可插入自定义二进制协议(如 MessagePack)。
  • 接口代理 —— CreateProxy<T>() 把任意接口变成进程内强类型客户端。
  • 自由端点 —— 对标 Minimal API 的 Map / MapGet / MapPost / Handle,注册委托端点。
  • 性能 —— 路由表预构建;热路径分发采用表达式编译调用器而非反射。
  • AOT 友好 —— IsAotCompatible / IsTrimmable 已开启;反射相关公开 API 均有 [RequiresUnreferencedCode] / [RequiresDynamicCode] / [DynamicallyAccessedMembers] 标注,裁剪与 NATIVE AOT 场景可得到准确警告。

快速开始

从 NuGet 安装:

dotnet add package Vane.Dispatch

定义一个控制器(类级 [Route] 的模板即路由组名,缺省时取类型名去掉 Controller 后缀):

using Vane.Dispatch;

[Route("math")]
public class MathController
{
    public int Add(int a, int b) => a + b;
    public int Square(int x) => x * x;
}

用自己的解析器构建引擎(此处是一个基于 Activator 的极简解析器,仅作演示):

ServiceResolver resolver = serviceType =>
    serviceType.GetConstructor(Type.EmptyTypes)?.Invoke(null)
    ?? throw new MissingMethodException(serviceType.FullName);

var engine = resolver
    .BuildDispatchEngine()
    .MapDispatchable<MathController>()
    .Build();

// 强类型分发
int sum = engine.Dispatch<int>("math", "Add", new { a = 2, b = 3 });   // 5

// 强类型便捷调用
int sq = engine.Send<MathController, int>("Square", 6);                // 36

// 接口代理
public interface IMath { int Square(int x); }
var proxy = engine.CreateProxy<IMath>();
int px = proxy.Square(9);                                             // 81

如果你已有 IServiceProvider,直接调用 services.BuildDispatchEngine() —— BCL 适配器会把你的 provider 包装成解析委托。无需引入 Vane.Container。

批量注册与自由端点

// 扫描整个程序集中带 [Route] 的类型(需保留类型,见“AOT 兼容性”)
var engine = resolver.BuildDispatchEngine()
    .MapDispatchablesFromAssembly(typeof(MathController).Assembly)
    .Build();

// 注册自由函数端点(对标 Minimal API 的 MapGet/MapPost/Map)
var engine2 = resolver.BuildDispatchEngine()
    .MapGet("/ping", () => "pong")
    .MapPost("/echo", (string msg) => msg)
    .Build();

目录结构

src/Vane.Dispatch    库本体(自包含,双目标 net8.0 / net10.0,全部类型归属 Vane.Dispatch 命名空间)
tests/               自包含 NUnit 测试套件(不依赖容器或传输层)
examples/            控制台示例
docs/                开发者使用手册等文档

文档:系统教程 · 开发者使用手册

子目录(如 Annotations、ModelBinding)仅用于源码归类,不影响命名空间。

AOT 兼容性

Vane.Dispatch 以「兼容标注」方式支持裁剪与原生 AOT:

  • 程序集已声明 <IsTrimmable>true</IsTrimmable> 与 <IsAotCompatible>true</IsAotCompatible>。
  • 走反射的公开 API(如 MapDispatchablesFromAssembly、Dispatch<TResult>(object args)、CreateProxy<T>()、JSON 格式化与模型校验)均标注 [RequiresUnreferencedCode] / [RequiresDynamicCode],并在目标类型上加 [DynamicallyAccessedMembers]。

因此:

  • 仅裁剪(Trim):直接可用;只会对确实依赖反射的路径给出可读警告。
  • 原生 AOT(NativeAOT):避免 object 匿名参数分发与程序集扫描,改用以下 AOT 友好形式,可显著减少警告。Build() 自身带 RequiresDynamicCode,Native AOT 下仍需为构建入口提供抑制或替换方案:
    • 用 DispatchRequest.Create(name, op, IDictionary<string, object> args) 字典构造请求,而非匿名对象;
    • 显式 MapDispatchable<T>() 注册,而非 MapDispatchablesFromAssembly;
    • 二进制协议选用 RawBytesFormatter / 自定义 IInputFormatter,JSON 请配合 JsonSerializerContext 源生成或改用二进制。

异常处理(对标 MVC)

Vane.Dispatch 的异常语义对齐 MVC 的「三段式」:OnExecuted 恒运行 → 异常 / 取消分类 → 结构化错误体。下表给出逐项对标关系。

MVC 语义 Vane.Dispatch 对应
处理器未捕获异常 → 异常过滤器 → 500 捕获入 ActionExecutedContext.Exception → 500
IExceptionFilter / IAsyncExceptionFilter(可置 ExceptionHandled) IExceptionFilter(置 ExceptionHandled 免除 500 / 499)
OnActionExecuted 在异常 / 取消仍触发 OnExecuted 三态恒运行,上下文携带 Exception / Canceled
请求取消 → 抛取消异常(多为 400) 令牌取消 → 499(RequestCanceled)
400 + ModelState 400 + 统一 ModelState(UseValidation() 一键启用)
RFC 7807 ProblemDetails 可选 ProblemDetails(成功零分配,失败惰性生成)

与 MVC 的差异集中在「不绑 HTTP」:异常在分发内收口到响应对象——response.Exception 保留原始异常供进程内调用方查看,ProblemDetails 供跨进程序列化,二者共享同一失败判定,不依赖 HTTP 异常处理中间件。

设计取舍(同步快路径 + 按需异步)

  • 默认全同步快路径:Dispatch、模型绑定、同步过滤器、调用器全同步无 Task,不含异步状态机开销。带参数绑定或输出序列化时仍会分配对象,「零分配」只对无参且无过滤器的窄路径成立。跨进程 Send 阻塞等待。
  • 按需异步:DispatchAsync 复用同一同步内核(路由/模型绑定/同步过滤器原样同步),仅对 async 处理器(Task/ValueTask 及其泛型)执行 await,并支持 IAsyncFilter / AsyncActionFilterAttribute(方法级异步过滤器)。异步只落到真正有 I/O 的地方。
  • 取舍:formatter / 路由 / 模型绑定 / 值提供器均为纯 CPU 内存操作,保持同步不套 async(无阻塞点可重叠,套了只加成本)。
  • 何时用哪个:CPU 密集处理器用同步 Dispatch(零分配快路径);处理器确实要做 I/O 或需异步过滤器时,改用 DispatchAsync。异步 invoker 为惰性编译,纯同步应用不产生常驻异步委托成本。

构建与测试

dotnet build Vane.Dispatch.slnx -c Release
dotnet test  tests/Vane.Dispatch.Tests -c Release

库本体开启 XML 文档注释并未抑制 CS1591,构建保持 0 警告。

打包 / 发布

dotnet pack src/Vane.Dispatch -c Release   # 产出 Vane.Dispatch.{version}.nupkg

在 src/Vane.Dispatch/Vane.Dispatch.csproj 中设置 Version(当前 1.1.0)。RepositoryUrl / PackageProjectUrl 已指向 https://gitee.com/netcasewqs/vane-dispatch,迁移仓库时同步更新。

License

MIT

Product 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 is compatible.  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.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 49 11/13/2026
1.0.0 150 9/6/2026