HUMANiT.Core 1.2.0-rc-3016

This is a prerelease version of HUMANiT.Core.
dotnet add package HUMANiT.Core --version 1.2.0-rc-3016
NuGet\Install-Package HUMANiT.Core -Version 1.2.0-rc-3016
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="HUMANiT.Core" Version="1.2.0-rc-3016" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add HUMANiT.Core --version 1.2.0-rc-3016
#r "nuget: HUMANiT.Core, 1.2.0-rc-3016"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install HUMANiT.Core as a Cake Addin
#addin nuget:?package=HUMANiT.Core&version=1.2.0-rc-3016&prerelease

// Install HUMANiT.Core as a Cake Tool
#tool nuget:?package=HUMANiT.Core&version=1.2.0-rc-3016&prerelease

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 (2k+), last names (1k+), full names (2m+), URLs (800k+), emails (300m+), and street names (600k+).
  • 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

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

// 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 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<Person>.CreateError(HttpStatusCode.BadRequest);

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 hasing 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

Located in namespace HUMANiT.Core.Exceptions.

Example using the ExceptionSupport.NeverEndUpHereException property:

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:

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

ExceptionSupport.ThrowNeverEndUpHereException();
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on HUMANiT.Core:

Package Downloads
HUMANiT.Core.Web

RESTful base client that can call any RESTful API. Supports the HTTP verbs GET, POST and PATCH. Deals with the HTTP status code 200, 201, 204, 300, 301, 302, 303, 305, 307, 400, 404, 409, 500 and 502. [covered by 60+ tests]

HUMANiT.Azure

Simplified RESTful API proxies with built-in secondary proxy. Simplified logging, enabled/disabled during runtime. HTTP methods. Media types. Extensions.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.2.0-rc-3016 366 2/8/2024
1.1.0 1,108 11/4/2023
1.0.5 570 9/12/2023
1.0.4 1,957 3/27/2023
1.0.3 1,567 1/17/2023
1.0.1 1,422 1/10/2023
1.0.0 2,894 8/21/2022
0.8.0 997 8/4/2022
0.7.0 12,986 3/31/2020
0.6.1 23,226 12/2/2019
0.6.0 8,154 10/19/2019
0.5.2 7,278 2/10/2019
0.5.1 5,912 1/27/2019
0.4.1 8,595 4/1/2018
0.4.0 7,695 2/3/2018
0.3.2 4,951 1/12/2018
0.3.0 2,427 12/9/2017
0.2.2 1,529 9/18/2017
0.1.6 1,549 9/1/2017

Contact HUMANiT for details: support@HUMANiT.nz