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

• Low-allocation interpolated string support on .NET Framework that avoids boxing and intermediate formatting strings ($"Age: {age}")
• Handler-backed formatting into TextWriter, or raw UTF-16 code-unit output to Stream, without materializing a result string
• Robust and performant StringSegment struct for working with substrings without allocations
• SpanReader, SpanWriter, and span-based byte run-length encoding
• BufferScope<T> for easy management of temporary ArrayPool and stack based buffers
• Value for carrying primitives, nullables, enums, and object values through one API without boxing supported primitives
• Pooled, single-item-optimized, and sequence-interning collections (ArrayPoolList<T>, SingleOptimizedList<TItem, TList>, SequenceSet<T>), plus ref-counted resource caches
• Reusable compiled glob matching for POSIX, Bash/extglob, Git/gitignore, MSBuild, Microsoft.Extensions.FileSystemGlobbing, PowerShell, and simple wildcard dialects
• Lazy file-system glob enumeration with include/exclude patterns, plus a compatibility-focused MSBuild result API with drive-root safety
• Gitignore parsing with ordered include/exclude rules and best-effort text clipboard access across supported desktop platforms
• Raw .resources inspection, registered-type NRBF deserialization for trusted payloads, and NativeAOT-compatible string lookup from ILC-embedded resources, loose resources, or managed owner/satellite assemblies parsed as data
• Interop ownership helpers that pair native handles with their managed owners
• Polyfills for many modern .NET BCL APIs on .NET Framework 4.7.2 (see the polyfill guide)
• A DisposableBase with double-disposal protection and disposal tracking helpers for diagnosing leaks
• Roslyn analyzers that run automatically through the package's KlutzyNinja.Touki.Analyzers dependency, which can also be installed independently
• Much more!

Overviews

• Configuring Your Project for Touki
• Touki Analyzers
• Reducing String Allocations with Touki
• Low-Allocation Collections
• Interning Variable-Length Sequences with SequenceSet<T>
• Buffers, Span Readers, and Span Writers
• Compiled Glob Matching and File-System Enumeration
• IO Helpers (globs, gitignore, clipboard, paths, temp folders, streams)
• Resources and Legacy Serialization
• Generated String Resource Solution
• .NET Framework polyfill layout and disambiguation: Polyfill guide
• Span performance on .NET Framework (net472+): Reference
• Stack and pooled scratch-buffer performance (net481/net10): Reference

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 depends on KlutzyNinja.Touki.Analyzers, so referencing KlutzyNinja.Touki is all it takes to run the Roslyn analyzers. The analyzer package can also be referenced independently when the runtime library is not needed, and it has its own release version.

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 Touki Analyzers 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.