Skip to main content

Introduction

After you complete the ASP.NET Core installation, unhandled exceptions are reported automatically. Inject LerixClient to report handled exceptions yourself with extra context.

Automatic capture

AddLerix and UseLerix register two things:
  • A middleware. Every exception that escapes the middleware after it (routing, authentication, your endpoints) passes through it. By default it reports every exception except those that carry a status below 500, such as a BadHttpRequestException with status 400. The middleware then rethrows, so UseExceptionHandler or the developer exception page builds exactly the response it would have built without Lerix. Requests the client aborted are not reported.
  • Process-level handlers. AppDomain.UnhandledException and TaskScheduler.UnobservedTaskException are reported as Crash with Critical severity. Set CaptureUnhandled = false to skip them.
Every automatic report carries the request method, URL, route pattern, status code, and the X-Request-Id header (or ASP.NET’s TraceIdentifier) under metadata.request.

Change what is reported

ShouldCapture receives the exception, the HttpContext and the status that will be sent when it is known:
Program.cs
IgnorePaths is a shortcut for skipping whole route prefixes without a delegate.

Middleware order

UseLerix must sit after UseExceptionHandler (which would otherwise catch the exception first) and before the middleware you want covered. A typical pipeline:
Program.cs

Filtering errors

Requires Lerix / Lerix.AspNetCore 0.4.0 or later. Three LerixOptions properties decide what leaves the process. They apply to every report, whatever its origin: the ASP.NET Core middleware, the process-level handlers, and CaptureException / CaptureMessage. Use them for message-based filtering; use ShouldCapture (above) to decide by exception, request or status.
Program.cs
IgnoreErrors can also be bound from appsettings.json:
appsettings.json
  • IgnoreErrors (IList<string>) and IgnoreErrorPatterns (IList<Regex>) run first, then BeforeSend (Func<LerixErrorEvent, LerixErrorEvent?>) sees only what’s left.
  • The message matched and passed to BeforeSend is the issue title shown in the dashboard, for example InvalidOperationException: boom.
  • LerixErrorEvent has Message, Stack (at ... lines), Type (BugType), Severity (BugSeverity) and Metadata (what you passed to the capture call, or the request context from the middleware). Device, app and runtime details are added after the hook, which runs on the thread that captured the error.
  • If BeforeSend throws, the original event is sent and the exception is only logged. It is never reported or rethrown.
  • A dropped report does not pin its request’s trace.
Lerix also groups repeated errors into one issue and filters common noise on the server, for every SDK version. See How errors are grouped into issues.

Report an error manually

LerixClient is a singleton in the container:
OrdersService.cs
CaptureException never throws and completes once the report has been accepted or given up on. You can also discard the task with _ = to keep going without waiting. Use CaptureMessage for something that was not thrown:

Parameters

BugType values

BugSeverity values

What is attached to a report

Stack traces include inner exceptions, each introduced by a --- caused by ... --- line.

File and line numbers

.NET only puts file and line numbers in stack traces when your app’s .pdb files are available at runtime. Add a Directory.Build.props file at the root of your repository:
Directory.Build.props
The SDK strips the deterministic /_/ root, so this frame:
is reported as src/Api/Orders.cs:line 42. A ContinuousIntegrationBuild build produces the same /_/ root. If stack traces arrive with no file or line at all, the SDK logs one warning per process that points to this page.

Other LerixClient members

Disable in tests

Set Enabled = false to turn every call into a no-op without changing your code: