A lightweight traceability library for building robust error handling in .NET applications using FluentResults patterns.
Get Started
$ dotnet add package Baubit.TraceabilityReadme
Baubit.Traceability
A lightweight .NET library for building robust error handling and result tracing in .NET applications using the FluentResults pattern.
Overview
Baubit.Traceability provides a comprehensive set of abstractions and extension methods for working with operation results, errors, and success states. It extends the popular FluentResults library with additional traceability features, making it easier to track, understand, and debug complex operation chains in your applications.
Features
- 🎯 Abstract Base Classes - Ready-to-use base classes for errors, reasons, and successes
- 🔍 Rich Traceability - Track operation results with metadata and timestamps
- 🛡️ Type-Safe Error Handling - Leverage .NET type system for robust error handling
- 🔄 FluentResults Integration - Seamlessly extends FluentResults with additional functionality
- 📦 Zero Configuration - Works out of the box with sensible defaults
Installation
dotnet add package Baubit.Traceability
Quick Start
Basic Error Handling
using Baubit.Traceability;
using FluentResults;
public class UserService
{
public Result<User> GetUser(int id)
{
var result = ValidateUserId(id);
if (result.IsFailed)
{
return result.ToResult<User>()
.AddReasonIfFailed(new UserNotFoundReason(id));
}
var user = FetchUserFromDatabase(id);
return Result.Ok(user);
}
}
Custom Errors and Reasons
using Baubit.Traceability.Errors;
using Baubit.Traceability.Reasons;
public class UserNotFoundError : AError
{
public UserNotFoundError(int userId)
: base([], $"User with ID {userId} was not found", new Dictionary<string, object>
{
{ "UserId", userId },
{ "Timestamp", DateTime.UtcNow }
})
{
}
}
public class UserNotFoundReason : AReason
{
public UserNotFoundReason(int userId)
: base($"User {userId} does not exist in the database", new Dictionary<string, object>
{
{ "UserId", userId }
})
{
}
}
Using Extension Methods
using Baubit.Traceability;
using FluentResults;
// Throw exception on failure
var result = PerformOperation()
.ThrowIfFailed();
// Add success markers
var successResult = Result.Ok(data)
.AddSuccessIfPassed(new OperationSuccess("Data loaded successfully"));
// Unwrap nested reasons
var reasons = complexResult.UnwrapReasons();
// Dispose resources safely
var disposables = new List<IDisposable> { resource1, resource2 };
var disposeResult = disposables.Dispose();
Working with Successes
using Baubit.Traceability.Successes;
public class DataSavedSuccess : ASuccess
{
public DataSavedSuccess(string entityId)
: base($"Data saved successfully for entity {entityId}", new Dictionary<string, object>
{
{ "EntityId", entityId },
{ "SavedAt", DateTime.UtcNow }
})
{
}
}
public Result SaveData(Data data)
{
// Save logic...
return Result.Ok()
.AddSuccessIfPassed(new DataSavedSuccess(data.Id));
}
API Reference
Base Classes
AError
Abstract base class for custom error types. Provides:
Message- Error messageReasons- List of nested error reasonsMetadata- Additional context as key-value pairsCreationTime- Timestamp when error was created
AReason
Abstract base class for custom reason types. Provides:
Message- Reason descriptionMetadata- Additional context as key-value pairsCreationTime- Timestamp when reason was created
ASuccess
Abstract base class for custom success types. Inherits from AReason and implements ISuccess.
Extension Methods
Result Extensions
ThrowIfFailed<TResult>()- ThrowsFailedOperationExceptionif result is failedThrowIfFailed<TResult>(Task<TResult>)- Async version of ThrowIfFailedAddSuccessIfPassed<TResult>(params ISuccess[])- Adds success markers when result succeedsAddReasonIfFailed(params IReason[])- Adds reasons when result failsAddErrorIfFailed<TError>(params TError[])- Adds errors when result failsUnwrapReasons<TResult>()- Recursively unwraps all reasons including nested exceptionsGetNonErrors<TResult>()- Returns only non-error reasons
Collection Extensions
Dispose<TDisposable>(IList<TDisposable>)- Safely disposes a collection of disposable objects
Exceptions
FailedOperationException
Exception thrown by ThrowIfFailed() when a result has failed. Contains the original IResultBase result.
Advanced Scenarios
Nested Error Unwrapping
try
{
var result = PerformComplexOperation()
.ThrowIfFailed();
}
catch (FailedOperationException ex)
{
var allReasons = ex.Result.UnwrapReasons();
// Process all reasons including those from nested exceptions
}
Conditional Success Tracking
var result = Result.Ok(data);
if (shouldLogSuccess)
{
result = result.AddSuccessIfPassed(
(r, successes) => r.WithSuccesses(successes),
new OperationSuccess("Operation completed")
);
}
Resource Cleanup
var resources = new List<IDisposable>
{
connection,
transaction,
reader
};
var cleanupResult = resources.Dispose();
if (cleanupResult.IsFailed)
{
logger.LogError("Failed to dispose resources", cleanupResult.Errors);
}
Building from Source
# Clone the repository
git clone https://github.com/pnagoorkar/Baubit.Traceability.git
cd Baubit.Traceability
# Build the solution
dotnet build
# Run tests
dotnet test
# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"
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.
Development Guidelines
- Ensure all tests pass before submitting PR
- Add tests for new functionality
- Maintain 100% code coverage
- Follow existing code style and conventions
- Update documentation for API changes
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
See ACKNOWLEDGEMENT.md for details on libraries and ideas that support this project.
Support
Copyright © 2025 Prashant Nagoorkar