UniversalQueryBuilder.Extensions 10.0.13-beta

QueryBuilder.Extensions

Consolidated service registration for Universal Query Builder

QueryBuilder.Extensions provides a single AddQueryBuilder() extension method that registers all Universal Query Builder services with sensible defaults and feature toggles.

Table of Contents

• Overview
• Quick Start
• AddQueryBuilder() API
  • Minimal Configuration
  • Custom Configuration
  • Feature Toggles
  • Assembly Scanning
• Registration Order
• Architecture

Overview

What is QueryBuilder.Extensions?

QueryBuilder.Extensions consolidates all Universal Query Builder service registration into a single extension method. Instead of calling 9+ separate registration methods in the correct order, call AddQueryBuilder() once with optional configuration.

Before:

// Multiple registration calls in correct order
builder.Services.AddCodeFirstSchemaRegistry(/* ... */);
builder.Services.AddExpressionBuilders();
builder.Services.AddFilterShorthandParser();
builder.Services.AddShorthandFilterApplicator();
builder.Services.AddShorthandQueryTemplates();
builder.Services.AddSchemaRegistry();
// ... more services

After:

// Single method call
builder.Services.AddQueryBuilder(options => { });

What it Includes

The AddQueryBuilder() method registers:

1. Schema Registry - Code-first data source configuration and discovery
2. Expression Compilation - Filter expression builder with optional 2-level caching
3. Shorthand Parser - Human-readable query syntax (is:active AND age>18)
4. Query Templates - Reusable query shortcuts (optional)
5. Export Services - Formatting strategy registry

Quick Start

Installation

dotnet add package QueryBuilder.Extensions

Basic Setup

// Register Query Builder with default settings
builder.Services.AddQueryBuilder(options => { });

That's it! All Query Builder services are registered and ready to use.

AddQueryBuilder() API

Minimal Configuration

The simplest configuration uses all defaults:

builder.Services.AddQueryBuilder(options => { });

Defaults:

• Scans entry assembly for IDataSourceConfiguration<T> implementations
• Enables shorthand parser
• Enables query templates
• Enables 2-level expression caching

Custom Configuration

builder.Services.AddQueryBuilder(options =>
{
    // Scan specific assemblies for data source configurations
    options.ScanAssemblies(typeof(Program).Assembly, typeof(SharedConfigs).Assembly);

    // Configure schema registry conventions
    options.ConfigureSchemaRegistry(schema =>
    {
        schema.DefaultSourceNameCase = SourceNameCase.CamelCase;
        schema.DefaultPropertyNameCase = PropertyNameCase.CamelCase;
    });

    // Configure nested projection options
    options.ConfigureProjections(proj =>
    {
        proj.StrictMode = false;         // Allow unknown fields (log warnings instead of errors)
        proj.MaxCollectionLimit = 500;   // Max items per collection
        proj.MaxNestingDepth = 5;        // Limit nesting depth
    });

    // Disable expression caching for testing
    options.DisableExpressionCaching();
});

Feature Toggles

Turn features on/off with fluent methods:

builder.Services.AddQueryBuilder(options =>
{
    options
        .DisableShorthandParser()    // Skip shorthand syntax support
        .DisableTemplates()           // Skip query template shortcuts
        .DisableExpressionCaching();  // Skip 2-level expression cache
});

When to Disable Features:

• DisableShorthandParser() - JSON-only APIs, no human-readable queries needed
• DisableTemplates() - No reusable query shortcuts needed
• DisableExpressionCaching() - Testing environments, memory-constrained deployments

Assembly Scanning

By default, AddQueryBuilder() scans the entry assembly (the assembly that started the application) for IDataSourceConfiguration<T> implementations. Override with ScanAssemblies():

builder.Services.AddQueryBuilder(options =>
{
    options.ScanAssemblies(
        typeof(Program).Assembly,
        typeof(SharedConfigs).Assembly,
        typeof(PluginModule).Assembly
    );
});

Registration Order

AddQueryBuilder() registers services in this order:

1. Schema Registry (AddCodeFirstSchemaRegistry) - IHostedService: SchemaRegistryBootstrapper
2. Expression Compilation (AddExpressionBuilders or AddExpressionCompilation)
3. Shorthand Parser (AddFilterShorthandParser, AddShorthandFilterApplicator)
4. Query Templates (AddShorthandQueryTemplates) - IHostedService: TemplateBootstrapper
5. Export Services (AddSchemaRegistry - FormattingStrategyRegistry only)

Why Order Matters:

• Schema Registry must run first (IHostedService order)
• Expression compilation required by shorthand parser
• Templates require shorthand parser
• Templates must run after Schema Registry (IHostedService order)

Architecture

QueryBuilderOptions

Fluent builder for configuring Query Builder services:

public class QueryBuilderOptions
{
    public QueryBuilderOptions ScanAssemblies(params Assembly[] assemblies);
    public QueryBuilderOptions ConfigureSchemaRegistry(Action<SchemaRegistryOptions> configure);
    public QueryBuilderOptions ConfigureProjections(Action<NestedProjectionOptions> configure);
    public QueryBuilderOptions DisableShorthandParser();
    public QueryBuilderOptions DisableTemplates();
    public QueryBuilderOptions DisableExpressionCaching();

    internal void Validate();  // Validates configuration (e.g., templates require shorthand)
    internal void Build();     // Registers all services
}

QueryBuilderServiceCollectionExtensions

Provides the single entry point:

public static void AddQueryBuilder(
    this IServiceCollection services,
    Action<QueryBuilderOptions> configure)

Related Projects

• QueryBuilder.Core - Core models and abstractions
• QueryBuilder.SchemaRegistry - Code-first data source configuration
• QueryBuilder.Shorthand - Shorthand query parser
• QueryBuilder.Expressions - Expression compilation with caching
• QueryBuilder.EntityFramework - Entity Framework execution strategy
• QueryBuilder.InMemory - In-memory LINQ execution strategy