NeeLib 2.3.0

NeeLib

Author: SRTECH
Developer: SRTECH
Version: 2.3.0

NeeLib is a compact, production-ready .NET utility library for ASP.NET Core developers. It bundles a set of well-tested helpers for common web application tasks: alert payloads, in-memory caching, preference storage, session & cookie helpers, email (SMTP + Microsoft Graph), file I/O, secure random generation, date/time utilities, Excel export, HTML→PDF conversion, QR/barcode generation, REST client helpers, and encryption/password handling.

Target framework: .NET 10.0

Quick links

• Project: NeeLib
• License: MIT (see LICENSE.txt)

---

Project Introduction

NeeLib solves recurring infrastructure tasks developers reimplement across web projects. Instead of rebuilding email senders, Excel exports, file utilities, or cryptography helpers, NeeLib provides a focused, dependency-light toolkit that:

• Reduces boilerplate and accelerates development
• Uses secure, modern primitives (RandomNumberGenerator, AesGcm, DataProtection, BCrypt)
• Is optimized for performance (zero-allocation patterns, stream-based JSON, static HttpClient)
• Is cross-platform (ImageSharp & ZXing for images instead of System.Drawing)

Use cases: send transactional email, cache computed data, export DataTables to Excel, convert generated HTML to PDF, create QR codes for receipts, securely protect small secrets, and call external REST APIs.

---

Prerequisites & Setup

• .NET 10 SDK
• Register services in your ASP.NET Core app when using DI-dependent features:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Required for CacheMemory
builder.Services.AddMemoryCache();

// Required for SessionCookies
builder.Services.AddHttpContextAccessor();
builder.Services.AddSession();

// Required for Data Protection usage in Protector (if you want shared key management)
builder.Services.AddDataProtection();

var app = builder.Build();
app.UseSession();
app.Run();

Notes:

• For sending email via Microsoft Graph, configure Azure AD credentials (TenantId, ClientId, Client Secret).
• The library targets .NET 10 and uses modern APIs (AesGcm, RandomNumberGenerator, System.Text.Json where appropriate).

---

Class Details and Function Examples

This section lists the main public classes in the package and example usage for their most important functions. Each example is self-contained and demonstrates typical usage.

Alerts

Class summary A small utility that constructs JSON alert payloads (SweetAlert2 style) with minimal allocations. Designed for generating ready-to-send JSON objects used by client-side alert libraries.

Public functions

• AlertBox(string title, string message, string icon, bool toast)

Function explanation

• AlertBox: returns a compact JSON string representing alert configuration. Use on server to emit payloads consumed by front-end notification components.

Example

using NeeLib;

var json = Alerts.AlertBox("Saved", "Your item was saved successfully.", Alerts.Success, false);
// json -> {"title":"Saved","text":"Your item was saved successfully.","icon":"success","toast":false}

Purpose: produces a compact JSON string that front-end code can pass to an alert library. Ensure client-side HTML encoding to avoid XSS.

---

CacheMemory

Class summary Wrapper around IMemoryCache with recommended patterns: generic read/write, GetOrSet factory (async & sync), and sized entries. Provides typed access and prevents cache stampedes.

Main public functions

• ConfigCache(TimeSpan sliding, TimeSpan absolute, long size)
  • Explanation: returns MemoryCacheEntryOptions configured with sliding and absolute expirations and estimated size.
• WriteCache(string key, string value, MemoryCacheEntryOptions options)
  • Explanation: writes string value only if key does not exist; prevents overwrites.
• ReadCache(string key)
  • Explanation: returns cached string or null if missing.
• WriteCache<T>(string key, T value, MemoryCacheEntryOptions options)
  • Explanation: generic variant to store any object
• ReadCache<T>(string key)
  • Explanation: typed read; returns default(T) if not present
• GetOrSetCacheAsync<T>(string key, Func<Task<T>> factory, MemoryCacheEntryOptions options)
  • Explanation: atomic async factory to prevent concurrent requests from triggering duplicate work

Example (async factory)

// inside a controller/service with IMemoryCache injected
var cacheUtil = new CacheMemory(memoryCache);
var options = cacheUtil.ConfigCache(TimeSpan.FromMinutes(5), TimeSpan.FromHours(1), size:1);

string value = await cacheUtil.GetOrSetCacheAsync<string>("greeting", async () => {
    await Task.Delay(10);
    return "Hello from DB";
}, options);

Purpose: avoid duplicate work (cache stampede protection via GetOrCreateAsync) and keep memory usage explicit.

---

Preference

Class summary Process-lifetime in-memory key-value store optimized for concurrent access using ConcurrentDictionary. Good for quick application-scoped flags or small cached values.

Public functions (examples)

• SetString/GetString/ClearString
  • Explanation: store, retrieve, or clear plain string values
• SetBool/GetBool/ClearBool
  • Explanation: boolean flags storage
• SetInt/GetInt/ClearInt
  • Explanation: integer values
• SetFloat/GetFloat/ClearFloat
  • Explanation: float values
• SetDouble/GetDouble/ClearDouble
  • Explanation: double values

Example

Preference.SetString("Theme","dark");
var theme = Preference.GetString("Theme"); // "dark"

Preference.SetInt("MaxItems", 50);
int max = Preference.GetInt("MaxItems"); // 50

Purpose: fast, thread-safe in-memory store for app preferences. Not persisted across restarts.

---

SessionCookies

Class summary Helper bound to IHttpContextAccessor for safe read/write of cookies and session values, including object serialization to JSON and Base64 encoding of cookie values. Designed to be registered with DI and used in controllers/services.

Important public functions

• WriteCookie(string key, string value, DateTime expire)
  • Explanation: appends an HttpOnly, Secure cookie with SameSite=strict and base64-encoded value
• ReadCookie(string key)
  • Explanation: returns decoded cookie value or empty string
• DeleteCookie(string key)
  • Explanation: removes cookie from response
• WriteCookieObject<T>(string key, T value, DateTime expire)
  • Explanation: serializes object to JSON then stores as cookie
• ReadCookieObject<T>(string key)
  • Explanation: reads cookie and deserializes JSON to T
• WriteSessionString/ReadSessionString/DeleteSession/ClearSession
  • Explanation: session string lifecycle helpers (base64 encoded for strings)
• WriteSessionObject<T>/ReadSessionObject<T>
  • Explanation: stores and retrieves JSON-serialized objects in session

Example (cookie)

// assume injected SessionCookies sessionCookies
sessionCookies.WriteCookie("user", "alice@example.com", DateTime.UtcNow.AddDays(7));
string user = sessionCookies.ReadCookie("user");

Example (session object)

sessionCookies.WriteSessionObject("cart", new { Items = 3, Total = 29.99m });
var cart = sessionCookies.ReadSessionObject<dynamic>("cart");

Prerequisites: Register IHttpContextAccessor and enable sessions in the web host.

---

Email

Class summary High-level email utilities supporting SMTP (sync/async) and Microsoft Graph. Supports file attachments and asynchronous sending. Provides helper EmailModel DTO for common properties.

Key functions

• SendTextSMTP/SendFileSMTP (sync) — legacy
  • Explanation: synchronous SMTP send; blocks calling thread (use async in web apps)
• SendTextSMTPAsync/SendFileSMTPAsync (async) — recommended
  • Explanation: async SMTP send using SmtpClient.SendMailAsync
• SendTextApi/SendFileApi (Microsoft Graph)
  • Explanation: sends email via GraphServiceClient using ClientSecretCredential
• GetUsers (sync) and GetUsersAsync
  • Explanation: list Graph users; prefer GetUsersAsync to avoid deadlocks

Example (async SMTP)

var model = new EmailModel
{
    From = "sender@example.com",
    Password = "smtp-password",
    Host = Email.GmailHost,
    Port = Email.Port_587,
    Ssl = Email.GmailSsl,
    To = new[] { "recipient@example.com" },
    Subject = "Test",
    Body = "Hello from NeeLib",
    BodyType = Email.HTML
};

string result = await Email.SendTextSMTPAsync(model, cc:false, bcc:false);
// result == "OK" on success

Notes: For Microsoft Graph usage, populate Tenantid, Clientid, Secretid in EmailModel and call SendTextApi/SendFileApi. Use GetUsersAsync to avoid sync-over-async.

---

FilesIO

Class summary File and directory utilities with async I/O, base64 file creation, and safe directory management.

Key functions

• CreateDir(string dirPath)
  • Explanation: creates directory if missing; returns string status
• CreateFile(string filePath, string data) (async)
  • Explanation: writes text content asynchronously
• CreateFile(string filePath, byte[] data) (async)
  • Explanation: writes binary content asynchronously
• CreateFileToBase64(string filePath, string base64string) (async)
  • Explanation: decodes base64 and writes binary file
• Other helpers for deletes and existence checks

Example

await FilesIO.CreateFile("/tmp/log.txt", "Log entry at " + DateTime.UtcNow);
await FilesIO.CreateFileToBase64("/tmp/picture.png", base64Data);

Purpose: consistent cross-platform file operations with asynchronous APIs.

---

Generate

Class summary Secure random generation helpers that use RandomNumberGenerator for cryptographic security and zero-allocation string creation.

Public functions

• Word(int length) — alphanumeric
  • Explanation: returns secure alphanumeric string; prevents leading '0' when requested
• Number(int length) — numeric string
  • Explanation: returns secure numeric string of requested length
• NumberAsInt(int length) — int
  • Explanation: returns secure integer in range for given digits (1-9)
• NumberAsLong(int length) — long
  • Explanation: returns secure long for lengths up to 18 digits

Example

var token = Generate.Word(32); // 32-character secure token
var otp = Generate.Number(6);  // 6-digit secure OTP

Purpose: create secure tokens, OTPs, and identifiers.

---

GetDateTime

Class summary Date/time formatting constants and timezone ID constants for conversion and display. Provides predefined format strings and common Windows timezone IDs.

Example

string now = DateTime.UtcNow.ToString(GetDateTime.LONG_TIME1); // e.g., "14:23:05"

Public functions / constants

• LONG_TIME1, LONG_TIME2, ISO_8601, etc.
  • Explanation: predefined date/time format strings for consistent formatting across the app. Use these constants to avoid magic format strings.
• WindowsTimeZoneIds (collection)
  • Explanation: common Windows timezone identifier constants to be used when converting or displaying localized times.

Note: Timezone IDs are Windows standard; if running cross-platform you may need mapping to IANA names.

---

MSOffice

Class summary Excel/CSV export helpers using ClosedXML. Supports DataTable and generic IEnumerable<T> exports to XLSX and FileContentResult for direct controller responses.

Key functions

• CreateExcelSheet(DataTable)
• CreateExcelSheets(List<DataTable>)
• CreateExcelSheet<T>(IEnumerable<T> data)
• ExportExcelSheet / ExportExcelSheets (FileContentResult)

Example

var bytes = MSOffice.CreateExcelSheet(dataTable);
System.IO.File.WriteAllBytes("out.xlsx", bytes);

Purpose: quickly produce Excel files for download or storage.

Function explanation (selected)

• CreateExcelSheet(DataTable)
  • Explanation: converts a DataTable into an in-memory XLSX and returns the byte[] ready to be written or returned from a controller.
• CreateExcelSheet<T>(IEnumerable<T>)
  • Explanation: serializes a sequence of POCOs into an XLSX worksheet using property names as headers.
• ExportExcelSheet / ExportExcelSheets
  • Explanation: convenience helpers that return FileContentResult for direct use in ASP.NET Core controller actions.

---

Pdf

Class summary HTML minifier and HTML→PDF conversion via iText7. Includes resource-safe file creation.

Key functions

• Minifier(string filePath) : Task<string>
• Create(string baseUri, string htmlString, string filePath) : bool

Example

string html = await Pdf.Minifier("templates/invoice.html");
Pdf.Create("https://example.com/assets/", html, "invoice.pdf");

Purpose: convert server-generated HTML pages to PDF documents suitable for printing or archival.

Function explanation (selected)

• Minifier(string filePath)
  • Explanation: reads an HTML template and removes unnecessary whitespace/comments to reduce PDF size and improve rendering determinism.
• Create(string baseUri, string htmlString, string filePath)
  • Explanation: renders provided HTML (resolving relative resources against baseUri) into a PDF file saved at filePath using iText7.

---

CodeGenerator (QR & Barcode)

Class summary Uses QRCoder + ImageSharp + ZXing to produce raster (PNG/JPG/GIF), SVG QR codes and 1D barcodes. Supports logo compositing and cross-platform image handling.

Key functions

• GenerateQrCode(QrConfig config) : byte[]? (raster)
• GenerateQrCodeSvg(QrConfig config) : string? (SVG)
• GenerateBarcode(BarcodeConfig config) : byte[]?

Example (PNG QR)

var cfg = new QrConfig { Payload = "https://example.com", PixelsPerModule = 20, Format = CodeImageFormat.Png };
byte[] png = CodeGenerator.GenerateQrCode(cfg);
File.WriteAllBytes("qrcode.png", png);

Purpose: create printable and web-friendly QR/barcode assets without System.Drawing.

Function explanation (selected)

• GenerateQrCode(QrConfig config)
  • Explanation: produces a raster image (PNG/JPG/GIF) from the provided configuration, optionally compositing a logo and returning image bytes.
• GenerateQrCodeSvg(QrConfig config)
  • Explanation: generates a scalable SVG representation of the QR payload suitable for inline HTML or vector print output.
• GenerateBarcode(BarcodeConfig config)
  • Explanation: creates a 1D barcode image (e.g., CODE128) as raw bytes for inclusion in documents or labels.

---

RestClient

Class summary High-performance REST client offering GET/POST/PUT/PATCH/DELETE, JSON (strongly-typed) helpers, multipart/form-data and form-url-encoded posting, and a shared static HttpClient for connection pooling.

Key functions (selected)

• Get/GetBytes/GetStream
• Post/PostBytes/PostStream
• PostFormUrlEncoded/PostFormData
• GetFromJsonAsync<T>
• PostAsJsonAsync<TRequest,TResponse>

Example (Post JSON and parse response)

var result = await RestClient.PostAsJsonAsync<RequestModel, ResponseModel>("https://api.example.com/submit", new RequestModel { Name = "Alice" });

Purpose: reduce HttpClient boilerplate and ensure safe, efficient calls.

Function explanation (selected)

• Get(url): performs GET and returns string content.
  • Explanation: use for small JSON/plain-text responses where buffering is acceptable.
• GetBytes(url): returns raw bytes (useful for images/files).
  • Explanation: stream-optimized for binary payloads.
• GetStream(url): returns Stream for large responses.
  • Explanation: avoids buffering large responses in memory.
• PostAsJsonAsync<TRequest,TResponse>(url, request): post JSON and parse typed response.
  • Explanation: serializes request using System.Text.Json and deserializes response to TResponse.
• PostFormData(url, multipart): posts multipart/form-data.
  • Explanation: use for file uploads or complex form payloads.

---

Protector

Class summary Comprehensive cryptography and encoding helpers: Base64/Hex, URL-safe Base64, Data Protection API wrappers (Lock/UnLock), MD5/SHA hashing, HMAC, AES-CBC and AES-GCM encryption, BCrypt password hashing, and constant-time comparison.

Key functions (selected)

• ToBase64/FromBase64, ToBase64Url/FromBase64Url
• Lock(string)/UnLock(string) // Data Protection API
• MD5Hash / SHA256Hash / SHA512Hash
• HMACSHA256 / HMACSHA512
• Encrypt/Decrypt (AES-CBC, random IV prepended)
• EncryptGcm/DecryptGcm (AES-GCM)
• HashPassword / VerifyPassword (BCrypt Enhanced)
• SecureEquals / GenerateSecureRandomString

Example (protect small secret)

string protectedBase64 = Protector.Lock("my-secret-value");
string original = Protector.UnLock(protectedBase64);

string aesCipher = Protector.Encrypt("password-key", "sensitive text");
string decrypted = Protector.Decrypt("password-key", aesCipher);

Security notes: use AesGcm for new development when authenticated encryption is required. Configure Data Protection key storage for multi-instance deployments.

Function explanation (selected)

• ToBase64/FromBase64
  • Explanation: encode/decode binary or text to standard Base64 strings.
• ToBase64Url/FromBase64Url
  • Explanation: produce URL-safe Base64 (replace +/ with -_) and trim padding.
• Lock/UnLock
  • Explanation: wrapper around ASP.NET Core Data Protection to persist small secrets tied to application keys.
• Encrypt/Decrypt
  • Explanation: AES-CBC with random IV prepended to ciphertext; suitable for legacy compatibility but not for new data.
• EncryptGcm/DecryptGcm
  • Explanation: AES-GCM authenticated encryption; use for new scenarios requiring integrity protection.
• HashPassword/VerifyPassword
  • Explanation: BCrypt-based password hashing utilities with configurable cost factor.
• SecureEquals
  • Explanation: constant-time comparison to mitigate timing attacks when comparing secrets.

---

Program (test harness)

Class summary Small entry point used during development to exercise library functions. Not required by consumers of the NuGet package.

---

Practical Use Case Example — End-to-End

Scenario: Generate a secure token, protect it, create a QR containing the protected token, export a small Excel report, and email the report with the QR image attached. Log timestamps at each step.

Prerequisites:

• ASP.NET Core or console app with access to NeeLib
• SMTP credentials if using SMTP sample

Example (console app)

using System;
using System.IO;
using System.Threading.Tasks;
using NeeLib;

class Demo
{
	public static async Task Main()
	{
		// 1) Generate a secure token and timestamp it
		string token = Generate.Word(32);
		string timestamp1 = DateTime.UtcNow.ToString("o"); // ISO 8601
		Console.WriteLine($"[{timestamp1}] Generated token: {token}");

		// 2) Protect the token with Data Protection API and produce URL-safe base64
		string protectedToken = Protector.Lock(token);
		string protectedTokenUrl = Protector.ToBase64Url(protectedToken);
		string timestamp2 = DateTime.UtcNow.ToString("o");
		Console.WriteLine($"[{timestamp2}] Protected token (URL-safe): {protectedTokenUrl}");

		// 3) Create a QR code that contains a verification URL with the protected token
		var qrCfg = new QrConfig
		{
			Payload = $"https://example.com/verify?t={protectedTokenUrl}",
			PixelsPerModule = 6,
			Format = CodeImageFormat.Png
		};

		byte[] qrPng = CodeGenerator.GenerateQrCode(qrCfg) ?? Array.Empty<byte>();
		File.WriteAllBytes("verify_qr.png", qrPng);
		string timestamp3 = DateTime.UtcNow.ToString("o");
		Console.WriteLine($"[{timestamp3}] QR code written to verify_qr.png");

		// 4) Build a simple DataTable report and export to Excel
		var dt = new System.Data.DataTable("Report");
		dt.Columns.Add("GeneratedAt");
		dt.Columns.Add("TokenPreview");
		dt.Rows.Add(DateTime.UtcNow.ToString("o"), token.Substring(0, 8));

		byte[] excelBytes = MSOffice.CreateExcelSheet(dt);
		File.WriteAllBytes("report.xlsx", excelBytes);
		string timestamp4 = DateTime.UtcNow.ToString("o");
		Console.WriteLine($"[{timestamp4}] Excel report written to report.xlsx");

		// 5) Send an email with report and QR attached (SMTP async)
		var email = new EmailModel
		{
			From = "sender@example.com",
			Password = "smtp-password",
			Host = Email.GmailHost,
			Port = Email.Port_587,
			Ssl = Email.GmailSsl,
			To = new[] { "recipient@example.com" },
			Subject = "Verification Report",
			Body = $"Report generated at {DateTime.UtcNow:o}",
			BodyType = Email.TEXT,
			Filespath = new[] { "report.xlsx", "verify_qr.png" }
		};

		var smtpResult = await Email.SendFileSMTPAsync(email, cc: false, bcc: false);
		string timestamp5 = DateTime.UtcNow.ToString("o");
		Console.WriteLine($"[{timestamp5}] Email send result: {smtpResult}");
	}
}

Explanation of steps and expected results

1. Generate a cryptographically secure token and log the timestamp.
2. Protect the token with the library's Data Protection wrapper and produce a URL-safe form so it can be embedded into a verification link.
3. Generate a QR image pointing to a verification URL and save it to disk.
4. Produce a one-row Excel report and save it as report.xlsx.
5. Send an email with both the report and QR image attached using SMTP async API; log the send result.

At each step the example writes a UTC timestamp (ISO 8601) to the console to demonstrate traceability and ordering.

---

Recommendations & Best Practices

• Use async APIs in ASP.NET Core (SendTextSMTPAsync, GetOrSetCacheAsync, etc.).
• Configure Data Protection key storage for multi-instance apps (Azure Blob, Redis, or key vault).
• Prefer AES-GCM (EncryptGcm/DecryptGcm) for new symmetric encryption use-cases.
• Keep secrets (SMTP passwords, Azure client secrets) in secure stores (Azure Key Vault, user secrets, environment variables).

---