跳到正文

Fast.Runtime ​

逐成员 API、参数与返回参考

参考源码版本 3.5.37;目标 net8.0、net9.0、net10.0。提供模块扫描、配置绑定、请求扩展、验证特性和共享运行上下文。其他 Web 模块通常传递引用此包;它不是应用启动器。

bash
dotnet add package Fast.Runtime

配置与 MVC 入口 ​

命名空间为 Fast.Runtime。以下扩展返回原 IServiceCollection,用于继续注册。

公开入口参数、返回与行为
AddConfigurableOptions<TOptions>(string path = null)TOptions : class, new();未给 path 时由 MAppContext.GetOptionName<TOptions>() 推导;绑定配置、允许非公开属性绑定并启用 DataAnnotations 验证
IPostConfigure.PostConfigure()选项类型实现该接口后,绑定阶段追加后配置调用;默认值由各选项自己的实现提供
AddMvcFilter<TFilter>(Action<MvcOptions> configure = null)TFilter : IFilterMetadata;将过滤器加入 MVC 选项,随后执行配置回调
AddMvcFilter(IFilterMetadata filter, Action<MvcOptions> configure = null)注册指定过滤器实例

以下为消费端 Program.cs,使用 Microsoft.NET.Sdk.Web,目标选择本页列出的 .NET 8、9 或 10,并安装上方指定包。app.Run() 表示正常宿主启动;本次文档维护不会执行它。

csharp
using Fast.Runtime;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddConfigurableOptions<FeatureOptions>("Feature");

var app = builder.Build();
app.MapGet("/feature", (Microsoft.Extensions.Options.IOptions<FeatureOptions> options) => options.Value.BatchSize);
app.Run();

public sealed class FeatureOptions : IPostConfigure
{
    public int? BatchSize { get; set; }
    public void PostConfigure() => BatchSize ??= 50;
}

配置节点由宿主的 appsettings.json、环境变量或其它配置提供器提供。选项验证异常与后配置异常不会被本扩展转为成功结果。

运行上下文与公开辅助类型 ​

API / 类型使用边界
MAppContext.Assemblies、ProjectAssemblies、Types、EffectiveTypes、ProjectEffectiveTypes框架扫描集合;动态 API、约定式 DI 等按这些集合发现类型,并非扫描磁盘上任意程序集
SuppressSnifferAttribute标记不参与框架类型嗅探的类型
MAppContext.ConsoleWrite(Action<ConsoleWriter>)同步执行回调;串行保护控制台输出,在 finally 恢复进入时颜色;输出重定向时不写颜色控制
ConsoleWriterForegroundColor、BackgroundColor、Write、WriteLine、ResetColor();回调异常继续传播,不在回调中启动未等待任务
MAppContext.GetExecutionTime(Action)执行操作并取得耗时,不是取消或超时机制
GetServiceProvider、GetTraceId、GetCurrentStartupUri接收服务提供器、请求或服务器对象;后台作业不能假设 HTTP 请求存在
UserFriendlyException 及扩展携带可由上层异常处理模块识别的业务异常信息;Runtime 自身不保证 HTTP 响应包装
ApiInfoAttribute、MapHubAttribute、FastEnumAttributeAPI 描述、Hub 路由和枚举元信息
StringRequiredAttribute、数值/日期/枚举 Required 特性DataAnnotations 验证入口;不同类型分别验证,不等同于通用空值判断
LinqExpression、表达式与集合扩展构建/组合表达式;能否被 ORM 翻译取决于实际查询提供器

请求扩展的 LocalIpv4/LocalIpv6 使用服务器连接端地址;RemoteIpv4/RemoteIpv6 使用 Connection.RemoteIpAddress。缺少请求上下文应按各方法空值合同处理,不把结果作为必有值。旧的 LanIpv4/LanIpv6 已不在当前 API 中。

来源与验证 ​

依据源版本的 配置注册实现、MAppContext。本页为源码静态核对,新增片段本轮未编译、未运行;完整重载与 XML 参数合同以该版本源码为准。

后台作用域与防重放接口 ​

没有 HTTP 请求时,框架不再创建隐藏 Scoped 作用域,也不会由无关请求结束时统一释放后台服务。后台任务应显式持有 CreateScope() / CreateAsyncScope(),在该任务结束时释放,并把作用域 provider 传给需要解析服务的调用。

根 provider 只用于已注册的 Singleton。作用域对象不能从 helper 中“借出”后失去所有者。显式登记的 UnmanagedObjects 属于应用生命周期,由宿主停止时清理,不是逐请求垃圾回收机制。

IRefreshTokenReplayStore.TryConsumeAsync(string key, DateTimeOffset expiresAt, long reuseLeewaySeconds, CancellationToken cancellationToken = default) 返回是否获得刷新令牌消费权。输入 key 是用途前缀加摘要,expiresAt 为绝对过期时间;不应输入明文令牌。MemoryRefreshTokenReplayStore 仅支持进程内缓存,不能替代共享存储的原子操作。

IPv4 查询取消与升级兼容 ​

RemoteIpv4InfoAsync(this HttpContext httpContext, string ip = null, CancellationToken? cancellationToken = null) 可通过第三个参数控制取消。Fast.Runtime 3.5.33 优先返回 HttpContext.Items 中的请求内缓存结果,命中时不检查取消令牌,因此默认或显式令牌已经取消也可返回该缓存结果。未命中时才解析并检查令牌,再查询共享内存缓存、等待锁或发起远程请求;即使共享内存缓存命中,也仍需先通过取消检查。未提供令牌或传入 null 时使用 HttpContext.RequestAborted;显式令牌替代默认令牌,不会自动关联两者。上下文为 null 时仍直接返回 null。

自 Fast.Runtime 3.5.32 起,三参数方法替换了旧两参数声明。3.5.33 保留该公开签名,仅调整缓存与取消检查的先后顺序。普通直接调用可以在重新编译后继续省略新参数,但已有消费者程序集必须重新编译,不能仅替换 Runtime DLL。依赖旧签名的方法组委托、反射查找及动态调用也需核对。该兼容性变化按本次要求继续使用 3.5.x 补丁版本。

2026-10-17 批次仅按当时源码同步说明和版本,按要求未执行 Fast.NET 构建、打包或测试;此前批次的验证结果不代表该批次已验证。

3.5.37 移动端 H5 与数值迁移 ​

2026-11-02 将 Fast.Runtime 从 3.5.36 递增至 3.5.37,新增 H5 = 1L << 4(16),用于移动端 H5 页面,与 Web 平台标识区分。Android 及其后的全部独立位依次左移一位,25 个成员连续占用 bit 0~24,互不重叠。枚举仍使用 long 与 [Flags],四个旧组合成员仍不提供。Runtime 及其 13 个引用包各递增一个补丁版本,见本批次版本表。

这是数字合同的破坏性变更,本次按要求沿用 3.5.x 补丁版本。Web=1、Windows=2、Mac=4、Linux=8 保持不变;其余映射以 3.5.36 为基线:

成员3.5.363.5.37新位值
H5新增161L << 4
Android16321L << 5
HarmonyOS32641L << 6
IOS641281L << 7
QuickApp1282561L << 8
WeChatMiniProgram2565121L << 9
WeChatOfficialAccount51210241L << 10
WeChatServiceAccount102420481L << 11
WeChatOpenPlatform204840961L << 12
WorkWeChat409681921L << 13
AlipayMiniProgram8192163841L << 14
TiktokMiniProgram16384327681L << 15
DingTalkMiniProgram32768655361L << 16
FeiShuMiniProgram655361310721L << 17
QQMiniProgram1310722621441L << 18
BaiduMiniProgram2621445242881L << 19
KuaiShouMiniProgram52428810485761L << 20
XiaoHongShuMiniProgram104857620971521L << 21
JDMiniProgram209715241943041L << 22
Api419430483886081L << 23
Other8388608167772161L << 24

数据库、缓存、配置和数字协议中的旧值须按旧版本的成员含义逐位迁移并重新组合,不能整体乘二:Web~Linux 未变,Android 及后续位才左移。旧 Android=16 在新版本中代表 H5;混合掩码 Web | Android | Api 从 4194321 迁移为 8388641。升级更早版本时,先按对应历史记录确定原含义。

旧掩码迁移不会自动纳入新增 H5。以下调用方代码显式区分原生移动端与包含 H5 的范围:

csharp
using System;

const AppEnvironmentEnum nativeMobile =
    AppEnvironmentEnum.Android | AppEnvironmentEnum.HarmonyOS | AppEnvironmentEnum.IOS;
const AppEnvironmentEnum mobileWithH5 = nativeMobile | AppEnvironmentEnum.H5;

Console.WriteLine(mobileWithH5.HasFlag(AppEnvironmentEnum.H5));

原生移动端掩码从 112 变为 224;明确包含 H5 时使用 240。旧小程序范围从 4186496 变为 8372992,原生移动端与小程序组合从 4186608 变为 8373216;Desktop 的原范围仍为 14。这些是调用方掩码示例,不会恢复已移除的四个 SDK 组合成员。

同步前端枚举并重新编译消费端;常量可能内嵌在调用方,只替换 DLL 不会更新既有数字值。字符串名称虽然仍可表达原成员,但数字值、掩码及生成的枚举映射必须同步更新。2026-11-02 验证通过:全解决方案最终还原、Release 构建和本地打包零警告、零错误;获准联网重试已消除最初的 NU1900 网络警告。14 个受影响包的 84 个 DLL/XML 文件、42 个程序集版本和 45 条内部依赖核验通过,三个目标的 XML 均包含 H5 说明及 Web 引用。中英文示例一致且三目标编译通过,打包程序集在 .NET 8/9/10 上各通过 290 项数值、唯一性、平台范围、JSON 往返和混合掩码断言;42 行中英文数值映射与新旧源码一致。Runtime 公开声明由 261 项增至 262 项。Fast.Docs 完整检查通过,含 34 项测试通过/1 项因缺少 Nginx 跳过、434 个页面的链接检查及格式检查。未执行数据库迁移、应用宿主或真实外部服务操作。

3.5.36 组合成员移除与迁移 ​

此节记录 3.5.36 的历史行为及数值;3.5.37 新增 H5 后的位移与当前掩码见上节。

2026-10-31 将 Fast.Runtime 从 3.5.35 递增至 3.5.36,移除 Desktop、Mobile、MiniProgram、MobileThree 四个组合枚举成员。枚举仍使用 long 和 [Flags],24 个独立成员的位值与 3.5.35 完全一致,继续连续占用 bit 0~23。本次按要求沿用补丁版本,但删除公开成员属于破坏性 API 变更;其余 13 个引用包同步升版,见本批次版本表。

引用已移除成员的源码需改为调用方自己维护的位或组合。以下示例保留原组合范围:

csharp
using System;

const AppEnvironmentEnum desktop =
    AppEnvironmentEnum.Windows | AppEnvironmentEnum.Mac | AppEnvironmentEnum.Linux;
const AppEnvironmentEnum mobile =
    AppEnvironmentEnum.Android | AppEnvironmentEnum.HarmonyOS | AppEnvironmentEnum.IOS;
const AppEnvironmentEnum miniProgram =
    AppEnvironmentEnum.QuickApp
    | AppEnvironmentEnum.WeChatMiniProgram
    | AppEnvironmentEnum.AlipayMiniProgram
    | AppEnvironmentEnum.TiktokMiniProgram
    | AppEnvironmentEnum.DingTalkMiniProgram
    | AppEnvironmentEnum.FeiShuMiniProgram
    | AppEnvironmentEnum.QQMiniProgram
    | AppEnvironmentEnum.BaiduMiniProgram
    | AppEnvironmentEnum.KuaiShouMiniProgram
    | AppEnvironmentEnum.XiaoHongShuMiniProgram
    | AppEnvironmentEnum.JDMiniProgram;
const AppEnvironmentEnum mobileThree = mobile | miniProgram;

Console.WriteLine(mobileThree.HasFlag(AppEnvironmentEnum.Android));
原成员调用方组合保留数值
DesktopWindows、Mac、Linux14
MobileAndroid、HarmonyOS、IOS112
MiniProgram上例中的 11 个快应用/小程序独立成员4186496
MobileThreemobile 与 miniProgram 按位或4186608

从 3.5.35 升级时,已经持久化的数字掩码不需要重新编号;从更早版本升级仍需遵循下方历史数值映射。不能因组合声明删除而清空有效数字值。

重新生成客户端枚举并替换四个旧成员的源码引用。常量可能内嵌在旧程序集,已有数字常量仍可能正常工作,但名称已不属于当前枚举声明。使用 Enum.Parse、枚举字符串序列化、ToString、反射、下拉列表或枚举名称协议的消费端需要单独核对:旧组合名称无法再作为声明名称解析,组合值显示可能改为独立成员列表。上述示例仅保留原组合语义,不扩展其平台范围。

2026-10-31 已核对公开声明从 265 项减少为 261 项,仅移除上述四个成员。全解决方案最终还原、Release 构建和本地打包通过,零警告、零错误;最初受网络限制产生的 NU1900 已在获准联网重试后消除。上方中英文迁移示例一致,已针对三个目标编译;打包程序集在 .NET 8/9/10 上各通过 182 项独立值、名称解析、组合范围和 JSON 字符串往返断言。Fast.Docs 完整检查通过,含 34 项测试通过/1 项因缺少 Nginx 跳过、434 个页面的链接检查及格式检查。未执行数据库迁移、应用宿主、真实外部服务或发布操作。

鸿蒙平台与枚举数值迁移 ​

System.AppEnvironmentEnum 采用 long 和 [Flags]。3.5.34 曾新增 HarmonyOS = 64,并将原 IOS 及其后的独立标志位左移一位;该版本的 Android 仍为 32,且存在空缺位。以下以 3.5.34 为迁移基线,不能直接用于更早版本的数据。

2026-10-30 将 Fast.Runtime 从 3.5.34 递增至 3.5.35,使全部 24 个独立标志位按声明顺序连续使用 bit 0~23:Android 从 1L << 4 开始,后续成员依次递增,包括 Api 和 Other。引用 Runtime 的其余 13 个包同步递增一个补丁版本,外部依赖版本不变;完整列表见依赖链版本表。本次按要求继续使用 3.5.x 补丁版本,但数值合同发生了破坏性变化。

Web=1、Windows=2、Mac=4、Linux=8 保持不变;其余独立成员的迁移关系如下:

成员3.5.343.5.35新位值
Android32161L << 4
HarmonyOS64321L << 5
IOS128641L << 6
QuickApp2561281L << 7
WeChatMiniProgram5122561L << 8
WeChatOfficialAccount10245121L << 9
WeChatServiceAccount204810241L << 10
WeChatOpenPlatform409620481L << 11
WorkWeChat819240961L << 12
AlipayMiniProgram1638481921L << 13
TiktokMiniProgram32768163841L << 14
DingTalkMiniProgram65536327681L << 15
FeiShuMiniProgram131072655361L << 16
QQMiniProgram2621441310721L << 17
BaiduMiniProgram5242882621441L << 18
KuaiShouMiniProgram10485765242881L << 19
XiaoHongShuMiniProgram209715210485761L << 20
JDMiniProgram419430420971521L << 21
Api429496729641943041L << 22
Other858993459283886081L << 23

以下为 3.5.35 的历史组合声明及数值;3.5.36 已移除这些声明,但调用方仍可使用相同位或掩码:

组合成员3.5.343.5.35
Desktop1414
Mobile224112
MiniProgram83729924186496
MobileThree83732164186608

迁移数据库、缓存、配置和数字协议时,必须先确认数据使用的旧版本,再按旧成员含义逐位映射并重新组合。不能整体右移掩码:Web~Linux 未变,Api/Other 的位移跨度也不同;例如 3.5.34 的 Android=32 在新版本已代表鸿蒙。来自 3.5.33 的旧 Mobile=96 若保留 Android/IOS 范围,应迁移为 80;只有明确新增鸿蒙范围时才使用包含三平台的掩码 112;Mobile 名称已在 3.5.36 移除。

重新编译依赖程序集并重新生成前端枚举;枚举常量可能内嵌在调用方,不能只替换 Runtime DLL。本次只调整平台标识数值,不实现消费端的鸿蒙包上传、安装或热更新,也不执行数据库迁移。2026-10-30 已通过 net8.0、net9.0、net10.0 Release 构建和本地打包,零警告、零错误;核验了 3.5.35 包元数据及每个目标的 DLL/XML,打包程序集在三个运行时上各通过 131 项数值、组合成员和混合掩码断言。中英文 40 行迁移映射与旧版及当前源码一致。Fast.Docs 的 pnpm run check 通过,含类型检查、lint、34 项文档测试通过/1 项因缺少 Nginx 跳过、API 覆盖、站点构建、434 个 HTML 页面的链接/资源/锚点及格式检查。未执行应用宿主、真机或数据库操作,也未发布 NuGet 包。