ktsu.Essentials 1.1.0

Prefix Reserved

dotnet add package ktsu.Essentials --version 1.1.0

NuGet\Install-Package ktsu.Essentials -Version 1.1.0

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="ktsu.Essentials" Version="1.1.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="ktsu.Essentials" Version="1.1.0" />
                    

                            Directory.Packages.props

<PackageReference Include="ktsu.Essentials" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add ktsu.Essentials --version 1.1.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: ktsu.Essentials, 1.1.0"

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

#:package ktsu.Essentials@1.1.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=ktsu.Essentials&version=1.1.0
                    

                            Install as a Cake Addin

#tool nuget:?package=ktsu.Essentials&version=1.1.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

ktsu.Essentials

A comprehensive .NET library providing high-performance interfaces and implementations for common cross-cutting concerns including compression, encoding, encryption, hashing, serialization, caching, persistence, validation, logging, navigation, command execution, and filesystem access.

Introduction

ktsu.Essentials defines a consistent, high-performance API for common cross-cutting concerns in .NET applications. Each provider interface follows a three-tier pattern: zero-allocation Try* methods using Span<byte> and Stream, convenient self-allocating methods, and async variants with CancellationToken support. Implementers only need to provide the core Try* methods — all convenience and async methods are provided via default interface implementations. The package also includes ready-to-use provider implementations for compression, hashing, encoding, encryption, serialization, caching, persistence, logging, navigation, and command execution.

Features

Compression: ICompressionProvider with Gzip, Brotli, Deflate, and ZLib implementations
Encoding: IEncodingProvider with Base64 and Hex implementations for format/transport encoding
Encryption: IEncryptionProvider with AES implementation including key and IV generation
Hashing: IHashProvider with 15 implementations (MD5, SHA1/256/384/512, FNV1/FNV1a 32/64-bit, CRC32/64, XxHash32/64/3/128)
Serialization: ISerializationProvider with JSON, YAML, and TOML implementations plus configurable ISerializationOptions
Caching: ICacheProvider<TKey, TValue> with in-memory implementation supporting expiration and get-or-add semantics
Persistence: IPersistenceProvider<TKey> with AppData, FileSystem, InMemory, and Temp implementations
Validation: IValidationProvider<T> with structured results, error codes, and throw-on-failure support
Logging: ILoggingProvider with console implementation supporting six severity levels
Navigation: INavigationProvider<T> with in-memory implementation for browser-like back/forward navigation
Command Execution: ICommandExecutor with native implementation for running shell commands and capturing output
Filesystem: IFileSystemProvider extending Testably.Abstractions for testable filesystem access
Zero-Allocation Core: All byte-oriented providers support Span<byte> and Stream for allocation-free operations
Minimal Implementation Burden: Default interface implementations reduce boilerplate — implement only the core Try* methods
Comprehensive Async Support: Every operation has async variants with proper CancellationToken support

Installation

Package Manager Console

Install-Package ktsu.Essentials

.NET CLI

dotnet add package ktsu.Essentials

Package Reference

<PackageReference Include="ktsu.Essentials" Version="x.y.z" />

Usage Examples

Basic Example

using ktsu.Essentials;
using ktsu.Essentials.HashProviders;
using ktsu.Essentials.CompressionProviders;
using ktsu.Essentials.EncodingProviders;
using Microsoft.Extensions.DependencyInjection;

// Register provider implementations via DI
IServiceCollection services = new ServiceCollection();
services.AddSingleton<IHashProvider, SHA256>();
services.AddSingleton<ICompressionProvider, Gzip>();
services.AddSingleton<IEncodingProvider, EncodingProviders.Base64>();

using IServiceProvider provider = services.BuildServiceProvider();
IHashProvider hashProvider = provider.GetRequiredService<IHashProvider>();

// Convenience method (auto-allocates buffer)
byte[] hash = hashProvider.Hash("Hello, World!");

// Zero-allocation method
Span<byte> buffer = stackalloc byte[hashProvider.HashLengthBytes];
if (hashProvider.TryHash("Hello, World!"u8, buffer))
{
    string hex = Convert.ToHexString(buffer);
}

// Async method
byte[] asyncHash = await hashProvider.HashAsync("Hello, World!");

Compression

ICompressionProvider compressor = provider.GetRequiredService<ICompressionProvider>();

byte[] compressed = compressor.Compress(originalData);
byte[] decompressed = compressor.Decompress(compressed);

// String convenience
string compressedText = compressor.Compress("Large text content...");

Serialization

ISerializationProvider serializer = provider.GetRequiredService<ISerializationProvider>();

string json = serializer.Serialize(myObject);
MyClass? deserialized = serializer.Deserialize<MyClass>(json);

// Async
string asyncJson = await serializer.SerializeAsync(myObject);

Caching

ICacheProvider<string, MyData> cache = provider.GetRequiredService<ICacheProvider<string, MyData>>();

cache.Set("key", myData, expiration: TimeSpan.FromMinutes(5));
MyData value = cache.GetOrAdd("key", k => LoadData(k));

Persistence

IPersistenceProvider<string> persistence = provider.GetRequiredService<IPersistenceProvider<string>>();

await persistence.StoreAsync("settings", mySettings);
MySettings? loaded = await persistence.RetrieveAsync<MySettings>("settings");
MySettings guaranteed = await persistence.RetrieveOrCreateAsync<MySettings>("settings");

Implementing a Custom Provider

Implementers only need to provide the core Try* methods — all other methods are inherited:

using ktsu.Essentials;

public sealed class MyHashProvider : IHashProvider
{
    public int HashLengthBytes => 32;

    public bool TryHash(ReadOnlySpan<byte> data, Span<byte> destination)
    {
        if (destination.Length < HashLengthBytes) return false;
        // Custom hash logic here
        return true;
    }

    public bool TryHash(Stream data, Span<byte> destination)
    {
        if (destination.Length < HashLengthBytes) return false;
        // Custom stream hash logic here
        return true;
    }

    // Hash(), HashAsync(), TryHashAsync(), string overloads — all inherited
}

API Reference

`ICompressionProvider`

Compress and decompress data with Span, Stream, and string support.

Name	Return Type	Description
`TryCompress(ReadOnlySpan<byte>, Span<byte>)`	`bool`	Zero-allocation compression
`TryCompress(Stream, Stream)`	`bool`	Stream-based compression
`Compress(ReadOnlySpan<byte>)`	`byte[]`	Self-allocating compression
`Compress(string)`	`string`	UTF8 string compression
`TryDecompress(ReadOnlySpan<byte>, Span<byte>)`	`bool`	Zero-allocation decompression
`Decompress(ReadOnlySpan<byte>)`	`byte[]`	Self-allocating decompression

`IEncodingProvider`

Format/transport encoding (Base64, Hex) — not text character encodings.

Name	Return Type	Description
`TryEncode(ReadOnlySpan<byte>, Span<byte>)`	`bool`	Zero-allocation encoding
`TryEncode(Stream, Stream)`	`bool`	Stream-based encoding
`Encode(ReadOnlySpan<byte>)`	`byte[]`	Self-allocating encoding
`TryDecode(ReadOnlySpan<byte>, Span<byte>)`	`bool`	Zero-allocation decoding
`Decode(ReadOnlySpan<byte>)`	`byte[]`	Self-allocating decoding

`IEncryptionProvider`

Encrypt and decrypt data with key and IV management.

Name	Return Type	Description
`TryEncrypt(ReadOnlySpan<byte>, Span<byte>, byte[], byte[])`	`bool`	Zero-allocation encryption
`TryDecrypt(ReadOnlySpan<byte>, Span<byte>, byte[], byte[])`	`bool`	Zero-allocation decryption
`GenerateKey()`	`byte[]`	Generates a new encryption key
`GenerateIV()`	`byte[]`	Generates a new initialization vector

`IHashProvider`

Hash data with configurable output length. Exposes HashLengthBytes property for the output size in bytes.

Name	Return Type	Description
`TryHash(ReadOnlySpan<byte>, Span<byte>)`	`bool`	Zero-allocation hashing
`TryHash(Stream, Span<byte>)`	`bool`	Stream-based hashing
`Hash(ReadOnlySpan<byte>)`	`byte[]`	Self-allocating hashing
`Hash(string)`	`byte[]`	Hash a UTF8 string

`ISerializationProvider`

Serialize and deserialize objects supporting JSON, YAML, TOML, and other text-based formats.

Name	Return Type	Description
`TrySerialize(object, TextWriter)`	`bool`	Serialize to a TextWriter
`Serialize(object)`	`string`	Serialize to a string
`Deserialize<T>(ReadOnlySpan<byte>)`	`T?`	Deserialize from bytes
`Deserialize<T>(string)`	`T?`	Deserialize from a string
`Deserialize<T>(TextReader)`	`T?`	Deserialize from a TextReader

`ICacheProvider<TKey, TValue>`

Cache key-value pairs with optional expiration.

Name	Return Type	Description
`TryGet(TKey, out TValue?)`	`bool`	Try to get a cached value
`Get(TKey)`	`TValue`	Get a value or throw
`Set(TKey, TValue, TimeSpan?)`	`void`	Set a value with optional expiration
`GetOrAdd(TKey, Func<TKey, TValue>, TimeSpan?)`	`TValue`	Get or create a value
`Remove(TKey)`	`bool`	Remove a cached value
`Clear()`	`void`	Clear all entries

`IPersistenceProvider<TKey>`

Store and retrieve objects with pluggable storage backends. Exposes ProviderName and IsPersistent properties.

Name	Return Type	Description
`StoreAsync<T>(TKey, T)`	`Task`	Store an object
`RetrieveAsync<T>(TKey)`	`Task<T?>`	Retrieve an object
`RetrieveOrCreateAsync<T>(TKey)`	`Task<T>`	Retrieve or create a new instance
`ExistsAsync(TKey)`	`Task<bool>`	Check if a key exists
`RemoveAsync(TKey)`	`Task<bool>`	Remove an object
`GetAllKeysAsync()`	`Task<IEnumerable<TKey>>`	List all stored keys
`ClearAsync()`	`Task`	Clear all stored objects

`IValidationProvider<T>`

Validate objects and return structured results.

Name	Return Type	Description
`Validate(T)`	`ValidationResult`	Validate and return result
`IsValid(T)`	`bool`	Check validity
`ValidateAndThrow(T)`	`void`	Validate or throw `ValidationException`

`ILoggingProvider`

Write structured log messages at various severity levels.

Name	Return Type	Description
`Log(LogLevel, string)`	`void`	Write a log entry
`Log(LogLevel, Exception, string)`	`void`	Write a log entry with an exception
`IsEnabled(LogLevel)`	`bool`	Check if a log level is enabled
`LogTrace(string)` through `LogCritical(string)`	`void`	Level-specific convenience methods

`INavigationProvider<T>`

Browser-like back/forward navigation. Exposes Current, CanGoBack, and CanGoForward properties.

Name	Return Type	Description
`NavigateTo(T)`	`void`	Navigate to a destination
`GoBack()`	`T?`	Navigate backward
`GoForward()`	`T?`	Navigate forward
`Clear()`	`void`	Clear all history

`ICommandExecutor`

Run shell commands and capture output.

Name	Return Type	Description
`ExecuteAsync(string, string?)`	`Task<CommandResult>`	Execute a command
`Execute(string, string?)`	`CommandResult`	Execute a command synchronously
`ExecuteAndGetOutputAsync(string, string?)`	`Task<string>`	Execute and return stdout or throw

`IFileSystemProvider`

Extends Testably.Abstractions.IFileSystem for testable filesystem operations.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

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 is compatible. 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 is compatible. 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. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.
.NET Core	netcoreapp3.0 was computed. netcoreapp3.1 was computed.
.NET Standard	netstandard2.1 is compatible.
MonoAndroid	monoandroid was computed.
MonoMac	monomac was computed.
MonoTouch	monotouch was computed.
Tizen	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.

.NETStandard 2.1
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.0)
- Testably.Abstractions (>= 10.0.0)
net10.0
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.0)
- Testably.Abstractions (>= 10.0.0)
net6.0
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.0)
- Testably.Abstractions (>= 10.0.0)
net7.0
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.0)
- Testably.Abstractions (>= 10.0.0)
net8.0
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.0)
- Testably.Abstractions (>= 10.0.0)
net9.0
- Microsoft.SourceLink.AzureRepos.Git (>= 10.0.102)
- Microsoft.SourceLink.GitHub (>= 10.0.102)
- Polyfill (>= 9.8.0)
- Testably.Abstractions (>= 10.0.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.1.0	31	2/19/2026

## v1.1.0 (major)

- Update documentation to reflect changes in hash provider implementations ([@matt-edmondson](https://github.com/matt-edmondson))
- Rename to Essentials ([@matt-edmondson](https://github.com/matt-edmondson))
- Add persistence providers: AppData, FileSystem, and Temp ([@matt-edmondson](https://github.com/matt-edmondson))
- Consolidate shared functionality ([@matt-edmondson](https://github.com/matt-edmondson))
- Rename tests project and convert to slnx ([@matt-edmondson](https://github.com/matt-edmondson))
- Merge remote-tracking branch 'common/main' into merge-common-providers ([@matt-edmondson](https://github.com/matt-edmondson))
- Add configuration providers for JSON, TOML, and YAML formats ([@matt-edmondson](https://github.com/matt-edmondson))
- Add abstractions for command execution, configuration, encoding, logging, navigation, persistence, and validation ([@matt-edmondson](https://github.com/matt-edmondson))
- Add .gitignore and project.yml for Serena configuration ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor permissions in dotnet.yml for least privilege; add SonarLint settings.json for project configuration ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove legacy build scripts ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove skipped_release logic from build steps in dotnet.yml ([@matt-edmondson](https://github.com/matt-edmondson))
- api suppressions ([@matt-edmondson](https://github.com/matt-edmondson))
- Update KtsuBuild cloning method to retrieve the latest tag correctly ([@matt-edmondson](https://github.com/matt-edmondson))
- Update KtsuBuild cloning method to use latest tag ([@matt-edmondson](https://github.com/matt-edmondson))
- Add compression, hashing, and obfuscation providers ([@matt-edmondson](https://github.com/matt-edmondson))
- Migrate to KtsuBuild dotnet build pipeline ([@matt-edmondson](https://github.com/matt-edmondson))
- Add .gitignore and project.yml for Serena configuration ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor null checks in IObfuscationProvider and ISerializationProvider to use Ensure.NotNull method; update Polyfill package version to 9.8.0 ([@matt-edmondson](https://github.com/matt-edmondson))
- Update docs and api compatibility files ([@matt-edmondson](https://github.com/matt-edmondson))
- Add project references and update AssemblyInfo for testing and source linking ([@matt-edmondson](https://github.com/matt-edmondson))
- Change project SDK from Microsoft.NET.Sdk to MSTest.Sdk ([@matt-edmondson](https://github.com/matt-edmondson))
- Update target framework to net10.0 and adjust assertions in tests ([@matt-edmondson](https://github.com/matt-edmondson))
- Update package versions in Directory.Packages.props ([@matt-edmondson](https://github.com/matt-edmondson))
- Add CLAUDE.md for project guidance and documentation ([@matt-edmondson](https://github.com/matt-edmondson))
- Add test project detection to Invoke-DotNetTest function ([@matt-edmondson](https://github.com/matt-edmondson))
- Update .NET version to 10.0 and adjust test coverage reporting ([@matt-edmondson](https://github.com/matt-edmondson))
- Update project configuration and add CLAUDE.md for documentation ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance project type detection in update-winget-manifests.ps1 by adding checks for generated NuGet packages and refining logic to distinguish between library, executable, test, and demo projects. ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor ISerializationOptions interface to unify member serialization policies and enhance clarity. Introduce new properties for serialization and deserialization policies, and update related enums for improved configurability. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add ISerializationOptions interface and related policies for serialization configuration ([@matt-edmondson](https://github.com/matt-edmondson))
- Add SHA384 and SHA512 hash providers, along with FNV1_32, FNV1a_32, FNV1_64, and FNV1a_64 implementations. Update Common.sln and add corresponding unit tests for all new providers. Enhance existing tests for dependency injection and serialization. Include necessary project files and suppressions for compatibility. ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove .runsettings file, update project references in Common.sln, and add new providers for Gzip, Aes, Base64, MD5, SHA1, and SHA256 with corresponding project files. Update package versions in Directory.Packages.props and global.json. Add unit tests for dependency injection and functionality verification. ([@matt-edmondson](https://github.com/matt-edmondson))
- Update global.json and Abstractions.csproj to use ktsu.Sdk version 1.60.0 and switch project SDK to Microsoft.NET.Sdk, improving compatibility with .NET 8.0. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add MD5HashProvider implementation and project files ([@matt-edmondson](https://github.com/matt-edmondson))
- Initial commit ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor ISerializationProvider interface to use generic type parameters for deserialization methods, enhancing type safety and usability. Update CompatibilitySuppressions.xml to remove obsolete suppressions related to nullable attributes, ensuring compatibility with .NET 8.0. ([@matt-edmondson](https://github.com/matt-edmondson))
- Update CompatibilitySuppressions.xml to reflect changes in diagnostic IDs and target methods for the ktsu.Abstractions library, enhancing compatibility with .NET 8.0. This includes updates for compression, encryption, hashing, and obfuscation methods, ensuring accurate suppression of diagnostics across versions. ([@matt-edmondson](https://github.com/matt-edmondson))
- Enhance ktsu.Abstractions library by refining interface descriptions and adding zero-allocation Try methods for compression, encryption, hashing, obfuscation, and serialization. Update README to reflect these changes, emphasizing performance improvements and usage examples. ([@matt-edmondson](https://github.com/matt-edmondson))
- Update README to reflect changes in target frameworks and provide an example implementation of a custom MD5 hash provider, enhancing clarity on usage and functionality. ([@matt-edmondson](https://github.com/matt-edmondson))
- Refactor interfaces in ktsu.Abstractions to use Try methods for compression, encryption, hashing, obfuscation, and serialization, enhancing performance by reducing allocations. Update README to reflect these changes and clarify usage. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add System.Memory package reference and enhance interfaces in ktsu.Abstractions for better async support. Update README for clarity on usage and installation. ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove EnumOrderingAnalyzer project and related files from the solution, streamlining the project structure and eliminating unused analyzers. ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove obsolete abstraction models for compression, encryption, hashing, obfuscation, and filesystem types, along with global usings. This cleanup streamlines the project structure. ([@matt-edmondson](https://github.com/matt-edmondson))
- Add detailed README for ktsu.Abstractions library, outlining interfaces for compression, encryption, hashing, obfuscation, serialization, and filesystem access. Include installation instructions, quickstart examples, and contributing guidelines. ([@matt-edmondson](https://github.com/matt-edmondson))
- Remove outdated files and update project references to reflect the new repository name 'Abstractions'. Set version to 1.0.0 and clean up changelog, README, and tags. ([@matt-edmondson](https://github.com/matt-edmondson))
- Initial commit ([@matt-edmondson](https://github.com/matt-edmondson))

ktsu.Essentials 1.1.0

ktsu.Essentials

Introduction

Features

Installation

Package Manager Console

.NET CLI

Package Reference

Usage Examples

Basic Example

Compression

Serialization

Caching

Persistence

Implementing a Custom Provider

API Reference

ICompressionProvider

IEncodingProvider

IEncryptionProvider

IHashProvider

ISerializationProvider

ICacheProvider<TKey, TValue>

IPersistenceProvider<TKey>

IValidationProvider<T>

ILoggingProvider

INavigationProvider<T>

ICommandExecutor

IFileSystemProvider