ViewForge 1.0.0

ViewForge ⚒️

A high-performance .NET library that dynamically maps SQL Views to strongly-typed models with built-in dynamic filtering, sorting, and pagination — all via a clean, fluent API. No manual SQL building required.

✨ Features

• 🎯 Auto Model Mapping — Maps view columns to C# properties (snake_case, PascalCase, camelCase, custom)
• 🔍 Dynamic Filtering — Filter by any field: string, int, double, decimal, DateTime, Guid, bool, and all nullable variants
• 📊 Dynamic Sorting — Sort by any property with asc/desc support, multi-column sorting
• 📄 Pagination — Built-in PagedResult<T> with fully parameterized page/pageSize
• 🏷️ Attribute-Based Config — [ViewName], [ViewColumn], [ViewIgnore], [Filterable], [Sortable]
• ⚡ Expression Tree Based — Builds Expression<Func<T, bool>> dynamically — SQL-injection safe
• 🎛️ Fluent API + String API — Use type-safe expressions or query string filters
• 🌍 Multi-Target — .NET 7 / .NET 8 / .NET 9 / .NET 10

📦 Installation

dotnet add package ViewForge

Or via Package Manager:

Install-Package ViewForge

🚀 Quick Start

1. Define Your View Model

using ViewForge.Attributes;

[ViewName("vw_product_summary")]
public class ProductSummaryView
{
    public Guid Id { get; set; }
    public string ProductName { get; set; }
    public decimal TotalSales { get; set; }
    public int Quantity { get; set; }
    public DateTime CreatedDate { get; set; }
    public Guid? CategoryId { get; set; }
    public string? CategoryName { get; set; }

    [ViewIgnore]
    public string DisplayName => $"{ProductName} ({CategoryName})";
}

2. Register ViewForge

builder.Services.AddViewForge(options =>
{
    options.DefaultNamingConvention = NamingConvention.SnakeCase;
    options.DefaultPageSize = 25;
    options.MaxPageSize = 100;
    options.CaseInsensitiveFilters = true;
});

3. Use in Your Controller

[HttpGet]
public async Task<PagedResult<ProductSummaryView>> GetProducts(
    [FromQuery] string? filters,
    [FromQuery] string? sorting,
    [FromQuery] int page = 1,
    [FromQuery] int pageSize = 20,
    CancellationToken ct = default)
{
    var filterGroup = _filterParser.Parse(filters);
    var sortDescriptors = SortBuilder.Parse(sorting);

    return await _dbContext.ProductSummaries
        .ApplyFilters(filterGroup, _filterBuilder)
        .ApplySorting(sortDescriptors, _sortBuilder)
        .ToPagedResultAsync(page, pageSize, ct);
}

🔍 Dynamic Filtering

Supported Filter Operators

Supported Types

All operators work with: string, int, long, double, decimal, float, bool, DateTime, DateTimeOffset, Guid, TimeSpan — and all nullable variants (int?, DateTime?, Guid?, etc.).

Query String Format

GET /api/products?filters=ProductName~contains~keyboard;Price~gt~100;CreatedDate~btw~2024-01-01,2024-12-31&sorting=TotalSales desc,ProductName asc&page=1&pageSize=20

Multiple filters are separated by ; and combined with AND logic.

Programmatic API

// Build filters programmatically
var filters = FilterGroup.And(
    FilterDescriptor.Create("ProductName", FilterOperator.Contains, "keyboard"),
    FilterDescriptor.Create("Price", FilterOperator.GreaterThan, 100m),
    FilterDescriptor.Create("CategoryId", FilterOperator.IsNotNull)
);

// Or use OR logic
var orFilters = FilterGroup.Or(
    FilterDescriptor.Create("Status", FilterOperator.Equals, "Active"),
    FilterDescriptor.Create("Priority", FilterOperator.Equals, "High")
);

📊 Dynamic Sorting

// From query string
var sorts = SortBuilder.Parse("TotalSales desc, ProductName asc");

// Alternative minus syntax
var sorts2 = SortBuilder.Parse("-TotalSales, ProductName");

// Programmatic
var sorts3 = new List<SortDescriptor>
{
    SortDescriptor.Create("TotalSales", SortDirection.Descending),
    SortDescriptor.Create("ProductName", SortDirection.Ascending)
};

📄 Pagination

Pagination is fully parameterized — page and pageSize come from external sources (controller parameters, query strings, etc.):

// page & pageSize are passed from controller parameters
public async Task<PagedResult<ProductView>> GetProducts(
    int page = 1, int pageSize = 20, CancellationToken ct = default)
{
    return await _dbContext.ProductSummaries
        .ApplyFilters(filterGroup, _filterBuilder)
        .ApplySorting(sortDescriptors, _sortBuilder)
        .ToPagedResultAsync(page, pageSize, ct);
}

PagedResult Response

{
    "items": [...],
    "totalCount": 150,
    "page": 1,
    "pageSize": 20,
    "totalPages": 8,
    "hasPreviousPage": false,
    "hasNextPage": true
}

🏷️ Attributes

[ViewName("vw_orders", Schema = "sales")]
public class OrderView
{
    [ViewColumn("order_total")]
    public decimal Total { get; set; }

    [Filterable(AllowedOperators = new[] { FilterOperator.Equals, FilterOperator.In })]
    public string Status { get; set; }

    [ViewIgnore]
    public string ComputedField => "...";
}

🔧 Configuration

builder.Services.AddViewForge(options =>
{
    options.DefaultNamingConvention = NamingConvention.SnakeCase;  // snake_case column mapping
    options.AllPropertiesFilterableByDefault = true;               // all props filterable
    options.AllPropertiesSortableByDefault = true;                 // all props sortable
    options.CaseInsensitiveFilters = true;                        // case-insensitive string filters
    options.DefaultPageSize = 20;                                  // default page size
    options.MaxPageSize = 100;                                     // max allowed page size
    options.FilterSeparator = "~";                                 // PropertyName~operator~value
    options.FilterDelimiter = ";";                                 // filter1;filter2;filter3
});

Available Options

📁 Project Structure

ViewForge/
├── src/
│   ├── ViewForge/                     # Core NuGet library
│   │   ├── Attributes/               # ViewName, ViewColumn, ViewIgnore, Filterable, Sortable
│   │   ├── Builders/                  # FilterBuilder, SortBuilder, FilterParser
│   │   ├── Configuration/            # ViewForgeOptions
│   │   ├── Enums/                     # FilterOperator, SortDirection, LogicalOperator
│   │   ├── Extensions/               # DI registration, IQueryable extensions
│   │   ├── Mapping/                  # ViewMapper, NamingConventionHelper
│   │   ├── Models/                   # PagedResult, FilterDescriptor, SortDescriptor
│   │   └── Providers/                # IViewQueryProvider, EfCoreViewQueryProvider
│   │
│   ├── ViewForge.Sample/             # Sample API project
│   └── ViewForge.Tests/              # Unit tests (50 tests)
│
├── .github/workflows/                # CI/CD pipelines
├── ViewForge.sln
└── README.md

🤝 Contributing

Contributions are welcome! Feel free to open issues and submit pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

🔗 Links

• GitHub Repository
• Report an Issue

Made with ⚒️ by ViewForge