skip to content

A .NET 10 invoice-number Regex pins a request thread on crafted input; what do match timeouts, RegexOptions.NonBacktracking and [GeneratedRegex] each change?

level: seniorimportance: should knowfreq 30%

answer

  1. default engine backtracks, never times out
  2. exception after the interval
  3. linear time, fewer constructs
  4. build-time code, same semantics

basics

~20 s

The default .NET Regex engine backtracks and has no timeout (Regex.InfiniteMatchTimeout), so a nested quantifier can run for a very long time. A matchTimeout throws RegexMatchTimeoutException; NonBacktracking matches in linear time; [GeneratedRegex] moves construction to build time but keeps backtracking.

solid answer

~40 s

A `Regex` built without a timeout uses `Regex.InfiniteMatchTimeout` unless the process sets the `REGEX_DEFAULT_MATCH_TIMEOUT` AppContext value, so a pattern such as `^(a+)+$` on a long crafted string can keep a thread busy for as long as the backtracking takes. Passing a `TimeSpan` (constructor, static methods or `matchTimeoutMilliseconds` on `[GeneratedRegex]`) makes the engine throw `RegexMatchTimeoutException` at its next check after the interval. `RegexOptions.NonBacktracking` (.NET 7) uses an automaton that is linear in the input length, but rejects backreferences, lookarounds, atomic groups, balancing groups, conditionals and `\G` with `NotSupportedException`. `[GeneratedRegex]` (.NET 7; on partial properties since .NET 9 with C# 13) emits the matcher as C# at build time for startup, throughput and Native AOT; it does not make a backtracking pattern safe, and with NonBacktracking it just caches a normal instance.

code

csharp · 22 lines
csharp
using System.Text.RegularExpressions;

string crafted = new string('a', 40) + "!";

var guarded = new Regex(@"^(a+)+$", RegexOptions.None, TimeSpan.FromMilliseconds(250));
try { guarded.IsMatch(crafted); }
catch (RegexMatchTimeoutException e) { Console.WriteLine($"timed out after {e.MatchTimeout.TotalMilliseconds} ms"); }

var linear = new Regex(@"^(a+)+$", RegexOptions.NonBacktracking);
Console.WriteLine(linear.IsMatch(crafted));               // False, returned at once

try { _ = new Regex(@"^(INV)-\d+-\1$", RegexOptions.NonBacktracking); }
catch (NotSupportedException e) { Console.WriteLine(e.Message); }

Console.WriteLine(InvoiceRules.Number.IsMatch("INV-2026-000042"));  // True
Console.WriteLine(InvoiceRules.Number.MatchTimeout);                // 00:00:00.1000000

static partial class InvoiceRules
{
    [GeneratedRegex(@"^INV-[0-9]{4}-[0-9]{6}\z", RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 100)]
    public static partial Regex Number { get; }
}

go deeper

for a junior

Know that a .NET Regex has no timeout unless you pass one, and that RegexMatchTimeoutException is what a timed-out match throws.

for a middle

Explain how timeouts are set per instance, per call and process-wide, and what [GeneratedRegex] changes compared with RegexOptions.Compiled.

for a senior

Choose between a timeout and NonBacktracking for untrusted input, knowing the constructs NonBacktracking rejects and that the source generator keeps backtracking semantics.

for a principal

Argue for a rule that every regex over external input carries a timeout or NonBacktracking, enforced in review alongside SYSLIB1045 adoption.

## Why the default engine can pin a thread `System.Text.RegularExpressions.Regex` uses a **backtracking** engine by default, whether interpreted or compiled. Patterns with nested or overlapping quantifiers, such as `^(a+)+$`, can explore an exponential number of paths before reporting "no match" on input like forty `a` characters followed by `!`. Why that happens in general is regex theory; what matters here is what .NET gives you to bound it. The key default: a `Regex` constructed without a timeout gets **`Regex.InfiniteMatchTimeout`**, so nothing stops the match. ## Match timeouts - Pass a timeout to the constructor, `new Regex(pattern, options, TimeSpan.FromMilliseconds(250))`, to static methods such as `Regex.IsMatch(input, pattern, options, matchTimeout)`, or set `matchTimeoutMilliseconds` on `[GeneratedRegex]`. - When the interval passes, the engine throws **`RegexMatchTimeoutException`** at its next timing check. The runtime source notes that the backtracking implementations do no more than O(N) work between checks, so the exception arrives close to, not exactly at, the interval. The exception exposes `Input`, `Pattern` and `MatchTimeout` for logging. - A **process-wide default** comes from AppContext data: `AppContext.SetData("REGEX_DEFAULT_MATCH_TIMEOUT", TimeSpan.FromSeconds(2))` before the first `Regex` is created. The value must be a `TimeSpan`, and any timeout passed explicitly, even an infinite one, wins over it. - Catching the exception means "no answer within budget", not "partial match": treat the input as invalid or retry elsewhere. ## RegexOptions.NonBacktracking Introduced in .NET 7, **`RegexOptions.NonBacktracking`** runs the pattern as an automaton and guarantees processing linear in the length of the input. The cost is expressiveness: - Not supported: **backreferences**, **lookarounds**, **atomic groups**, **balancing groups**, **conditionals** and the `\G` anchor. The constructor throws `NotSupportedException`, for example "RegexOptions.NonBacktracking is not supported in conjunction with expressions containing: 'backreference (\ number)'." - It cannot be combined with `RightToLeft` or `ECMAScript`. - A capture group inside a loop reports only its final capture, unlike the backtracking engines, which keep every capture. - A very large pattern can exceed the engine's automaton size limit, which also throws `NotSupportedException` at construction. The docs add that the engine assumes the **pattern** is trusted; NonBacktracking protects against expensive input, not hostile patterns. ## [GeneratedRegex] The **regex source generator** ships with the SDK. Apply `[GeneratedRegex(pattern, options, matchTimeoutMilliseconds)]` to a `static partial` method returning `Regex` (.NET 7) or to a `static partial` property (.NET 9, using C# 13 partial properties), and the generator writes a `Regex`-derived class as C# into your build: 1. **Startup**: no parsing or IL emission at run time, unlike `RegexOptions.Compiled`, which uses Reflection.Emit and pays a large construction cost. 2. **Throughput**: comparable to or better than `Compiled`; the `Compiled` flag is ignored by the generator. 3. **Native AOT and trimming**: the code exists at build time, while `Compiled` becomes a no-op where dynamic code cannot run. 4. **Same semantics**: the generated matcher still backtracks, so it needs a timeout or a safer pattern just as much as the interpreter does. With `NonBacktracking`, the generator cannot produce a custom matcher and falls back to caching a normal `Regex` instance. Analyzer **SYSLIB1045** suggests converting constant-pattern `Regex` construction to `[GeneratedRegex]`. ## Handling the timeout in a service - Pick a budget from measured worst cases for legitimate input, for example tens of milliseconds for an invoice number, rather than seconds. - Catch `RegexMatchTimeoutException` at the validation boundary, log `Pattern` and the input length rather than the raw input, and reject the value. - Keep patterns that face external input simple: anchored, no nested quantifiers over the same characters, explicit character classes. - Prefer one shared instance (a `static readonly` field or a `[GeneratedRegex]` member) so construction cost is paid once; the static `Regex` methods keep a cache of recently used patterns, 15 by default (`Regex.CacheSize`). ## Comparison | Approach | Stops a runaway match? | Construct limits | Main benefit | |---|---|---|---| | Default interpreter, no timeout | No | None | Simplicity | | Any engine plus a match timeout | Yes, with `RegexMatchTimeoutException` | None | Bounded time per match | | `RegexOptions.NonBacktracking` | Linear time by design | No backreferences or lookarounds | Predictable cost on untrusted input | | `[GeneratedRegex]` | Only with its timeout argument | Same as the backtracking engine | Startup, throughput, AOT | ## Validation details that bite - `RegexOptions.IgnoreCase` uses the current culture's casing rules; add `RegexOptions.CultureInvariant` for identifiers such as invoice numbers. - `$` also matches before a final `\n`, so `^INV-\d{4}-\d{6}$` accepts `"INV-2026-000042\n"`; use `\z` to anchor at the very end. - `\d` matches any Unicode decimal digit, including Arabic-Indic digits; write `[0-9]` when you mean ASCII.

  • Why does ^INV-\d{4}-\d{6}$ accept an invoice number followed by a newline, or written with Arabic-Indic digits?
    In .NET, `$` matches at the end or just before a final `\n`, so a trailing newline passes; `\z` anchors at the absolute end. `\d` matches every Unicode decimal digit, not only 0 to 9, so `[0-9]` is the ASCII-only spelling. Both were confirmed on the .NET 10 runtime.
  • How do you give every Regex in a service a default timeout without editing each call site?
    Call `AppContext.SetData("REGEX_DEFAULT_MATCH_TIMEOUT", TimeSpan.FromSeconds(2))` at startup, before any `Regex` is constructed. Instances created without a timeout then use it; an explicitly passed timeout, including `Regex.InfiniteMatchTimeout`, still wins. The value must be a `TimeSpan`.
  • When is RegexOptions.Compiled still a reasonable choice?
    When the pattern is known only at run time, for example loaded from configuration, and is used heavily enough to repay its Reflection.Emit construction cost. For constant patterns `[GeneratedRegex]` is better, and where dynamic code is unavailable, such as Native AOT, `Compiled` has no effect.

  • Regex has a built-in default timeout of a few seconds, so runaway matches stop themselves.
  • [GeneratedRegex] makes any pattern immune to catastrophic backtracking.
  • NonBacktracking supports every construct the default engine does, just faster.
  • RegexOptions.Compiled removes the need for a match timeout.
  • A RegexMatchTimeoutException means the input partly matched.

Assumes .NET 10 with C# 14; NonBacktracking and [GeneratedRegex] on partial methods arrived in .NET 7, and [GeneratedRegex] on partial properties needs .NET 9 and C# 13.