Getting Started
+This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project.
+Install
+Add CapyKit to your project from NuGet:
+dotnet add package CapyKit
+If you are working from a local checkout instead, reference the project directly:
+dotnet add reference ../CapyKit/CapyKit.csproj
+Add Namespaces
+Most APIs live in one of three namespaces:
+using CapyKit;
+using CapyKit.Extensions;
+using CapyKit.Helpers;
+Use CapyKit for core types such as Password, Pool<T>, and CapyEventReporter. Use CapyKit.Extensions for extension methods. Use CapyKit.Helpers for serialization, compression, security, keys, language, and calculation helpers.
Work With Strings
+using CapyKit.Extensions;
+
+string? suppliedName = "";
+string name = suppliedName.IfNullOrWhiteSpace("Guest");
+IfNullOrEmpty and IfNullOrWhiteSpace return the original value when it is usable and return your replacement value when it is not.
Page And Filter Collections
+using CapyKit.Extensions;
+
+var activeUsers = users.Filter(user => user.Disabled);
+var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25);
+int pageCount = activeUsers.PageCount(pageSize: 25);
+Filter removes items that match the predicate. Page uses natural page numbering, so the first page is 1.
Serialize And Compress Data
+using CapyKit.Helpers;
+
+var json = SerializationHelper.SerializeToString(order);
+var copy = SerializationHelper.Deserialize<Order>(json);
+
+var compressed = CompressionHelper.CompressToString(order);
+var restored = CompressionHelper.Decompress<Order>(compressed);
+Serialization uses System.Text.Json. Compression stores the serialized JSON payload using gzip; CompressToString returns a Base64 representation for easier storage or transport.
Hash And Verify Passwords
+using CapyKit;
+using CapyKit.Helpers;
+
+Password storedPassword = SecurityHelper.Pbkdf2("correct horse battery staple");
+
+bool passwordMatches = SecurityHelper.CompareHashedPassword(
+ storedPassword,
+ "correct horse battery staple",
+ storedPassword.Salt,
+ Password.Pbkdf2Algorithm);
+SecurityHelper.Pbkdf2 creates a Password with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm.
Generate Random Values
+using CapyKit.Helpers;
+
+string token = SecurityHelper.GetRandomString(32);
+string password = SecurityHelper.GetRandomPassword(
+ 20,
+ ValidCharacterCollection.Lowercase,
+ ValidCharacterCollection.Uppercase,
+ ValidCharacterCollection.Numbers,
+ ValidCharacterCollection.Special);
+Random string and password generation use .NET cryptographic random number generation.
+Create And Validate Keys
+using System.Text;
+using CapyKit.Helpers;
+
+var keyHelper = new KeyHelper();
+keyHelper.SetMasterKeyAccessor(() => Encoding.UTF8.GetBytes("replace-with-your-master-key"));
+keyHelper.SetSaltSizeAccessor(() => 8);
+keyHelper.SetNumPartsAccessor(() => 4);
+
+string key = keyHelper.GenerateKey();
+bool valid = keyHelper.ValidateKey(key);
+KeyHelper uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time.
Subscribe To CapyKit Events
+using CapyKit;
+
+CapyEventReporter.Subscribe(
+ e => Console.WriteLine($"[{e.Level}] {e.MethodName}: {e.Message}"),
+ EventLevel.Warning);
+CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses.
+Browse The API
+For the full list of namespaces, types, overloads, and member signatures, open the generated API Reference.