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.
• 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 returning true.

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.

• AddExceptionHandler(IExceptionHandler)
• AddExceptionHandler<THandler>()
• ClearExceptionHandlers()

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.

C#

Copy

app.UseSeltzr<MyModel>(api => {
    api
		.CatchExceptions()
		.FilterByQueryEqual(m => m.Id);
});

Request

GET https://localhost:5000/?id=20000000000

Response

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

C#

Copy

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

C#

Copy

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.

C#

Copy

app.UseSeltzr<MyModel>(api => {
    api
		.Catch((e, c) => {
			c.RequestServices.GetRequiredService<ILogger<MyModel>>().LogError(e, "An error occurred");
		});
});