Exception Handlers
An unlimited number of Exception Handlers can be added to a route to catch exceptions thrown during request execution. An exception handler can return three values indicating the status of the request:
- A return value of
true
indicates that the exception should not halt request execution, and that the request should continue with the next route registered for the request path.- If
true
is returned when there are no routes left, the server will return an empty response.
- If
- A return value of
false
indicates that request execution should halt immediately and not call any other exception handlers.- In this case, the exception handler should write directly to the response body with a message indicating why the request failed. Otherwise no content will be returned.
- A return value of
null
indicates that the exception was not handled here and the next exception handler registered for the route should be called.- If
null
is returned for the last registered exception handler, it has the same effect as returningtrue
.
- If
Builder Methods
Low-Level Methods
These methods are primarily used when you've implemented your own IExceptionHandler and want to attach it to a route.
High-Level Methods
Builder Prefix: Catch
- Catch(Action<Exception, HttpContext>)
- Catch(Action<Exception>)
- Catch(Func<Exception, HttpContext, Nullable<Boolean>>)
- Catch(Func<Exception, Nullable<Boolean>>)
- Catch<TException>(IExceptionHandler)
- Catch<TException>(Action<Exception, HttpContext>)
- Catch<TException>(Action<Exception>)
- Catch<TException>(Func<Exception, HttpContext, Nullable<Boolean>>)
- Catch<TException>(Func<Exception, Nullable<Boolean>>)
- CatchAsync(Func<Exception, HttpContext, Boolean, Task<Nullable<Boolean>>>)
- CatchAsync(Func<Exception, HttpContext, Task<Nullable<Boolean>>>)
- CatchAsync(Func<Exception, HttpContext, Task>)
- CatchAsync(Func<Exception, Task<Nullable<Boolean>>>)
- CatchAsync(Func<Exception, Task>)
- CatchAsync<TException>(Func<Exception, HttpContext, Boolean, Task<Nullable<Boolean>>>)
- CatchAsync<TException>(Func<Exception, HttpContext, Task<Nullable<Boolean>>>)
- CatchAsync<TException>(Func<Exception, HttpContext, Task>)
- CatchAsync<TException>(Func<Exception, Task<Nullable<Boolean>>>)
- CatchAsync<TException>(Func<Exception, Task>)
- CatchExceptions(Boolean)
- FailOnInvalidAuth()
Examples
Using a default exception handler
The CatchExceptions(Boolean) method adds the SimpleExceptionHandler to the route, which catches all exceptions, writing a message for most exceptions, but continuing request execution if authentication fails and there are more routes registered for the path. See Authentication for more details.
app.UseSeltzr<MyModel>(api => {
api
.CatchExceptions()
.FilterByQueryEqual(m => m.Id);
});
GET https://localhost:5000/?id=20000000000
Unable to parse parameter value "20000000000"
Reason: Value was either too large or too small for an Int32.
Catching all exceptions
The CatchAsync(Func<Exception, Task<Nullable<Boolean>>>) method will add an exception handler that is called for all exceptions
app.UseSeltzr<MyModel>(api => {
api
.CatchAsync(async (e, c) => {
await c.Response.WriteAsync("An error occurred");
return false;
})
});
Catching a specific exception
The CatchAsync<TException>(Func<Exception, Task<Nullable<Boolean>>>) method will add an exception handler that is called for all exceptions
app.UseSeltzr<MyModel>(api => {
api
.CatchAsync<ParsingFailedException>(async (e, c) => {
await c.Response.WriteAsync("Failed to parse request body");
return false;
})
});
Logging an exception, but taking no action
The Catch(Action<Exception, HttpContext>) takes in an exception handler that doesn't return anything.
app.UseSeltzr<MyModel>(api => {
api
.Catch((e, c) => {
c.RequestServices.GetRequiredService<ILogger<MyModel>>().LogError(e, "An error occurred");
});
});