132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
dotnet add package CapyKit
|
|
```
|
|
|
|
If you are working from a local checkout instead, reference the project directly:
|
|
|
|
```bash
|
|
dotnet add reference ../CapyKit/CapyKit.csproj
|
|
```
|
|
|
|
## Add Namespaces
|
|
|
|
Most APIs live in one of three namespaces:
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```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);
|
|
```
|
|
|
|
`Filter` removes items that match the predicate. `Page` uses natural page numbering, so the first page is `1`.
|
|
|
|
## Serialize And Compress Data
|
|
|
|
```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);
|
|
```
|
|
|
|
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
|
|
|
|
```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);
|
|
```
|
|
|
|
`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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```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);
|
|
```
|
|
|
|
`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
|
|
|
|
```csharp
|
|
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](api/toc.yml).
|