StrongOf.AspNetCore 3.1.2

StrongOf.AspNetCore

ASP.NET Core integration for StrongOf types. Includes MVC model binders, Minimal API validation, and OpenAPI schema transformation.

NativeAOT boundary

This extension package has no package-wide NativeAOT guarantee. The core StrongOf package is independently AOT-compatible. ASP.NET Core MVC is not supported by NativeAOT; neither explicit model binders nor disabling warnings changes that framework limitation.

Assembly-scanning registration is annotated with RequiresUnreferencedCode, and registration that constructs closed generic binder types at runtime is annotated with RequiresDynamicCode. Prefer explicit binder mappings for predictable registration in MVC applications. These mappings do not make MVC NativeAOT-compatible.

Minimal API applications have a different deployment model. Use the ASP.NET Core NativeAOT template, generated request delegates, and generated JSON metadata for all request/response types. The examples below show integration API usage, not a complete AOT application. User-defined strong types freshly generated in that application also need the explicit type-level JSON converter described in the JSON documentation. OpenAPI and other ASP.NET Core dependencies must be evaluated separately for the selected version.

See ASP.NET Core's compatibility table.

Installation

dotnet add package StrongOf.AspNetCore

MVC Model Binders (StrongOf.AspNetCore.Mvc)

Enables route values, query strings, and form fields to be automatically parsed into strong types.

Available Binders

Setup

Register the built-in StrongOf model binder provider in your ASP.NET Core startup. For most applications, passing the StrongOf model types directly is the simplest option:

using StrongOf.AspNetCore.Mvc;

// Program.cs
builder.Services.AddControllers(options =>
    options.AddStrongOfModelBinderProvider(
        typeof(UserId),
        typeof(EmailAddress)));

If you want to register all StrongOf types from one or more assemblies, you can scan them automatically:

using StrongOf.AspNetCore.Mvc;

builder.Services.AddControllers(options =>
    options.AddStrongOfModelBinderProviderFromAssemblies(typeof(UserId).Assembly));

The explicit Dictionary<Type, Type> overload remains available when you need full manual control.

Custom Binders

Extend StrongOfBinder to add custom parsing logic:

using StrongOf.AspNetCore.Mvc;

public sealed class MyUserIdBinder : StrongOfBinder
{
    public override bool TryHandle(string value, out ModelBindingResult result)
    {
        if (StrongGuid<UserId>.TryParse(value, out UserId? id))
        {
            result = ModelBindingResult.Success(id);
            return true;
        }
        result = ModelBindingResult.Failed();
        return false;
    }
}

Minimal APIs (StrongOf.AspNetCore.MinimalApis)

All strong types implement IParsable<TSelf> and work as route/query parameters in Minimal APIs out of the box.

Use the validation filter to automatically validate IValidatable parameters:

using StrongOf.AspNetCore.MinimalApis;

// Strong types work as route parameters out of the box
app.MapGet("/users/{id}", (UserId id) => Results.Ok(id));

// Register the endpoint filter for automatic validation of IValidatable types
app.MapPost("/users", (EmailAddress email) => Results.Ok(email))
   .WithStrongOfValidation();

OpenAPI Schema Transformer (StrongOf.AspNetCore.OpenApi)

Requires .NET 9.0 or later

Maps strong types to their underlying primitive types in OpenAPI documentation, so API schemas show string (uuid) instead of a complex object for UserId.

using StrongOf.AspNetCore.OpenApi;

builder.Services.AddOpenApi(options =>
{
    options.AddSchemaTransformer<StrongOfSchemaTransformer>();
});

Type Mappings

Mapping is resolved via the IStrong* marker interfaces, so custom strong types are covered automatically without additional registration.

GitHub

See https://github.com/BenjaminAbt/StrongOf