A comprehensive .NET library providing utilities for logging (file/JSON with folder organization), security (JWT, JWK, JWS, TOTP, AES-GCM, password hashing), extensions (string, object, LINQ expressions, DateTime), saga orchestration, COMB GUIDs, Web API pagination, and more.
Get Started
$ dotnet add package MaksIT.CoreReadme
MaksIT.Core Library Documentation
Table of Contents
- Abstractions
- Extensions
- Logging
- Threading
- Networking
- Security
- Web API
- Sagas
- CombGuidGenerator
- Others
Abstractions
Base Classes
The following base classes in the MaksIT.Core.Abstractions namespace provide a foundation for implementing domain, DTO, and Web API models, ensuring consistency and maintainability in application design.
1. DomainObjectBase
Summary
Represents the base class for all domain objects in the application.
Purpose
- Serves as the foundation for all domain objects.
- Provides a place to include shared logic or properties for domain-level entities in the future.
2. DomainDocumentBase<T>
Summary
Represents a base class for domain documents with a unique identifier.
Purpose
- Extends
DomainObjectBaseto include an identifier. - Provides a common structure for domain entities that need unique IDs.
Example Usage
public class UserDomainDocument : DomainDocumentBase<Guid> {
public UserDomainDocument(Guid id) : base(id) {
}
}
3. DtoObjectBase
Summary
Represents the base class for all Data Transfer Objects (DTOs).
Purpose
- Serves as the foundation for all DTOs.
- Provides a place to include shared logic or properties for DTOs in the future.
4. DtoDocumentBase<T>
Summary
Represents a base class for DTOs with a unique identifier.
Purpose
- Extends
DtoObjectBaseto include an identifier. - Provides a common structure for DTOs that need unique IDs.
Example Usage
public class UserDto : DtoDocumentBase<Guid> {
public required string Name { get; set; }
}
5. RequestModelBase
Summary
Represents the base class for Web API request models.
Purpose
- Serves as a foundation for request models used in Web API endpoints.
- Provides a common structure for request validation or shared properties.
Example Usage
public class CreateUserRequest : RequestModelBase {
public required string Name { get; set; }
}
6. ResponseModelBase
Summary
Represents the base class for Web API response models.
Purpose
- Serves as a foundation for response models returned by Web API endpoints.
- Provides a common structure for standardizing API responses.
Example Usage
public class UserResponse : ResponseModelBase {
public required Guid Id { get; set; }
public required string Name { get; set; }
}
Features and Benefits
-
Consistency:
- Ensures a uniform structure for domain, DTO, and Web API models.
-
Extensibility:
- Base classes can be extended to include shared properties or methods as needed.
-
Type Safety:
- Generic identifiers (
T) ensure type safety for domain documents and DTOs.
- Generic identifiers (
-
Reusability:
- Common logic or properties can be added to base classes and reused across the application.
Example End-to-End Usage
// Domain Class
public class ProductDomain : DomainDocumentBase<int> {
public ProductDomain(int id) : base(id) { }
public string Name { get; set; } = string.Empty;
}
// DTO Class
public class ProductDto : DtoDocumentBase<int> {
public required string Name { get; set; }
}
// Web API Request Model
public class CreateProductRequest : RequestModelBase {
public required string Name { get; set; }
}
// Web API Response Model
public class ProductResponse : ResponseModelBase {
public required int Id { get; set; }
public required string Name { get; set; }
}
Best Practices
-
Keep Base Classes Lightweight:
- Avoid adding unnecessary properties or methods to base classes.
-
Encapsulation:
- Use base classes to enforce encapsulation and shared behavior across entities.
-
Validation:
- Extend
RequestModelBaseorResponseModelBaseto include validation logic if needed.
- Extend
This structure promotes clean code principles, reducing redundancy and improving maintainability across the application layers.
CombGuidGenerator
The CombGuidGenerator class in the MaksIT.Core.Comb namespace provides methods for generating and extracting COMB GUIDs (GUIDs with embedded timestamps). COMB GUIDs improve index locality by combining randomness with a sortable timestamp.
Features
-
Generate COMB GUIDs:
- Create GUIDs with embedded timestamps for improved database indexing.
-
Extract Timestamps:
- Retrieve the embedded timestamp from a COMB GUID.
-
Support for Multiple Formats:
- Generate COMB GUIDs compatible with SQL Server and PostgreSQL.
Example Usage
Generating a COMB GUID
var baseGuid = Guid.NewGuid();
var timestamp = DateTime.UtcNow;
// Generate a COMB GUID for SQL Server
var combGuid = CombGuidGenerator.CreateCombGuid(baseGuid, timestamp, CombGuidType.SqlServer);
// Generate a COMB GUID for PostgreSQL
var combGuidPostgres = CombGuidGenerator.CreateCombGuid(baseGuid, timestamp, CombGuidType.PostgreSql);
Extracting a Timestamp
var extractedTimestamp = CombGuidGenerator.ExtractTimestamp(combGuid, CombGuidType.SqlServer);
Console.WriteLine($"Extracted Timestamp: {extractedTimestamp}");
Generating a COMB GUID with Current Timestamp
var combGuidWithCurrentTimestamp = CombGuidGenerator.CreateCombGuid(Guid.NewGuid(), CombGuidType.SqlServer);
Best Practices
-
Use COMB GUIDs for Indexing:
- COMB GUIDs are ideal for database indexing as they improve index locality.
-
Choose the Correct Format:
- Use
CombGuidType.SqlServerfor SQL Server andCombGuidType.PostgreSqlfor PostgreSQL.
- Use
-
Ensure UTC Timestamps:
- Always use UTC timestamps to ensure consistency across systems.
The CombGuidGenerator class simplifies the creation and management of COMB GUIDs, making it easier to work with GUIDs in database applications.
Enumeration
The Enumeration class in the MaksIT.Core.Abstractions namespace provides a base class for creating strongly-typed enumerations. It enables you to define enumerable constants with additional functionality, such as methods for querying, comparing, and parsing enumerations.
Features and Benefits
-
Strongly-Typed Enumerations:
- Combines the clarity of enums with the extensibility of classes.
- Supports additional fields, methods, or logic as needed.
-
Reflection Support:
- Dynamically retrieve all enumeration values with
GetAll.
- Dynamically retrieve all enumeration values with
-
Parsing Capabilities:
- Retrieve enumeration values by ID or display name.
-
Comparison and Equality:
- Fully implements equality and comparison operators for use in collections and sorting.
Example Usage
Defining an Enumeration
public class MyEnumeration : Enumeration {
public static readonly MyEnumeration Value1 = new(1, "Value One");
public static readonly MyEnumeration Value2 = new(2, "Value Two");
private MyEnumeration(int id, string name) : base(id, name) { }
}
Retrieving All Values
var allValues = Enumeration.GetAll<MyEnumeration>();
allValues.ToList().ForEach(Console.WriteLine);
Parsing by ID or Name
var valueById = Enumeration.FromValue<MyEnumeration>(1);
var valueByName = Enumeration.FromDisplayName<MyEnumeration>("Value One");
Console.WriteLine(valueById); // Output: Value One
Console.WriteLine(valueByName); // Output: Value One
Comparing Enumeration Values
var difference = Enumeration.AbsoluteDifference(MyEnumeration.Value1, MyEnumeration.Value2);
Console.WriteLine($"Absolute Difference: {difference}"); // Output: 1
Using in Collections
var values = new List<MyEnumeration> { MyEnumeration.Value2, MyEnumeration.Value1 };
values.Sort(); // Orders by ID
Best Practices
-
Extend for Specific Enums:
- Create specific subclasses for each enumeration type.
-
Avoid Duplicates:
- Ensure unique IDs and names for each enumeration value.
-
Use Reflection Sparingly:
- Avoid calling
GetAllin performance-critical paths.
- Avoid calling
The Enumeration class provides a powerful alternative to traditional enums, offering flexibility and functionality for scenarios requiring additional metadata or logic.
Sagas
The Sagas namespace in the MaksIT.Core project provides a framework for managing distributed transactions or workflows. It includes classes for defining saga steps, contexts, and builders.
Features
-
Saga Context:
- Manage the state and data of a saga.
-
Saga Steps:
- Define individual steps in a saga workflow.
-
Saga Builder:
- Build and execute sagas dynamically.
Example Usage
Defining a Saga Step
public class MySagaStep : LocalSagaStep {
public override Task ExecuteAsync(LocalSagaContext context) {
// Perform step logic here
return Task.CompletedTask;
}
}
Building a Saga
var saga = new LocalSagaBuilder()
.AddStep(new MySagaStep())
.Build();
await saga.ExecuteAsync();
Best Practices
-
Idempotency:
- Ensure saga steps are idempotent to handle retries gracefully.
-
Error Handling:
- Implement robust error handling and compensation logic for failed steps.
-
State Management:
- Use the saga context to manage state and pass data between steps.
The Sagas namespace simplifies the implementation of distributed workflows, making it easier to manage complex transactions and processes.
Extensions
Expression Extensions
The ExpressionExtensions class provides utility methods for combining and manipulating LINQ expressions. These methods are particularly useful for building dynamic queries in a type-safe manner.
Features
-
Combine Expressions:
- Combine two expressions using logical operators like
AndAlsoandOrElse.
- Combine two expressions using logical operators like
-
Negate Expressions:
- Negate an expression using the
Notmethod.
- Negate an expression using the
-
Batch Processing:
- Divide a collection into smaller batches for processing.
Example Usage
Combining Expressions
Expression<Func<int, bool>> isEven = x => x % 2 == 0;
Expression<Func<int, bool>> isPositive = x => x > 0;
var combined = isEven.AndAlso(isPositive);
var result = combined.Compile()(4); // True
Negating Expressions
Expression<Func<int, bool>> isEven = x => x % 2 == 0;
var notEven = isEven.Not();
var result = notEven.Compile()(3); // True
DateTime Extensions
The DateTimeExtensions class provides methods for manipulating and querying DateTime objects. These methods simplify common date-related operations.
Features
-
Add Workdays:
- Add a specified number of workdays to a date, excluding weekends and holidays.
-
Find Specific Dates:
- Find the next occurrence of a specific day of the week.
-
Month and Year Boundaries:
- Get the start or end of the current month or year.
Example Usage
Adding Workdays
DateTime today = DateTime.Today;
DateTime futureDate = today.AddWorkdays(5);
Finding the Next Monday
DateTime today = DateTime.Today;
DateTime nextMonday = today.NextWeekday(DayOfWeek.Monday);
String Extensions
The StringExtensions class provides a wide range of methods for string manipulation, validation, and conversion.
Features
-
Pattern Matching:
- Check if a string matches a pattern using SQL-like wildcards.
-
Substring Extraction:
- Extract substrings from the left, right, or middle of a string.
-
Type Conversion:
- Convert strings to various types, such as integers, booleans, and enums.
Example Usage
Pattern Matching
bool matches = "example".Like("exa*e"); // True
Substring Extraction
string result = "example".Left(3); // "exa"
Object Extensions
The ObjectExtensions class provides advanced methods for working with objects, including serialization, deep cloning, and structural equality comparison.
Features
-
JSON Serialization:
- Convert objects to JSON strings with optional custom converters.
-
Deep Cloning:
- Create a deep clone of an object, preserving reference identity and supporting cycles.
-
Structural Equality:
- Compare two objects deeply for structural equality, including private fields.
-
Snapshot Reversion:
- Revert an object to a previous state by copying all fields from a snapshot.
Example Usage
JSON Serialization
var person = new { Name = "John", Age = 30 };
string json = person.ToJson();
// With custom converters
var converters = new List<JsonConverter> { new CustomConverter() };
string jsonWithConverters = person.ToJson(converters);
Deep Cloning
var original = new Person { Name = "John", Age = 30 };
var clone = original.DeepClone();
Structural Equality
var person1 = new Person { Name = "John", Age = 30 };
var person2 = new Person { Name = "John", Age = 30 };
bool areEqual = person1.DeepEqual(person2); // True
Snapshot Reversion
var snapshot = new Person { Name = "John", Age = 30 };
var current = new Person { Name = "Doe", Age = 25 };
current.RevertFrom(snapshot);
// current.Name is now "John"
// current.Age is now 30
Best Practices
-
Use Deep Cloning for Complex Objects:
- Ensure objects are deeply cloned when working with mutable reference types.
-
Validate Structural Equality:
- Use
DeepEqualfor scenarios requiring precise object comparisons.
- Use
-
Revert State Safely:
- Use
RevertFromto safely restore object states in tracked entities.
- Use
DataTable Extensions
The DataTableExtensions class provides methods for working with DataTable objects, such as counting duplicate rows and retrieving distinct records.
Features
-
Count Duplicates:
- Count duplicate rows between two
DataTableinstances.
- Count duplicate rows between two
-
Retrieve Distinct Records:
- Get distinct rows based on specified columns.
Example Usage
Counting Duplicates
int duplicateCount = table1.DuplicatesCount(table2);
Retrieving Distinct Records
DataTable distinctTable = table.DistinctRecords(new[] { "Name", "Age" });
Guid Extensions
The GuidExtensions class provides methods for working with Guid values, including converting them to nullable types.
Features
- Convert to Nullable:
- Convert a
Guidto a nullableGuid?, returningnullif theGuidis empty.
- Convert a
Example Usage
Converting to Nullable
Guid id = Guid.NewGuid();
Guid? nullableId = id.ToNullable();
Logging
The Logging namespace provides a custom file-based logging implementation that integrates with the Microsoft.Extensions.Logging framework.
File Logger
The FileLogger class in the MaksIT.Core.Logging namespace provides a simple and efficient way to log messages to plain text files. It supports log retention policies and ensures thread-safe writes using the LockManager.
Features
-
Plain Text Logging:
- Logs messages in a human-readable plain text format.
-
Log Retention:
- Automatically deletes old log files based on a configurable retention period.
-
Thread Safety:
- Ensures safe concurrent writes to the log file using the
LockManager.
- Ensures safe concurrent writes to the log file using the
-
Folder-Based Logging:
- Organize logs into subfolders using the
LoggerPrefixfeature.
- Organize logs into subfolders using the
Example Usage
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddFileLogger("logs", TimeSpan.FromDays(7)));
var logger = services.BuildServiceProvider().GetRequiredService<ILogger<FileLogger>>();
logger.LogInformation("Logging to file!");
JSON File Logger
The JsonFileLogger class in the MaksIT.Core.Logging namespace provides structured logging in JSON format. It is ideal for machine-readable logs and integrates seamlessly with log aggregation tools.
Features
-
JSON Logging:
- Logs messages in structured JSON format, including timestamps, log levels, and exceptions.
-
Log Retention:
- Automatically deletes old log files based on a configurable retention period.
-
Thread Safety:
- Ensures safe concurrent writes to the log file using the
LockManager.
- Ensures safe concurrent writes to the log file using the
-
Folder-Based Logging:
- Organize logs into subfolders using the
LoggerPrefixfeature.
- Organize logs into subfolders using the
Example Usage
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddJsonFileLogger("logs", TimeSpan.FromDays(7)));
var logger = services.BuildServiceProvider().GetRequiredService<ILogger<JsonFileLogger>>();
logger.LogInformation("Logging to JSON file!");
Logger Prefix
The LoggerPrefix class in the MaksIT.Core.Logging namespace provides a type-safe way to specify logger categories with special prefixes. It extends the Enumeration base class and enables organizing logs into subfolders or applying custom categorization without using magic strings.
Features
-
Type-Safe Prefixes:
- Avoid magic strings by using strongly-typed prefix constants.
-
Folder-Based Organization:
- Use
LoggerPrefix.Folderto write logs to specific subfolders.
- Use
-
Extensible Categories:
- Additional prefixes like
LoggerPrefix.CategoryandLoggerPrefix.Tagare available for future use.
- Additional prefixes like
-
Automatic Parsing:
- Parse category names to extract prefix and value using
LoggerPrefix.Parse().
- Parse category names to extract prefix and value using
-
Backward Compatible:
- Standard
ILogger<T>usage remains unchanged; prefixes are only applied when explicitly used.
- Standard
Available Prefixes
| Prefix | Purpose |
|---|---|
LoggerPrefix.Folder | Writes logs to a subfolder with the specified name |
LoggerPrefix.Category | Reserved for categorization (future use) |
LoggerPrefix.Tag | Reserved for tagging (future use) |
Example Usage
Creating a Logger with a Folder Prefix
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddFileLogger("logs", TimeSpan.FromDays(7)));
var provider = services.BuildServiceProvider();
var loggerFactory = provider.GetRequiredService<ILoggerFactory>();
// Create a logger that writes to logs/Audit/log_yyyy-MM-dd.txt
var auditLogger = loggerFactory.CreateLogger(LoggerPrefix.Folder.WithValue("Audit"));
auditLogger.LogInformation("Audit event occurred");
// Create a logger that writes to logs/Orders/log_yyyy-MM-dd.txt
var ordersLogger = loggerFactory.CreateLogger(LoggerPrefix.Folder.WithValue("Orders"));
ordersLogger.LogInformation("Order processed");
Standard ILogger Usage (Unchanged)
// Standard usage - logs go to the default folder (logs/log_yyyy-MM-dd.txt)
var logger = provider.GetRequiredService<ILogger<MyService>>();
logger.LogInformation("Standard log message");
Parsing a Category Name
var categoryName = "Folder:Audit";
var (prefix, value) = LoggerPrefix.Parse(categoryName);
if (prefix == LoggerPrefix.Folder) {
Console.WriteLine($"Folder: {value}"); // Output: Folder: Audit
}
Result
| Logger Creation | Log File Location |
|---|---|
ILogger<MyService> | logs/log_2026-01-30.txt |
CreateLogger(LoggerPrefix.Folder.WithValue("Audit")) | logs/Audit/log_2026-01-30.txt |
CreateLogger(LoggerPrefix.Folder.WithValue("Orders")) | logs/Orders/log_2026-01-30.txt |
Best Practices
-
Use Type-Safe Prefixes:
- Always use
LoggerPrefix.Folder.WithValue()instead of raw strings like"Folder:Audit".
- Always use
-
Organize by Domain:
- Use meaningful folder names to organize logs by domain (e.g., "Audit", "Orders", "Security").
-
Keep Default Logging Simple:
- Use standard
ILogger<T>for general application logging and folder prefixes for specialized logs.
- Use standard
Threading
Lock Manager
The LockManager class in the MaksIT.Core.Threading namespace provides a robust solution for managing concurrency and rate limiting. It ensures safe access to shared resources in multi-threaded or multi-process environments.
Features
-
Thread Safety:
- Ensures mutual exclusion using a semaphore.
-
Rate Limiting:
- Limits the frequency of access to shared resources using a token bucket rate limiter.
-
Reentrant Locks:
- Supports reentrant locks for the same thread.
Example Usage
var lockManager = new LockManager();
await lockManager.ExecuteWithLockAsync(async () => {
// Critical section
Console.WriteLine("Executing safely");
});
lockManager.Dispose();
Networking
Network Connection
The NetworkConnection class provides methods for managing connections to network shares on Windows.
Features
-
Connect to Network Shares:
- Establish connections to shared network resources.
-
Error Handling:
- Provides detailed error messages for connection failures.
Example Usage
var credentials = new NetworkCredential("username", "password");
if (NetworkConnection.TryCreate(logger, "\\server\share", credentials, out var connection, out var error)) {
connection.Dispose();
}
Ping Port
The PingPort class provides methods for checking the reachability of a host on specified TCP or UDP ports.
Features
-
TCP Port Checking:
- Check if a TCP port is reachable.
-
UDP Port Checking:
- Check if a UDP port is reachable.
Example Usage
Checking a TCP Port
if (PingPort.TryHostPort("example.com", 80, out var error)) {
Console.WriteLine("Port is reachable.");
}
Security
AES-GCM Utility
The AESGCMUtility class provides methods for encrypting and decrypting data using AES-GCM.
Features
-
Secure Encryption:
- Encrypt data with AES-GCM.
-
Data Integrity:
- Ensure data integrity with authentication tags.
Example Usage
Encrypting Data
var key = AESGCMUtility.GenerateKeyBase64();
AESGCMUtility.TryEncryptData(data, key, out var encryptedData, out var error);
Base32 Encoder
The Base32Encoder class provides methods for encoding and decoding data in Base32 format.
Features
-
Encoding:
- Encode binary data to Base32.
-
Decoding:
- Decode Base32 strings to binary data.
Example Usage
Encoding Data
Base32Encoder.TryEncode(data, out var encoded, out var error);
Checksum Utility
The ChecksumUtility class provides methods for calculating and verifying CRC32 checksums.
Features
-
Checksum Calculation:
- Calculate CRC32 checksums for data.
-
Checksum Verification:
- Verify data integrity using CRC32 checksums.
Example Usage
Calculating a Checksum
ChecksumUtility.TryCalculateCRC32Checksum(data, out var checksum, out var error);
Password Hasher
The PasswordHasher class provides methods for securely hashing and validating passwords using salt and pepper.
Features
- Salted & Peppered Hashing:
- Hash passwords with a unique salt and a required application-level pepper (secret).
- Validation:
- Validate passwords against stored hashes using the same salt and pepper.
- Strong Security:
- Uses PBKDF2 with HMACSHA512 and 100,000 iterations.
Example Usage
Hashing a Password
const string pepper = "YourAppSecretPepper";
PasswordHasher.TryCreateSaltedHash("password", pepper, out var hashResult, out var error);
// hashResult.Salt and hashResult.Hash are Base64 strings
Validating a Password
const string pepper = "YourAppSecretPepper";
PasswordHasher.TryValidateHash("password", hashResult.Salt, hashResult.Hash, pepper, out var isValid, out var error);
API
public static bool TryCreateSaltedHash(
string value,
string pepper,
out (string Salt, string Hash)? saltedHash,
out string? errorMessage)
value: The password to hash.pepper: Application-level secret (not stored with the hash).saltedHash: Tuple containing the generated salt and hash (Base64 strings).errorMessage: Error message if hashing fails.
public static bool TryValidateHash(
string value,
string salt,
string hash,
string pepper,
out bool isValid,
out string? errorMessage)
value: The password to validate.salt: The Base64-encoded salt used for hashing.hash: The Base64-encoded hash to validate against.pepper: Application-level secret (must match the one used for hashing).isValid: True if the password is valid.errorMessage: Error message if validation fails.
Security Notes
- Pepper should be kept secret and not stored alongside the hash or salt.
- Changing the pepper will invalidate all existing password hashes.
- Always use a strong, random pepper value for your application.
JWT Generator
The JwtGenerator class provides methods for generating and validating JSON Web Tokens (JWTs).
Features
-
Token Generation:
- Generate JWTs with claims and metadata.
-
Token Validation:
- Validate JWTs against a secret.
Example Usage
Generating a Token
JwtGenerator.TryGenerateToken(secret, issuer, audience, 60, "user", roles, out var token, out var error);
JWK Generator
The JwkGenerator class in the MaksIT.Core.Security.JWK namespace provides a utility method for generating a minimal RSA public JWK (JSON Web Key) from a given RSA instance.
Features
- Generate RSA Public JWK:
- Extracts the RSA public exponent and modulus from an
RSAobject and encodes them as a JWK.
Example Usage
using System.Security.Cryptography;
using MaksIT.Core.Security.JWK;
using var rsa = RSA.Create(2048);
var result = JwkGenerator.TryGenerateFromRSA(rsa, out var jwk, out var errorMessage);
if (result)
{
// jwk contains KeyType, RsaExponent, RsaModulus
Console.WriteLine($"Exponent: {jwk!.RsaExponent}, Modulus: {jwk.RsaModulus}");
}
else
{
Console.WriteLine($"Error: {errorMessage}");
}
API
public static bool TryGenerateFromRSA(
RSA rsa,
[NotNullWhen(true)] out Jwk? jwk,
[NotNullWhen(false)] out string? errorMessage
)
rsa: The RSA instance to extract public parameters from.jwk: The resulting JWK object (withKeyType,RsaExponent, andRsaModulus).errorMessage: Error message if generation fails.
Notes
- Only supports RSA public keys.
- The generated JWK includes only the public exponent and modulus.
- Returns
falseand an error message if the RSA parameters are missing or invalid.
JWS Generator
The JwsGenerator class in the MaksIT.Core.Security.JWS namespace provides methods for creating JSON Web Signatures (JWS) using RSA keys and JWKs. It supports signing string or object payloads and produces JWS objects with protected headers, payload, and signature.
Features
- JWS Creation:
- Sign string or object payloads using an RSA key and JWK.
- Produces a JWS message containing the protected header, payload, and signature.
- Supports generic protected header and payload types.
- Automatically sets the
Algorithmproperty toRS256in the protected header. - Sets either the
KeyIdor the fullJwkin the protected header, depending on the presence ofKeyId.
Example Usage
using System.Security.Cryptography;
using MaksIT.Core.Security.JWK;
using MaksIT.Core.Security.JWS;
using var rsa = RSA.Create(2048);
JwkGenerator.TryGenerateFromRSA(rsa, out var jwk, out var errorMessage);
var header = new JwsHeader();
var payload = "my-payload";
var result = JwsGenerator.TryEncode(rsa, jwk!, header, payload, out var jwsMessage, out var error);
if (result)
{
Console.WriteLine($"Signature: {jwsMessage!.Signature}");
}
else
{
Console.WriteLine($"Error: {error}");
}
API
public static bool TryEncode<THeader>(
RSA rsa,
Jwk jwk,
THeader protectedHeader,
[NotNullWhen(true)] out JwsMessage? message,
[NotNullWhen(false)] out string? errorMessage
) where THeader : JwsHeader
- Signs an empty payload with a generic protected header.
public static bool TryEncode<THeader, TPayload>(
RSA rsa,
Jwk jwk,
THeader protectedHeader,
TPayload? payload,
[NotNullWhen(true)] out JwsMessage? message,
[NotNullWhen(false)] out string? errorMessage
) where THeader : JwsHeader
- Signs the provided payload (string or object) with a generic protected header.
Notes
- Only supports signing (no verification or key authorization).
- The protected header is automatically set to use RS256.
- If the JWK has a
KeyId, it is set in the header; otherwise, the full JWK is included. - The payload is base64url encoded (as a string or JSON).
- Returns
falseand an error message if signing fails.
JWK Thumbprint Utility
The JwkThumbprintUtility class in the MaksIT.Core.Security.JWK namespace provides methods for computing RFC7638 JWK SHA-256 thumbprints and generating key authorization strings for ACME challenges.
Features
- JWK SHA-256 Thumbprint:
- Computes the RFC7638-compliant SHA-256 thumbprint of a JWK (Base64Url encoded).
- ACME Key Authorization:
- Generates the key authorization string for ACME/Let's Encrypt HTTP challenges.
Example Usage
Computing a JWK Thumbprint
using System.Security.Cryptography;
using MaksIT.Core.Security.JWK;
using var rsa = RSA.Create(2048);
JwkGenerator.TryGenerateFromRSA(rsa, out var jwk, out var errorMessage);
var result = JwkThumbprintUtility.TryGetSha256Thumbprint(jwk!, out var thumbprint, out var error);
if (result)
{
Console.WriteLine($"Thumbprint: {thumbprint}");
}
else
{
Console.WriteLine($"Error: {error}");
}
Generating ACME Key Authorization
var token = "acme-token";
var result = JwkThumbprintUtility.TryGetKeyAuthorization(jwk!, token, out var keyAuth, out var error);
if (result)
{
Console.WriteLine($"Key Authorization: {keyAuth}");
}
else
{
Console.WriteLine($"Error: {error}");
}
API
public static bool TryGetSha256Thumbprint(
Jwk jwk,
[NotNullWhen(true)] out string? thumbprint,
[NotNullWhen(false)] out string? errorMessage
)
- Computes the RFC7638 SHA-256 thumbprint of the JWK.
public static bool TryGetKeyAuthorization(
Jwk jwk,
string token,
[NotNullWhen(true)] out string? keyAuthorization,
[NotNullWhen(false)] out string? errorMessage
)
- Generates the ACME key authorization string:
{token}.{thumbprint}.
Notes
- Only supports RSA JWKs (requires exponent and modulus).
- Returns
falseand an error message if required JWK fields are missing or invalid. - Thumbprint is Base64Url encoded and suitable for ACME/Let's Encrypt HTTP challenges.
TOTP Generator
The TotpGenerator class in the MaksIT.Core.Security namespace provides methods for generating and validating Time-based One-Time Passwords (TOTP) for two-factor authentication.
Features
-
TOTP Validation:
- Validate TOTP codes against a shared secret with configurable time tolerance.
-
TOTP Generation:
- Generate TOTP codes from a Base32-encoded secret.
-
Secret Generation:
- Generate cryptographically secure Base32 secrets for TOTP setup.
-
Recovery Codes:
- Generate backup recovery codes for account recovery.
-
Auth Link Generation:
- Generate
otpauth://URIs for QR code scanning in authenticator apps.
- Generate
Example Usage
Generating a Secret
TotpGenerator.TryGenerateSecret(out var secret, out var error);
// secret is a Base32-encoded string for use with authenticator apps
Validating a TOTP Code
var timeTolerance = 1; // Allow 1 time step before/after current
TotpGenerator.TryValidate(totpCode, secret, timeTolerance, out var isValid, out var error);
if (isValid) {
Console.WriteLine("TOTP is valid");
}
Generating Recovery Codes
TotpGenerator.TryGenerateRecoveryCodes(10, out var recoveryCodes, out var error);
// recoveryCodes contains 10 codes in format "XXXX-XXXX"
Generating an Auth Link for QR Code
TotpGenerator.TryGenerateTotpAuthLink(
"MyApp",
"user@example.com",
secret,
"MyApp",
null, // algorithm (default SHA1)
null, // digits (default 6)
null, // period (default 30)
out var authLink,
out var error
);
// authLink = "otpauth://totp/MyApp:user@example.com?secret=...&issuer=MyApp"
Web API
The Webapi namespace provides models and utilities for building Web APIs, including pagination support and patch operations.
Paged Request
The PagedRequest class in the MaksIT.Core.Webapi.Models namespace provides a base class for paginated API requests with filtering and sorting capabilities.
Features
-
Pagination:
- Configure page size and page number for paginated results.
-
Dynamic Filtering:
- Build filter expressions from string-based filter queries.
-
Dynamic Sorting:
- Build sort expressions with ascending/descending order.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
PageSize | int | 100 | Number of items per page |
PageNumber | int | 1 | Current page number |
Filters | string? | null | Filter expression string |
SortBy | string? | null | Property name to sort by |
IsAscending | bool | true | Sort direction |
Example Usage
var request = new PagedRequest {
PageSize = 20,
PageNumber = 1,
Filters = "Name.Contains(\"John\") && Age > 18",
SortBy = "Name",
IsAscending = true
};
var filterExpression = request.BuildFilterExpression<User>();
var sortExpression = request.BuildSortExpression<User>();
var results = dbContext.Users
.Where(filterExpression)
.OrderBy(sortExpression)
.Skip((request.PageNumber - 1) * request.PageSize)
.Take(request.PageSize)
.ToList();
Paged Response
The PagedResponse<T> class in the MaksIT.Core.Webapi.Models namespace provides a generic wrapper for paginated API responses.
Properties
| Property | Type | Description |
|---|---|---|
Items | IEnumerable<T> | The items for the current page |
PageNumber | int | Current page number |
PageSize | int | Number of items per page |
TotalCount | int | Total number of items across all pages |
TotalPages | int | Calculated total number of pages |
HasPreviousPage | bool | Whether a previous page exists |
HasNextPage | bool | Whether a next page exists |
Example Usage
var items = await dbContext.Users
.Skip((pageNumber - 1) * pageSize)
.Take(pageSize)
.ToListAsync();
var totalCount = await dbContext.Users.CountAsync();
var response = new PagedResponse<UserDto>(items, totalCount, pageNumber, pageSize);
// response.TotalPages, response.HasNextPage, etc. are automatically calculated
Patch Operation
The PatchOperation enum in the MaksIT.Core.Webapi.Models namespace defines operations for partial updates (PATCH requests).
Values
| Value | Description |
|---|---|
SetField | Set or replace a normal field value |
RemoveField | Set a field to null |
AddToCollection | Add an item to a collection property |
RemoveFromCollection | Remove an item from a collection property |
Example Usage
public class UserPatchRequest : PatchRequestModelBase {
public PatchOperation Operation { get; set; }
public string PropertyName { get; set; }
public object? Value { get; set; }
}
// Example: Set a field
var patch = new UserPatchRequest {
Operation = PatchOperation.SetField,
PropertyName = "Name",
Value = "New Name"
};
// Example: Add to collection
var patch = new UserPatchRequest {
Operation = PatchOperation.AddToCollection,
PropertyName = "Roles",
Value = "Admin"
};
Others
Culture
The Culture class provides methods for dynamically setting the culture for the current thread.
Features
- Dynamic Culture Setting:
- Change the culture for the current thread.
Example Usage
Setting the Culture
Culture.TrySet("fr-FR", out var error);
Environment Variables
The EnvVar class provides methods for managing environment variables.
Features
-
Add to PATH:
- Add directories to the
PATHenvironment variable.
- Add directories to the
-
Set and Unset Variables:
- Manage environment variables at different scopes.
Example Usage
Adding to PATH
EnvVar.TryAddToPath("/usr/local/bin", out var error);
File System
The FileSystem class provides methods for working with files and directories.
Features
-
Copy Files and Folders:
- Copy files or directories to a target location.
-
Delete Files and Folders:
- Delete files or directories.
Example Usage
Copying Files
FileSystem.TryCopyToFolder("source", "destination", true, out var error);
Processes
The Processes class provides methods for managing system processes.
Features
-
Start Processes:
- Start new processes with optional arguments.
-
Kill Processes:
- Terminate processes by name.
Example Usage
Starting a Process
Processes.TryStart("notepad.exe", "", 0, false, out var error);
Enum Extensions
The EnumExtensions class provides utility methods for working with enum types, specifically for retrieving display names defined via the DisplayAttribute.
Features
- Get Display Name:
- Retrieve the value of the
DisplayAttribute.Nameproperty for an enum value, or fall back to the enum's name if the attribute is not present.
- Retrieve the value of the
Example Usage
using System.ComponentModel.DataAnnotations;
using MaksIT.Core.Extensions;
public enum Status {
[Display(Name = "In Progress")]
InProgress,
Completed
}
var status = Status.InProgress;
string displayName = status.GetDisplayName(); // "In Progress"
var completed = Status.Completed;
string completedName = completed.GetDisplayName(); // "Completed"
Best Practices
- Use the
Displayattribute on enum members to provide user-friendly names for UI or logging. - Use
GetDisplayName()to consistently retrieve display names for enums throughout your application.
Contact
If you have any questions or need further assistance, feel free to reach out:
- Email: maksym.sadovnychyy@gmail.com
License
See LICENSE.md.