ArchSoft.CustomExceptions 1.0.4

ArchSoft.CustomExceptions

English | Português (Brasil)

A comprehensive collection of domain-specific custom exceptions for .NET applications. This library extends ArchSoft.Http.Exceptions to provide typed exceptions for common scenarios like business rules, resource management, security, and more.

Installation

dotnet add package ArchSoft.CustomExceptions

Features

• Domain-specific exceptions – Business, Resource, Security, Concurrency, and more
• Built on HTTP exceptions – Extends ArchSoft.Http.Exceptions for seamless API integration
• Factory pattern support – Use HttpExceptionFactory and HttpStatusCodeFactory from the base library
• Clean architecture friendly – Separate domain errors from transport-layer concerns

Exception Categories

Api

Exceptions for API communication failures.

Auth

Authentication and authorization exceptions.

Broker

Message broker exceptions (Kafka, RabbitMQ, etc.).

Business

Business rule validation exceptions.

Concurrency

Concurrency control exceptions.

Configuration

Configuration-related exceptions.

Integration

External service integration exceptions.

IO

Input/Output operation exceptions.

Operation

General operation exceptions.

Process

Data processing exceptions.

Resource

Resource management exceptions.

Resilience

Resilience pattern exceptions (circuit breaker, rate limiting, etc.).

Security

Security-related exceptions.

Unavailable

Service availability exceptions.

Unexpected

Unexpected error exceptions.

Usage Examples

Basic Usage

using ArchSoft.CustomExceptions.Exceptions.Resource;

public class UserService
{
    public User GetUser(Guid id)
    {
        var user = _repository.Find(id);

        if (user == null)
            throw new ResourceNotFoundException($"User with id {id} not found");

        return user;
    }
}

Business Rule Validation

using ArchSoft.CustomExceptions.Exceptions.Business;

public class OrderService
{
    public void PlaceOrder(OrderRequest request)
    {
        if (request.Items.Count == 0)
            throw new ValidationException("Order must contain at least one item");

        if (request.TotalAmount <= 0)
            throw new RuleException("Order total must be greater than zero");

        // Process order...
    }
}

Concurrency Control

using ArchSoft.CustomExceptions.Exceptions.Concurrency;

public class DocumentService
{
    public void UpdateDocument(Guid id, DocumentUpdate update, long expectedVersion)
    {
        var document = _repository.Get(id);

        if (document.Version != expectedVersion)
            throw new VersionMismatchException(
                $"Document version mismatch. Expected: {expectedVersion}, Actual: {document.Version}");

        // Update document...
    }
}

Security Operations

using ArchSoft.CustomExceptions.Exceptions.Security;

public class CryptoService
{
    public string Decrypt(string cipherText)
    {
        try
        {
            return _encryptionProvider.Decrypt(cipherText);
        }
        catch (CryptographicException ex)
        {
            throw new DecryptionException("Failed to decrypt data", ex);
        }
    }
}

Using Factories

Since all exceptions extend ArchSoft.Http.Exceptions, you can use the factories from that package:

Creating Exceptions by HTTP Status Code

using ArchSoft.Http.Exceptions.Factories;
using System.Net;

// Create appropriate exception based on status code
var ex = HttpExceptionFactory.Create(HttpStatusCode.NotFound, "Resource not found");
throw ex;

Mapping Exceptions to HTTP Status Codes

using ArchSoft.Http.Exceptions.Factories;
using Microsoft.AspNetCore.Http;

public async Task InvokeAsync(HttpContext context)
{
    try
    {
        await _next(context);
    }
    catch (Exception ex)
    {
        // Automatically maps custom exceptions to appropriate HTTP status codes
        var statusCode = new HttpStatusCodeFactory().Create(ex);
        context.Response.StatusCode = (int)statusCode;
        await context.Response.WriteAsync(ex.Message);
    }
}

Complete Middleware Example

using System.Text.Json;
using ArchSoft.Http.Exceptions.Factories;

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unhandled exception occurred");

            var statusCode = new HttpStatusCodeFactory().Create(ex);
            context.Response.StatusCode = (int)statusCode;
            context.Response.ContentType = "application/json";

            var response = new
            {
                error = ex.Message,
                statusCode = (int)statusCode,
                timestamp = DateTime.UtcNow
            };

            await context.Response.WriteAsync(JsonSerializer.Serialize(response));
        }
    }
}

Register in Program.cs:

app.UseMiddleware<ExceptionHandlingMiddleware>();

Requirements

• .NET 8.0 or .NET 9.0 (multi-targeted)
• ArchSoft.Http.Exceptions 1.0.2 or higher

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

Developed by ArchSoft - Software Architecture Solutions