Nextended.ResponseFilters 10.1.17

Nextended.ResponseFilters

Fluent, attribute-aware response-filtering pipeline for redacting, masking, or transforming object graphs before serialization.

A ResponseFilter<T> looks like a FluentValidator<T> — but instead of validating, it mutates the DTO right before it leaves your service: null out fields the user must not see, mask emails, replace internal flags, drop collection items conditionally.

Installation

dotnet add package Nextended.ResponseFilters
# ASP.NET Core integration:
dotnet add package Nextended.ResponseFilters.AspNetCore

Quick Start

public class OrderResponseFilter : ResponseFilter<OrderDto>
{
    public OrderResponseFilter()
    {
        // Null out cost fields unless the user has the "Finance" role
        Nullify(x => x.TotalCost, x => x.UnitCost)
            .Unless(WhenInstance(_ => HasRole("Finance")));

        // Mask credit card: 1234########5678
        Mask(x => x.CreditCard).KeepFirst(4).KeepLast(4).When((_, ctx) => !ctx.IsAdmin());

        // Pattern-replace email for unauthenticated callers
        Mask(x => x.CustomerEmail).WithPattern("***@***.***")
            .When((_, ctx) => !ctx.Services.GetRequiredService<ICurrentUser>().IsAuthenticated);

        // Truncate notes after 200 chars with ellipsis
        Truncate(x => x.Notes).After(200, "…").Always();

        // Reset multiple heterogeneous fields to their default values
        SetToDefault(x => x.InternalScore, x => x.IsBookmarked, x => x.HiddenTags)
            .When(NotInRole("Internal"));

        // Hash a token (default: SHA-256 hex)
        Hash(x => x.AuditToken).Always();

        // Round prices for non-premium users
        Round(x => x.Price).To(0).When(NotInRole("Premium"));

        // Clear an internal-only collection
        Clear(x => x.DebugTrace).When(NotInRole("Internal"));

        // Strip hidden line items, then cap at 10
        RemoveItems<LineDto>(x => x.Lines)
            .Where(l => l.Hidden)
            .Always();
        Take<LineDto>(x => x.Lines).First(10).When(NotInRole("Premium"));

        // Recurse into a collection — each line item gets its own sub-filter
        ForEach(x => x.Lines, line =>
        {
            line.Nullify(l => l.UnitCost).Unless(_ => HasRole("Finance"));
            line.Truncate(l => l.Description).After(80).Always();
        });

        // Escape hatch for cross-property logic
        Apply((order, _) =>
        {
            if (order.Status == "Cancelled") order.PaymentDetails = null;
        }).Always();
    }

    private static bool HasRole(string role) => /* check current principal */ false;
    private static SyncPredicate<OrderDto> NotInRole(string role) => (_, _) => !HasRole(role);
}

Then wire it up:

// Program.cs / Startup.cs
services.AddResponseFilters(new[] { typeof(OrderResponseFilter).Assembly });

// Manually run it (e.g. in a worker service)
var pipeline = sp.GetRequiredService<IResponseFilterPipeline>();
await pipeline.ProcessAsync(myOrderDto, new ResponseFilterContext(sp));

For ASP.NET Core: see Nextended.ResponseFilters.AspNetCore — one extension call and every controller response is filtered automatically.

Concepts

Rule builders

Property mutators

String operations

Numeric operations

Collection operations

Structural operations (key-level)

A POCO can't drop a property or rename its JSON key at runtime, so these builders don't mutate the instance — they record an edit that is replayed against the serialized JSON tree. In ASP.NET Core this happens automatically (the result filter swaps in the transformed JsonNode); when you run the pipeline yourself, apply the edits with JsonStructuralTransformer.Transform(dto, ctx.StructuralEdits, jsonOptions).

The key transform receives the serialized key (after any JsonNamingPolicy / [JsonPropertyName]), and edits resolve against the CLR member, so they keep working under any naming policy. Structural edits inside ForEach sub-filters are applied per element. (Limitation: values reached only through dictionary entries are not descended into for nested structural edits.)

Metadata-aware property selection

Two complementary ways to target properties by their PropertyInfo (e.g. an attribute) instead of, or in addition to, naming them explicitly. Property metadata is static, so both are resolved at build time — zero runtime cost.

.WhenProperty(p => …) — a cross-cutting refinement available on every property-targeting builder. It restricts the rule to the already-selected properties whose PropertyInfo matches, and composes with When/Unless (and can be chained, logical AND):

// Only null the listed properties that carry [Secret]
Nullify(x => x.A, x => x.B, x => x.C)
    .WhenProperty(p => p.GetCustomAttribute<SecretAttribute>() != null)
    .When(NotInRole("Admin"));

Remove(x => x.Token).WhenProperty(p => p.PropertyType == typeof(string));

Properties(...) / PropertiesWhere(...) — a transposed entry point: select the property set first, then pick a type-agnostic operation (.Nullify(), .Remove(), .SetToDefault(), .TransformKey()). PropertiesWhere scans the type and selects by metadata, so you don't have to enumerate the properties:

// Remove every [Secret] property from the response
PropertiesWhere(p => p.GetCustomAttribute<SecretAttribute>() != null).Remove().Always();

// Null a named set
Properties(x => x.Name, x => x.Id).Nullify().When(...);

This avoids a combinatorial NullifyWhere/RemoveWhere/… explosion: one WhenProperty works for all operations, and PropertiesWhere exposes the type-agnostic operations from a single builder. (WhenProperty has no effect on Apply, which targets no property.)

Escape hatch

Predicate vocabulary

All builders end with the same terminal vocabulary. Each terminal accepts predicates in every shape (no-arg, context-only, instance-only, or both), in both sync and async (Task) variants. Pick the overload that reads best at the call site — the library adapts it to the canonical AsyncPredicate<T> internally.

.WhenProperty(Func<PropertyInfo,bool>) is a refinement (not a terminal): it narrows the rule to the target properties matching a metadata predicate at build time, then you still close with one of the terminals above. See Metadata-aware property selection.

Supported predicate shapes (each on When and Unless)

Extending the vocabulary

Every builder implements IRuleBuilder<T>, so consumer projects can plug in their own domain-specific terminals as ordinary extension methods — without having to wire them per builder type:

public static class PermissionRuleBuilderExtensions
{
    public static ResponseFilter<T> WhenMissingPermission<T>(this IRuleBuilder<T> b, string policy)
        where T : class
        => b.When(async (_, ctx) =>
        {
            var checker = ctx.Services.GetRequiredService<IPermissionChecker>();
            return !await checker.IsGrantedAsync(policy).ConfigureAwait(false);
        });
}

Then at the call site:

Nullify(x => x.TotalCost).WhenMissingPermission("Insights.ViewFinancial");

Why use this over attributes?

If your needs are simple (always-null-on-missing-permission), attributes are fine. Use this package when you need real conditional logic, transformation, or testability.

Performance

• PropertyAccessor uses compiled Expression-Tree get/set delegates (cached per PropertyInfo) — typically 10-50× faster than PropertyInfo.SetValue.
• TypeGraphInspector caches per-type metadata so the graph walker never reflects twice on the same type.
• TypeReachabilityCache precomputes per response root type whether any registered filter's target is reachable in the graph. When the answer is no, the pipeline is a one-cache-lookup no-op for that response — no reflection, no walk, no allocation.
• The walker also short-circuits per branch: if a nested property's static type can't reach a filtered type, that subtree is skipped entirely.
• Cycle detection via ReferenceEqualityComparer prevents infinite recursion on back-references.

Configuration

AddResponseFilters / AddNextendedResponseFilters accept an optional Action<ResponseFilterOptions>:

builder.Services.AddNextendedResponseFilters(
    assemblies: new[] { typeof(OrderResponseFilter).Assembly },
    configure: opts =>
    {
        // Default: propagate exceptions thrown by filter rules to the host's exception handler.
        // Switch to LogAndContinue if you'd rather absorb filter bugs at the cost of visibility.
        opts.ExceptionBehavior = FilterExceptionBehavior.Rethrow;

        // Default: skip the entire pipeline if no registered filter's target type is reachable
        // in the response's type graph. Turn off only if you have run-time polymorphism that
        // the static analyzer can't see (e.g. List<object> holding heterogeneous DTOs).
        opts.SkipUnaffectedResponses = true;

        // Custom opt-out predicate evaluated against the response root type.
        opts.SkipResponseType = t => typeof(System.IO.Stream).IsAssignableFrom(t)
                                  || t.Namespace?.StartsWith("Volo.Abp") == true;
    });

Exception handling

By default, exceptions thrown inside a filter rule propagate — they reach the host's global exception handler unchanged. This is the right behaviour for almost every app: a filter throwing a BusinessException or UserFriendlyException is intentional and must be visible.

If you'd rather absorb filter failures (e.g. for a public CMS that must never 500), switch to FilterExceptionBehavior.LogAndContinue — exceptions are caught, logged via ILogger<ResponseFilterPipeline>, and remaining filters keep running.

OperationCanceledException always propagates regardless of the chosen behaviour, so request aborts and host shutdown work correctly.

Supported Frameworks

• .NET 8.0, .NET 9.0, .NET 10.0

License

GPL-3.0-or-later (same as the rest of the Nextended ecosystem).