TinyHelpers 3.3.26

Tiny .NET Helpers

TinyHelpers is a small .NET utility library that groups common helpers into a single package. It is designed to reduce repeated boilerplate in application code while keeping each helper focused, discoverable, and explicit about the contract it supports.

Compatibility

The package targets:

• .NET Standard 2.0
• .NET 8
• .NET 9
• .NET 10

Some helpers are available only on newer frameworks when the underlying platform adds the required APIs.

Installation

Install the package from NuGet:

dotnet add package TinyHelpers

Or search for TinyHelpers in the Visual Studio Package Manager.

Other package documentation

Additional documentation is available for these packages:

• TinyHelpers.AspNetCore
• TinyHelpers.AspNetCore.Swashbuckle
• TinyHelpers.EntityFrameworkCore
• TinyHelpers.Dapper

Contents

• Collections and sequences
• Strings
• Enums, reflection, and comparisons
• Dates, times, and ranges
• GUID helpers
• HTTP helpers
• JSON serialization
• Threading
• Quick examples

Collections and sequences

The collection helpers keep common null-safety, indexing, asynchronous projection, and conditional filtering patterns reusable. They are intended for code that repeatedly composes LINQ queries or optional collections and should avoid scattering small guard clauses across the codebase.

CollectionExtensions

Example

using TinyHelpers.Extensions;

public IQueryable<Person> SearchPeople(string? nameInitials, string? surnameInitials, string? city)
{
    return context.People
        .WhereIf(!string.IsNullOrWhiteSpace(nameInitials), person => person.FirstName.StartsWith(nameInitials!))
        .WhereIf(!string.IsNullOrWhiteSpace(surnameInitials), person => person.LastName.StartsWith(surnameInitials!))
        .WhereIf(!string.IsNullOrWhiteSpace(city), person => person.City == city);
}

// Example:
// SearchPeople("Ma", "Ro", "Taggia") filters by first name, last name, and city.
// SearchPeople(null, null, "Taggia") filters only by city.

Strings

StringExtensions

Example

using TinyHelpers.Extensions;

var value = "tiny helpers";
var display = value.FirstCharToUpper();
var contains = value.ContainsIgnoreCase("HELP");

Enums, reflection, and comparisons

EnumExtensions

Other helpers

• IComparableExtensions.IsBetween() checks whether a value falls inside a range.
• AssemblyExtensions.GetAttribute() reads a custom attribute from an assembly.

Example

using TinyHelpers.Extensions;

var description = ConsoleColor.DarkBlue.GetDescription();
var insideRange = 5.IsBetween(1, 10);

Dates, times, and ranges

DateTimeExtensions

DateTimeOffsetExtensions

DateOnlyExtensions

TimeSpanExtensions

RangeExtensions

StopwatchExtensions

Example

using TinyHelpers.Extensions;

var createdAt = DateTime.UtcNow;
var dateOnly = createdAt.ToDateOnly();
var timeOnly = createdAt.ToTimeOnly();

GUID helpers

GuidExtensions

Example

using TinyHelpers.Extensions;

Guid? id = null;
var hasValue = id.HasValue();
var safeId = id.GetValueOrCreateNew();
var defaultId = id.GetValueOrDefault();

HTTP helpers

AuthenticatedParameterizedHttpClientHandler

Adds an access token to outgoing requests through a delegate that can inspect the current HttpRequestMessage. If a request returns 401 Unauthorized and a refresh delegate is configured, the handler can refresh the token and retry the request once. The authorization scheme is configurable and defaults to Bearer.

Use this handler when token acquisition depends on the outgoing request, such as per-tenant or per-resource tokens, or when you need a lightweight refresh flow around a protected API.

Example

var handler = new AuthenticatedParameterizedHttpClientHandler(
    async request => await tokenProvider.GetTokenAsync(request),
    async request => await tokenProvider.RefreshTokenAsync(request),
    innerHandler: new HttpClientHandler());

var client = new HttpClient(handler);

HeaderInjectorHttpClientHandler

Adds headers to outgoing requests by invoking a delegate that returns a dictionary of header names and values. Each returned header is applied with TryAddWithoutValidation, so the handler is suitable for custom or preformatted header values.

Use this handler when headers such as correlation IDs, tenant identifiers, or custom API metadata need to be injected per request without repeating header setup at every call site.

Example

var handler = new HeaderInjectorHttpClientHandler(async request =>
    new Dictionary<string, string>
    {
        ["X-Correlation-Id"] = Guid.NewGuid().ToString(),
        ["X-Tenant"] = "contoso"
    }, innerHandler: new HttpClientHandler());

var client = new HttpClient(handler);

QueryStringInjectorHttpClientHandler

Adds query string parameters to outgoing requests by merging the values returned by a delegate into the current request URI. Existing query string values are preserved, and new values are appended to the request URL.

Use this handler when the query string depends on the current request context and you want to centralize URL composition for pagination, tenant selection, feature flags, or similar cross-cutting values.

Example

var handler = new QueryStringInjectorHttpClientHandler(async request =>
    new Dictionary<string, string>
    {
        ["page"] = "1",
        ["pageSize"] = "25"
    }, innerHandler: new HttpClientHandler());

var client = new HttpClient(handler)
{
    BaseAddress = new Uri("https://api.example.com/")
};

JSON serialization

ShortDateConverter

Serializes and deserializes a DateTime using only the date portion when time-of-day information is not part of the JSON contract.

UtcDateTimeConverter

Serializes and deserializes DateTime values in UTC format so the JSON boundary normalizes date-time values instead of preserving local offsets or unspecified kinds.

TimeSpanTicksConverter

Serializes and deserializes a TimeSpan as ticks so durations round-trip without string-format ambiguity.

StringTrimmingConverter

Trims leading and trailing whitespace from JSON strings during read and write operations when the JSON boundary should normalize user-entered text.

StringEnumMemberConverter

Converts enum values using EnumMember metadata. This type is kept for backward compatibility.

Example

var options = new JsonSerializerOptions
{
    Converters =
    {
        new UtcDateTimeConverter(),
        new ShortDateConverter(),
        new TimeSpanTicksConverter()
    }
};

Threading

AsyncLock

Provides an asynchronous lock that serializes access to a shared resource without blocking threads. It supports an unlimited wait, a timeout in milliseconds, or a TimeSpan timeout. The timed overloads return LockResult, which tells you whether the lock was acquired.

Example

using TinyHelpers.Threading;

var queue = new Queue<string>(new[] { "Order-1001", "Order-1002", "Order-1003" });
var asyncLock = new AsyncLock();

var readers = new[]
{
    ReadNextAsync("Worker-1", asyncLock, queue),
    ReadNextAsync("Worker-2", asyncLock, queue),
    ReadNextAsync("Worker-3", asyncLock, queue)
};

await Task.WhenAll(readers);

static async Task ReadNextAsync(string workerName, AsyncLock queueLock, Queue<string> queue)
{
    await using var handle = await queueLock.LockAsync();

    if (queue.Count == 0)
    {
        return;
    }

    var item = queue.Dequeue();
    await Task.Delay(Random.Shared.Next(100, 500));

    Console.WriteLine($"{workerName} processed {item}");
}

Timed acquisition

using TinyHelpers.Threading;

var (isOwned, queueLock) = await asyncLock.LockAsync(TimeSpan.FromSeconds(2));

if (isOwned && queueLock is not null)
{
    try
    {
        // read or update the shared queue here
    }
    finally
    {
        queueLock.Dispose();
    }
}

Quick examples

Filtering a sequence conditionally

using TinyHelpers.Extensions;

var numbers = new[] { 1, 2, 3, 4, 5 };
var evenNumbers = numbers.WhereIf(true, number => number % 2 == 0);

Reading a readable enum value

using TinyHelpers.Extensions;

var label = DayOfWeek.Monday.GetDescription();

Converting dates

using TinyHelpers.Extensions;

var today = DateTime.UtcNow.ToDateOnly();

Working with asynchronous locks

await using var lease = await asyncLock.LockAsync();
// critical section

Contribute

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