HUMANiT.Core 1.0.4-alpha-2792

HUMANiT Core

This package provides platform features that we miss in .NET, but that find valuable for our own daily software development. -- the people of HUMANiT

This package is covered by over 800 automated tests and offers an API that is documented extensively inline.

Features

• Inspections: Pre and post verification of parameters and variables to check their conditions. Fast and reliable.
• Domains: Consitent domain objects.
• Shipping: Consitent shipping models.
• Vault: Cache with multiple shelves (sub-caches), simple lifetime principles. Fast, thread-safe, reliable; also for SharePoint.
• Object analysis: Provides an easy test whether a generic type is null-able.
• Call result: Generic carrier of a call result such as of a standard method or a Web service call.
• Type converter: Converts enumeration values into pre-defined strings and vice versa.
• Cryptography: Creation and verification of cryptographic salted hashes; fast; using RFC2898 instead of the insecure MD5.
• Randomizer: Generates random codes of different lengths and passwords as well as numbers, first names (>400), last names (>200), full names (>97k), URLs (>39k) and emails (>9m).
• Extensions: Enhancements and validations to datesdatetimes, datetimeoffsets, passwords, PINs, phone numbers, names, emails, and exceptions.
• Exception support: Provides easy ways to throw an exception for reached code that was expected to be unreachable.

Extensions will move into their own NuGet package in a future version, so if you use them, consider that a future package upgrade may cause compiler errors and you will need to add the HUMANiT.Core.Extensions package (yet unavailable).

This package contains features which we require for our own software; therefore, some features are highly custom. If you require a fix, an enhancement, or a more configurable solution, please contact us.

Contact

• Twitter -- stay in touch (@HUMANiTnz)
• Facebook -- message with us (@HUMANiTnz)
• support@humanit.nz -- contact us via email

License

MIT -- free software, hell yeah 🤩

Quickstarts

Inspections

Located in namespace HUMANiT.Core.Diagnostics.

Inspections are the incarnation of verification. Data verification is checking rules and ensure they are correct. A passed inspection means we can trust data is of a certain state and our code can be based on that. A failed inspection leads to an exception highlighting at which point we came aware of a problem with expected data quality.

Parameter inspections verify thatmethod or constructor parameters are of an expected qyality. When such an inspection fails, it throws argument exceptions such as ArgumentNullException and ArgumentOutOfRangeException. Examples:

// verify that a birthday lies in the past
// throws an ArgumentException if the birthday lies in the past
Inspect.Param.IsTrue(birthday <= DateTimeOffset.Today());

// verify that there are vehicles in the vehicle list
// throws an ArgumentNullException if the list is null, or an ArgumentException if it's empty
Inspect.Param.IsNotEmpty(vehicleList, nameof(vehicleList));

// verify that there is a last name
// throws an ArgumentNullException if the last name is null, or an ArgumentException if it's empty or whitespace
Inspect.Param.IsNotNullOrWhitespace(lastName, nameof(lastName), "Last name is mandatory.");

Value inspections verify that methods return what they promise. When such an inspection fails, it throws an InvalidOperationException. Examples:

// verify that there are less than 100 things
Inspect.Value.IsBetween(CountThings(), 0, 99); // CountThings() returns a number

// verify that there are details for a customer
Inspect.Value.IsNotNull(LoadDetails(customerId), message: $"Details for customer {customerId} are missing.");

Inspection methods return the to be verified information which allows using inspections inline with operations. Examples:

var numberOfThings = Inspect.Value.IsBetween(CountThings(), 0, 99);
var details = Inspect.Value.IsNotNull(LoadDetails(name));

Available inspections: AreEqual<T>(), AreNotEqual<T>(), IsBetween<T>(), IsEmpty<T>(), IsFalse(), IsGreater<T>(), IsGreaterOrEqual<T>(), IsLessOrEqual<T>(), IsNotEmpty<T>(), IsNotNull<T>(), IsNotNullOrEmpty<T>(), IsNotNullOrWhitespace<T>(), IsNotWhitespace<T>(), IsNull<T>(), IsNullOrEmpty<T>(), IsOfExactType<T>(), IsOfType<T>(), IsTrue(), IsWhitespace<T>()

Domains

Located in namespace HUMANiT.Core.Domain.

Domain objects (or domain entities) form central part of many object-oriented software architectures and engineering principles such as the Onion Architecture. Domain objects' purpose is to represent things of our modelled world.

This packages provides a set of base classes for domain objects. It allows for a consistent approach to implementing domain objects. They can be further used in conjunction with transporting data between services and applications; see Shipping further below; and storing in persitencies using either an ORM or more basic data layers; see our HUMANiT.Azure.Data NuGet package for integration with Azure Cosmos DB.

DomainObject is the topmost base class of all domain objects.

IdentifiableDomainObject is the topmost base class of all domain objects that require an identifier. The type of the identifier is generic (TIdType), so not only typical ID types such as Guid, long, and string can be used, but also custom identifiers of any sort.

• Id gets the ID of the domain object. If defaulted (null, empty, ...), the domain object cannot be identified yet.
• IsTransient gets true if the domain object is transient (not persisted); otherwise, false. A transient domain object is a non-persisted domain object meaning it has no Id.

PersistableDomainObject is the topmost base class of all domain objects that can be persisted.

• Created gets the creation date and time of the domain object.
• Modified gets the date and time when the domain object was modifed last.
• HealthState gets the health state of this domain object which allows modelling of complex object state such as when virtually deleted or deactivated. Default is Active.
• TenantId get the ID of the tenant to which this domain object belongs. This allows using domain objects in software systems designed to provide tenancy functionality.
• UserId get the ID of the user who originally created or last modified this domain object.

EmbeddedPersistableDomainObject is the topmost base class for any domain object that is embedded into another domain object, either directly or as a linked resource.

• HealthState gets the health state of this domain object which allows modelling of complex object state such as when virtually deleted or deactivated. Default is Active.

All base classes are immutable.

Shipping

Consitent shipping models.

Quickstart guidance will come.

Vault

Cache with multiple shelves (sub-caches), simple lifetime principles. Fast, thread-safe, reliable; also for SharePoint.

Quickstart guidance will come.

Object analysis

Provides an easy test whether a generic type is null-able.

Quickstart guidance will come.

Call result

Generic carrier of a call result such as of a standard method or a Web service call.

Quickstart guidance will come.

Type converter

Converts enumeration values into pre-defined strings and vice versa.

Quickstart guidance will come.

Cryptography

Creation and verification of cryptographic salted hashes; fast; using RFC2898 instead of the insecure MD5.

Quickstart guidance will come.

Randomizer

Generates random codes of different lengths and passwords as well as numbers, first names (>400), last names (>200), full names (>97k), URLs (>39k) and emails (>9m).

Quickstart guidance will come.

Extensions

Enhancements and validations to datesdatetimes, datetimeoffsets, passwords, PINs, phone numbers, names, and exceptions.

Quickstart guidance will come.

Exception support

Provides easy ways to throw an exception for reached code that was expected to be unreachable.

Quickstart guidance will come.