Version: Next

Understanding Failures

When a rule fails, you usually want two answers. Which part of a combined rule failed? And what exactly was wrong? Explain trees answer the first question. Rich results answer the second.

Explain trees

Call Explain to see why a combined rule passed or failed. It runs the rule once and returns a tree with one node for each rule it visited. Use it in logs, support tools and tests.

// context and the three KYC rules come from your application
GroupBusinessRule kyc = RuleGroup.All(
        "KYC.INCOMPLETE",
        "All KYC checks must pass",
        identityVerified,
        addressVerified,
        sanctionsCleared)
    .WithShortCircuit();

RuleExplanation explanation = kyc.Explain(context);
Console.WriteLine(explanation.ToText());

The output looks like this (durations vary):

[BROKEN] ALL  KYC.INCOMPLETE  "All KYC checks must pass"  (0.9 ms)
 ├─ [PASSED]  KYC.ID  (0.1 ms)
 ├─ [BROKEN]  KYC.ADDRESS  "Address must be verified"  (0.2 ms)
 └─ [NOT EVALUATED]  KYC.SANCTIONS  reason: short-circuit

Each line reads [OUTCOME] OPERATOR CODE "message" (duration) reason: .... The message appears only on broken nodes. The duration appears only on nodes that actually ran.

Both sync and async rules can be explained:

Call	Notes
`rule.Explain(context, captureExceptions)`	Both parameters are optional. The context defaults to `null`.
`await asyncRule.ExplainAsync(context, cancellationToken)`	The context is required. A `null` context throws `ArgumentNullException`.
`await asyncRule.ExplainAsync(context, captureExceptions, cancellationToken)`	Same, with exception capture.

Each node has an Outcome:

Outcome	Meaning	Counts as broken
`Passed`	The rule ran and passed.	No
`Broken`	The rule ran and is broken.	Yes
`Skipped`	A wrapper did not run the rule: a `.When(...)` precondition was false, or a feature gate was closed.	No
`CacheHit`	A cached rule returned its stored verdict without running.	The cached verdict
`NotEvaluated`	The rule was skipped by a short-circuit, or a custom wrapper never ran it.	No
`Faulted`	The rule threw, and you passed `captureExceptions: true`.	Yes

A node also gives you:

Code, Message and Severity of the rule.
IsBroken: whether the node counted as broken for its parent.
Operator: the label of a combined or wrapped node, such as AND, OR, NOT, ALL, ANY, AT LEAST 2, EXACTLY 1, CACHED, WHEN, SEVERITY, GATED, SHADOW or ADAPTER. It is empty for a plain rule.
Reason: why the outcome happened, such as short-circuit, precondition not met or cache hit.
Duration, Fault (the captured exception) and Children.
BrokenLeaves(): the deepest broken nodes, which are usually the rules you need to report.

// explanation is from the example above
foreach (RuleExplanation failure in explanation.BrokenLeaves())
{
    Console.WriteLine($"{failure.Code}: {failure.Message}"); // KYC.ADDRESS: Address must be verified
}

Your own rule classes, and any rule that is not a combination or a library wrapper, appear as a single node.

note

Explain is a real evaluation, not a dry run. Each rule runs exactly once, and wrappers behave as they do in Check. For example, a cached rule can serve or store its verdict.

Capturing exceptions. By default, an exception thrown by a rule propagates out of Explain. Pass captureExceptions: true to record it in the tree instead:

// kyc and context are from the first example in this section
RuleExplanation explanation = kyc.Explain(context, captureExceptions: true);

The throwing rule becomes a Faulted node. Its Fault holds the exception, and its Reason reads ExceptionType: message.
A faulted node counts as broken for its parent, and the rest of the tree is still evaluated.
Cancellation (OperationCanceledException) is never captured. It always propagates.
A cached rule never stores a verdict that rests on a captured exception.

Advanced

A wrapper you write yourself shows up as a single node. To show it as its own node with the inner rule's subtree below it, implement IExplainableDecoratedBusinessRule (async: IExplainableDecoratedAsyncBusinessRule). Give it an ExplanationOperator label and implement EvaluateDecorated(evaluation), calling evaluation.EvaluateInner() to run the inner rule.

Rich results

A message such as "Transaction limit exceeded" says that something failed, not what. A rich result also says which value broke the rule, what was expected and how to fix it.

public sealed class TransactionLimitRule : BaseBusinessRule
{
    private readonly decimal _amount;
    private readonly decimal _limit;

    public TransactionLimitRule(decimal amount, decimal limit)
    {
        _amount = amount;
        _limit = limit;
    }

    public override string Code => "LIMIT.EXCEEDED";

    public override string Message => "Transaction limit exceeded.";

    public override string Category => "Payments";

    public override IReadOnlyList<string> Tags => new[] { "customer-facing" };

    public override bool IsBroken() => _amount > _limit;

    // Runs only when the rule is broken
    protected override RuleResultDetails Describe(BusinessRuleContext? context) => RuleResultDetails
        .Detail($"Amount {_amount:N2} exceeds the limit of {_limit:N2}.")
        .Actual(_amount)
        .Expected($"<= {_limit}")
        .Remediation("Reduce the amount or request a limit increase.")
        .With("currency", "USD");
}

Every BusinessRuleResult carries these members:

Member	Content
`Code`, `Message`, `Severity`	The rule's metadata.
`Name`, `Category`, `Tags`	The rule's metadata, so you can filter results without looking the rule up again.
`Detail`	A formatted sentence about this violation, or `null`.
`Actual`, `Expected`	The value that broke the rule and the expected value or range, or `null`.
`Remediation`	A hint on how to fix the violation, or `null`.
`Data`	Extra key/value pairs. Empty by default.
`Details`	The broken members of a combined rule. Empty for a plain rule.

Describing a violation. Override Describe(context) on BaseBusinessRule or BaseAsyncBusinessRule to fill in the details. Subject-typed rules override Describe(subject, context).

Start with RuleResultDetails.Detail($"...") or RuleResultDetails.Empty. Then chain .Actual(...), .Expected(...), .Remediation(...) and .With(key, value). Each call returns a new object.
The library calls Describe only when the rule is broken. It passes the same context the rule was evaluated with.
If Describe throws, the result is still reported, just without details. A bug in Describe never hides the violation. Cancellation still propagates.
Detail is an interpolated string. It is formatted with context.FormatProvider when you set one, and with the invariant culture otherwise. Message is a plain string and is never formatted.
Actual and Expected are stored as you pass them (object?).
Wrappers keep the details. .Cached(...) and .When(...) return the inner rule's result, and .WithSeverity(...) changes only the severity.

note

On a sync rule, Evaluate() and Evaluate(context) build the result, including Describe, without checking whether the rule is broken. Call them only after IsBroken returned true (see Three ways to run a rule).

To format the detail sentence for the caller's culture, set the provider on the context:

BusinessRuleContext context = new BusinessRuleContext();
context.FormatProvider = CultureInfo.GetCultureInfo("de-DE");

IBusinessRule limit = new TransactionLimitRule(5200m, 5000m);
BusinessRuleResult result = limit.Evaluate(context);
// result.Detail: "Amount 5.200,00 exceeds the limit of 5.000,00."

Details with the builder. Builder rules get the same details from WithDetail, WithActual, WithExpected and WithRemediation. Each one takes a function of the context. WithExpected and WithRemediation also accept a fixed value.

IBusinessRule limit = BusinessRuleBuilder.Create("LIMIT.EXCEEDED")
    .WithMessage("Transaction limit exceeded.")
    .WithCategory("Payments")
    .WithTags("customer-facing")
    .When(ctx => ctx.Get<decimal>("amount") > ctx.Get<decimal>("limit"))
    .WithDetail(ctx => $"Amount {ctx.Get<decimal>("amount"):N2} exceeds the limit of {ctx.Get<decimal>("limit"):N2}.")
    .WithActual(ctx => ctx.Get<decimal>("amount"))
    .WithExpected(ctx => $"<= {ctx.Get<decimal>("limit")}")
    .WithRemediation("Split the transaction.")
    .Build();

The functions run only when the rule is broken. If one throws, the result is reported without details.
When the rule runs without a context, the functions receive an empty context.
The builder has no equivalent of .With(key, value). To fill Data, write a rule class with Describe.

Filtering results. The exception and the evaluation results let you pick out results by category or tag:

// rules (a List<IBusinessRule>) and context come from your application
try
{
    BusinessRuleChecker.CheckAll(rules, context: context);
}
catch (BusinessRuleValidationException exception)
{
    IEnumerable<BusinessRuleResult> paymentErrors = exception.ByCategory("Payments");
    IEnumerable<BusinessRuleResult> customerFacing = exception.ByTag("customer-facing");
}

ByCategory(category) matches exactly and is case-sensitive.
ByTag(tag) ignores case.
Both exist on BusinessRuleValidationException, on the EvaluateAll result and on the EvaluateAllAsync result.
result.HasTag(tag) checks a single result and also ignores case.

note

The filters look only at the top-level results. Groups and other combined rules have no category or tags, so a broken rule inside a group is not matched. Filter the flattened results instead: exception.Flatten().Where(result => result.HasTag("customer-facing")).

Returning Problem Details. A result holds everything an RFC 7807 Problem Details response needs. This ASP.NET Core helper turns the exception into a 422 response body:

private static ProblemDetails ToProblemDetails(BusinessRuleValidationException exception)
{
    ProblemDetails problem = new ProblemDetails
    {
        Title = "One or more business rules were violated.",
        Status = StatusCodes.Status422UnprocessableEntity,
    };

    problem.Extensions["errors"] = exception.Flatten()
        .Select(result => new
        {
            code = result.Code,
            category = result.Category,
            message = result.Message,
            detail = result.Detail,           // "Amount 5,200.00 exceeds the limit of 5,000.00."
            actual = result.Actual,           // 5200
            expected = result.Expected,       // "<= 5000"
            remediation = result.Remediation,
            data = result.Data,
        })
        .ToList();

    return problem;
}

In a controller, catch the exception and return UnprocessableEntity(ToProblemDetails(exception)). Flatten() makes sure that each broken rule inside a group gets its own entry.

Explain trees​

Rich results​

Explain trees

Rich results