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.

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.

3.8 KiB Raw Blame History