HangFire未记录含元数据的自定义异常问题排查

针对你在ASP.NET Core 2.1 + HangFire 1.6.17环境下遇到的自定义异常元数据不被记录的问题，我整理了几个实用的排查和解决方向：

1. 确保自定义异常支持序列化 #

HangFire在存储和记录异常时依赖.NET的序列化机制，如果你的自定义异常没有正确实现序列化逻辑，元数据很可能会丢失。

• 给自定义异常类加上[Serializable]特性
• 必须实现序列化构造函数（这是.NET序列化要求的）
• 重写GetObjectData方法，把你的元数据属性加入序列化信息中

示例代码：

[Serializable]
public class CustomApiException : Exception
{
    public HttpStatusCode StatusCode { get; }
    public string ErrorContent { get; }

    public CustomApiException(string message, HttpStatusCode statusCode, string errorContent)
        : base(message)
    {
        StatusCode = statusCode;
        ErrorContent = errorContent;
    }

    // 序列化构造函数，必须是protected或private
    protected CustomApiException(SerializationInfo info, StreamingContext context)
        : base(info, context)
    {
        StatusCode = (HttpStatusCode)info.GetValue(nameof(StatusCode), typeof(HttpStatusCode));
        ErrorContent = info.GetString(nameof(ErrorContent));
    }

    // 重写此方法以序列化自定义属性
    public override void GetObjectData(SerializationInfo info, StreamingContext context)
    {
        base.GetObjectData(info, context);
        info.AddValue(nameof(StatusCode), StatusCode);
        info.AddValue(nameof(ErrorContent), ErrorContent);
    }
}

2. 检查HangFire的日志与过滤器配置 #

如果你的HangFire配置了自定义作业过滤器或者日志提供程序，可能会拦截或丢失异常元数据：

• 检查是否添加了自定义IJobFilter，比如异常处理过滤器，确保它没有吞掉异常的自定义属性，而是完整传递给HangFire的日志系统
• 如果你用了第三方日志库（比如Serilog、NLog），需要配置异常解构规则，让日志库能识别并记录自定义异常的元数据。比如Serilog中可以这样配置：

Log.Logger = new LoggerConfiguration()
    .Destructure.ByTransforming<CustomApiException>(ex => new {
        ex.Message,
        ex.StatusCode,
        ex.ErrorContent
    })
    // 其他配置...
    .CreateLogger();

3. 验证异常抛出逻辑的正确性 #

先排除是你的HttpResponseMessage扩展方法没有正确抛出带元数据的异常：

• 手动调用你的扩展方法，模拟API请求失败的场景，检查抛出的CustomApiException是否确实包含预期的元数据
• 确保扩展方法没有把自定义异常包装在其他异常里（比如AggregateException），否则HangFire可能只会记录外层异常，丢失内层自定义异常的元数据

示例扩展方法：

public static async Task EnsureSuccessWithMetadataAsync(this HttpResponseMessage response)
{
    if (!response.IsSuccessStatusCode)
    {
        var errorContent = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
        // 直接抛出自定义异常，不要包装
        throw new CustomApiException(
            $"API请求失败，状态码: {response.StatusCode}",
            response.StatusCode,
            errorContent);
    }
}

4. 考虑HangFire 1.6.x版本的局限性 #

HangFire 1.6.17是比较旧的版本，可能存在一些序列化相关的bug：

• 尝试升级到HangFire 1.6系列的最新稳定版（比如1.6.31），这个版本修复了不少序列化相关的问题
• 如果暂时无法升级，可以重写自定义异常的ToString()方法，把元数据直接包含在异常字符串中，这样即使序列化有问题，HangFire记录的异常信息也能看到元数据：

public override string ToString()
{
    return $"{base.ToString()}\n状态码: {StatusCode}\n错误内容: {ErrorContent}";
}

按照这个顺序排查，应该能解决HangFire不记录自定义异常元数据的问题。

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