ktsu.Abstractions 1.0.8

Prefix Reserved
.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. .NET Standard 2.1 This package targets .NET Standard 2.1. The package is compatible with this framework or higher. 
dotnet add package ktsu.Abstractions --version 1.0.8
                    


                    

                
NuGet\Install-Package ktsu.Abstractions -Version 1.0.8
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.Abstractions" Version="1.0.8" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ktsu.Abstractions" Version="1.0.8" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ktsu.Abstractions" />
                    


                            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.Abstractions --version 1.0.8
                    


                    

                
#r "nuget: ktsu.Abstractions, 1.0.8"
#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.Abstractions@1.0.8
#: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.Abstractions&version=1.0.8
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ktsu.Abstractions&version=1.0.8
                    


                            Install as a Cake Tool

status: draft title: ktsu.Abstractions description: A library providing a comprehensive set of interfaces for compression, encryption, hashing, obfuscation, serialization, and filesystem access with zero-allocation Try* methods and convenient default implementations. tags:

  • abstractions
  • .net
  • csharp
  • provider pattern
  • dependency injection
  • serialization
  • compression
  • encryption
  • hashing
  • obfuscation
  • zero-allocation
  • spans

ktsu.Abstractions

A comprehensive library of interfaces that define a consistent, high-performance API for common cross-cutting concerns:

  • Compression: ICompressionProvider - compress/decompress data with Span<byte> and Stream support
  • Encryption: IEncryptionProvider - encrypt/decrypt data with key and IV management
  • Hashing: IHashProvider - hash data with configurable output length
  • Obfuscation: IObfuscationProvider - reversible obfuscation/deobfuscation
  • Serialization: ISerializationProvider - serialize/deserialize objects with TextReader/TextWriter support
  • Filesystem: IFileSystemProvider - file system operations abstraction

Each interface supports both zero-allocation Try* and Stream based methods and convenient self-allocating methods, with comprehensive async support.

Target frameworks

This package multi-targets common frameworks for broad compatibility:

  • netstandard2.1
  • net5.0, net6.0, net7.0, net8.0, net9.0

Supported OS: Windows, Linux, macOS.

Install

Via dotnet CLI:

dotnet add package ktsu.Abstractions

Via NuGet Package Manager:

Install-Package ktsu.Abstractions

Via PackageReference in csproj:

<ItemGroup>
    <PackageReference Include="ktsu.Abstractions" Version="1.0.0" />
</ItemGroup>

Quickstart

Using the implementations from the ktsu.Common package via DI:

using ktsu.Abstractions;
using ktsu.Common;
using Microsoft.Extensions.DependencyInjection;

IServiceCollection services = new ServiceCollection();
services.AddTransient<ICompressionProvider, ktsu.Common.GZipCompressionProvider>();
services.AddTransient<IEncryptionProvider, ktsu.Common.AesEncryptionProvider>();
services.AddTransient<IHashProvider, ktsu.Common.Sha256HashProvider>();
services.AddTransient<IObfuscationProvider, ktsu.Common.Base64ObfuscationProvider>();
services.AddTransient<ISerializationProvider, ktsu.Common.JsonSerializationProvider>();
services.AddTransient<IFileSystemProvider, ktsu.Common.FileSystemProvider>();

using IServiceProvider provider = services.BuildServiceProvider();

ICompressionProvider compressionProvider = provider.GetRequiredService<ICompressionProvider>();
IEncryptionProvider encryptionProvider = provider.GetRequiredService<IEncryptionProvider>();
IHashProvider hashProvider = provider.GetRequiredService<IHashProvider>();

API Design Pattern

All interfaces follow a consistent pattern:

  1. Core methods: Zero-allocation Try* methods that work with Span<byte> and Stream parameters
  2. Convenience methods: Allocating methods that call the Try* methods and handle buffer management
  3. Async support: Task-based async versions of all operations with CancellationToken support
  4. String overloads: UTF8-encoded string variants for convenience

Example Implementation

Here's how to implement a custom MD5 hash provider:

using System.Security.Cryptography;
using ktsu.Abstractions;

public sealed class MyMD5HashProvider : IHashProvider
{
    public int HashLengthBytes => 16; // MD5 produces 128-bit (16-byte) hashes

    // Zero-allocation implementation
    public bool TryHash(ReadOnlySpan<byte> data, Span<byte> destination)
    {
        if (destination.Length < HashLengthBytes)
        {
            return false;
        }

        using var md5 = MD5.Create();
        byte[] hashBytes = md5.ComputeHash(data.ToArray());
        hashBytes.AsSpan().CopyTo(destination);
        
        return true;
    }

    // Stream implementation
    public bool TryHash(Stream data, Span<byte> destination)
    {
        if (destination.Length < HashLengthBytes)
        {
            return false;
        }

        using var md5 = MD5.Create();
        byte[] hashBytes = md5.ComputeHash(data);
        hashBytes.AsSpan().CopyTo(destination);
        
        return true;
    }
    
    // All other methods (Hash(), HashAsync(), etc.) are provided by default implementations
}

Usage Example

using System.Text;
using ktsu.Abstractions;
using Microsoft.Extensions.DependencyInjection;

IServiceCollection services = new ServiceCollection();
services.AddTransient<IHashProvider, MyMD5HashProvider>();

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

// Using the convenience method (allocates and manages buffer)
byte[] inputData = Encoding.UTF8.GetBytes("Hello, World!");
byte[] hash = hashProvider.Hash(inputData);

// Using string convenience method
string textHash = Convert.ToHexString(hashProvider.Hash("Hello, World!"));

// Using the zero-allocation Try method
Span<byte> hashBuffer = stackalloc byte[hashProvider.HashLengthBytes];
if (hashProvider.TryHash(inputData, hashBuffer))
{
    string result = Convert.ToHexString(hashBuffer);
}

// Async usage
byte[] asyncHash = await hashProvider.HashAsync(inputData);

Design principles

  • Core methods support zero-allocation and streaming implementations: The fundamental operations use Try* methods that work with caller-provided Span<byte> or Stream destinations, returning boolean success indicators.
  • Default implementations provide convenience: Interfaces include default implementations for allocating methods (Hash(), Compress(), etc.) that handle buffer management and forward to the Try* methods.
  • Comprehensive async support: All operations have async variants with proper CancellationToken support.
  • String convenience methods: UTF8-encoded string overloads are provided where appropriate for developer convenience.
  • Minimal implementation burden: Implementers only need to provide the core Try* methods; all other functionality is inherited through default interface implementations.

Security notes

  • Obfuscation in IObfuscationProvider is not cryptography. Use it only for non-security scenarios (e.g., casual hiding). For confidentiality and integrity, use strong, vetted cryptography via IEncryptionProvider implementations.
  • Implementations of IEncryptionProvider should rely on proven libraries (e.g., .NET BCL crypto, libsodium bindings) and follow best practices (AEAD modes, random IVs/nonces, key management).

Thread-safety and lifetime

  • Provider implementations should be stateless or internally synchronized and safe to register as singletons in DI.
  • If an implementation maintains internal mutable state, document the concurrency model and recommended lifetime.

Why use these abstractions?

  • Consistency: A single, predictable surface across implementations
  • Testability: Swap implementations and mock easily, especially for filesystem
  • Separation of concerns: Keep app code free of vendor-specific details

Contributing

  • Fork the repo and create a feature branch
  • Implement or refine providers/analyzers and add tests
  • Open a pull request

License

Licensed under the MIT License. See LICENSE.md 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 was computed.  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.

NuGet packages (16)

Showing the top 5 NuGet packages that depend on ktsu.Abstractions:

Package Downloads
ktsu.SerializationProviders.SystemTextJson

A collection of serialization providers implementing ktsu.Abstractions.ISerializationProvider for popular .NET JSON libraries including Newtonsoft.Json and System.Text.Json.
ktsu.SerializationProviders.NewtonsoftJson

A collection of serialization providers implementing ktsu.Abstractions.ISerializationProvider for popular .NET JSON libraries including Newtonsoft.Json and System.Text.Json.
ktsu.HashProviders.SHA256

A collection of serialization providers implementing ktsu.Abstractions.ISerializationProvider for popular .NET JSON libraries including Newtonsoft.Json and System.Text.Json.
ktsu.CompressionProviders.Gzip

A collection of serialization providers implementing ktsu.Abstractions.ISerializationProvider for popular .NET JSON libraries including Newtonsoft.Json and System.Text.Json.
ktsu.HashProviders.MD5

A collection of serialization providers implementing ktsu.Abstractions.ISerializationProvider for popular .NET JSON libraries including Newtonsoft.Json and System.Text.Json.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.8 77 8/15/2025
1.0.7 93 8/12/2025
1.0.6 90 8/11/2025
1.0.5 87 8/11/2025
1.0.4 87 8/11/2025
1.0.3 89 8/11/2025
1.0.2 86 8/10/2025
1.0.1 87 8/10/2025

## v1.0.8 (patch)

Changes since v1.0.7:

- Add ISerializationOptions interface and related policies for serialization configuration ([@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))
## v1.0.7 (patch)

Changes since v1.0.6:

- 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))
## v1.0.6 (patch)

Changes since v1.0.5:

- 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))
## v1.0.5 (patch)

Changes since v1.0.4:

- 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))
## v1.0.4 (patch)

Changes since v1.0.3:

- 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))
## v1.0.3 (patch)

Changes since v1.0.2:

- 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))
- 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))
## v1.0.2 (patch)

Changes since v1.0.1:

- Remove EnumOrderingAnalyzer project and related files from the solution, streamlining the project structure and eliminating unused analyzers. ([@matt-edmondson](https://github.com/matt-edmondson))
## v1.0.1 (patch)

Changes since v1.0.0:

- 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 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))
## v1.0.0 (major)

- Initial commit ([@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))