Getting Started with LayerZero.Tools.Routing

1. Install the Package

Add the NuGet package to your project:

dotnet add package LayerZero.Tools.Routing

2. Register Controllers

ZRouting currently requires controllers to be registered explicitly.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
        

Future versions will support seamless integration with AddControllersWithViews().

3. Configure ZRouting

Configure ZRouting during application startup:

builder.AddZRouting(cfg =>
{
    cfg.Tokens = new List<ZRouteToken>
    {
        new ZRouteToken
        {
            NameSpaceIndex = 5,
            DefaultValue = "0_0",
            Name = "version"
        },
        new ZRouteToken
        {
            NameSpaceIndex = 6,
            DefaultValue = "unknown",
            Name = "feature"
        },
        new ZRouteToken
        {
            NameSpaceIndex = 4,
            DefaultValue = "unknown",
            Name = "area"
        }
    };

    cfg.RouteTemplate = "[area]/v[version]/[feature]/[controller]/[action]";
});

var app = builder.Build();

app.MapControllers();
app.Run();
        

The configuration above is only a sample. Token names, namespace indexes, and route templates are fully customizable.

4. Namespace-Driven Routing

ZRouting derives route segments directly from your controller namespace. Example:

namespace Company.Product.Admin.V1_0.Reporting.Controllers;
        

With the sample configuration, this could resolve to:

/Admin/v1_0/Reporting/YourController/YourAction
        

Namespace structure and route mapping are entirely controlled by your configured tokens.

5. Coexistence with Minimal APIs

ZRouting can coexist with Minimal APIs.

• Ensure route patterns do not overlap.
• ZRouting affects controllers only.
• Minimal API endpoints remain unaffected unless paths collide.

6. Override Routing Behavior

If a controller should bypass ZRouting and revert to native ASP.NET Core routing, apply the ZRouteIgnoreAttribute.

[ZRouteIgnore]
public class LegacyController : ControllerBase
{
}
        

This allows selective opt-out for special cases, legacy endpoints, or externally constrained route structures.

7. Important Notes

• Token resolution occurs at application startup.
• No per-request reflection overhead is introduced.
• Namespace depth must match configured NameSpaceIndex values.
• Default values are applied when a namespace segment is missing.

Because routing is namespace-driven, renaming or restructuring namespaces will directly impact generated URLs.

8. Architectural Recommendations

ZRouting works best in modular or feature-based architectures where namespace hierarchy reflects domain boundaries and versioning strategy.

• Define namespace conventions early.
• Keep version placement consistent.
• Avoid arbitrary namespace depth changes.
• Use ZRouteIgnoreAttribute intentionally for exceptions.