Touki (登器): Code for .NET and .NET Framework

Provides useful functionality both for .NET and .NET Framework applications.

Tōki (登器) is the Japanese word for (Ninja) "climbing gear" or "climbing equipment". This library is designed to help developers "climb" the challenges of cross framework .NET development by providing tools and utilities that enhance performance and efficiency.

Some of the design goals include:

• Avoiding unnecessary allocations
• Avoiding code that prevents AOT compilation on .NET
• Leveraging the latest C# (14+) features to improve usability and performance

Features

• Non allocating interpolated string support on .NET Framework ($"Age: {age}")
• Formatting directly into Stream and TextWriter without unnecessary allocations
• Robust and performant StringSegment struct for working with substrings without allocations
• SpanReader and SpanWriter for efficient reading and writing of data in spans
• BufferScope<T> for easy management of temporary ArrayPool and stack based buffers
• Value struct for creating strongly typed arbitrary collections of values without boxing most primitives
• Pooled and single-item-optimized list types (ArrayPoolList<T>, SingleOptimizedList<TItem, TList>) and ref-counted resource caches
• MSBuildEnumerator for MSBuild-style glob enumeration with no allocations until a match is produced
• Polyfills for many modern .NET BCL APIs on .NET Framework 4.7.2 (see the polyfill layout doc for the full list)
• A DisposableBase with double-disposal protection and disposal tracking helpers for diagnosing leaks
• Roslyn analyzers that ship in the package and run automatically - no separate analyzer package to install
• Much more!

Overviews

• Configuring Your Project for Touki
• Analyzers Shipped in the Package
• Reducing String Allocations with Touki
• Low-Allocation Collections
• Buffers, Span Readers, and Span Writers
• IO Helpers (globs, paths, temp folders, stream formatting)
• .NET Framework Polyfill Layout & Disambiguation
• Span Performance on .NET Framework (net472+)
• ArrayPool vs Stack Scratch Buffers (net481/net10)

Package Installation

Using the .NET CLI:

dotnet add package KlutzyNinja.Touki

Or with the NuGet Package Manager:

PM> Install-Package KlutzyNinja.Touki

View on NuGet.org

Analyzers

The package includes Roslyn analyzers. They are delivered inside KlutzyNinja.Touki itself, so referencing the package is all it takes - there is nothing extra to install.

They encode the conventions the library is built on, across a few areas:

• Reliability - hidden struct copies, values that must be disposed deterministically, and stackalloc requests large enough to threaten the stack.
• Maintainability - one type per file, and file names that say which type a file holds.
• Performance - building strings without the StringBuilder allocation.
• Usage and naming - pattern matching for null checks, and an opt-in naming engine that replaces IDE1006.

See Analyzers Shipped in the Package for the full rule list, what each one flags, and how to configure it.

Requirements

• .NET 10.0 or later OR .NET Framework 4.7.2 or later
• C# 14.0 or later for the best experience
• Any CPU architecture supported by .NET - the package ships architecture-neutral ("AnyCPU") assemblies with no native components, so x64 and ARM64 are both fully supported on Windows, Linux, and macOS

Contributing

See CONTRIBUTING.md for more information on how to contribute to this project.