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

• 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 culture side-file string resources
• 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 ship in the package and run automatically - no separate analyzer package to install
• Much more!

• Configuring Your Project for Touki
• Analyzers Shipped in the Package
• 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
• .NET Framework polyfill layout and disambiguation: Polyfill guide
• Span performance on .NET Framework (net472+): Reference
• Stack and pooled scratch-buffer performance (net481/net10): Reference

Using the .NET CLI:

dotnet add package KlutzyNinja.Touki

Or with the NuGet Package Manager:

PM> Install-Package KlutzyNinja.Touki

View on NuGet.org

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.

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

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