Hexalith.Commons.Configurations 2.30.3

Hexalith.Commons

A modular .NET utility library providing essential building blocks for enterprise applications.

Overview

Hexalith.Commons is a collection of focused .NET libraries that provide reusable utilities for common programming tasks. Each package is lightweight, well-tested, and easy to integrate.

Key Capabilities

Requirements

• .NET 10.0 or later
• Compatible with ASP.NET Core, Console, Worker Services, and library projects

Installation

Install packages via NuGet:

# Core utilities
dotnet add package Hexalith.Commons

# Configuration management
dotnet add package Hexalith.Commons.Configurations

# String encoding
dotnet add package Hexalith.Commons.StringEncoders

# Unique ID generation
dotnet add package Hexalith.Commons.UniqueIds

# Message metadata
dotnet add package Hexalith.Commons.Metadatas

Hexalith.Commons (Core)

The core library provides essential utilities organized into focused namespaces.

String Utilities

Namespace: Hexalith.Extensions.Helpers

using Hexalith.Extensions.Helpers;

// Format strings with named placeholders
string template = "Hello {name}, your order #{orderId} is ready";
string result = template.FormatWithNamedPlaceholders(
    new Dictionary<string, object> { ["name"] = "John", ["orderId"] = 12345 }
);
// Result: "Hello John, your order #12345 is ready"

// Culture-invariant number conversions
string number = "42.5";
decimal value = number.ToDecimal();  // Works regardless of system culture

// RFC1123 hostname validation
bool isValid = "my-server.example.com".IsRfc1123Compliant();  // true
bool isInvalid = "my_server".IsRfc1123Compliant();            // false

Error Handling

Namespace: Hexalith.Commons.Errors

Structured error handling with railway-oriented programming support.

using Hexalith.Commons.Errors;

// Create structured errors
var error = new ApplicationError
{
    Title = "Validation Failed",
    Detail = "The field {fieldName} is required",
    Category = ErrorCategory.Validation,
    Arguments = new object[] { "Email" }
};

string message = error.GetDetailMessage();
// Result: "The field Email is required"

// Railway-oriented error handling with ValueOrError<T>
ValueOrError<User> result = await GetUserAsync(userId);

if (result.HasError)
{
    // Handle error
    logger.LogError(result.Error.GetDetailMessage());
}
else
{
    // Use the value
    User user = result.Value;
}

Object Utilities

Namespace: Hexalith.Commons.Objects

Deep equality comparison and object introspection.

using Hexalith.Commons.Objects;

// Deep equality comparison (supports nested objects, collections, dictionaries)
bool areEqual = EquatableHelper.AreSame(object1, object2);

// Attribute-based object description
var description = ObjectDescriptionHelper.Describe(typeof(MyClass));
// Returns: Name, DisplayName, Description from attributes

// Implement custom equality
public class Order : IEquatableObject
{
    public string Id { get; set; }
    public decimal Total { get; set; }

    public IEnumerable<object?> GetEqualityComponents()
    {
        yield return Id;
        yield return Total;
    }
}

Reflection Utilities

Namespace: Hexalith.Commons.Reflections

Type discovery and mapping utilities.

using Hexalith.Commons.Reflections;

// Find all implementations of an interface
IEnumerable<Type> handlers = ReflectionHelper.GetInstantiableTypesOf<ICommandHandler>();

// Create instances of discovered types
IEnumerable<ICommandHandler> instances = ReflectionHelper.GetInstantiableObjectsOf<ICommandHandler>();

// Type name mapping
var mapper = new TypeMapper();
mapper.Register<OrderCreatedEvent>("order-created");
Type eventType = mapper.GetType("order-created");

Date Utilities

Namespace: Hexalith.Commons.Dates

Timezone-aware date operations.

using Hexalith.Commons.Dates;

// Convert DateOnly to DateTimeOffset with timezone
DateOnly date = new(2024, 1, 15);
TimeSpan offset = TimeSpan.FromHours(-5); // EST
DateTimeOffset result = DateHelper.ToLocalTime(date, offset);

// Convert to UTC
DateTimeOffset utc = DateHelper.ToUniversalTime(date);

// Calculate wait time between dates
TimeSpan waitTime = DateHelper.WaitTime(targetDate, currentDate);

Assembly Utilities

Namespace: Hexalith.Commons.Assemblies

Version information retrieval.

using Hexalith.Commons.Assemblies;

// Get entry assembly version
string? version = VersionHelper.EntryProductVersion();

// Get version from specific assembly
string? assemblyVersion = typeof(MyClass).Assembly.GetAssemblyVersion();

Logging Helpers

Namespace: Hexalith.Commons.Helpers

Structured logging for application errors.

using Hexalith.Commons.Helpers;

// Log application errors with full context
logger.LogApplicationError(applicationError);

Hexalith.Commons.Configurations

Type-safe configuration management with validation support.

Defining Settings

using Hexalith.Commons.Configurations;

public class DatabaseSettings : ISettings
{
    public string ConnectionString { get; set; } = string.Empty;
    public int CommandTimeout { get; set; } = 30;
    public int MaxRetryCount { get; set; } = 3;

    // Configuration section name in appsettings.json
    public static string ConfigurationName() => "Database";
}

appsettings.json:

{
  "Database": {
    "ConnectionString": "Server=localhost;Database=MyApp",
    "CommandTimeout": 60,
    "MaxRetryCount": 5
  }
}

Registration and Usage

// Program.cs - Register settings
builder.Services.ConfigureSettings<DatabaseSettings>(builder.Configuration);

// Service class - Inject and use
public class DataService
{
    private readonly DatabaseSettings _settings;

    public DataService(IOptions<DatabaseSettings> options)
    {
        _settings = options.Value;

        // Validate required settings
        SettingsException<DatabaseSettings>.ThrowIfUndefined(_settings.ConnectionString);
    }
}

FluentValidation Integration

using FluentValidation;

public class DatabaseSettingsValidator : AbstractValidator<DatabaseSettings>
{
    public DatabaseSettingsValidator()
    {
        RuleFor(x => x.ConnectionString)
            .NotEmpty()
            .WithMessage("Database connection string is required");

        RuleFor(x => x.CommandTimeout)
            .InclusiveBetween(1, 300)
            .WithMessage("Command timeout must be between 1 and 300 seconds");
    }
}

// Registration with validation
services.ConfigureSettings<DatabaseSettings>(configuration);
services.AddValidatorsFromAssemblyContaining<DatabaseSettingsValidator>();

Hexalith.Commons.StringEncoders

Reversible string encoding for RFC1123-compliant contexts.

Encoding Rules

Usage Examples

using Hexalith.Commons.StringEncoders;

// Basic encoding
string encoded = "Hello World!".ToRFC1123();
// Result: "Hello_20World_21"

// Unicode support
string chinese = "你好".ToRFC1123();
// Result: "_E4_BD_A0_E5_A5_BD"

// Email addresses
string email = "user@example.com".ToRFC1123();
// Result: "user_40example.com"

// Decoding
string original = "Hello_20World_21".FromRFC1123();
// Result: "Hello World!"

// Round-trip guarantee
string input = "Any string with émojis 🎉!";
string roundTrip = input.ToRFC1123().FromRFC1123();
Assert.Equal(input, roundTrip);  // Always true

Use Cases

• File system paths: Generate safe filenames from user input
• URL identifiers: Create URL-safe slugs from arbitrary text
• Message headers: Encode values for protocols with character restrictions
• Database keys: Create compliant identifiers from any string

Hexalith.Commons.UniqueIds

Three ID strategies — DateTime, Base64URL, and ULID — plus bidirectional ULID-Guid conversion.

Quick Start

using Hexalith.Commons.UniqueIds;

// Sortable + distributed (event sourcing, DDD aggregates)
string ulidId = UniqueIdHelper.GenerateSortableUniqueStringId();
// "01HYX7QS3NP8M4KQJR5A7CVWKM" — 26-char ULID

// Distributed (legacy keys, session tokens)
string base64Id = UniqueIdHelper.GenerateUniqueStringId();
// "gZOW2EgVrEq5SBJLegYcVA" — 22-char Base64URL

// Human-readable (single machine, logs)
string dateId = UniqueIdHelper.GenerateDateTimeId();
// "20260314143052789" — 17-char timestamp

Strategy Comparison

ULID-Guid Conversion Utilities

Bidirectional conversion between ULID strings and System.Guid for interop with Guid-only systems.

// ULID → Guid (for external systems that require Guid)
string ulid = UniqueIdHelper.GenerateSortableUniqueStringId();
Guid guid = UniqueIdHelper.ToGuid(ulid);

// Guid → ULID (lossless round-trip)
string restored = UniqueIdHelper.ToSortableUniqueId(guid);
// restored == ulid (case-insensitive)

// Extract creation timestamp from any ULID
DateTimeOffset created = UniqueIdHelper.ExtractTimestamp(ulid);

Note: ToGuid preserves identity but NOT lexicographic sort order. Converting a non-ULID Guid (e.g., Guid.NewGuid()) produces a valid ULID string, but its embedded timestamp is meaningless.

Decision Guide

Hexalith.Commons.Metadatas

Metadata structures for message tracking in distributed systems.

Metadata Structure

Metadata
├── MessageMetadata
│   ├── Id          (string)    - Unique message identifier
│   ├── Name        (string)    - Message type name
│   ├── Version     (int)       - Message schema version
│   ├── CreatedDate (DateTimeOffset)
│   └── Domain      (DomainMetadata)
│       ├── Id      (string)    - Aggregate identifier
│       └── Name    (string)    - Aggregate type name
└── ContextMetadata
    ├── CorrelationId  (string) - Request correlation
    ├── UserId         (string) - User performing action
    ├── PartitionId    (string) - Partition for distribution
    ├── SessionId      (string) - User session
    ├── SequenceNumber (long)   - Message ordering
    ├── ReceivedDate   (DateTimeOffset)
    └── Scopes         (IEnumerable<string>)

Usage Example

using Hexalith.Commons.Metadatas;

// Create message metadata
var messageMetadata = new MessageMetadata(
    Id: UniqueIdHelper.GenerateUniqueStringId(),
    Name: "OrderCreated",
    Version: 1,
    Domain: new DomainMetadata(Id: "ORD-12345", Name: "Order"),
    CreatedDate: DateTimeOffset.UtcNow
);

// Create context metadata
var contextMetadata = new ContextMetadata(
    CorrelationId: correlationId,
    UserId: currentUser.Id,
    PartitionId: tenantId,
    SessionId: sessionId,
    SequenceNumber: 1,
    ReceivedDate: DateTimeOffset.UtcNow,
    Scopes: new[] { "orders", "write" }
);

// Combine into complete metadata
var metadata = new Metadata(messageMetadata, contextMetadata);

// Generate domain global identifier
string globalId = metadata.DomainGlobalId;
// Format: "{partitionId}-{aggregateName}-{aggregateId}"

// Logging-friendly representation
string logEntry = metadata.ToLogString();

Use Cases

• Event sourcing: Track event origin and context
• Message routing: Route messages based on partition and domain
• Audit trails: Complete traceability of all operations
• Correlation: Link related messages across services
• Ordering: Maintain message sequence within partitions

Quality Metrics

Building from Source

# Clone the repository
git clone https://github.com/Hexalith/Hexalith.Commons.git
cd Hexalith.Commons

# Build
dotnet build

# Build the complete owned-project package-mode surface used by dependency governance
dotnet build Hexalith.Commons.Standalone.slnx -c Release -p:UseNuGetDeps=true

# Run tests
dotnet test

Hexalith.Commons.slnx remains the canonical development solution. The Hexalith.Commons.Standalone.slnx solution is a governance-only inventory of all 20 owned projects and deliberately excludes projects and files under references/.

Releases are dispatched manually from .github/workflows/release.yml after CI passes for the current main commit. The production environment requires approval before publication. The release validates and publishes all 12 Commons packages using NuGet trusted publishing.

Set the repository variable NUGET_USER to the individual NuGet.org username that created the trusted publishing policy, and keep HEXALITH_RELEASE_PUBLISH_ENABLED set to true to enable publication. The NuGet policy must trust repository Hexalith/Hexalith.Commons, workflow release.yml, and environment production. The workflow exchanges its OIDC identity for a short-lived credential; it does not use a stored NUGET_API_KEY secret.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

• GitHub Repository
• NuGet Packages
• Discord Community
• Issue Tracker