HUMANiT.Core 1.2.0-rc-3054

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

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, booleans, first names (2.2k+ variations), last names (1.1k+), full names (2.5m+), URLs (830k+), emails (1.6b+), and street names (680k+).
• Extensions: Enhancements and validations to strings, dates, date times, date-time offsets, 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

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 that method or constructor parameters are of an expected quality. When such an inspection fails, it throws argument exceptions such as ArgumentNullException and ArgumentOutOfRangeException. Examples:

using HUMANiT.Core.Diagnostics;
...

// 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:

using HUMANiT.Core.Diagnostics;
...

// 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:

using HUMANiT.Core.Diagnostics;
...
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 a central part in many object-oriented software architectures and engineering principles such as the Onion Architecture. The purpose of domain objects is to represent things of our modelled world.

This packages provides a set of base classes for domain objects. It allows to implementing domain objects consistently. They can be used as the source for data transport between services and applications (see Shipping below) and data storages such as when using an ORM or basic data layers. For an integration with Azure Cosmos DB see our HUMANiT.Azure.Data NuGet package.

DomainObject is the topmost base class of all domain objects.

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

• 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.

BasicPersistableDomainObject is the topmost base class of all domain objects that can be persisted. Important properties:

• 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 the modeling of complex object states such as when virtually deleted or deactivated. Default is Active.

PersistableDomainObject is an extented base class of all persistable domain objects that require individual tenancy and/or user information. Important properties:

• TenantId gets the ID of the tenant to which this domain object belongs. This allows using domain objects in software systems designed with tenancy functionality in mind.
• UserId gets 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. Important property:

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

All base classes are immutable.

Shipping

Located in namespace HUMANiT.Core.Shipping. Quickstart guidance will come.

Vault

Located in namespace HUMANiT.Core.Caching. Quickstart guidance will come.

Object analysis

Quickstart guidance will come.

Call result

Located in namespace HUMANiT.Core.

A CallResult holds the result of a call to a method, component, or Web service. ⚠️ Methods that return a CallResult should be designed to never throw an exception. Instead, they should return an error CallResult.

If the call was successfully executed, IsOkay is set to true; otherwise, HasError is set to true. HasWarning may be set to true and indicates an abnormality even though IsOkay is set to true.

HttpStatusCode and RawMessage provide details around the call result. The code is of type System.Net.HttpStatusCode. See HTTP Status Codes for an interpretation of the code.

There are 3 methods that create a call result: CreateOkay(), CreateWarning(), and CreateError(). Examples:

return CallResult<int>.CreateOkay(content: 42);
return CallResult<Thing>.CreateWarning(HttpStatusCode.NotModified, originalValue);
return CallResult.CreateError(HttpStatusCode.BadRequest);

If you don't require a return type, use CallResult. Otherwise, use CallResult<T>; T declares the return type. The return value is held in the Content property. Example:

CallResult<int> result = await DoSomethingAsync(); // no try catch needed
int i = result.IsOkay ? result.Content : -1;

CallResult is immutable.

Type converter

Located in namespace HUMANiT.Core.ComponentModel. Quickstart guidance will come.

Cryptography

If your looking for a fast way to store salted and hashed passwords, use the HUMANiT.Core.Cryptography.Crypto class that offers the salted hashing of secrest and verifying them.

Example using the CreateHash() method to salt and hash a secret:

using HUMANiT.Core.Cryptography;
...
var hashedPassword = Crypto.CreateHash(password);

Example using the VerifyHash() method to verify a salted hash:

using HUMANiT.Core.Cryptography;
...
if(!Crypto.VerifyHash(password, hashedPassword))
    return "The entered password is wrong.";

Note: Hashed passwords, even when using salt, are possible to crack with a dictionary attack. Computers are fast and so are hash algorithms thus the offered features add complexity to the algorithm by relying on implementations similar to RFC2898.

Randomizer

Located in namespace HUMANiT.Core. Quickstart guidance will come.

Extensions

Located in namespace HUMANiT.Core.Consistency. Quickstart guidance will come.

Exception support

Example using the ExceptionSupport.NeverEndUpHereException property:

using HUMANiT.Core.Exceptions;
...
return fact switch
{
    Facts.Option1 => "Great stuff.",
    Facts.Option2 => "OMG. That is terrible.",
    _ => "You got a problem to sort."
};

throw ExceptionSupport.NeverEndUpHereException;

Example using the ExceptionSupport.ThrowNeverEndUpHereException() method:

using HUMANiT.Core.Exceptions;
...
return fact switch
{
    Facts.Option1 => "Great stuff.",
    Facts.Option2 => "OMG. That is terrible.",
    _ => "You got a problem to sort."
};

ExceptionSupport.ThrowNeverEndUpHereException();