Nextended.ResponseFilters 10.1.34

Nextended.ResponseFilters

Fluent, provider-agnostic pipeline that redacts, masks, rounds, truncates, hashes, prunes and restructures response DTOs before serialization — per request, per user, per permission.

📖 Documentation: English · Deutsch

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

• net8.0
• net9.0
• net10.0

Dependencies

• Nextended.Core

The Nextended family

The other 17 packages in the suite:

Core libraries

• Nextended.Core — Foundation library — extension methods, custom types (Money, Date, BaseId, SuperType), class mapping, deep clone, encryption, hashing and the code-generation attributes.
• Nextended.Cache — Expression-based caching — automatic cache keys from method expressions, CacheProvider with condition-based invalidation, thread-safe AddOrGetExisting.

Data access

• Nextended.EF — Entity Framework Core extensions — graph loading (LoadGraphAsync, IncludeAll, MultiInclude), declarative include definitions, paging, dynamic sorting and bulk operations.

ASP.NET Core & web

• Nextended.Web — ASP.NET Core utilities — zero-config OData (AddODataAuto), composable IQueryable OData appliers, strongly typed controller URLs, streaming download helpers and a background executor that can replay a captured request.
• Nextended.ResponseFilters — Fluent, provider-agnostic pipeline that redacts, masks, rounds, truncates, hashes, prunes and restructures response DTOs before serialization — per request, per user, per permission. (this package)
• Nextended.ResponseFilters.AspNetCore — ASP.NET Core adapter for Nextended.ResponseFilters — registers the pipeline as a global IAsyncResultFilter and replays structural edits against the serialized JSON tree.

UI libraries

• Nextended.Blazor — Blazor helpers — IBrowserFile extensions (bytes, data URLs, downloads), a hierarchical model for browsing inside uploaded zip/tar/rar archives, MIME-type detection and component-parameter reflection.
• Nextended.UI — WPF and Windows desktop helpers — a global input-binding manager with hold/sequence matching, DirectInput and XInput gamepad readers, key-bind capture controls, converters, behaviours, markup extensions and runtime-defined PropertyGrid types.

Code generation & tooling

• Nextended.Imaging — Image processing — aspect-preserving resize, crop, colour replacement, brightness-based foreground picking, thumbnail generation, byte/data-URL conversion and MIME detection from magic bytes.
• Nextended.CodeGen — Roslyn source generator — DTOs and interfaces from your entities, strongly typed classes from JSON/XML, lookup tables from Excel, and documentation from source files.

.NET Aspire hosting

• Nextended.Aspire — Conditional AppHost builder extensions — WithReferenceIf / WaitForIf / WithExplicitStartIf, strongly typed environment variables from config objects, HTTPS dev-cert wiring, Docker guards, GitHub-source resources and npm app discovery.
• Nextended.Aspire.Hosting.Supabase — The complete Supabase stack — Postgres, Auth (GoTrue), REST, Realtime, Storage, Studio, Kong and Edge Functions — as one composable Aspire resource.
• Nextended.Aspire.Hosting.N8n — The n8n workflow-automation platform as an Aspire resource, with Postgres persistence, workflow import and a typed client for triggering workflows from .NET.
• Nextended.Aspire.Hosting.Grafana — Grafana, Prometheus, Loki, Tempo, Promtail, cAdvisor, postgres_exporter and the OpenTelemetry Collector as composable resources with auto-provisioned datasources.
• Nextended.Aspire.Hosting.WebDataStudio — WebDataStudio — a browser database studio for PostgreSQL, MySQL, SQL Server, SQLite, Oracle, DuckDB, ClickHouse, MongoDB and Redis — wired to the databases of your stack, with accounts and roles, an optional SQL assistant, and an MCP endpoint for AI agents.
• Nextended.Aspire.Hosting.AspireUI — AspireUI — the visual AppHost builder — as a resource inside your own Aspire stack, with an optional pre-seeded admin user and a starter stack built from your project paths.
• Nextended.Aspire.Hosting.LocalAI — Self-hosted, OpenAI-compatible multimodal AI — image generation, text-to-speech, speech-to-text and video — with gallery model management, GPU support and Open WebUI.
• Nextended.Aspire.Hosting.Php — Run PHP endpoints inside your Aspire stack — a docroot folder or a single router script served by PHP's built-in web server, with php.ini settings as fluent options.

Links

• 📦 NuGet package
• 📖 Documentation — English
• 📖 Dokumentation — Deutsch
• 🏠 Documentation portal
• 🧑‍💻 Source code
• 🐛 Report an issue

License

GPL-3.0-or-later — see LICENSE.