Codezerg.DynamicRouter

A flexible dynamic routing library for Blazor applications that enables runtime navigation without @page directives, providing type-safe navigation and efficient state management.

Features

• 🚀 Dynamic Route Resolution - Navigate to components at runtime without @page directives
• 🔒 Type-Safe Navigation - Strongly-typed navigation with compile-time safety
• 📦 Efficient State Management - Binary serialization with optional compression
• 🌐 WebAssembly Compatible - Works with both Blazor Server and WebAssembly
• ⚡ Lightweight URLs - FNV-1a hashing and compression for compact URLs
• 🔧 Extensible Architecture - Replace core services with custom implementations

Installation

Install via NuGet Package Manager:

dotnet add package Codezerg.DynamicRouter

Or via Package Manager Console:

Install-Package Codezerg.DynamicRouter

Quick Start

1. Configure Services

In your Program.cs:

builder.Services.AddDynamicRouter(options =>
{
    options.DynamicRoutePrefix = "dynamic";
    options.Serialization.EnableCompression = true;
});

2. Create Catch-All Route (Required)

Create a catch-all route component to enable dynamic routing:

@* Pages/DynamicCatchAll.razor *@
@page "/dynamic/{**catch-all}"

@* This component's content is never displayed *@

3. Replace Router with DynamicRouter

In your Routes.razor or App.razor:

<DynamicRouter AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <p role="alert">Sorry, there's nothing at this address.</p>
    </NotFound>
</DynamicRouter>

4. Navigate to Components

@inject IDynamicNavigationService Navigator

@code {
    void NavigateToCounter()
    {
        // Navigate without parameters
        Navigator.NavigateTo<Counter>();
        
        // Navigate with parameters
        Navigator.NavigateTo<Counter>(new { CurrentCount = 10 });
        
        // Get URL for navigation
        var url = Navigator.GetUrl<Counter>(new { CurrentCount = 5 });
    }
}

Supported Parameter Types

The library supports all .NET primitive types via the TypeCode system:

• Integers: byte, sbyte, short, ushort, int, uint, long, ulong
• Floating-point: float, double, decimal
• Text: string, char
• Boolean: bool
• Date/Time: DateTime

Complex objects and collections are not currently supported.

Configuration Options

builder.Services.AddDynamicRouter(options =>
{
    // URL prefix for dynamic routes (default: "dynamic")
    options.DynamicRoutePrefix = "app";
    
    // Enable state compression (default: true)
    options.Serialization.EnableCompression = true;
    
    // Compression level (default: Optimal)
    options.Serialization.CompressionLevel = CompressionLevel.Fastest;
});

Advanced Usage

Custom Navigation Service

Implement your own navigation logic:

public class CustomNavigationService : IDynamicNavigationService
{
    // Implementation
}

// Register
builder.Services.AddDynamicRouter()
    .AddNavigationService<CustomNavigationService>();

Custom State Serializer

Implement custom serialization:

public class JsonStateSerializer : IRouteStateSerializer
{
    // Implementation
}

// Register
builder.Services.AddDynamicRouter()
    .AddStateSerializer<JsonStateSerializer>();

Navigate by Type

// Navigate using Type
Navigator.NavigateTo(typeof(Counter), new { CurrentCount = 10 });

// Navigate using assembly and type name
Navigator.NavigateTo("MyApp", "MyApp.Pages.Counter", new { CurrentCount = 10 });

Examples

The repository includes two complete example applications:

• Blazor Server Example - src/Codezerg.DynamicRouter.Example
• Blazor WebAssembly Example - src/Codezerg.DynamicRouter.WasmExample

Run the examples:

# Blazor Server
cd src/Codezerg.DynamicRouter.Example
dotnet run

# Blazor WebAssembly
cd src/Codezerg.DynamicRouter.WasmExample
dotnet run

How It Works

1. Component Discovery - Scans assemblies for ComponentBase-derived types on initialization
2. Type Identification - Uses FNV-1a 32-bit hash of type names for compact, WebAssembly-compatible identification
3. State Encoding - Binary serialization of parameters with optional Deflate compression
4. URL Generation - Base64url encoding for URL-safe state representation
5. Route Resolution - Runtime matching and component instantiation with parameters

Requirements

• .NET 9.0 or later
• Blazor Server or Blazor WebAssembly
• A catch-all route component for dynamic navigation

Documentation

• Architecture - Design decisions and technical details
• Development Guide - Contributing and development setup
• API Reference - Complete API documentation

Contributing

Contributions are welcome! Please read our Development Guide before submitting pull requests.

License

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

Support

• 📝 Report Issues
• 💬 Discussions
• 📧 Contact: support@codezerg.com

Acknowledgments

Built with ❤️ for the Blazor community.