ASP.NET Core Web API逻辑正常但响应时报流不支持超时异常

所有业务逻辑可正常执行、Cosmos数据读写正常的前提下，异常发生在控制器执行完成后的响应序列化阶段，完全不在业务代码的try-catch覆盖范围内，因此不会触发catch块逻辑。
从调用栈可明确定位触发链路：

1. 框架使用默认的System.Text.Json输出格式化器序列化接口返回值
2. 序列化器递归遍历返回对象的所有公共属性，尝试访问某个Stream类型属性的ReadTimeout getter
3. 该Stream对象（通常是请求附带的文件流、证书内部流）不支持超时设置，直接抛出System.InvalidOperationException: Timeouts are not supported on this stream

结合代码实现可以快速缩小定位范围：

• 接口用[FromForm]接收GlobalDesignTenant对象，这类表单绑定的模型通常会包含上传文件对应的IFormFile属性，这类属性底层是请求上下文的文件流，本身就不支持超时配置
• 你把绑定完成的模型直接传给Cosmos存储做新增、更新，即使清空了CertPfxFile、CertificatePassword两个敏感字段，也没有处理IFormFile类型的属性，最终返回的result对象依然持有流引用
• 如果实体里嵌入了前面代码中实例化的X509Certificate2对象，其内部封装的证书流同样会触发相同的序列化错误

• 临时将控制器中的return Ok(result)替换为return Ok(new { status = "success" });重新测试，若错误消失，即可确认是返回值序列化触发的问题，与业务逻辑无关
• 逐层检查GlobalDesignTenant实体的所有公共属性，定位类型为Stream、IFormFile、X509Certificate2的属性
• 对定位到的上述类型属性临时添加[JsonIgnore]标记，重新测试验证错误是否消失，即可锁定具体触发属性

• 对不需要序列化输出的Stream、IFormFile、X509Certificate2类型属性，直接添加[System.Text.Json.Serialization.JsonIgnore]特性，避免序列化器遍历访问
• 不要直接返回Cosmos存储返回的完整实体对象，手动定义响应DTO类，仅映射需要对外输出的字符串、数字、日期等纯值类型字段，不携带任何流、证书类引用
• 在实体存入Cosmos前，将临时绑定的IFormFile属性置为null，避免对象长期持有请求流造成资源泄漏
• 若使用第三方库生成的实体类无法直接修改，可在全局JSON序列化配置中注册Stream类型的忽略转换器，示例代码：

  builder.Services.AddControllers().AddJsonOptions(options =>
  {
      options.SerializerOptions.Converters.Add(new StreamJsonConverter());
  });
  
  // Stream类型的自定义忽略转换器
  public class StreamJsonConverter : System.Text.Json.Serialization.JsonConverter<Stream>
  {
      public override Stream Read(ref System.Text.Json.Utf8JsonReader reader, Type typeToConvert, System.Text.Json.JsonSerializerOptions options)
          => Stream.Null;
      public override void Write(System.Text.Json.Utf8JsonWriter writer, Stream value, System.Text.Json.JsonSerializerOptions options)
          => writer.WriteNullValue();
  }
  

注意：全局配置转换器后，所有Stream类型的属性都会被序列化为null，不会触发流属性的超时访问逻辑。

内容的提问来源于stack exchange，提问作者Luis Valencia