NuvTools.Common

A cross-platform utility library for .NET 8, 9, and 10, designed to streamline development for Web, Desktop, and Mobile (MAUI) applications.

Installation

Install via NuGet Package Manager:

dotnet add package NuvTools.Common

Or via Package Manager Console:

Install-Package NuvTools.Common

Overview

NuvTools.Common provides a rich set of reusable components, extension methods, and helpers that address frequent programming needs, focusing on consistency, safety, and productivity. The library follows modern .NET best practices with nullable reference types, async/await patterns, and minimal dependencies.

Key Features

1. ResultWrapper - Railway-Oriented Programming

Standardize operation outcomes with a fluent result pattern supporting success, error, and validation states.

using NuvTools.Common.ResultWrapper;

public IResult<User> GetUser(int id)
{
    if (id <= 0)
        return Result<User>.ValidationFail("Invalid user ID");

    var user = _repository.FindById(id);
    if (user == null)
        return Result<User>.FailNotFound("User not found");

    return Result<User>.Success(user, new MessageDetail("User retrieved successfully"));
}

// Usage
var result = GetUser(123);
if (result.Succeeded)
{
    Console.WriteLine($"Found user: {result.Data.Name}");
}
else
{
    Console.WriteLine($"Error: {result.Message}");
}

Features:

Generic Result<T> and Result<T, E> for typed returns
Factory methods: Success(), Fail(), ValidationFail(), FailNotFound()
Structured messages with MessageDetail (code, severity, title, detail)
Built-in logging integration with ILogger
HTTP response conversion via ToResultAsync()

2. Timezone-Aware Date/Time Service

Cross-platform timezone handling with dependency injection support.

using NuvTools.Common.Dates;
using NuvTools.Common.Dates.Enumerations;

// Configure in DI container
services.AddDateTimeService(TimeZoneRegion.Brasilia);

// Use in your service
public class OrderService
{
    private readonly IDateTimeService _dateTime;

    public OrderService(IDateTimeService dateTime)
    {
        _dateTime = dateTime;
    }

    public void CreateOrder()
    {
        var orderTime = _dateTime.Now; // Local time in Brasilia
        var utcTime = _dateTime.UtcNow; // Always UTC
    }
}

// Extension methods for conversion
var localTime = DateTime.UtcNow.ToTimeZone(TimeZoneRegion.Tokyo, UtcDirection.FromUtc);

Features:

19 predefined timezone regions (Brasilia, UTC, Tokyo, NYC, London, etc.)
Automatic Windows/IANA timezone ID mapping
IDateTimeService abstraction for testability
Custom UTC offset support

3. Enhanced Enum Support

Extract rich metadata from enums using DisplayAttribute and DescriptionAttribute.

using NuvTools.Common.Enums;
using System.ComponentModel.DataAnnotations;

public enum Status
{
    [Display(Name = "Active", ShortName = "ACT", Description = "Currently active")]
    Active = 1,

    [Display(Name = "Inactive", ShortName = "INA", Description = "Not active")]
    Inactive = 2
}

public enum Priority
{
    Low = 1,
    Medium = 2,
    High = 3
}

// Extract metadata
var name = Status.Active.GetName();           // "Active"
var shortName = Status.Active.GetShortName(); // "ACT"
var description = Status.Active.GetDescription(); // "Currently active"

// Convert to list for dropdowns
var statusList = Enumeration.ToList<Status>();

// Find enum by metadata
var status = Enumeration.GetEnumByShortName<Status>("ACT"); // Status.Active

// Concatenate enum values into a composite integer
int composite = Enumeration.ConcatEnumValues(Status.Active, Priority.High);
// Result: 13 (concatenation of "1" + "3")

int multiValue = Enumeration.ConcatEnumValues(Status.Active, Status.Inactive, Priority.Medium);
// Result: 122 (concatenation of "1" + "2" + "2")

Features:

Extract Name, ShortName, Description, GroupName from DisplayAttribute
Fallback to DescriptionAttribute when DisplayAttribute is not present
Convert enums to lists for UI dropdowns with sorting options
Find enum values by metadata (name, short name, description)
Concatenate multiple enum values into a single composite integer
Support for different underlying types (int, byte, short, long)

4. String Extensions

Powerful string manipulation utilities.

using NuvTools.Common.Strings;

// Extract substrings
string text = "Hello World";
text.Left(5);  // "Hello"
text.Right(5); // "World"

// Remove diacritics
"Olá, Mundo!".RemoveDiacritics(); // "Ola, Mundo!"

// Advanced formatting with named placeholders
var template = "Hello {name}, you have {count} messages";
template.Format(new Dictionary<string, object>
{
    { "name", "John" },
    { "count", 5 }
}); // "Hello John, you have 5 messages"

// Extract numbers
"ABC-123-XYZ-456".GetNumbersOnly(); // "123456"

// Validate JSON
string json = "{\"key\":\"value\"}";
bool isValid = json.IsValidJson(); // true

5. Safe Number Parsing

Parse strings to numeric types with null or zero fallback.

using NuvTools.Common.Numbers;

string value = "123";
long? number = value.ParseToLongOrNull(); // 123

string invalid = "abc";
long? nullResult = invalid.ParseToLongOrNull(); // null
long zeroResult = invalid.ParseToLongOrNull(returnZeroIsNull: true); // 0

// Also available for int, short, decimal
int? intValue = "42".ParseToIntOrNull();
decimal? decimalValue = "3.14".ParseToDecimalOrNull();

6. Web Utilities

Generate and parse query strings from objects.

using NuvTools.Common.Web;

public class SearchRequest
{
    public string Query { get; set; }
    public int Page { get; set; }
    public DateTime? StartDate { get; set; }
}

var request = new SearchRequest
{
    Query = "test",
    Page = 1,
    StartDate = DateTime.Now
};

// Convert to query string
string url = request.GetQueryString("https://api.example.com/search");
// Result: https://api.example.com/search?Query=test&Page=1&StartDate=2025-12-06T10:30:00

// Parse query string back
var dict = "?Query=test&Page=1".ParseQueryString();

7. Exception Utilities

Aggregate multi-level exception messages for better error reporting.

using NuvTools.Common.Exceptions;

try
{
    // Code that throws nested exceptions
}
catch (Exception ex)
{
    // Get all inner exception messages
    string fullMessage = ex.AggregateExceptionMessages(level: 3);
    // Result: "Level 0: Outer exception -> Level 1: Inner exception -> Level 2: Root cause"
}

8. Stream Extensions

Convert streams to byte arrays with sync and async support.

using NuvTools.Common.IO;

// Async
byte[] bytes = await stream.ToByteListAsync();

// Sync
byte[] bytes = stream.ToByteList();

9. Assembly Reflection

Extract metadata from assemblies.

using NuvTools.Common.Reflection;

var assembly = Assembly.GetExecutingAssembly();
var info = assembly.ProgramInfo();

Console.WriteLine($"Name: {info.Name}");
Console.WriteLine($"Version: {info.Version}");
Console.WriteLine($"Description: {info.Description}");

// List all referenced assemblies
var components = assembly.ListComponent();

10. JSON Serialization

Deep cloning and serialization utilities.

using NuvTools.Common.Serialization.Json;

var original = new MyObject { Name = "Test" };
var clone = original.Clone();

string json = original.Serialize();
var deserialized = json.Deserialize<MyObject>();

Why NuvTools.Common?

✅ Type-Safe - Strong typing and generics throughout ✅ Null-Safe - Nullable reference types enabled with defensive coding ✅ Async-First - Modern async/await patterns with ConfigureAwait(false) ✅ Minimal Dependencies - Only depends on Microsoft.Extensions.Logging.Abstractions ✅ Cross-Platform - Works on Windows, Linux, and macOS ✅ Well-Documented - Complete XML documentation for IntelliSense ✅ Battle-Tested - Strong-named, production-ready code ✅ Multi-Targeted - Supports .NET 8, 9, and 10

Supported Frameworks

.NET 8.0
.NET 9.0
.NET 10.0

Requirements

No external dependencies (except Microsoft.Extensions.Logging.Abstractions for logging integration)
Works with Web, Desktop, Console, and MAUI applications

Documentation

All public APIs include comprehensive XML documentation. IntelliSense will show detailed information about:

Method purposes and usage
Parameter descriptions
Return values
Exception scenarios
Code examples

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the terms specified in the LICENSE file.

Repository

GitHub: https://github.com/nuvtools/nuvtools-common
NuGet: https://www.nuget.org/packages/NuvTools.Common/
Website: https://nuvtools.com

NuvTools.Common

A cross-platform utility library for .NET 8, 9, and 10, designed to streamline development for Web, Desktop, and Mobile (MAUI) applications.

Installation

Install via NuGet Package Manager:

dotnet add package NuvTools.Common

Or via Package Manager Console:

Install-Package NuvTools.Common

Overview

Key Features

1. ResultWrapper - Railway-Oriented Programming

Standardize operation outcomes with a fluent result pattern supporting success, error, and validation states.

using NuvTools.Common.ResultWrapper;

public IResult<User> GetUser(int id)
{
    if (id <= 0)
        return Result<User>.ValidationFail("Invalid user ID");

    var user = _repository.FindById(id);
    if (user == null)
        return Result<User>.FailNotFound("User not found");

    return Result<User>.Success(user, new MessageDetail("User retrieved successfully"));
}

// Usage
var result = GetUser(123);
if (result.Succeeded)
{
    Console.WriteLine($"Found user: {result.Data.Name}");
}
else
{
    Console.WriteLine($"Error: {result.Message}");
}

Features:

Generic Result<T> and Result<T, E> for typed returns
Factory methods: Success(), Fail(), ValidationFail(), FailNotFound()
Structured messages with MessageDetail (code, severity, title, detail)
Built-in logging integration with ILogger
HTTP response conversion via ToResultAsync()

2. Timezone-Aware Date/Time Service

Cross-platform timezone handling with dependency injection support.

using NuvTools.Common.Dates;
using NuvTools.Common.Dates.Enumerations;

// Configure in DI container
services.AddDateTimeService(TimeZoneRegion.Brasilia);

// Use in your service
public class OrderService
{
    private readonly IDateTimeService _dateTime;

    public OrderService(IDateTimeService dateTime)
    {
        _dateTime = dateTime;
    }

    public void CreateOrder()
    {
        var orderTime = _dateTime.Now; // Local time in Brasilia
        var utcTime = _dateTime.UtcNow; // Always UTC
    }
}

// Extension methods for conversion
var localTime = DateTime.UtcNow.ToTimeZone(TimeZoneRegion.Tokyo, UtcDirection.FromUtc);

Features:

19 predefined timezone regions (Brasilia, UTC, Tokyo, NYC, London, etc.)
Automatic Windows/IANA timezone ID mapping
IDateTimeService abstraction for testability
Custom UTC offset support

3. Enhanced Enum Support

Extract rich metadata from enums using DisplayAttribute and DescriptionAttribute.

using NuvTools.Common.Enums;
using System.ComponentModel.DataAnnotations;

public enum Status
{
    [Display(Name = "Active", ShortName = "ACT", Description = "Currently active")]
    Active = 1,

    [Display(Name = "Inactive", ShortName = "INA", Description = "Not active")]
    Inactive = 2
}

public enum Priority
{
    Low = 1,
    Medium = 2,
    High = 3
}

// Extract metadata
var name = Status.Active.GetName();           // "Active"
var shortName = Status.Active.GetShortName(); // "ACT"
var description = Status.Active.GetDescription(); // "Currently active"

// Convert to list for dropdowns
var statusList = Enumeration.ToList<Status>();

// Find enum by metadata
var status = Enumeration.GetEnumByShortName<Status>("ACT"); // Status.Active

// Concatenate enum values into a composite integer
int composite = Enumeration.ConcatEnumValues(Status.Active, Priority.High);
// Result: 13 (concatenation of "1" + "3")

int multiValue = Enumeration.ConcatEnumValues(Status.Active, Status.Inactive, Priority.Medium);
// Result: 122 (concatenation of "1" + "2" + "2")

Features:

Extract Name, ShortName, Description, GroupName from DisplayAttribute
Fallback to DescriptionAttribute when DisplayAttribute is not present
Convert enums to lists for UI dropdowns with sorting options
Find enum values by metadata (name, short name, description)
Concatenate multiple enum values into a single composite integer
Support for different underlying types (int, byte, short, long)

4. String Extensions

Powerful string manipulation utilities.

using NuvTools.Common.Strings;

// Extract substrings
string text = "Hello World";
text.Left(5);  // "Hello"
text.Right(5); // "World"

// Remove diacritics
"Olá, Mundo!".RemoveDiacritics(); // "Ola, Mundo!"

// Advanced formatting with named placeholders
var template = "Hello {name}, you have {count} messages";
template.Format(new Dictionary<string, object>
{
    { "name", "John" },
    { "count", 5 }
}); // "Hello John, you have 5 messages"

// Extract numbers
"ABC-123-XYZ-456".GetNumbersOnly(); // "123456"

// Validate JSON
string json = "{\"key\":\"value\"}";
bool isValid = json.IsValidJson(); // true

5. Safe Number Parsing

Parse strings to numeric types with null or zero fallback.

using NuvTools.Common.Numbers;

string value = "123";
long? number = value.ParseToLongOrNull(); // 123

string invalid = "abc";
long? nullResult = invalid.ParseToLongOrNull(); // null
long zeroResult = invalid.ParseToLongOrNull(returnZeroIsNull: true); // 0

// Also available for int, short, decimal
int? intValue = "42".ParseToIntOrNull();
decimal? decimalValue = "3.14".ParseToDecimalOrNull();

6. Web Utilities

Generate and parse query strings from objects.

using NuvTools.Common.Web;

public class SearchRequest
{
    public string Query { get; set; }
    public int Page { get; set; }
    public DateTime? StartDate { get; set; }
}

var request = new SearchRequest
{
    Query = "test",
    Page = 1,
    StartDate = DateTime.Now
};

// Convert to query string
string url = request.GetQueryString("https://api.example.com/search");
// Result: https://api.example.com/search?Query=test&Page=1&StartDate=2025-12-06T10:30:00

// Parse query string back
var dict = "?Query=test&Page=1".ParseQueryString();

7. Exception Utilities

Aggregate multi-level exception messages for better error reporting.

using NuvTools.Common.Exceptions;

try
{
    // Code that throws nested exceptions
}
catch (Exception ex)
{
    // Get all inner exception messages
    string fullMessage = ex.AggregateExceptionMessages(level: 3);
    // Result: "Level 0: Outer exception -> Level 1: Inner exception -> Level 2: Root cause"
}

8. Stream Extensions

Convert streams to byte arrays with sync and async support.

using NuvTools.Common.IO;

// Async
byte[] bytes = await stream.ToByteListAsync();

// Sync
byte[] bytes = stream.ToByteList();

9. Assembly Reflection

Extract metadata from assemblies.

using NuvTools.Common.Reflection;

var assembly = Assembly.GetExecutingAssembly();
var info = assembly.ProgramInfo();

Console.WriteLine($"Name: {info.Name}");
Console.WriteLine($"Version: {info.Version}");
Console.WriteLine($"Description: {info.Description}");

// List all referenced assemblies
var components = assembly.ListComponent();

10. JSON Serialization

Deep cloning and serialization utilities.

using NuvTools.Common.Serialization.Json;

var original = new MyObject { Name = "Test" };
var clone = original.Clone();

string json = original.Serialize();
var deserialized = json.Deserialize<MyObject>();

Why NuvTools.Common?

Supported Frameworks

.NET 8.0
.NET 9.0
.NET 10.0

Requirements

No external dependencies (except Microsoft.Extensions.Logging.Abstractions for logging integration)
Works with Web, Desktop, Console, and MAUI applications

Documentation

All public APIs include comprehensive XML documentation. IntelliSense will show detailed information about:

Method purposes and usage
Parameter descriptions
Return values
Exception scenarios
Code examples

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the terms specified in the LICENSE file.

Repository

GitHub: https://github.com/nuvtools/nuvtools-common
NuGet: https://www.nuget.org/packages/NuvTools.Common/
Website: https://nuvtools.com

nuvtools/NuvTools.Commonv10.0.2

Get Started

Readme

NuvTools.Common

Installation

Overview

Key Features

1. ResultWrapper - Railway-Oriented Programming

2. Timezone-Aware Date/Time Service

3. Enhanced Enum Support

4. String Extensions

5. Safe Number Parsing

6. Web Utilities

7. Exception Utilities

8. Stream Extensions

9. Assembly Reflection

10. JSON Serialization

Why NuvTools.Common?

Supported Frameworks

Requirements

Documentation

Contributing

License

Repository

nuvtools/NuvTools.Commonv10.0.2

Get Started

Readme

NuvTools.Common

Installation

Overview

Key Features

1. ResultWrapper - Railway-Oriented Programming

2. Timezone-Aware Date/Time Service

3. Enhanced Enum Support

4. String Extensions

5. Safe Number Parsing

6. Web Utilities

7. Exception Utilities

8. Stream Extensions

9. Assembly Reflection

10. JSON Serialization

Why NuvTools.Common?

Supported Frameworks

Requirements

Documentation

Contributing

License

Repository