TinyHelpers.AspNetCore 4.2.16

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 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. Use it when the file-name suffix is part of the upload contract and downstream processing or policy checks require known formats.

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

ContentTypeAttribute

Validates the Content-Type of an IFormFile. Use it when the server accepts only MIME types that can be rendered, transcoded, stored, or otherwise processed safely.

• 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 the built-in ContentTypeAttribute MIME type groups:

• Image
• Video
• Audio

FileSizeAttribute

Validates that an IFormFile does not exceed a maximum size. Use it to reject oversized uploads at the request boundary before later validation, storage, or media-processing work starts.

• 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 role values, keeping role-based authorization declarations readable without manually composing a comma-delimited string.

• 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 behavior and OpenAPI metadata close to the route mapping. This makes endpoint declarations easier to review and helps the generated document stay synchronized with runtime behavior.

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. They centralize reusable OpenAPI conventions so shared parameters, error responses, schema IDs, and schema transformations do not need to be repeated for every endpoint or document.

OpenApiExtensions

OpenApiSchemaHelper

This utility creates ready-to-use schema fragments that can be reused in transformers or other OpenAPI customizations. It keeps default values, formats, and enum choices consistent across generated documents.

.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 reusable string schema, optionally with a default value.
• CreateSchema(..., format) creates a primitive schema with explicit type and format metadata.
• CreateSchema(..., defaultValue) also adds the default value that clients should display or assume.
• CreateSchema(IEnumerable<string> values, ...) turns externally defined choices into a string-based OpenAPI enum.
• CreateSchema<TEnum>(...) builds an enum schema directly from a CLR enum so every declared value is documented.

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()

Register shared parameters during service registration, then enable AddOperationParameters() in OpenAPI configuration. This keeps cross-cutting inputs centralized while still exposing them in the generated client contract.

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

builder.Services.AddOpenApi(options =>
{
    options.AddOperationParameters();
});

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.