Tingle.Extensions.Primitives 4.6.0

Tingle.Extensions.Primitives

This library contains extra primitive types. These are additional to what the framework already provides. Some are inspired by community projects.

For some primitive types, there are also some validation attributes for easier validation of input data.

ByteSize

Handling of byte calculations. Extended from ByteSize.

var bs = ByteSize.FromKiloBytes(1.5);
Console.WriteLine(bs);

ConnectionStringBuilder

Helps you with the manipulation of connection strings. In most SDKs provided by Microsoft the builders are usually internal and cannot be reused or are very usage centric. This type helps in the manipulation of connection strings either from the final string or parts and can then produce the final string or segments.

var cs = "HostName=contoso.com;Scheme=https;Key=abcd";
var csb = new ConnectionStringBuilder(cs);
Console.WriteLine("contoso.com", csb.GetHostname());
Console.WriteLine("https", csb.GetScheme());
Console.WriteLine("abcd", csb.GetKey());

Country

Easier handling of countries with support for validation.

if (Country.TryGetFromCode('KEN', out var country))
{
    Console.WriteLine(country.Name); // Kenya
}

Supports validation via attributes too:

class TestModel1
{
    [CountryCode]
    public string? SomeCode { get; set; }
}

Currency

Easier handling of currencies with support for validation.

if (Currency.TryGetFromCode('KES', out var currency))
{
    Console.WriteLine(currency.Name); // Kenyan Shilling
}

Supports validation via attributes too:

class TestModel1
{
    [Currency]
    public string? SomeCode { get; set; }
}

Duration

TimeSpan is great but when dealing with values outside the .NET ecosystem you can either specify the time in seconds, milliseconds, or minutes. This type provides an alternative, by using ISO8601 durations e.g. PT10M for 10 minutes. It can be used to perform operations against DateTime and DateTimeOffset instances.

var ts = TimeSpan.FromDays(1.556); // 1 day, 13 hours, 20 minutes and 38 seconds
var duration = new Duration(ts);
Console.WriteLine(duration); // P1DT13H20M38S

DateTime dt = new(2022, 08, 31, 12, 19, 10);
var equal = dt.AddMonths(1) == dt + Duration.FromMonths(1);

Etag

A convenience type for handling Etag values. For example, you can use this to read values from SQLServer's RowVersion or you can create your own version when working with MongoDB. It is also useful when combining multiple values such when you want a new Etag if an entry in an array of items changes.

var etag = new Etag("0x75BCD15");
Console.WriteLine(etag.ToString("H")); // 0x75BCD15
Console.WriteLine(etag.ToString("B")); // Fc1bBwAAAAA=
Console.WriteLine(etag); // Fc1bBwAAAAA=

ImageDimensions

Simple convenience for storing image dimensions similar to System.Drawing.Size.

var value = new ImageDimensions(50, 45);
Console.WriteLine(value); // 50px by 45px

ImageDimensionsRange

A type that eases the check for whether an image's dimensions are contained in a given range.

var value = new ImageDimensionsRange(45, 50);
Console.WriteLine(value); // within (45px by 45px) and (50px by 50px)

var min = new ImageDimensions(45, 45);
var max = new ImageDimensions(100, 100);
var range = new ImageDimensionsRange(min, max);
var dimensions = new ImageDimensions(width, height);
Console.WriteLine(range.IsWithin(dimensions)); // true

Ksuid

A K-Sortable Globally Unique Identifier, based on the reference implementation from Segment.

var id = Ksuid.Generate(); // generation
Console.WriteLine(id);

if (Ksuid.TryParse("0o5Fs0EELR0fUjHjbCnEtdUwQe3", out var id)) {
    Console.WriteLine($"{id.Created:o}"); // 2017-05-17T01:49:21+00:00
}

Language

Easier handling of languages with support for validation.

if (Language.TryGetFromCode('swa', out var language))
{
    Console.WriteLine(language.Name); // Swahili
}

Supports validation via attributes too:

class TestModel1
{
    [LanguageCode]
    public string? SomeCode { get; set; }
}

SequenceNumber

A sequential number inspired by Twitter's (late) Snowflake project and Instagram's implementation. This is very useful for situations where you want non-predictable identifiers. It can also be used for sorting data in a database without exposing the field in APIs.

var sequenceNumber1 = SequenceNumber.Generate(); // generation
Console.WriteLine(sequenceNumber1);

SwiftCode

Represents a SWIFT Code broken down into its components. The format of a Swift Code is as specified under ISO-9362.

var sw = SwiftCode.Parse("KCBLKENXXXX");
Console.WriteLine(sw.Institution); // "KCBL"
Console.WriteLine(sw.Country); // "KE"
Console.WriteLine(sw.Location); // "NX"
Console.WriteLine(sw.Branch); // "XXX"

Keygen

Helper for generating non-sequential keys such as those use as client secrets, webhook secrets, signing keys, etc. The keys can be generated from bytes, strings, and numbers where deterministic outputs are desired.

Console.WriteLine(Keygen.Create(BitConverter.GetBytes(100), Keygen.OutputFormat.Base64)); // ZAAAAAAAAAA=
Console.WriteLine(Keygen.Create(BitConverter.GetBytes(100), Keygen.OutputFormat.Hex)); // 6400000000000000
Console.WriteLine(Keygen.Create(BitConverter.GetBytes(100), Keygen.OutputFormat.Base62)); // 8aISBA7FdnE

Console.WriteLine(Keygen.Create("100", Keygen.OutputFormat.Base64, null)); // MTAw
Console.WriteLine(Keygen.Create("000", Keygen.OutputFormat.Hex, Encoding.ASCII)); // MDAw
Console.WriteLine(Keygen.Create("000", Keygen.OutputFormat.Hex, Encoding.Unicode)); // MAAwADAA

Conversion

Most of the types have conversion to/from JSON using System.Text.Json. Support for Type converters is also included to allow binding via IConfiguration instances.