Xpandables.Entities.Data 10.0.0

<div align="center">

📦 Xpandables.Net

A comprehensive, modular .NET library for building modern, scalable applications with clean architecture patterns

Features • Getting Started • Documentation • Real-World Example • Architecture • Contributing

</div>

📋 Overview

Xpandables.Net is a powerful, production-ready library ecosystem designed to accelerate .NET application development while promoting best practices, clean architecture, and maintainable code. Built with .NET 10 and leveraging the latest C# language features, it provides a rich set of tools for enterprise-grade applications.

💡 Philosophy

• 🧩 Modular Design: Pick only what you need - each package is independently versioned and maintained
• ⚡ Performance First: Built for high-performance scenarios with AOT compatibility
• 🔒 Type Safety: Leverage strong typing to catch errors at compile time
• ✅ Testability: Designed with unit testing and integration testing in mind
• 📖 Well Documented: Comprehensive XML documentation for IntelliSense support

🎯 Key Features

Core Capabilities

🚀 Getting Started

Prerequisites

• .NET 10 SDK or later
• Visual Studio 2026 (or later) or JetBrains Rider 2025.3+ (recommended)
• Basic understanding of C# and async/await patterns

Installation

Install the packages you need via NuGet Package Manager:

# Core operation result handling
dotnet add package System.Results

# Optional value handling
dotnet add package System.Optionals

# Mediator and pipeline support
dotnet add package System.Results.Tasks

# Pipeline decorators
dotnet add package System.Results.Pipelines

# Validation framework
dotnet add package System.Validation

# Repository pattern with EF Core
dotnet add package System.Entities.Data

# REST client
dotnet add package System.Rests

# Event sourcing
dotnet add package System.Events
dotnet add package System.Events.Data

# Async paging
dotnet add package System.AsyncPaged
dotnet add package System.AsyncPaged.Linq
dotnet add package System.AsyncPaged.Json

# ASP.NET Core integration
dotnet add package AspNetCore.Net
dotnet add package AspNetCore.AsyncPaged
dotnet add package AspNetCore.Events
dotnet add package AspNetCore.Results
dotnet add package AspNetCore.Composition

Quick Example

using System.Results;
using System.Results.Requests;
using System.Optionals;

// Define a request
public sealed record GetUserQuery(Guid UserId) : IRequest<User>;

// Handle the request
public sealed class GetUserHandler : IRequestHandler<GetUserQuery, User>
{
    private readonly IUserRepository _repository;
    
    public GetUserHandler(IUserRepository repository) 
        => _repository = repository;
    
    public async Task<Result<User>> HandleAsync(
        GetUserQuery request, 
        CancellationToken cancellationToken)
    {
        // Fetch user with Optional to handle null cases
        Optional<User> user = await _repository
            .FindByIdAsync(request.UserId, cancellationToken);
        
        return user
            .Map(u => Result.Success(u))
            .Empty(() => Result
                .NotFound<User>("userId", "User not found"));
    }
}

💼 Real-World Example

This repository includes a complete Event Sourcing Banking Sample API that demonstrates how to build a production-ready application using Xpandables.Net. See the SampleApi README for a detailed walkthrough.

Sample API Highlights

The Xpandables.Net.SampleApi project showcases:

✅ Event Sourcing & CQRS - Complete bank account management with domain events
✅ Minimal API Endpoints - Clean, modular endpoint definitions with IEndpointRoute
✅ EF Core Integration - Event store and outbox pattern with SQL Server
✅ Swagger Documentation - Fully documented API with OpenAPI support
✅ Docker Support - Production-ready containerization

Running the Sample

# Clone the repository
git clone https://github.com/Francescolis/Xpandables.Net.git
cd Xpandables.Net

# Navigate to sample project
cd Xpandables.Net.SampleApi

# Update connection string in appsettings.json
# Run migrations (automatic on startup)

# Run the application
dotnet run

# Navigate to Swagger UI
# https://localhost:5001/swagger

Key Files to Explore:

• Program.cs - Application setup with event sourcing
• BankAccounts/Features/CreateBankAccount/ - Complete CQRS command example
• EventStorage/ - Event store and outbox configuration

📚 Documentation

Package Documentation

Each package has detailed documentation with examples and API references:

Foundation Packages

• 🔧 System.Primitives - Core primitives and utilities
• ✅ System.Results - Operation result handling with request/handler pattern
• 🎁 System.Optionals - Null-safe optional value types

Application Layer

• 📡 System.Results.Tasks - Mediator pattern and request dispatching
• 🔗 System.Results.Pipelines - Pipeline decorators for validation, transactions, events
• ✔️ System.Validation - Specification pattern and rule validators
• 🧩 System.Composition - MEF-based service composition

Data Access

• 💾 System.Entities.Data - EF Core repository with DataContext

Event Handling

• 📝 System.Events - Event sourcing and domain events
• 🗄️ System.Events.Data - EF Core event store implementation

HTTP & REST

• 🌐 System.Rests - Type-safe REST client with attribute-based routing

Async & Utilities

• 🔄 System.AsyncPaged - Async paged collections
• 🔄 System.AsyncPaged.Linq - LINQ extensions for async paging
• 📄 System.AsyncPaged.Json - JSON serialization for paged data

ASP.NET Core Integration

• 🌐 AspNetCore.Net - ASP.NET Core minimal API with endpoint routing
• 📄 AspNetCore.AsyncPaged - Async paged response formatters
• 🌐 AspNetCore.Events - W3C trace context middleware
• ✅ AspNetCore.Results - Result type HTTP integrations
• 🔌 AspNetCore.Composition - MEF service composition

🏗️ Architecture

Xpandables.Net follows clean architecture principles with clear separation of concerns:

┌─────────────────────────────────────────┐
│         Presentation Layer              │
│  (AspNetCore.Net, AspNetCore.Events,    │
│   AspNetCore.AsyncPaged,                │
│   AspNetCore.Results)                   │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Application Layer               │
│  (System.Results, System.Results.Tasks, │
│   System.Results.Pipelines,             │
│   System.Composition)                   │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           Domain Layer                  │
│ (System.Events, System.Optionals,       │
│  System.Primitives, System.Validation,  │
│  System.AsyncPaged)                     │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│       Infrastructure Layer              │
│  (System.Entities.Data, System.Events.  │
│   Data, System.Rests,                   │
│   System.AsyncPaged.Linq)               │
└─────────────────────────────────────────┘

Design Patterns Implemented

• 📂 Repository Pattern - Abstraction over data access
• 🔄 Unit of Work - Transaction management
• 📡 Mediator Pattern - Decoupled request handling
• 🎨 Decorator Pattern - Pipeline behaviors
• 📋 Specification Pattern - Business rule encapsulation
• 📝 Event Sourcing - Event-driven architecture
• 🔀 CQRS - Command Query Responsibility Segregation
• ✅ Result Pattern - Functional error handling

💎 Highlights

1. Operation Results - Railway Oriented Programming

using System.Results;

public async Task<Result<Order>> CreateOrderAsync(CreateOrderRequest request)
{
    // Validate
    if (string.IsNullOrEmpty(request.CustomerId))
        return Result.Failure<Order>("customerId", "Customer ID is required");

    // Create order
    var order = new Order { CustomerId = request.CustomerId };
    await _repository.AddAsync(order);

    return Result.Created(order)
        .WithLocation($"/api/orders/{order.Id}");
}

2. Type-Safe REST Client

using System.Rests;

[RestPost("/api/users")]
public sealed record CreateUserRequest(string Name, string Email) 
    : IRestRequest<User>, IRestString;

var response = await _restClient.SendAsync(
    new CreateUserRequest("John", "john@example.com"));
    
var user = response.Result;

3. Fluent Validation with Specifications

using System.ComponentModel.DataAnnotations;

// Create specifications using factory methods
var nameSpec = Specification.IsNotNull<User, string>(u => u.Name);
var emailSpec = Specification.Contains<User>(u => u.Email, "@");
var ageSpec = Specification.GreaterThan<User, int>(u => u.Age, 18);

// Combine specifications
var validUser = Specification.All(nameSpec, emailSpec, ageSpec);

// Check if satisfied
if (validUser.IsSatisfiedBy(user))
{
    Console.WriteLine("User meets all criteria");
}

// Use in LINQ queries
var activeAdults = users.Where(validUser.Expression.Compile());

4. Event Sourcing with Aggregates

using System.Events.Aggregates;

public sealed class OrderAggregate : Aggregate
{
    public string OrderNumber { get; private set; } = string.Empty;
    public decimal TotalAmount { get; private set; }

    public static OrderAggregate Create(string orderNumber, decimal amount)
    {
        var aggregate = new OrderAggregate();
        aggregate.AppendEvent(new OrderCreatedEvent
        {
            OrderNumber = orderNumber,
            Amount = amount
        });
        return aggregate;
    }

    public void AddItem(string productId, decimal price)
    {
        AppendEvent(new ItemAddedEvent { ProductId = productId, Price = price });
    }

    // Event handlers (called automatically)
    private void On(OrderCreatedEvent evt)
    {
        OrderNumber = evt.OrderNumber;
        TotalAmount = evt.Amount;
    }

    private void On(ItemAddedEvent evt)
    {
        TotalAmount += evt.Price;
    }
}

// Usage
var order = OrderAggregate.Create("ORD-001", 100m);
order.AddItem("PROD-1", 25m);
await _aggregateStore.AppendAsync(order);

5. W3C Trace Context for Distributed Tracing

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Register event context with W3C trace support
builder.Services.AddXEventContext();
builder.Services.AddXEventContextMiddleware();

var app = builder.Build();

// Middleware reads traceparent header (W3C format) and establishes EventContext
app.UseXEventContextMiddleware();

app.MapPost("/api/orders", async (
    CreateOrderRequest request,
    IEventContextAccessor context,
    CancellationToken ct) =>
{
    // CorrelationId is automatically populated from traceparent header
    // or Activity.Current.Id, or generated as GUID string
    var correlationId = context.Current.CorrelationId; // W3C trace ID string

    // Events inherit correlation/causation for distributed tracing
    var order = OrderAggregate.Create(request.OrderNumber, request.Amount);
    await orderStore.SaveAsync(order, ct);

    return Results.Created($"/api/orders/{order.StreamId}", order);
});

app.Run();

🧪 Testing

The library includes comprehensive unit tests demonstrating usage patterns:

# Run all tests
dotnet test

# Run specific test project
dotnet test Xpandables.Net.UnitTests

📦 All Packages

🤝 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 Setup

1. Clone the repository

   git clone https://github.com/Francescolis/Xpandables.Net.git
   

2. Open in Visual Studio 2022 (17.13+) or Rider 2024.3+

3. Build the solution

   dotnet build
   

4. Run tests

   dotnet test
   

📄 License

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

Copyright © Kamersoft 2025
Licensed under the Apache License, Version 2.0

👤 Author

Francescolis

• GitHub: @Francescolis
• Company: Kamersoft

💬 Support

If you find this library useful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting issues
• 💡 Suggesting new features
• 📝 Improving documentation

<div align="center">

Built with ❤️ using .NET 10

⬆ back to top

</div>