Tooark.Exceptions 4.6.0

Tooark.Exceptions

Library that provides standardized exceptions for .NET projects, mapped to HTTP status codes and supporting several ways to build error messages.

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

Contents

• Installation
• Overview
• Supported Features
• Error Messages
• Available Exceptions
• Usage Examples
• Dependencies
• Contributing
• License

Installation

dotnet add package Tooark.Exceptions

The package has no configuration and no container registration: the exceptions are thrown and caught directly.

Overview

Every specific exception of the package inherits from TooarkException, which in turn inherits from Exception. The base class is abstract and its constructors are protected — it is not instantiated directly, but extended, either by the package's exceptions or by your application's.

The base class concentrates:

• error messages (GetErrorMessages());
• equivalent notifications (GetNotifications());
• the HTTP status code contract (GetStatusCode()).

Two guarantees hold for every constructor:

• The collections are read-only. GetErrorMessages() and GetNotifications() always return the same read-only instance, so no external code can empty or alter the error the exception carries — which would make a failure vanish in the middle of its handling.
• The collections are never empty. Null, empty or message-less input records a known key instead of producing an exception that claims to be an error but carries none. The two readings go together: the same position describes the same error in both.

Supported Features

The exception classes support the following constructors:

Overload resolution: new NotFoundException("Failure: {0}", exceptionObject) binds to the inner exception constructor, not the formatting one, because Exception is the more specific parameter. To format using an exception as argument, convert it first (for instance ex.Message).

When formatting, a format incompatible with the parameters does not throw: the message is kept as received. The exception exists to report the original error, and failing in its own presentation would trade the real error for a FormatException. Messages with literal braces, such as JSON, fall into this case.

Error Messages

The static class ExceptionErrorMessages gathers the messages generated by the package itself. They are translation keys, not final texts.

Null handling:

Available Exceptions

The parenthesis shows the System.Net.HttpStatusCode member. For 413 .NET keeps the old name RequestEntityTooLarge, although RFC 7231 calls the status Payload Too Large.

Usage Examples

1) Simple message

throw new BadRequestException("Invalid payload.");

2) Multiple messages

throw new BadRequestException([
  "Name is required.",
  "Invalid email."
]);

3) Formatted message

var userId = 42;
throw new NotFoundException("User with ID {0} not found.", userId);

4) From a Notification

Creating notifications is protected, so the notifying object is the one that notifies:

using Tooark.Notifications;

public sealed class DomainNotification : Notification
{
  public void NotifyRequired(string field) =>
    AddNotification($"{field} is required.", field, "T.DOM1");
}

var notification = new DomainNotification();
notification.NotifyRequired("Document");
notification.NotifyRequired("Phone");

throw new BadRequestException(notification);

The notification items are preserved as they are, keeping the key and the code of each one.

5) Preserving the root cause

try
{
  await _httpClient.GetAsync(url, cancellationToken);
}
catch (HttpRequestException ex)
{
  // The original exception stays reachable in InnerException, for diagnostics
  throw new BadGatewayException("Payment service unavailable.", ex);
}

6) Standardized handling

using Tooark.Exceptions;

try
{
  throw new ServiceUnavailableException("External service unavailable.");
}
catch (TooarkException ex)
{
  var statusCode = ex.GetStatusCode();
  var errors = ex.GetErrorMessages();
  var notifications = ex.GetNotifications();

  Console.WriteLine($"Status: {(int)statusCode} - {statusCode}");
  Console.WriteLine($"First error: {errors[0]}");
  Console.WriteLine($"Notification count: {notifications.Count}");
}

errors[0] is safe: the collections are never empty.

7) State conflict (409)

throw new ConflictException("A user with this email already exists.");

8) Payload too large (413)

throw new PayloadTooLargeException(
  "File exceeds the allowed limit of {0} MB.",
  10
);

9) Unsupported media type (415)

throw new UnsupportedMediaTypeException("Content-Type 'text/plain' is not supported.");

10) Unprocessable entity (422)

throw new UnprocessableEntityException([
  "CPF invalid for the business rule.",
  "Birth date incompatible with the registration."
]);

11) Too many requests (429)

throw new TooManyRequestsException("Request limit exceeded. Try again in a few seconds.");

12) Creating your own exception

The hierarchy is open: inherit from TooarkException and provide the HTTP status code. Every base constructor becomes available, with the same read-only and never-empty collection guarantees.

using System.Net;
using Tooark.Exceptions;
using Tooark.Notifications;

public class PaymentRequiredException : TooarkException
{
  public PaymentRequiredException(string message) : base(message) { }

  public PaymentRequiredException(string message, Exception innerException)
    : base(message, innerException) { }

  public PaymentRequiredException(IList<string> messages) : base(messages) { }

  public PaymentRequiredException(Notification notification) : base(notification) { }

  public PaymentRequiredException(string messageFormat, params object[] args)
    : base(messageFormat, args) { }

  public override HttpStatusCode GetStatusCode() => HttpStatusCode.PaymentRequired;
}

The catch (TooarkException ex) of the standardized handling now catches it together with the others.

Dependencies

The package does not depend on ASP.NET Core: the HTTP status code is exposed as System.Net.HttpStatusCode, from the runtime itself, and translating it into the response is up to the application.

Contributing

Contributions are welcome! Feel free to open issues and pull requests in the Tooark.Exceptions repository.

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.