CSharpEssentials

CSharpEssentials is a comprehensive ecosystem of .NET libraries designed to modernize C# development. It bridges the gap between Object-Oriented and Functional Programming, providing robust tools for error handling, domain modeling, and enterprise application development.

Goal: Make C# code more expressive, safer, and easier to test without sacrificing performance.

📦 Ecosystem Overview

CSharpEssentials is modular. You can use the meta-package to get everything, or install specific modules to keep dependencies light.

Package	Description	NuGet
CSharpEssentials	The meta-package including all core functional modules and exclusive bridge extensions.
CSharpEssentials.Core	Foundational extensions, guard clauses, and utilities (Strings, Collections, GUIDs).
CSharpEssentials.Results	Railway-oriented programming with Result and Result<T> patterns.
CSharpEssentials.Maybe	Maybe<T> monad for null-safe optional value handling.
CSharpEssentials.Errors	Structured error handling with unique codes and standard types (NotFound, Validation, etc.).
CSharpEssentials.Rules	Composable business rule engine (And, Or, Linear, Conditional logic).
CSharpEssentials.Any	Discriminated Unions (Any<T1, T2, ...>) for type-safe polymorphic returns.
CSharpEssentials.Entity	Domain-Driven Design base classes (EntityBase, SoftDeletableEntityBase).
CSharpEssentials.EntityFrameworkCore	EF Core extensions, Interceptors (Slow Query), and Pagination support.
CSharpEssentials.AspNetCore	Web API utilities: Global Exception Handler, Problem Details, API Versioning.
CSharpEssentials.Json	Advanced JSON serialization: Polymorphism, String Enums, Multi-format Dates.
CSharpEssentials.Time	Testable IDateTimeProvider abstraction and extensions.
CSharpEssentials.RequestResponseLogging	Highly configurable HTTP traffic logging middleware.
CSharpEssentials.GcpSecretManager	Google Cloud Secret Manager integration for IConfiguration.
CSharpEssentials.Clone	Type-safe deep cloning interfaces and extensions.
CSharpEssentials.Enums	Attributes for controlling Enum serialization behavior.

🚀 Getting Started

Install the main package to get the core functional tools:

dotnet add package CSharpEssentials

Or pick individual packages as needed (e.g., dotnet add package CSharpEssentials.Results).

💡 Feature Highlights

1. Functional Error Handling (Results & Errors)

Stop throwing exceptions for flow control. Use Result<T> to express success or failure explicitly.

using CSharpEssentials.ResultPattern;
using CSharpEssentials.Errors;

public Result<User> RegisterUser(string email)
{
    if (string.IsNullOrEmpty(email))
        return Error.Validation("User.EmailRequired", "Email cannot be empty.");

    if (_repo.Exists(email))
        return Error.Conflict("User.Exists", "User already exists.");

    var user = new User(email);
    return user; // Implicit conversion to Result<User>
}

2. Safe Optionals (Maybe)

Eliminate NullReferenceException by explicitly modeling the absence of a value.

using CSharpEssentials.Maybe;

public Maybe<User> GetUserById(Guid id)
{
    var user = _repo.Find(id);
    return user; // Implicit conversion from User?
}

// Chaining with LINQ
var zipCode = GetUserById(id)
    .Map(u => u.Address)
    .Map(a => a.ZipCode)
    .GetValueOrDefault("00000");

3. Business Rules Engine

Compose complex logic from simple, reusable rules.

var rule = Rule.And(
    new MinimumAgeRule(18),
    new KycCompletedRule()
);

var result = RuleEngine.Evaluate(rule, userContext);

4. Robust Web APIs (AspNetCore)

Automatically convert Result failures into standard RFC 7807 Problem Details responses using the Global Exception Handler.

// Program.cs
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddEnhancedProblemDetails();

// Controller
[HttpPost]
public IActionResult Create(CreateUserRequest request)
{
    Result<User> result = _service.Create(request);
    
    // Returns 200 OK with data, or 400/404/409 ProblemDetails based on Error Type
    return result.ToActionResult(); 
}

5. Domain Modeling (Entity)

Build rich domain models with built-in Audit logs and Domain Events.

public class Order : EntityBase<Guid>
{
    public void MarkAsPaid()
    {
        Status = OrderStatus.Paid;
        Raise(new OrderPaidEvent(Id)); // Domain Event
        SetUpdatedInfo(DateTimeOffset.UtcNow, "System"); // Auditing
    }
}

🛠️ Development & Publishing

This repository includes a smart build script (build-and-publish-nugets.sh) that manages dependency orders and versioning for all packages.

# Build and Test all packages
./build-and-publish-nugets.sh

# Publish to NuGet (requires API Key)
./build-and-publish-nugets.sh --parallel YOUR_API_KEY

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md guide.

📄 License

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

🙏 Acknowledgments

Inspired by excellent community projects like ErrorOr, CSharpFunctionalExtensions, and OneOf.

Star History