TinyHelpers.AspNetCore 4.2.12

Tiny Helpers for ASP.NET Core

TinyHelpers.AspNetCore is a small collection of practical helpers for ASP.NET Core applications: claims handling, configuration binding, localization, middleware support, validation attributes, route helpers, OpenAPI helpers, and exception handling.

The package is designed to reduce code duplication and keep common behavior centralized in one place.

Compatibility

The package targets:

• .NET 8
• .NET 9
• .NET 10

OpenAPI features are available when the consuming project targets .NET 9 or .NET 10. Some extensions are also framework-specific:

• EnableEnumSupport() is available only on .NET 9+
• UseStrictNumericSchemas() is available only on .NET 10+
• WithResponseDescription() and WithLocationHeader() are available only on .NET 10+

Installation

Install the package from NuGet:

dotnet add package TinyHelpers.AspNetCore

Or search for TinyHelpers.AspNetCore in the Visual Studio Package Manager.

Contents

• Claims handling
• Configuration and options
• Localization and pipeline
• Validation and authorization attributes
• Route and Minimal API helpers
• OpenAPI
• Exception handling
• Quick examples

Claims handling

This area contains two groups of extensions:

• helpers for IList<Claim> that modify the collection
• helpers for ClaimsPrincipal that read values without repeating the same lookup logic

ClaimsExtensions

ClaimsPrincipalExtensions

Example

using System.Security.Claims;
using TinyHelpers.AspNetCore.Extensions;

var claims = new List<Claim>
{
    new(ClaimTypes.Name, "Marco"),
    new(ClaimTypes.Role, "Admin")
};

claims.Update(ClaimTypes.Name, "Mario");
claims.Remove(ClaimTypes.Role);

var principal = new ClaimsPrincipal(new ClaimsIdentity(claims));

var name = principal.GetClaimValue(ClaimTypes.Name);
var roles = principal.GetClaimValues(ClaimTypes.Role);
var hasName = principal.HasClaim(ClaimTypes.Name);

Configuration and options

IConfigurationExtensions

ServiceCollectionExtensions

Example

var settings = builder.Services.ConfigureAndGet<MySettings>(builder.Configuration, "MySettings");

builder.Services.AddRequestLocalization("it-IT", "en-US");
builder.Services.AddDefaultProblemDetails();
builder.Services.AddDefaultExceptionHandler();

Localization and pipeline

NavigationManagerExtensions

ApplicationBuilderExtensions

EnableRequestRewindMiddleware

The internal middleware used by UseRequestRewind() calls Request.EnableBuffering() before passing control to the next middleware. It is useful for audit, validation, or request-signature scenarios.

Example

app.UseRequestRewind();

if (navManager.TryGetQueryString<int>("page", out var page))
{
    // use page
}

Validation and authorization attributes

AllowedExtensionsAttribute

Validates that an IFormFile uses one of the allowed file extensions.

• Constructor: AllowedExtensionsAttribute(params string[] extensions)
• FormatErrorMessage(string name): generates the error message with the allowed extensions

ContentTypeAttribute

Validates the Content-Type of an IFormFile.

• ContentTypeAttribute(params string[] validContentTypes): uses an explicit MIME type list
• ContentTypeAttribute(FileType fileType): uses a predefined group
• FormatErrorMessage(string name): generates the error message with the allowed MIME types

FileType

Supporting enum for ContentTypeAttribute:

• Image
• Video
• Audio

FileSizeAttribute

Validates that an IFormFile does not exceed a maximum size.

• Constructor: FileSizeAttribute(int maxFileSizeInBytes)
• FormatErrorMessage(string name): generates the error message with the limit in bytes

RoleAuthorizeAttribute

Automatically builds the Roles list of AuthorizeAttribute from one or more roles.

• Constructor: RoleAuthorizeAttribute(params string[] roles)

Example

using TinyHelpers.AspNetCore.DataAnnotations;

public sealed class UploadModel
{
    [AllowedExtensions("jpg", "png")]
    [ContentType(FileType.Image)]
    [FileSize(2_000_000)]
    public IFormFile File { get; set; } = default!;
}

[RoleAuthorize("Admin", "Manager")]
public IActionResult SecretArea()
{
    return Ok();
}

Route and Minimal API helpers

RouteHandlerBuilderExtensions

These helpers keep Minimal API configuration close to the route instead of scattering OpenAPI metadata in separate places.

Example

app.MapPost("/orders", () => Results.Created("/orders/1", new { Id = 1 }))
   .ProducesDefaultProblem(StatusCodes.Status400BadRequest, StatusCodes.Status500InternalServerError);

.NET 10 example

app.MapPost("/orders", () => Results.Created("/orders/1", new { Id = 1 }))
   .WithResponseDescription(StatusCodes.Status201Created, "Order created successfully")
   .WithLocationHeader();

OpenAPI

The OpenAPI extensions are available when the consuming project uses the package on .NET 9 or .NET 10.

OpenApiExtensions

OpenApiSchemaHelper

This utility creates ready-to-use schema fragments that can be reused in transformers or other OpenAPI customizations.

.NET 9

• CreateStringSchema(string? defaultValue = null)
• CreateSchema<TValue>(string type, string? format = null)
• CreateSchema<TValue>(string type, string? format, TValue? defaultValue = null)
• CreateSchema(IEnumerable<string> values, string? defaultValue = null)
• CreateSchema<TEnum>(TEnum? defaultValue = null)

.NET 10

• CreateStringSchema(string? defaultValue = null)
• CreateSchema<TValue>(JsonSchemaType type, string? format = null)
• CreateSchema<TValue>(JsonSchemaType type, string? format, TValue? defaultValue = null)
• CreateSchema(IEnumerable<string> values, string? defaultValue = null)
• CreateSchema<TEnum>(TEnum? defaultValue = null)

What they do in practice

• CreateStringSchema() creates a simple string schema, optionally with a default.
• CreateSchema(..., format) creates a schema with explicit type and format.
• CreateSchema(..., defaultValue) also adds a default to the contract.
• CreateSchema(IEnumerable<string> values, ...) turns a list of values into a string-based OpenAPI enum.
• CreateSchema<TEnum>(...) builds an enum schema directly from a CLR enum.

Example

builder.Services.AddOpenApi(options =>
{
    options.AddAcceptLanguageHeader();
    options.AddDefaultProblemDetailsResponse();
    options.AddOperationParameters();
    options.RemoveServerList();
    options.WriteNumberAsString();
    options.DescribeAllParametersInCamelCase();
    options.AddTimeExamples();
    options.UseFullTypeNameSchemaIds();
#if NET9_0
    options.EnableEnumSupport();
#endif
#if NET10_0_OR_GREATER
    options.UseStrictNumericSchemas();
#endif
});

Example AddOpenApiOperationParameters()

builder.Services.AddOpenApiOperationParameters(parameters =>
{
    parameters.Parameters.Add(new OpenApiParameter
    {
        Name = "X-Correlation-Id",
        In = ParameterLocation.Header,
        Required = false,
        Description = "Identifier used to correlate requests"
    });
});

Example OpenApiSchemaHelper

var schema = OpenApiSchemaHelper.CreateStringSchema("it-IT");

Exception handling

DefaultExceptionHandler

TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken) converts unhandled exceptions into a consistent ProblemDetails response.

Main behavior:

• uses the StatusCode from BadHttpRequestException when present
• sets title, detail, instance, and traceId
• adds innerException when an inner exception exists
• includes stackTrace only in the Development environment

Example

builder.Services.AddDefaultExceptionHandler();
app.UseExceptionHandler();

If a route throws an exception, the response becomes predictable and easy for clients to document and consume.

Quick examples

Minimal API with ProblemDetails and OpenAPI

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDefaultProblemDetails();
builder.Services.AddDefaultExceptionHandler();
builder.Services.AddRequestLocalization("it-IT", "en-US");

builder.Services.AddOpenApi(options =>
{
    options.AddAcceptLanguageHeader();
    options.AddDefaultProblemDetailsResponse();
    options.UseFullTypeNameSchemaIds();
});

var app = builder.Build();

app.UseExceptionHandler();
app.UseRequestRewind();

app.MapGet("/hello", () => Results.Ok(new { Message = "Hello" }))
   .ProducesDefaultProblem(StatusCodes.Status500InternalServerError);

app.Run();

Reading a configuration section

var appSettings = builder.Services.ConfigureAndGet<AppSettings>(builder.Configuration, "AppSettings");

Contribute

The project is continuously evolving. Contributions, issues, and pull requests are welcome.