189 lines
8.3 KiB
HTML
189 lines
8.3 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Getting Started | CapyKit Documentation </title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="title" content="Getting Started | CapyKit Documentation ">
|
|
|
|
|
|
<link rel="icon" href="favicon.ico">
|
|
<link rel="stylesheet" href="public/docfx.min.css">
|
|
<link rel="stylesheet" href="public/main.css">
|
|
<meta name="docfx:navrel" content="toc.html">
|
|
<meta name="docfx:tocrel" content="toc.html">
|
|
|
|
<meta name="docfx:rel" content="">
|
|
|
|
|
|
|
|
<meta name="loc:inThisArticle" content="In this article">
|
|
<meta name="loc:searchResultsCount" content="{count} results for "{query}"">
|
|
<meta name="loc:searchNoResults" content="No results for "{query}"">
|
|
<meta name="loc:tocFilter" content="Filter by title">
|
|
<meta name="loc:nextArticle" content="Next">
|
|
<meta name="loc:prevArticle" content="Previous">
|
|
<meta name="loc:themeLight" content="Light">
|
|
<meta name="loc:themeDark" content="Dark">
|
|
<meta name="loc:themeAuto" content="Auto">
|
|
<meta name="loc:changeTheme" content="Change theme">
|
|
<meta name="loc:copy" content="Copy">
|
|
<meta name="loc:downloadPdf" content="Download PDF">
|
|
|
|
<script type="module" src="./public/docfx.min.js"></script>
|
|
|
|
<script>
|
|
const theme = localStorage.getItem('theme') || 'auto'
|
|
document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
|
|
</script>
|
|
|
|
</head>
|
|
|
|
<body class="tex2jax_ignore" data-layout="" data-yaml-mime="">
|
|
<header class="bg-body border-bottom">
|
|
<nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
|
|
<div class="container-xxl flex-nowrap">
|
|
<a class="navbar-brand" href="index.html">
|
|
<img id="logo" class="svg" src="logo.svg" alt="CapyKit Documentation">
|
|
CapyKit Documentation
|
|
</a>
|
|
<button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
|
|
<i class="bi bi-three-dots"></i>
|
|
</button>
|
|
<div class="collapse navbar-collapse" id="navpanel">
|
|
<div id="navbar">
|
|
<form class="search" role="search" id="search">
|
|
<i class="bi bi-search"></i>
|
|
<input class="form-control" id="search-query" type="search" disabled placeholder="Search" autocomplete="off" aria-label="Search">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
</header>
|
|
|
|
<main class="container-xxl">
|
|
|
|
<div class="content">
|
|
<div class="actionbar">
|
|
|
|
<nav id="breadcrumb"></nav>
|
|
</div>
|
|
|
|
<article data-uid="">
|
|
<h1 id="getting-started">Getting Started</h1>
|
|
|
|
<p>This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project.</p>
|
|
<h2 id="install">Install</h2>
|
|
<p>Add CapyKit to your project from NuGet:</p>
|
|
<pre><code class="lang-bash">dotnet add package CapyKit
|
|
</code></pre>
|
|
<p>If you are working from a local checkout instead, reference the project directly:</p>
|
|
<pre><code class="lang-bash">dotnet add reference ../CapyKit/CapyKit.csproj
|
|
</code></pre>
|
|
<h2 id="add-namespaces">Add Namespaces</h2>
|
|
<p>Most APIs live in one of three namespaces:</p>
|
|
<pre><code class="lang-csharp">using CapyKit;
|
|
using CapyKit.Extensions;
|
|
using CapyKit.Helpers;
|
|
</code></pre>
|
|
<p>Use <code>CapyKit</code> for core types such as <code>Password</code>, <code>Pool<T></code>, and <code>CapyEventReporter</code>. Use <code>CapyKit.Extensions</code> for extension methods. Use <code>CapyKit.Helpers</code> for serialization, compression, security, keys, language, and calculation helpers.</p>
|
|
<h2 id="work-with-strings">Work With Strings</h2>
|
|
<pre><code class="lang-csharp">using CapyKit.Extensions;
|
|
|
|
string? suppliedName = "";
|
|
string name = suppliedName.IfNullOrWhiteSpace("Guest");
|
|
</code></pre>
|
|
<p><code>IfNullOrEmpty</code> and <code>IfNullOrWhiteSpace</code> return the original value when it is usable and return your replacement value when it is not.</p>
|
|
<h2 id="page-and-filter-collections">Page And Filter Collections</h2>
|
|
<pre><code class="lang-csharp">using CapyKit.Extensions;
|
|
|
|
var activeUsers = users.Filter(user => user.Disabled);
|
|
var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25);
|
|
int pageCount = activeUsers.PageCount(pageSize: 25);
|
|
</code></pre>
|
|
<p><code>Filter</code> removes items that match the predicate. <code>Page</code> uses natural page numbering, so the first page is <code>1</code>.</p>
|
|
<h2 id="serialize-and-compress-data">Serialize And Compress Data</h2>
|
|
<pre><code class="lang-csharp">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);
|
|
</code></pre>
|
|
<p>Serialization uses <code>System.Text.Json</code>. Compression stores the serialized JSON payload using gzip; <code>CompressToString</code> returns a Base64 representation for easier storage or transport.</p>
|
|
<h2 id="hash-and-verify-passwords">Hash And Verify Passwords</h2>
|
|
<pre><code class="lang-csharp">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);
|
|
</code></pre>
|
|
<p><code>SecurityHelper.Pbkdf2</code> creates a <code>Password</code> 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.</p>
|
|
<h2 id="generate-random-values">Generate Random Values</h2>
|
|
<pre><code class="lang-csharp">using CapyKit.Helpers;
|
|
|
|
string token = SecurityHelper.GetRandomString(32);
|
|
string password = SecurityHelper.GetRandomPassword(
|
|
20,
|
|
ValidCharacterCollection.Lowercase,
|
|
ValidCharacterCollection.Uppercase,
|
|
ValidCharacterCollection.Numbers,
|
|
ValidCharacterCollection.Special);
|
|
</code></pre>
|
|
<p>Random string and password generation use .NET cryptographic random number generation.</p>
|
|
<h2 id="create-and-validate-keys">Create And Validate Keys</h2>
|
|
<pre><code class="lang-csharp">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);
|
|
</code></pre>
|
|
<p><code>KeyHelper</code> 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.</p>
|
|
<h2 id="subscribe-to-capykit-events">Subscribe To CapyKit Events</h2>
|
|
<pre><code class="lang-csharp">using CapyKit;
|
|
|
|
CapyEventReporter.Subscribe(
|
|
e => Console.WriteLine($"[{e.Level}] {e.MethodName}: {e.Message}"),
|
|
EventLevel.Warning);
|
|
</code></pre>
|
|
<p>CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses.</p>
|
|
<h2 id="browse-the-api">Browse The API</h2>
|
|
<p>For the full list of namespaces, types, overloads, and member signatures, open the generated <a href="api/toc.html">API Reference</a>.</p>
|
|
|
|
</article>
|
|
|
|
<div class="contribution d-print-none">
|
|
</div>
|
|
|
|
<div class="next-article d-print-none border-top" id="nextArticle"></div>
|
|
|
|
</div>
|
|
|
|
<div class="affix">
|
|
<nav id="affix"></nav>
|
|
</div>
|
|
</main>
|
|
|
|
<div class="container-xxl search-results" id="search-results"></div>
|
|
|
|
<footer class="border-top text-secondary">
|
|
<div class="container-xxl">
|
|
<div class="flex-fill">
|
|
<span>Made with <a href="https://dotnet.github.io/docfx">docfx</a></span>
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html>
|