Forem: Ahmad Al-Freihat

Your LINQ Filters Are Scattered Everywhere — Here's How to Fix It

Ahmad Al-Freihat — Fri, 09 Jan 2026 21:55:15 +0000

Ever found yourself copying the same LINQ Where clause across multiple services? Or debugging a filter condition that's duplicated in 15 different places? Let me introduce you to a pattern that's been saving my sanity: the Specification Pattern.

The Problem We All Face

Consider this common scenario in a typical .NET application:

// In CustomerService.cs
public async Task<List<Customer>> GetPremiumCustomers()
{
    return await _dbContext.Customers
        .Where(c => c.Balance >= 100000 && c.Age >= 18)
        .ToListAsync();
}

// In ReportService.cs
public async Task<int> GetPremiumCustomerCount()
{
    return await _dbContext.Customers
        .CountAsync(c => c.Balance >= 100000 && c.Age >= 18);
}

// In NotificationService.cs
public async Task SendPremiumOffers()
{
    List<Customer> customers = await _dbContext.Customers
        .Where(c => c.Balance >= 100000 && c.Age >= 18)
        .ToListAsync();

    foreach (Customer customer in customers)
    {
        await _emailService.SendOffer(customer);
    }
}

// In CustomerController.cs
[HttpGet("premium")]
public async Task<IActionResult> GetPremium()
{
    List<Customer> customers = await _dbContext.Customers
        .Where(c => c.Balance >= 100000 && c.Age >= 18)
        .ToListAsync();

    return Ok(customers);
}

The same filter appears 4 times. Now imagine:

Your business changes the premium threshold from $100,000 to $250,000
You need to add a new condition: customer must also be verified
One developer updates 3 places but misses the 4th

This is a maintenance nightmare waiting to happen.

The Solution: Specification Pattern

The Specification Pattern encapsulates business rules as reusable, testable objects. Instead of scattering conditions everywhere, you define them once:

public class PremiumCustomerSpecification : Specification<Customer>
{
    public override Expression<Func<Customer, bool>> ToExpression()
    {
        return customer => customer.Balance >= 100000 && customer.Age >= 18;
    }
}

Now your code becomes:

// In CustomerService.cs
public async Task<List<Customer>> GetPremiumCustomers()
{
    PremiumCustomerSpecification spec = new PremiumCustomerSpecification();
    return await _dbContext.Customers
        .Where(spec.ToExpression())
        .ToListAsync();
}

// In ReportService.cs
public async Task<int> GetPremiumCustomerCount()
{
    PremiumCustomerSpecification spec = new PremiumCustomerSpecification();
    return await _dbContext.Customers
        .CountAsync(spec.ToExpression());
}

// In NotificationService.cs
public async Task SendPremiumOffers()
{
    PremiumCustomerSpecification spec = new PremiumCustomerSpecification();
    List<Customer> customers = await _dbContext.Customers
        .Where(spec.ToExpression())
        .ToListAsync();

    foreach (Customer customer in customers)
    {
        await _emailService.SendOffer(customer);
    }
}

Change the rule once, it updates everywhere.

Enter Masterly.Specification

I've been working on Masterly.Specification, a .NET library that implements this pattern with powerful additions. Let me walk you through its features.

Installation

dotnet add package Masterly.Specification

Basic Usage: Two Ways to Use Specifications

1. Database Queries (Expression Trees)

Specifications work seamlessly with Entity Framework and other ORMs:

PremiumCustomerSpecification spec = new PremiumCustomerSpecification();

// The expression is translated to SQL by EF Core
List<Customer> premiumCustomers = await _dbContext.Customers
    .Where(spec.ToExpression())
    .ToListAsync();

// Also works with implicit conversion - no ToExpression() needed!
List<Customer> premiumCustomers = await _dbContext.Customers
    .Where(spec)
    .ToListAsync();

2. In-Memory Validation

Use the same specification to validate individual objects:

PremiumCustomerSpecification spec = new PremiumCustomerSpecification();

Customer customer = new Customer
{
    Name = "John",
    Balance = 150000,
    Age = 25
};

if (spec.IsSatisfiedBy(customer))
{
    Console.WriteLine("Customer is premium!");
    // Grant premium access, show special UI, etc.
}
else
{
    Console.WriteLine("Customer is not premium.");
}

Composing Specifications: Building Complex Rules

The real power comes from combining specifications. Let's say you have these business rules:

public class AdultSpecification : Specification<Customer>
{
    public override Expression<Func<Customer, bool>> ToExpression()
    {
        return customer => customer.Age >= 18;
    }
}

public class HighBalanceSpecification : Specification<Customer>
{
    public override Expression<Func<Customer, bool>> ToExpression()
    {
        return customer => customer.Balance >= 100000;
    }
}

public class VerifiedSpecification : Specification<Customer>
{
    public override Expression<Func<Customer, bool>> ToExpression()
    {
        return customer => customer.IsVerified;
    }
}

public class ActiveSpecification : Specification<Customer>
{
    public override Expression<Func<Customer, bool>> ToExpression()
    {
        return customer => customer.IsActive;
    }
}

Now combine them:

// AND: Customer must be adult AND have high balance
ISpecification<Customer> premiumSpec = new AdultSpecification()
    .And(new HighBalanceSpecification());

// OR: Customer is premium OR verified
ISpecification<Customer> qualifiedSpec = premiumSpec
    .Or(new VerifiedSpecification());

// NOT: Customer is NOT active
ISpecification<Customer> inactiveSpec = new ActiveSpecification().Not();

// AND NOT: Premium customers who are NOT inactive
ISpecification<Customer> activePremiumSpec = premiumSpec
    .AndNot(inactiveSpec);

// Use in query
List<Customer> results = await _dbContext.Customers
    .Where(activePremiumSpec.ToExpression())
    .ToListAsync();

Creating Reusable Composite Specifications

You can create a class for frequently used combinations:

public class EligibleForLoanSpecification : AndSpecification<Customer>
{
    public EligibleForLoanSpecification()
        : base(
            new AdultSpecification(),
            new VerifiedSpecification(),
            new ActiveSpecification())
    {
    }
}

// Usage
EligibleForLoanSpecification spec = new EligibleForLoanSpecification();
bool canApplyForLoan = spec.IsSatisfiedBy(customer);

Advanced Logic Operators

Version 2.0 introduces operators you won't find in basic implementations:

XOR (Exclusive Or)

Returns true when exactly one condition is true:

ISpecification<Customer> goldSpec = new GoldMemberSpecification();
ISpecification<Customer> silverSpec = new SilverMemberSpecification();

// Customer can be Gold OR Silver, but not both (exclusive tiers)
ISpecification<Customer> exclusiveTierSpec = goldSpec.Xor(silverSpec);

// Truth table:
// Gold=true,  Silver=true  -> false (can't be both)
// Gold=true,  Silver=false -> true
// Gold=false, Silver=true  -> true
// Gold=false, Silver=false -> false (must be one)

Implies (Material Implication)

Enforces business rules: "If A, then B must be true":

ISpecification<Order> highValueSpec = new ExpressionSpecification<Order>(o => o.Total > 10000);
ISpecification<Order> managerApprovedSpec = new ExpressionSpecification<Order>(o => o.ApprovedByManager);

// Business rule: High-value orders MUST have manager approval
ISpecification<Order> validOrderSpec = highValueSpec.Implies(managerApprovedSpec);

// Truth table:
// HighValue=true,  ManagerApproved=true  -> true  (rule satisfied)
// HighValue=true,  ManagerApproved=false -> false (VIOLATION!)
// HighValue=false, ManagerApproved=true  -> true  (rule doesn't apply)
// HighValue=false, ManagerApproved=false -> true  (rule doesn't apply)

Iff (If and Only If)

Both conditions must have the same truth value:

ISpecification<User> activeSpec = new ExpressionSpecification<User>(u => u.IsActive);
ISpecification<User> hasSubscriptionSpec = new ExpressionSpecification<User>(u => u.SubscriptionId != null);

// Users are active if and only if they have a subscription
// (ensures data consistency)
ISpecification<User> consistentSpec = activeSpec.Iff(hasSubscriptionSpec);

NAND and NOR

// NAND: Not both conditions true
ISpecification<Product> nandSpec = expensiveSpec.Nand(outOfStockSpec);
// Returns false only when product is BOTH expensive AND out of stock

// NOR: Neither condition true
ISpecification<Document> norSpec = expiredSpec.Nor(archivedSpec);
// Returns true only when document is NEITHER expired NOR archived

N-ary Composition: Multiple Specifications at Once

When you need flexible rules across many conditions:

ISpecification<Customer> hasEmail = new ExpressionSpecification<Customer>(c => !string.IsNullOrEmpty(c.Email));
ISpecification<Customer> hasPhone = new ExpressionSpecification<Customer>(c => !string.IsNullOrEmpty(c.Phone));
ISpecification<Customer> hasAddress = new ExpressionSpecification<Customer>(c => c.Address != null);
ISpecification<Customer> hasId = new ExpressionSpecification<Customer>(c => !string.IsNullOrEmpty(c.GovernmentId));

// ALL must be satisfied
ISpecification<Customer> completeProfile = Specifications.All(hasEmail, hasPhone, hasAddress, hasId);

// ANY ONE is enough
ISpecification<Customer> contactable = Specifications.AnyOf(hasEmail, hasPhone);

// EXACTLY 2 must be true
ISpecification<Customer> twoFactorReady = Specifications.Exactly(2, hasEmail, hasPhone, hasAddress);

// AT LEAST 2 must be true
ISpecification<Customer> minimalProfile = Specifications.AtLeast(2, hasEmail, hasPhone, hasAddress);

// AT MOST 1 can be true (useful for mutual exclusivity)
ISpecification<Customer> singleTier = Specifications.AtMost(1, isGold, isSilver, isBronze);

// NONE should be true
ISpecification<Customer> cleanRecord = Specifications.NoneOf(isBanned, isSuspended, hasWarnings);

Fluent Builder: Quick Specs Without Classes

For simple, one-off specifications, skip the class creation:

// Simple specification
ISpecification<User> adultUsers = Spec.Where<User>(u => u.Age >= 18);

// Complex specification with fluent API
ISpecification<User> eligibleUsers = Spec.For<User>()
    .Where(u => u.Age >= 18)
    .And(u => u.IsActive)
    .And(u => u.EmailConfirmed)
    .AndNot(u => u.IsBanned)
    .Build();

// With grouping for complex logic
// (Age >= 18 AND IsActive) OR (IsAdmin)
ISpecification<User> accessSpec = Spec.For<User>()
    .Group(g => g
        .Where(u => u.Age >= 18)
        .And(u => u.IsActive))
    .Or(u => u.IsAdmin)
    .Build();

// Factory methods
ISpecification<User> anyUser = Spec.Any<User>();      // Always returns true
ISpecification<User> noUser = Spec.None<User>();      // Always returns false

Property-Based Specifications: Type-Safe Filters

Create readable, strongly-typed property conditions:

// Numeric comparisons
ISpecification<Person> adults = Property<Person>.For(p => p.Age).GreaterThanOrEqual(18);
ISpecification<Person> seniors = Property<Person>.For(p => p.Age).GreaterThan(65);
ISpecification<Person> workingAge = Property<Person>.For(p => p.Age).InRange(18, 65);

// String operations
ISpecification<Person> gmailUsers = Property<Person>.For(p => p.Email).EndsWith("@gmail.com");
ISpecification<Person> hasEmail = Property<Person>.For(p => p.Email).IsNotNullOrEmpty();
ISpecification<Person> validEmailLength = Property<Person>.For(p => p.Email).HasLengthBetween(5, 100);

// Null checks
ISpecification<Person> hasManager = Property<Person>.For(p => p.Manager).IsNotNull();

// In collection
ISpecification<Person> inAllowedCountries = Property<Person>.For(p => p.Country).In("USA", "Canada", "UK");

// Custom predicates
ISpecification<Person> evenAge = Property<Person>.For(p => p.Age).Matches(age => age % 2 == 0);

// Combine them naturally
ISpecification<Person> targetAudience = Property<Person>.For(p => p.Age).InRange(25, 45)
    .And(Property<Person>.For(p => p.Email).EndsWith("@company.com"))
    .And(Property<Person>.For(p => p.Country).In("USA", "Canada"));

Temporal Specifications: DateTime Logic Made Easy

Date handling is notoriously error-prone. Temporal specifications make it clean:

// Basic comparisons
ISpecification<Event> futureEvents = Temporal<Event>.For(e => e.StartDate).After(DateTime.Now);
ISpecification<Event> pastEvents = Temporal<Event>.For(e => e.StartDate).Before(DateTime.Now);
ISpecification<Event> thisYear = Temporal<Event>.For(e => e.StartDate).InYear(2024);
ISpecification<Event> thisMonth = Temporal<Event>.For(e => e.StartDate).InMonth(2024, 6);

// Date ranges
ISpecification<Event> q1Events = Temporal<Event>.For(e => e.StartDate)
    .Between(new DateTime(2024, 1, 1), new DateTime(2024, 3, 31));

// Day of week
ISpecification<Event> weekendEvents = Temporal<Event>.For(e => e.StartDate).OnWeekend();
ISpecification<Event> weekdayEvents = Temporal<Event>.For(e => e.StartDate).OnWeekday();
ISpecification<Event> mondayEvents = Temporal<Event>.For(e => e.StartDate).OnDayOfWeek(DayOfWeek.Monday);

// Time of day (business hours: 9 AM to 5 PM)
ISpecification<Event> businessHours = Temporal<Event>.For(e => e.StartDate)
    .TimeBetween(TimeSpan.FromHours(9), TimeSpan.FromHours(17));

// Nullable DateTime support
ISpecification<Event> hasEndDate = Temporal<Event>.For(e => e.EndDate).HasValue();
ISpecification<Event> openEnded = Temporal<Event>.For(e => e.EndDate).IsNull();

// Combine for complex queries
ISpecification<Event> upcomingBusinessMeetings = Temporal<Event>.For(e => e.StartDate)
    .After(DateTime.Now)
    .And(Temporal<Event>.For(e => e.StartDate).OnWeekday())
    .And(Temporal<Event>.For(e => e.StartDate).TimeBetween(
        TimeSpan.FromHours(9),
        TimeSpan.FromHours(17)));

Conditional Pipelines: Dynamic Rule Application

Apply different rules based on runtime conditions:

// Apply specification only when a condition is true
bool applyPremiumFilter = user.HasPremiumAccess;
ISpecification<Product> conditionalSpec = premiumProductsSpec.OnlyWhen(applyPremiumFilter);
// If applyPremiumFilter is false, all products pass through

// Skip specification when condition is true
bool isAdmin = user.Role == "Admin";
ISpecification<Document> securitySpec = confidentialSpec.SkipWhen(isAdmin);
// Admins bypass the confidential filter

// Choose different specs based on entity properties
ISpecification<Order> orderValidation = PipelineExtensions
    .When<Order>(
        order => order.Type == "Premium",
        strictValidationSpec)
    .Otherwise(standardValidationSpec);

// Or with pass-through/fail-all options
ISpecification<Order> premiumOnlyFilter = PipelineExtensions
    .When<Order>(
        order => order.Total > 1000,
        requiresApprovalSpec)
    .OtherwisePass();  // Orders under $1000 pass without approval check

Diagnostics: Understanding Why Rules Fail

Debugging complex specifications is easy with built-in diagnostics:

ISpecification<Order> orderSpec = new ExpressionSpecification<Order>(o => o.Total > 100)
    .And(new ExpressionSpecification<Order>(o => o.Status == "Approved"))
    .And(new ExpressionSpecification<Order>(o => o.Items.Count > 0));

Order order = new Order
{
    Total = 50,           // Fails: not > 100
    Status = "Pending",   // Fails: not "Approved"
    Items = new List<OrderItem>()  // Fails: count is 0
};

// Get human-readable explanation
string explanation = orderSpec.Explain();
Console.WriteLine(explanation);
// Output: ((o.Total > 100) AND (o.Status == "Approved")) AND (o.Items.Count > 0)

// Get detailed evaluation
EvaluationResult result = orderSpec.Evaluate(order);

Console.WriteLine($"Satisfied: {result.IsSatisfied}");  // false
Console.WriteLine($"Summary: {result.Summary}");        // FAILED

Console.WriteLine("\nPassed conditions:");
foreach (string passed in result.GetPassedConditions())
{
    Console.WriteLine($"  ✓ {passed}");
}

Console.WriteLine("\nFailed conditions:");
foreach (string failed in result.GetFailureReasons())
{
    Console.WriteLine($"  ✗ {failed}");
}

// Output:
// Satisfied: False
// Summary: FAILED
// Passed conditions:
//   (none)
// Failed conditions:
//   ✗ o.Total > 100
//   ✗ o.Status == "Approved"
//   ✗ o.Items.Count > 0

Performance Optimization: Caching for Hot Paths

For frequently evaluated specifications, cache the compiled expression:

// Without caching - compiles expression every time
ISpecification<Item> spec = new ExpressionSpecification<Item>(i => i.Price > 50);
foreach (Item item in millionItems)
{
    spec.IsSatisfiedBy(item);  // Compiles expression each call
}

// With caching - compiles once, reuses
CachedSpecification<Item> cachedSpec = spec.Cached();
foreach (Item item in millionItems)
{
    cachedSpec.IsSatisfiedBy(item);  // Uses cached compiled delegate
}

// Access the compiled predicate directly for maximum performance
Func<Item, bool> predicate = cachedSpec.CompiledPredicate;
List<Item> filtered = millionItems.Where(predicate).ToList();

// Memoization - cache results per entity instance
ISpecification<Item> memoizedSpec = expensiveSpec.Memoized();
memoizedSpec.IsSatisfiedBy(item1);  // Evaluates and caches result
memoizedSpec.IsSatisfiedBy(item1);  // Returns cached result (no evaluation)
memoizedSpec.IsSatisfiedBy(item2);  // Different item, evaluates fresh

When Should You Use This?

Use specifications when:

Business rules are reused across multiple services/controllers
Filter logic is complex enough to deserve a name
You want testable, isolated business rules
Requirements change frequently (centralized updates)
You need to explain why something passed/failed

Skip specifications for:

One-off, simple queries (c => c.Id == id)
Reporting where raw SQL is more appropriate
Trivial conditions that don't benefit from naming

Complete Example: Putting It All Together

public class OrderService
{
    private readonly AppDbContext _dbContext;

    public OrderService(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<List<Order>> GetOrdersRequiringAttention()
    {
        // Define individual specifications
        ISpecification<Order> highValue = new ExpressionSpecification<Order>(o => o.Total > 5000);
        ISpecification<Order> pending = new ExpressionSpecification<Order>(o => o.Status == "Pending");
        ISpecification<Order> overdue = Temporal<Order>.For(o => o.DueDate).Before(DateTime.Now);
        ISpecification<Order> flagged = new ExpressionSpecification<Order>(o => o.IsFlagged);

        // Combine with business logic:
        // Orders need attention if:
        // - High value AND pending, OR
        // - Overdue (regardless of value), OR
        // - Manually flagged
        ISpecification<Order> needsAttention = highValue.And(pending)
            .Or(overdue)
            .Or(flagged);

        // Use cached version for performance
        CachedSpecification<Order> cachedSpec = needsAttention.Cached();

        return await _dbContext.Orders
            .Where(cachedSpec.ToExpression())
            .OrderByDescending(o => o.Total)
            .ToListAsync();
    }

    public async Task<bool> CanProcessOrder(Order order)
    {
        ISpecification<Order> canProcess = Spec.For<Order>()
            .Where(o => o.Status == "Approved")
            .And(o => o.PaymentVerified)
            .And(o => o.Items.Any())
            .Build();

        if (!canProcess.IsSatisfiedBy(order))
        {
            EvaluationResult result = canProcess.Evaluate(order);
            _logger.LogWarning(
                "Order {OrderId} cannot be processed. Failures: {Failures}",
                order.Id,
                string.Join(", ", result.GetFailureReasons()));
            return false;
        }

        return true;
    }
}

Wrapping Up

The Specification Pattern transforms scattered, duplicated business rules into clean, testable, reusable components. Masterly.Specification brings this pattern to .NET with:

Basic composition (And, Or, Not, AndNot)
Advanced logic (Xor, Implies, Iff, Nand, Nor)
N-ary composition (All, AnyOf, Exactly, AtLeast, AtMost, NoneOf)
Fluent builder for inline specs
Property-based specifications
Temporal (DateTime) specifications
Conditional pipelines
Diagnostics and explanation
Performance caching

Check out the GitHub repo for full documentation!

What patterns do you use to manage complex business logic in your .NET projects? Drop a comment below!

Stop Writing Unreadable Regex - Build Patterns the Fluent Way in C#

Ahmad Al-Freihat — Thu, 08 Jan 2026 10:34:18 +0000

The Problem Every Developer Knows

We've all been there. You're reviewing code and encounter something like this:

var regex = new Regex(@"^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=]).{8,}$");

What does it do? 🤔

You squint at it for 5 minutes, open regex101.com, and finally realize it's password validation. Now imagine coming back to this code 6 months later...

There's a Better Way

What if you could write regex like this instead?

Pattern password = Pattern.With
    .StartOfLine
    .PositiveLookahead(Pattern.With.Anything.Repeat.ZeroOrMore.Set(Pattern.With.LowercaseLetter))
    .PositiveLookahead(Pattern.With.Anything.Repeat.ZeroOrMore.Set(Pattern.With.UppercaseLetter))
    .PositiveLookahead(Pattern.With.Anything.Repeat.ZeroOrMore.Digit)
    .PositiveLookahead(Pattern.With.Anything.Repeat.ZeroOrMore.Set(Pattern.With.Literal("!@#$%^&*()_+-=")))
    .Anything.Repeat.AtLeast(8)
    .EndOfLine;

Self-documenting. Readable. Maintainable.

This is Masterly.FluentRegex - and v2.0 just dropped with some killer features! 🚀

What's New in v2.0

1. Named Groups & Backreferences

Extract data with meaningful names:

Pattern phone = Pattern.With
    .NamedGroup("area", Pattern.With.Digit.Repeat.Times(3))
    .Literal("-")
    .NamedGroup("exchange", Pattern.With.Digit.Repeat.Times(3))
    .Literal("-")
    .NamedGroup("number", Pattern.With.Digit.Repeat.Times(4));

Match match = phone.Match("555-123-4567");
Console.WriteLine(match.Groups["area"].Value);     // "555"
Console.WriteLine(match.Groups["exchange"].Value); // "123"
Console.WriteLine(match.Groups["number"].Value);   // "4567"

Find duplicate words with backreferences:

Pattern duplicates = Pattern.With
    .WordBoundary
    .NamedGroup("word", Pattern.With.Word.Repeat.OneOrMore)
    .Whitespace.Repeat.OneOrMore
    .Backreference("word")
    .WordBoundary;

duplicates.IsMatch("the the");     // true
duplicates.IsMatch("hello world"); // false

2. Lookahead & Lookbehind

Zero-width assertions made simple:

// Match digits only if preceded by '$'
Pattern price = Pattern.With
    .PositiveLookbehind(Pattern.With.Literal("$"))
    .Digit.Repeat.OneOrMore;

var match = price.Match("Price: $100");
Console.WriteLine(match.Value); // "100" (not "$100"!)

// Match 'q' only if NOT followed by 'u'
Pattern qNotU = Pattern.With
    .Literal("q")
    .NegativeLookahead(Pattern.With.Literal("u"));

qNotU.IsMatch("iraq");  // true
qNotU.IsMatch("queen"); // false

3. Full Matching API

No need to call ToRegex() anymore:

Pattern digits = Pattern.With.Digit.Repeat.OneOrMore;

// Direct matching
digits.IsMatch("abc123");           // true
digits.Match("abc123def456");       // First match: "123"
digits.Matches("abc123def456");     // All matches: ["123", "456"]

// Replace & Split
digits.Replace("a1b2c3", "X");      // "aXbXcX"
digits.Replace("a1b2", m => (int.Parse(m.Value) * 2).ToString()); // "a2b4"

Pattern comma = Pattern.With.Literal(",");
comma.Split("a,b,c");               // ["a", "b", "c"]

4. 20+ Pre-built Common Patterns

Stop reinventing the wheel:

// Email
CommonPatterns.Email().IsMatch("user@example.com"); // true

// URLs
CommonPatterns.Url().IsMatch("https://dev.to"); // true

// IP Addresses
CommonPatterns.IPv4().IsMatch("192.168.1.1"); // true
CommonPatterns.IPv4().IsMatch("256.1.1.1");   // false (validates 0-255!)

// And many more...
CommonPatterns.Guid();
CommonPatterns.HexColor();
CommonPatterns.CreditCard();
CommonPatterns.PhoneNumber();
CommonPatterns.StrongPassword();
CommonPatterns.DateIso();
CommonPatterns.Time24();
// ... and more!

5. Debugging Tools

Understand any pattern instantly:

Pattern pattern = Pattern.With
    .StartOfLine
    .NamedGroup("digits", Pattern.With.Digit.Repeat.OneOrMore)
    .EndOfLine;

Console.WriteLine(pattern.Explain());

Output:

Pattern: ^(?<digits>\d+)$

Explanation:
  - Start of line/string
  - Named capturing group 'digits'
    - Digit [0-9]
    - One or more
  - End of group
  - End of line/string

Validate before runtime errors:

Pattern invalid = Pattern.With.RegEx("[unclosed");

if (!invalid.TryValidate(out string error))
{
    Console.WriteLine($"Invalid: {error}");
}

Real-World Example: Log Parser

Pattern logEntry = Pattern.With
    .StartOfLine
    .Literal("[")
    .NamedGroup("date", Pattern.With.Digit.Repeat.Times(4)
        .Literal("-").Digit.Repeat.Times(2)
        .Literal("-").Digit.Repeat.Times(2))
    .Whitespace
    .NamedGroup("time", Pattern.With.Digit.Repeat.Times(2)
        .Literal(":").Digit.Repeat.Times(2)
        .Literal(":").Digit.Repeat.Times(2))
    .Literal("]")
    .Whitespace
    .Literal("[")
    .NamedGroup("level", Pattern.With.Word.Repeat.OneOrMore)
    .Literal("]")
    .Whitespace
    .NamedGroup("message", Pattern.With.Anything.Repeat.OneOrMore)
    .EndOfLine;

string log = "[2024-01-15 10:30:45] [ERROR] Connection timeout";
Match m = logEntry.Match(log);

Console.WriteLine($"Level: {m.Groups["level"].Value}");   // "ERROR"
Console.WriteLine($"Message: {m.Groups["message"].Value}"); // "Connection timeout"

Get Started

dotnet add package Masterly.FluentRegex

using Masterly.FluentRegex;

// Start building!
Pattern myPattern = Pattern.With
    .StartOfLine
    .Digit.Repeat.OneOrMore
    .EndOfLine;

Links

What regex patterns do you find yourself writing repeatedly? Drop a comment below - maybe we can add them to the CommonPatterns library! 👇

If this helps you write better regex, consider giving it a ⭐ on GitHub!

Stop Scattering Your Business Logic: Meet Masterly.BusinessRules for .NET

Ahmad Al-Freihat — Tue, 06 Jan 2026 21:37:26 +0000

Have you ever found yourself debugging a validation issue, only to discover the logic is scattered across controllers, services, and models? Or copying the same validation code between projects?

There's a better way.

Introducing Masterly.BusinessRules

Masterly.BusinessRules is a clean, composable, and extensible business rule engine for .NET that brings order to your validation chaos.

dotnet add package Masterly.BusinessRules

The Problem

Business rules are everywhere in your code:

// In your controller
if (order.Items.Count == 0)
    return BadRequest("Order must have items");

// In your service
if (!customer.IsActive)
    throw new Exception("Customer must be active");

// In another service
if (order.Total > customer.CreditLimit)
    throw new Exception("Order exceeds credit limit");

This leads to:

Duplicated validation logic
Inconsistent error messages
Hard-to-test business rules
Scattered domain knowledge

The Solution

Encapsulate each business rule in its own class:

public class OrderMustHaveItemsRule(Order order) : BaseBusinessRule
{
    public override string Code => "ORDER.NO_ITEMS";
    public override string Message => "Order must contain at least one item.";

    public override bool IsBroken() => !order.Items.Any();
}

Then use it anywhere:

new OrderMustHaveItemsRule(order).Check(); // Throws if broken

Why Developers Love It

1. Fluent Builders for Quick Rules

Don't want to create a class? Use the builder:

var rule = BusinessRuleBuilder.Create("AGE.INVALID")
    .WithMessage("Must be 18 or older")
    .WithSeverity(RuleSeverity.Error)
    .WithCategory("User Validation")
    .When(() => user.Age < 18)
    .Build();

2. Compose Rules Like LEGO Blocks

Combine simple rules into complex validation logic:

var accessRule = new CustomerIsAdultRule(customer)
    .And(new CustomerIsActiveRule(customer))
    .Or(new CustomerIsVIPRule(customer));

// Customer must be (adult AND active) OR VIP

3. First-Class Async Support

Database queries? API calls? No problem:

public class EmailMustBeUniqueRule(IUserRepository repo, string email)
    : BaseAsyncBusinessRule
{
    public override string Code => "EMAIL.DUPLICATE";
    public override string Message => $"Email '{email}' is already registered.";

    public override async Task<bool> IsBrokenAsync(
        BusinessRuleContext context,
        CancellationToken ct = default)
        => await repo.EmailExistsAsync(email, ct);
}

4. Batch Validation with Control

Check multiple rules at once with options:

// Fail fast - stop on first broken rule
BusinessRuleChecker.CheckAll(
    new OrderMustHaveItemsRule(order),
    new CustomerMustBeActiveRule(customer),
    stopOnFirstFailure: true
);

// Run async rules in parallel for performance
await AsyncBusinessRuleChecker.CheckAllAsync(
    context,
    rules,
    runInParallel: true
);

5. API-Friendly Error Collection

Get all validation errors without exceptions:

var result = await AsyncBusinessRuleChecker.EvaluateAllAsync(rules);

if (result.HasBrokenRules)
{
    return BadRequest(new {
        errors = result.BrokenRules.Select(r => new {
            code = r.Code,
            message = r.Message,
            severity = r.Severity
        })
    });
}

6. Built-in Caching for Expensive Rules

Cache results for rules that hit the database:

var cachedRule = new CachedBusinessRule(
    new ExpensiveValidationRule(),
    TimeSpan.FromMinutes(5)
);

// Or use extension method
var cachedRule = myRule.WithCache(TimeSpan.FromMinutes(5));

7. Conditional Execution

Run rules only when conditions are met:

var premiumRule = new ConditionalBusinessRule(
    new PremiumFeatureValidation(),
    () => user.IsPremium  // Only check for premium users
);

8. Rich Metadata for Organization

Categorize and filter your rules:

public class OrderLimitRule : BaseBusinessRule
{
    public override string Code => "ORDER.LIMIT";
    public override string Message => "Order exceeds daily limit.";
    public override string Name => "Daily Order Limit";
    public override string Description => "Validates orders don't exceed daily spending limits";
    public override string Category => "Financial";
    public override IEnumerable<string> Tags => ["order", "limit", "financial"];
    public override RuleSeverity Severity => RuleSeverity.Error;

    public override bool IsBroken() => /* validation logic */;
}

// Filter by category or tags
BusinessRuleChecker.CheckByCategory(context, "Financial", rules);
BusinessRuleChecker.CheckByTags(context, ["order"], rules);

9. Observability Built-in

Monitor rule execution for logging and metrics:

public class LoggingObserver : IRuleExecutionObserver
{
    public void OnBeforeEvaluate(IBusinessRule rule, BusinessRuleContext context)
        => _logger.LogDebug("Evaluating rule: {Code}", rule.Code);

    public void OnRuleBroken(IBusinessRule rule, BusinessRuleContext context)
        => _logger.LogWarning("Rule broken: {Code} - {Message}", rule.Code, rule.Message);
}

BusinessRuleChecker.CheckAll(context, observer, rules);

10. Testing Made Easy

Dedicated testing utilities:

[Fact]
public void OrderWithNoItems_ShouldBeBroken()
{
    var order = new Order { Items = [] };
    var rule = new OrderMustHaveItemsRule(order);

    RuleTestHelper.AssertBroken(rule);
}

[Fact]
public async Task DuplicateEmail_ShouldBeBroken()
{
    var rule = new EmailMustBeUniqueRule(mockRepo, "taken@email.com");

    await RuleTestHelper.AssertBrokenAsync(rule);
}

Real-World Example: Order Processing

public class OrderService(IRepository repository)
{
    public async Task<Result> ProcessOrderAsync(Order order, Customer customer)
    {
        var context = new BusinessRuleContext();
        context.Set("orderId", order.Id);

        var rules = new IAsyncBusinessRule[]
        {
            new OrderMustHaveItemsRule(order).ToAsync(),
            new CustomerMustBeActiveRule(customer).ToAsync(),
            new OrderWithinCreditLimitRule(order, customer).ToAsync(),
            new InventoryAvailableRule(repository, order)
        };

        var result = await AsyncBusinessRuleChecker.EvaluateAllAsync(
            context,
            rules,
            runInParallel: true
        );

        if (result.HasBrokenRules)
        {
            return Result.Failure(result.BrokenRules
                .Select(r => $"[{r.Code}] {r.Message}"));
        }

        // Process the order...
        return Result.Success();
    }
}

Key Features at a Glance

Feature	Description
Sync & Async	Full support for both patterns with CancellationToken
Fluent Builders	Create rules inline without subclassing
Composition	`And()`, `Or()`, `Not()` operators
Context	Pass data between rules with typed/untyped context
Caching	Cache expensive rule evaluations
Conditional	Execute rules based on preconditions
Batch Checking	Fail-fast, parallel execution, filtering
Evaluation Results	Non-throwing API for collecting all errors
Observers	Logging, metrics, audit trail hooks
Testing Utilities	AssertBroken, AssertNotBroken helpers

Get Started

dotnet add package Masterly.BusinessRules

Check out the full documentation and examples on GitHub.

Conclusion

Stop scattering your business logic. With Masterly.BusinessRules, you get:

Clean separation of business rules from application code
Reusable validation logic across your entire application
Testable rules with dedicated testing utilities
Composable rules that combine like building blocks
Observable execution for logging and monitoring
Performant validation with caching and parallel execution

Your future self (and your team) will thank you.

What business rules are you validating today? Drop a comment below!

Star on GitHub

Type-Safe Collections in C#: How NonEmptyList Eliminates Runtime Exceptions

Ahmad Al-Freihat — Fri, 02 Jan 2026 00:16:27 +0000

The Problem with Empty Collections

Every C# developer has encountered this scenario: a method returns a collection that should contain data, but at runtime, it's empty. The result? InvalidOperationException, null reference errors, or subtle bugs that only surface in production.

public async Task<decimal> CalculateAverageOrderValueAsync(int customerId)
{
    var orders = await _repository.GetOrdersAsync(customerId);
    return orders.Average(o => o.Total); // Throws if orders is empty
}

The traditional solution involves defensive programming:

if (orders.Any())
{
    return orders.Average(o => o.Total);
}
return 0m; // What does zero mean here? No orders? An error?

This approach has significant drawbacks:

Silent failures: Returning default values masks underlying issues
Code duplication: Empty checks scattered throughout the codebase
Semantic ambiguity: Is zero a valid average or an error state?

A Type-System Solution

What if we could express "this collection must have at least one element" directly in our type signatures? This is precisely what NonEmptyList provides.

public async Task<decimal> CalculateAverageOrderValueAsync(
    NonEmptyList<Order> orders)  // Guaranteed non-empty at compile time
{
    return orders.Average(o => o.Total); // Always safe
}

The compiler now enforces our business rule. Callers must provide a non-empty collection, shifting validation from runtime to compile time.

Installation

dotnet add package Masterly.NonEmptyList

Compatible with .NET 6.0 and .NET 8.0.

Core API Design

NonEmptyList draws inspiration from functional programming languages, particularly Scala's List type. It provides three fundamental properties for traversing collections:

Property	Type	Description
`Head`	`T`	First element (guaranteed to exist)
`Tail`	`NonEmptyList<T>?`	Remaining elements, or null if single
`Init`	`NonEmptyList<T>?`	All elements except last, or null if single

var numbers = new NonEmptyList<int>(1, 2, 3, 4, 5);

var head = numbers.Head;  // 1
var tail = numbers.Tail;  // NonEmptyList<int> { 2, 3, 4, 5 }
var init = numbers.Init;  // NonEmptyList<int> { 1, 2, 3, 4 }
var last = numbers.Last;  // 5

Deconstruction Support

C# pattern matching integrates naturally:

var (first, rest) = numbers;
// first = 1, rest = NonEmptyList<int> { 2, 3, 4, 5 }

Functional Transformations

Map and FlatMap

Transform elements while preserving the non-empty guarantee:

var orders = new NonEmptyList<Order>(order1, order2, order3);

// Transform to DTOs
NonEmptyList<OrderDto> dtos = orders.Map(o => new OrderDto(o));

// Flatten nested collections
NonEmptyList<LineItem> allItems = orders.FlatMap(o => o.Items);

Reduce: Aggregation Without Edge Cases

Traditional Aggregate requires handling empty collections:

// Standard LINQ - throws on empty collection
decimal total = orders.Aggregate(0m, (sum, o) => sum + o.Total);

With NonEmptyList, Reduce requires no seed value because the collection is guaranteed non-empty:

// NonEmptyList - always safe, no seed required
decimal total = orders.Reduce((sum, o) => sum + o.Total);

This eliminates an entire category of runtime errors.

Fold for Type Transformations

When the result type differs from the element type:

var summary = orders.Fold(
    new OrderSummary(),
    (summary, order) => summary.AddOrder(order)
);

Partition and GroupBy

Separate collections based on predicates:

var (highValue, standard) = orders.Partition(o => o.Total > 1000m);

var byStatus = orders.GroupByNonEmpty(o => o.Status);
// Dictionary<OrderStatus, NonEmptyList<Order>>

Pattern Matching

Handle single-element and multi-element cases explicitly:

string ProcessOrders(NonEmptyList<Order> orders) =>
    orders.Match(
        single: order =>
            $"Processing single order: {order.Id}",
        multiple: (first, remaining) =>
            $"Processing batch: {first.Id} and {remaining.Count} more"
    );

This pattern is particularly useful for recursive algorithms and batch processing logic.

Asynchronous Operations

Modern applications require async support. NonEmptyList provides both sequential and parallel async operations:

Sequential Processing

var enrichedOrders = await orders.MapAsync(
    async order => await _enrichmentService.EnrichAsync(order)
);

Parallel Processing with Controlled Concurrency

var results = await orders.MapParallelAsync(
    async order => await _processor.ProcessAsync(order),
    maxDegreeOfParallelism: 4
);

Async Aggregation

var totalRevenue = await orders.FoldAsync(
    0m,
    async (sum, order) => sum + await _calculator.CalculateRevenueAsync(order)
);

Immutable Variant

For concurrent scenarios or when immutability is required:

var immutable = new ImmutableNonEmptyList<int>(1, 2, 3);

// All operations return new instances
var appended = immutable.Append(4);      // New list: [1, 2, 3, 4]
var prepended = immutable.Prepend(0);    // New list: [0, 1, 2, 3]

// Original unchanged
Console.WriteLine(immutable.Count);      // Still 3

Convert between variants as needed:

var immutable = mutableList.ToImmutable();
var mutable = immutableList.ToMutable();

Serialization

JSON Support

Built-in System.Text.Json converters handle serialization automatically:

var orders = new NonEmptyList<Order>(order1, order2);

string json = JsonSerializer.Serialize(orders);
var restored = JsonSerializer.Deserialize<NonEmptyList<Order>>(json);

Deserialization enforces the non-empty constraint:

// Throws JsonException with descriptive message
JsonSerializer.Deserialize<NonEmptyList<int>>("[]");

Entity Framework Core Integration

A dedicated package provides database persistence support:

dotnet add package Masterly.NonEmptyList.EntityFrameworkCore

Configure properties and relationships:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    // Store as JSON column
    modelBuilder.Entity<Product>()
        .Property(p => p.Tags)
        .HasNonEmptyListConversion();

    // Configure relationships with non-empty constraint
    modelBuilder.Entity<Order>()
        .HasNonEmptyManyWithOne(
            o => o.LineItems,
            li => li.Order,
            li => li.OrderId
        );
}

Practical Example: Order Processing Pipeline

public class OrderProcessingService
{
    public async Task<ProcessingResult> ProcessBatchAsync(
        NonEmptyList<Order> orders,
        CancellationToken cancellationToken = default)
    {
        // Validate all orders in parallel
        var validationResults = await orders.MapParallelAsync(
            order => _validator.ValidateAsync(order, cancellationToken),
            maxDegreeOfParallelism: 8
        );

        // Partition by validation result
        var (valid, invalid) = orders
            .Zip(validationResults)
            .Partition(pair => pair.Item2.IsValid);

        if (invalid.Any())
        {
            _logger.LogWarning("Found {Count} invalid orders", invalid.Count);
        }

        // Process valid orders
        var processed = valid switch
        {
            null => new ProcessingResult(0, 0m),
            var validOrders => await ProcessValidOrdersAsync(
                validOrders.Map(pair => pair.Item1),
                cancellationToken
            )
        };

        return processed;
    }

    private async Task<ProcessingResult> ProcessValidOrdersAsync(
        NonEmptyList<Order> orders,
        CancellationToken cancellationToken)
    {
        // Calculate totals - Reduce is safe, no empty check needed
        var totalRevenue = orders.Reduce((sum, o) => sum + o.Total);

        // Process with pattern matching
        await orders.Match(
            single: async order =>
                await _processor.ProcessSingleAsync(order, cancellationToken),
            multiple: async (priority, remaining) =>
            {
                await _processor.ProcessPriorityAsync(priority, cancellationToken);
                await remaining.ForEachAsync(
                    order => _processor.ProcessAsync(order, cancellationToken)
                );
            }
        );

        return new ProcessingResult(orders.Count, totalRevenue);
    }
}

When to Use NonEmptyList

Ideal use cases:

Domain models where empty collections are invalid (orders must have line items)
API contracts that require at least one element
Aggregation operations where empty input is an error
Functional programming patterns (head/tail recursion)

Consider alternatives when:

Empty collections are valid in your domain
You need to gradually build collections from empty state
Performance is critical and allocation overhead matters

Resources

NonEmptyList brings a well-established functional programming pattern to C#, enabling developers to express domain constraints directly in the type system. By shifting validation from runtime to compile time, we eliminate entire categories of bugs while making code more expressive and self-documenting.

If this library helps your project, consider giving it a star on GitHub.