Exceptions
This convention explains how exceptions are designed, named and placed in the toolkit and in applications built on it. Every failure must be identifiable by type, carries its own message, and can still be caught by the native .NET type that callers already handle.
Recommendation, not a requirement. The packages work without following this convention. It is a rule only for code in the toolkit repository (see Contributing); applications can adopt it, adapt it or skip it. Opting out or adapting explains how.
Why
Failures identifiable by type can be caught, logged, mapped and alerted on precisely, while wrapping the native types keeps existing catch blocks working. See the Explicit failures value.
The four rules
- Every thrown exception is specialized. Never
throw new Exception(...),ArgumentException,InvalidOperationException,JsonExceptionor other native exceptions directly. Throw a custom type instead. - Custom exceptions extend a
Corebase whenever possible. The primitives wrap the native exceptions, socatch (ArgumentException)keeps working when you throwEmptyArgumentException. - Prefer the least context-specific exception. If a generic exception describes the failure (an empty argument, an undefined enum value, a missing environment variable), throw that. Only if the failure is truly contextual, create a specific exception that extends a mid-level one and encapsulates its own message.
- Exception classes live in an
Exceptionsfolder and namespace, never next to the code that throws or catches them. The more specific the exception, the closer itsExceptionsfolder is to where it is used.
The primitives
All of these live in Anarchy.Toolkit.Core.Exceptions (src/Core/Exceptions).
| Primitive | Wraps | Use for |
|---|---|---|
InvalidArgumentException |
ArgumentException |
Base for argument validation failures. |
↳ EmptyArgumentException |
A string or collection argument is null, empty or whitespace. | |
↳ InvalidEnumTypeException |
A Type argument must be an enum but is not. |
|
OutOfRangeArgumentException |
ArgumentOutOfRangeException |
Base for values outside the accepted set. |
↳ UndefinedEnumValueException |
An enum value is not defined (Enum.IsDefined fails, switch default arm). |
|
InvalidStateException |
InvalidOperationException |
Base for operations that cannot run in the current object or environment state. |
↳ MissingEnvironmentVariableException |
A required environment variable is not set. | |
InvalidFormatException |
FormatException |
A value cannot be parsed into or formatted as a target type. Has a generic (value, targetType) constructor. |
JsonParsingException |
System.Text.Json.JsonException |
Base for JSON parsing failures, safe to throw from JsonConverters. |
↳ UnexpectedJsonTokenException |
The reader sits on a token the converter cannot handle. | |
↳ UnexpectedJsonEndException |
The input ends before the value was fully read. | |
↳ EmptyJsonValueException |
A null or empty value where one is required. | |
↳ InvalidJsonValueException |
A well-formed value that is not valid for the target type. | |
NotFoundException |
Exception |
Base for “the thing you asked for does not exist”. |
↳ PropertyNotFoundException |
A property cannot be found through reflection. | |
ExternalDependencyException |
Exception |
Base for failures of a database, broker, secret store, identity provider or external process. Keep the original failure as the inner exception. |
OperationTimeoutException |
TimeoutException |
An operation exceeded its allotted time. |
UnsupportedOperationException |
NotSupportedException |
Base for intentionally unsupported operations. |
↳ UnsupportedTypeException |
A code path received a type it cannot handle. |
If none of these fits, first ask whether a new generic primitive is warranted (it would be reused across projects). Only then add one to Core, wrapping the matching native exception.
Choosing what to throw
Is there a generic primitive that describes the failure?
├── yes → throw it, with its structured constructor
│ throw new EmptyArgumentException(nameof(messages));
│ throw new UndefinedEnumValueException(nameof(instanceType), instanceType);
│ throw new MissingEnvironmentVariableException("DATABASE_URL");
└── no → is there a mid-level exception for this area (storage, broker, events...)?
├── yes → create a specific exception extending it, with its own message
└── no → create the mid-level first (extending a primitive), then the specific one
A specific exception encapsulates its message: the throw site passes data, never prose.
// Correct: the exception type owns the message
public class DbConnectionReleaseException(Exception innerException)
: DbPolicyExecutionException("Error releasing connection", innerException);
throw new DbConnectionReleaseException(exception);
// Incorrect: the throw site writes the message
throw new DbPolicyExecutionException("Error releasing connection", exception);
Expose the data that explains the failure as properties (SecretName, FailedMessageCount, EnumType, …) so that handlers and logs do not need to parse messages.
Mid-level exceptions
A mid-level exception groups the failures of one area so callers can catch them together. It takes a message (and usually an inner exception) and is extended by the specific exceptions; it is not normally thrown directly. Examples:
| Mid-level | Extends | Specific exceptions |
|---|---|---|
MessageBrokerPublisherException |
ExternalDependencyException |
MessagePublishException, MessageBatchPublishException |
MessageBrokerParsingException |
InvalidFormatException |
EventEnvelopeParsingException |
StoragePolicyExecutionException → DbPolicyExecutionException |
ExternalDependencyException |
DbConnectionAcquisitionException, DbConnectionReleaseException |
UnitOfWorkTransactionException |
TransactionException |
TransactionBeginException, TransactionCommitException, TransactionRollbackException, SessionAlreadyActiveException, SessionFinishException |
UnitOfWorkSessionException |
TransactionException |
SessionCallbackException |
UnableToHandleEventException |
Exception |
EventHandlerExecutionException, StateAlreadyInitializedEventHandlerException |
StorageException → PersistenceStorageException |
Exception |
EmptyEntityListForBatchSaveStorageException, DuplicatedEntityStorageException |
InvalidStartupTypeExceptionBase (abstract) |
InvalidStateException |
MissingStartupInterfaceException, MissingStartupConstructorException |
Where exception classes live
Exceptions always live in an Exceptions folder whose namespace matches the folder. Place that folder at the lowest common ancestor of the code that throws and catches the exception:
| Reach | Location | Example |
|---|---|---|
| Any project | src/Core/Exceptions |
EmptyArgumentException |
| An abstraction shared by several implementations | the abstraction project, next to the contract | Core.Persistence.Abstractions/Service/Storage/Exceptions/TransactionCommitException.cs (thrown by any IUnitOfWork) |
| One area of one project | the area’s folder | Core.Events/Domain/Exceptions |
| One class or feature | a sibling Exceptions folder |
Web/Helper/Presentation/Contract/Exceptions/MissingRouteParameterException.cs |
Never declare an exception in the same file or folder as the class that throws it, and never name the folder Exception (singular): it shadows System.Exception inside the parent namespace.
Writing an exception class
- Name it after the failure, ending in
Exception:UserNotFoundException, notUserServiceException2. - Use a primary constructor; pass the encapsulated message to the base.
- Add a
/// <summary>Thrown when ...</summary>doc comment. - Accept
Exception innerExceptionwhen you wrap a caught failure, and always pass it on. - Keep
sealed/abstractfor when it matters:abstractfor mid-levels that must never be thrown directly.
namespace Anarchy.Toolkit.Configuration.Service.AppSecret.Exceptions;
/// <summary>
/// Thrown when the secret store fails to return a secret.
/// </summary>
public class SecretRetrievalException(string secretName, Exception innerException)
: ExternalDependencyException(
$"Error getting secret with name: {secretName} returned: {innerException.Message}", innerException)
{
public string SecretName { get; } = secretName;
}
Catching and wrapping
- Catch the narrowest type you can handle. When wrapping everything in a
try, do not swallow your own specific exceptions:catch (Exception e) when (e is not SecretNotFoundException). - When wrapping, keep the original as the inner exception.
- Re-throw with
throw;, neverthrow ex;.
Base types change HTTP status codes
ExceptionMiddleware (Web) chooses the response status from the native base type: InvalidOperationException and Newtonsoft’s JsonException become 400, everything else 500. UnitOfWorkSessionException is unwrapped to its base exception first.
So picking a base is also picking a status code. InvalidStateException derives from InvalidOperationException and therefore returns 400. When you re-base an existing exception, check that it keeps the status code its callers expect.
Allowed exceptions to rule 1
These stay native on purpose:
- Null guards:
ArgumentNullException.ThrowIfNull(x)andx ?? throw new ArgumentNullException(nameof(x)). They are the idiomatic BCL guard and analyzers (CA1510) prefer them. - Cancellation:
cancellationToken.ThrowIfCancellationRequested(). - Re-throws:
throw;, and re-throwing an exception that was already thrown elsewhere. - Caller-supplied factories, such as
throw errorFunc(statusCode). - Third-party contracts that require a specific type with no primitive equivalent, like Newtonsoft’s
JsonSerializationExceptioninside aContractResolver. Still create a specific subclass (ConstructorParameterCasingException) in anExceptionsfolder.
Checklist
- No
throw new <NativeException>(...)outside the allowed cases. - The exception extends a primitive or a mid-level that does.
- A generic primitive was used if one describes the failure.
- The message is defined by the exception class, not the throw site.
- Inner exceptions are preserved.
- The class lives in the nearest
Exceptionsfolder shared by its throwers and catchers. - The base type keeps the expected HTTP status in
ExceptionMiddleware. - Tests assert the specific type (AwesomeAssertions’
Throw<T>also matches derived types).
Opting out or adapting
| You want to… | Do this |
|---|---|
Throw native exceptions (ArgumentException, …) |
Possible; the toolkit catches by native base type, so its behaviour does not change. |
| Map exceptions to HTTP responses your own way | Don’t use ExceptionMiddleware: register your own exception handler (or UseExceptionHandler) with a mapping per type. Common reasons: problem-details bodies, or ArgumentException as 400 instead of 500. |
| Keep exception classes next to the code that throws them | Fine for an application; the where they live table matters most for shared libraries. |
What you lose by opting out: precise status codes from ExceptionMiddleware and type-based alerting.