agilelabs-fx-docs main topics/utility/extension-methods.md

扩展方法支持

本页汇总框架里可直接复用的扩展方法入口，覆盖基础库 agilelabs 与 ASP.NET 集成层 agilelabs.aspnet。重点不是罗列全部文件，而是把最常用的扩展能力按场景归类。

基础类型与通用扩展

源码主要位于 agilelabs/AgileLabs/：

  • EnumerableExtensions
    • IsNullOrEmpty()：判断枚举是否为空。
    • EnsureHaveElements()：为空时抛异常。
    • ForEach()：遍历执行动作。
    • JoinStrings()：拼接字符串并去除空值。
  • EnumExtensions
    • GetDescription()：读取枚举上的 DescriptionAttribute。
  • TypeExtensions
    • GetUnNullableType()：把 Nullable<T> 还原成真实类型。
  • StringCaseExtensions
    • ToCamelCase()、ToPascalCase()、ToSnakeCase()
    • ConvertToCase()：统一大小写风格转换。
  • ActivityExtensions
    • GetTraceId()、GetSpanId()、GetParentId()：从 Activity 中提取链路标识。
  • StatusCodeExtensions
    • GetSuggestionHint()、GetCodeDescription()：读取状态码描述元数据。

Stream、对象与响应写入扩展

同样位于 agilelabs/AgileLabs/：

  • ObjectExtensions.CreateStreamFromObject()
    • 把对象序列化为 JSON 并写入 MemoryStream。
  • ObjectExtensions.SafeSeekToBegin()
    • 重置流位置到开头，适合重复读取。
  • ResponseExtensions.WriteContent(...)
    • 支持把字符串、JObject、普通对象写回流，并在写完后自动归位。

这组能力与 JSON converter 经常配合使用，特别适合测试、模拟响应和中间层数据搬运。

ASP.NET 请求与上下文扩展

源码主要位于 agilelabs.aspnet/src/AgileLabs.WebApp/：

  • HttpContextExtensions
    • IsAjaxRequest()、IsApiRequest()、IsStaticResource()：识别请求类型。
    • GetHeaderValueAs<T>()、GetQueryValueAs<T>()、GetCookieValueAs<T>()：按类型读取请求值。
    • GetClaimValueAs<T>()、GetClaimValueList()：读取 Claim。
    • ReadBodyAsync()：安全读取请求体。
    • SafeAdd()：字典覆盖式写入。
  • AppContextExtensions
    • AttachWorkContextForCurrentScope()：在当前作用域初始化 WorkContext。
    • GetCurrentWorkContext()、GetRequiredWorkContext()：获取当前上下文。
    • CreateScopeWithWorkContext()：从根容器拉起新的 WorkContext 作用域。

WorkContext 与依赖解析扩展

这部分是 agilelabs.aspnet 里非常核心的一组工具：

  • WorkContextScopeCreateExtensions
    • CreateScopeWithWorkContext()：在当前上下文或服务容器上创建新的 WorkContext Scope。
    • CreateScopeWithWorkContextForNewTask()：专门给 Task.Run、新线程使用，强制隔离父线程上下文。
    • InitWorkContextOnCurrentScope()：在当前 Scope 上显式附着 WorkContext。
  • WorkContextCoreResolveExtensions
    • Resolve<T>()、Resolve(Type)：从当前 WorkContext 解析服务。
    • ResolveOpentional(...)：可空解析。
    • ResolveByName()、ResolveByKey()：基于 Autofac 的命名或键值解析。
    • ResolveAll<T>()：解析同类型全部实现。
  • WorkContextScopeResolveExtensions
    • 对 IWorkContextScope 提供与上面一致的解析体验。
  • AdvancedServiceProviderExtensions
    • 在 IServiceProvider 上补充 ResolveByName()、ResolveByKey()、GetAdvancedServiceProvider() 等高级能力。

这组扩展适合框架层和基础设施代码，业务层如果只是在请求内取依赖，仍应优先使用常规 DI。

缓存、映射与查询扩展

来自 agilelabs.aspnet 的高频工具还包括：

  • DistributedCacheExtensions
    • GetObject<T>()、SetObject<T>()
    • GetOrCreateObjectAsync()：缓存不存在时自动执行回调并回写缓存。
  • AutoMapperCreateMapExtensions
    • 支持一次声明 TSource 到多个目标类型的双向映射。
  • QueryableSafeConvertExtensions
    • SafeCountAsync()、SafeToListAsync()：在异步和非异步 IQueryable 间安全兜底。
  • QueryableExtensions
    • 动态 Where(...)、字符串排序 OrderBy(...) / ThenBy(...)、分页 GetByPage(...)。
  • PaginationExtensions
    • 对 IQueryable<T> 和 List<T> 补充分页包装。
  • AgileLabs.EfCore.PostgreSQL/StringExtensions.FormatToTableName()
    • 把实体名转成下划线表名，并移除 Entity 后缀。

推荐查找顺序

  • 想找基础类型便捷方法：先看 agilelabs/AgileLabs/*Extensions.cs。
  • 想找请求、上下文、DI 相关扩展：先看 agilelabs.aspnet/src/AgileLabs.WebApp/。
  • 想找 EF Core 查询、分页、命名辅助：看 agilelabs.aspnet/src/AgileLabs.EfCore.PostgreSQL/。

使用时要注意

  • 部分扩展明显偏基础设施层，比如 ResolveByName()、CreateScopeWithWorkContextForNewTask()，不建议在普通业务代码里滥用。
  • 某些类是 internal 或为框架内部辅助实现准备，文档里可以认知，但不代表鼓励直接依赖。
  • 当前工作区里对应的 ASP.NET 集成仓库是 agilelabs.aspnet；本页按真实扫描结果维护，不臆造不存在的项目实现。

相关页面