Regira.Common 6.1.2

Regira Common

Regira.Common is the shared foundation library used by every other Regira project. It provides file abstractions, general-purpose utilities, normalising, caching, serialising, and lightweight DAL contracts — no external dependencies.

Projects

Installation

<PackageReference Include="Regira.Common" Version="6.*" />

Most Regira packages pull this in as a transitive dependency, so you rarely need to reference it explicitly.

IO Abstractions

The IO abstraction hierarchy is the most widely referenced part of this library. It is used as the common file contract throughout IO.Storage, Drawing, and Office projects.

Interface hierarchy

┌───────────────────┐    ┌───────────────────┐
│ IMemoryBytesFile  │    │ IMemoryStreamFile │
└─────────┬─────────┘    └─────────┬─────────┘
          └────────────┬───────────┘
                Input Interfaces
                       │
                ▼──────────────▼
                  IMemoryFile
                ┌──────────────┐
                │ INamedFile   │──▶ FileName
                └──────────────┘
                       │
                ┌──────────────┐
                │ IStorageFile │──▶ Identifier, Path, Prefix
                └──────────────┘
                       │
                ┌──────────────┐
                │ IBinaryFile  │
                └──────────────┘
                       │
                ┌──────────────┐
                │  ITextFile   │──▶ Contents
                └──────────────┘

BinaryFileItem

The standard concrete implementation of IBinaryFile.

byte[] pdfBytes = File.ReadAllBytes("invoice.pdf");

var file = new BinaryFileItem
{
    FileName    = "invoice.pdf",
    Bytes       = pdfBytes,
    ContentType = "application/pdf"
};

Implicit conversions are available from byte[] and Stream:

byte[] pdfBytes = File.ReadAllBytes("invoice.pdf");
using var someStream = File.OpenRead("invoice.pdf");

BinaryFileItem f1 = pdfBytes;
BinaryFileItem f2 = someStream;

Extension methods

MemoryFileExtensions — work with any IMemoryFile:

IMemoryFile file = new BinaryFileItem { FileName = "invoice.pdf" };

byte[]? bytes  = file.GetBytes();
Stream? stream = file.GetStream();
long    length = file.GetLength();
bool    hasIt  = file.HasContent();

BinaryFileExtensions — factory helpers (byte[]/Stream overloads take a content type; the IMemoryFile overload takes a filename):

byte[] bytes = File.ReadAllBytes("invoice.pdf");
using var stream = File.OpenRead("data.csv");
IMemoryFile memoryFile = new BinaryFileItem { Bytes = bytes };

IBinaryFile f1 = bytes.ToBinaryFile("application/pdf");
IBinaryFile f2 = stream.ToBinaryFile("text/csv");
IBinaryFile f3 = memoryFile.ToBinaryFile("copy.pdf");

ContentTypeUtility

Auto-detect MIME types from file extensions or byte sequences.

string mime = ContentTypeUtility.GetContentType("report.pdf");  // "application/pdf"
string? ext = ContentTypeUtility.GetExtension("image/webp");    // "webp" (no leading dot)

Register additional mappings (extensions without leading dot, each mapped to one or more MIME types):

ContentTypeUtility.Extend(new Dictionary<string, string[]>
{
    { "abc", ["application/x-abc"] }
});

FileUtility

Conversions between bytes, streams, strings, and Base64.

using var stream = File.OpenRead("data.bin");

byte[]? bytes   = FileUtility.GetBytes(stream);
Stream? stream2 = FileUtility.GetStream(bytes);
string? text    = FileUtility.GetString(bytes, Encoding.UTF8);
string  b64     = FileUtility.GetBase64String(bytes!);
byte[]  back    = FileUtility.GetBytes(b64);                     // Base64 → bytes
byte[]  encoded = FileUtility.GetBytesFromString(text!);         // text → bytes (encoding)

Utilities

StringUtility / RegexUtility

// Validation
bool okEmail = RegexUtility.IsValidEmail("alice@example.com");
bool okUrl   = RegexUtility.IsValidUrl("https://example.com");
bool okPhone = RegexUtility.IsValidPhoneNumber("+32 123 456 789");

CollectionUtility

List<T>           list     = source.AsList<T>();
IEnumerable<T>    distinct = source.DistinctBy(x => x.Id);

TypeUtility

bool isSimple     = TypeUtility.IsSimpleType(typeof(int));
bool isNullable   = TypeUtility.IsNullableType(typeof(int?));
bool isCollection = TypeUtility.IsTypeACollection(typeof(List<string>));
Type underlying   = TypeUtility.GetSimpleType(typeof(int?));   // int

ObjectUtility

// Merge non-null properties from one or more sources onto target
ObjectUtility.Merge(target, source);

// Populate from an anonymous object or dictionary
ObjectUtility.Fill(target, new { Name = "Alice", Age = 30 });

UriUtility

byte[] bytes = File.ReadAllBytes("logo.png");

string slug    = UriUtility.Slugify("Héllo Wörld!");           // "Hello-World" (case is preserved)
string dataUrl = UriUtility.ToBase64ImageUrl(bytes, "image/png");
string abs     = UriUtility.ToAbsoluteUri("../images/logo.png");

DimensionsUtility

float inches = DimensionsUtility.MmToIn(25.4f);   // 1.0f
float mm     = DimensionsUtility.InToMm(1.0f);    // 25.4f

Dimensions

Shared geometric primitives used by Drawing and PDF projects.

Size2D

var size = new Size2D(800, 600);
var half = size / 2;          // (400, 300)

Implicit conversions: from int (square), int[], float[].

Position2D

CSS-style distance from each edge (nullable floats).

var pos = new Position2D { Top = 10, Left = 20 };

LengthUnit

public enum LengthUnit { Points, Inches, Millimeters, Percent }

Used by Drawing DTOs and PDF layout engines when specifying measurements. See Drawing → DTOs & API Integration.

Normalizing

Attribute-driven string and object normalisation.

INormalizer

public interface INormalizer
{
    string? Normalize(string? input);
}

DefaultNormalizer removes diacritics, normalises whitespace, and optionally transforms case:

var normalizer = new DefaultNormalizer(new NormalizeOptions
{
    RemoveDiacritics = true,
    Transform        = TextTransform.ToLowerCase
});

string? result = normalizer.Normalize("Héllo Wörld");  // "hello world"

NormalizedAttribute

Decorate properties so ObjectNormalizer knows which ones to normalise.

public class Article
{
    public string? Title { get; set; }

    [Normalized]
    public string? Name { get; set; }

    [Normalized(SourceProperty = nameof(Title))]
    public string? NormalizedTitle { get; set; }
}

var normalizer = new ObjectNormalizer();
normalizer.HandleNormalize(myEntity, recursive: true);

Caching

ICacheProvider

public interface ICacheProvider
{
    IList<string> Keys { get; }
    object?       this[string key] { get; set; }
    T?    Get<T>(string key);
    void  Set<T>(string key, T? value, int? duration = null);
    void  Remove(string key);
    void  RemoveAll();
}

DictionaryCacheProvider

Thread-safe in-memory cache backed by a static ConcurrentDictionary — entries are shared process-wide across all instances; the optional key prefix is the only isolation between them.

var products = new List<string> { "chair", "table" };

var cache = new DictionaryCacheProvider("products");
cache.Set("list", products);
var list = cache.Get<List<string>>("list");

Serializing

ISerializer

public interface ISerializer
{
    string  Serialize<T>(T obj);
    T?      Deserialize<T>(string? content);
    object? Deserialize(string? content, Type type);
}

XmlSerializer ships in Common. JSON serialiser implementations live in separate packages. Inject ISerializer in consuming code to stay agnostic.

Security

Thin contracts for pluggable encryption and hashing.

public interface IEncrypter
{
    string Encrypt(string plainText, string? key = null);
    string Decrypt(string encryptedText, string? key = null);
}

public interface IHasher
{
    string Hash(string plainText);
    bool   Verify(string plainText, string hashedValue);
}

DAL Abstractions

Lightweight database connectivity contracts. Implementations live in the DAL.* projects.

IDbSettings

string BuildConnectionString(params KeyValuePair<string, string>[] extraOptions);

Extend DbSettingsBase to implement a provider-specific connection string builder.

IDbCommunicator

IDbConnection Open();
IDbConnection Close();

DbCommunicator<TDbConnection> is the generic implementation; provider-specific communicators (Postgres, MySQL, …) extend it.

PagingInfo + QueryExtensions

var query = Enumerable.Range(1, 100).AsQueryable();

var paging = new PagingInfo { PageSize = 20, Page = 2 };
var page   = query.PageQuery(paging).ToList();

IDbBackupService / IDbRestoreService

Shared backup/restore contracts implemented by the database-specific packages.

public interface IDbBackupService
{
    Task<IMemoryFile> Backup();
}

public interface IDbRestoreService
{
    Task Restore(IMemoryFile file);
}

See the individual DAL project docs for implementations:

• MongoDB
• MySQL
• PostgreSQL

Collections

DisposableCollection<T>

A List<T> that disposes every IDisposable element when itself is disposed. Useful for holding image files, streams, or other resources that need coordinated cleanup.

using var images = new DisposableCollection<IImageFile>();
images.Add((await imageService.Parse(bytes1))!);
images.Add((await imageService.Parse(bytes2))!);
// all entries disposed here

Related documentation

License

Apache License 2.0 — this package contains no license validation and no runtime limits. See LICENSE. A few companion packages are commercially licensed with a free tier; see the licensing overview.