merge: DocFX tutorials + runnable samples for all SquidStd libraries

Author: tgiachi

SquidStd.slnx

@@ -29,6 +29,22 @@
         <Project Path="src/SquidStd.Mail.MailKit/SquidStd.Mail.MailKit.csproj"/>
         <Project Path="src/SquidStd.Mail.Queue/SquidStd.Mail.Queue.csproj"/>
     </Folder>
+    <Folder Name="/samples/">
+        <Project Path="samples/SquidStd.Samples.WorkerSystem/SquidStd.Samples.WorkerSystem.csproj" />
+        <Project Path="samples/SquidStd.Samples.Templating/SquidStd.Samples.Templating.csproj" />
+        <Project Path="samples/SquidStd.Samples.Storage/SquidStd.Samples.Storage.csproj" />
+        <Project Path="samples/SquidStd.Samples.Search/SquidStd.Samples.Search.csproj" />
+        <Project Path="samples/SquidStd.Samples.ScriptingLua/SquidStd.Samples.ScriptingLua.csproj" />
+        <Project Path="samples/SquidStd.Samples.Plugins/SquidStd.Samples.Plugins.csproj" />
+        <Project Path="samples/SquidStd.Samples.Networking/SquidStd.Samples.Networking.csproj" />
+        <Project Path="samples/SquidStd.Samples.Email/SquidStd.Samples.Email.csproj" />
+        <Project Path="samples/SquidStd.Samples.Database/SquidStd.Samples.Database.csproj" />
+        <Project Path="samples/SquidStd.Samples.AspNetCore/SquidStd.Samples.AspNetCore.csproj" />
+        <Project Path="samples/SquidStd.Samples.Messaging/SquidStd.Samples.Messaging.csproj" />
+        <Project Path="samples/SquidStd.Samples.Caching/SquidStd.Samples.Caching.csproj" />
+        <Project Path="samples/SquidStd.Samples.EventsJobsScheduling/SquidStd.Samples.EventsJobsScheduling.csproj" />
+        <Project Path="samples/SquidStd.Samples.GettingStarted/SquidStd.Samples.GettingStarted.csproj" />
+    </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj"/>
     </Folder>

docs/docfx.json

@@ -15,7 +15,7 @@
   "build": {
     "content": [
       { "files": [ "api/**.{yml,md}" ] },
-      { "files": [ "articles/**.{md,yml}", "*.md", "toc.yml" ] }
+      { "files": [ "articles/**.{md,yml}", "tutorials/**.{md,yml}", "*.md", "toc.yml" ] }
     ],
     "resource": [
       { "files": [ "images/**" ] }

docs/toc.yml

@@ -2,5 +2,7 @@
   href: index.md
 - name: Articles
   href: articles/
+- name: Tutorials
+  href: tutorials/
 - name: API
   href: api/

docs/tutorials/aspnetcore-app.md

@@ -0,0 +1,55 @@
+# Host SquidStd in an ASP.NET Core app
+
+Wire SquidStd into an ASP.NET Core Minimal API and expose its health checks over HTTP.
+
+## What you'll build
+
+A Minimal API web app that uses SquidStd (`SquidStd.AspNetCore`) as its DryIoc-backed service provider, surfaces
+the registered SquidStd health checks at `/health`, and answers a simple root endpoint.
+
+## Prerequisites
+
+- .NET 10 SDK
+- `dotnet add package SquidStd.AspNetCore`
+
+## Steps
+
+### 1. Register SquidStd on the builder
+
+`UseSquidStd` swaps in DryIoc as the ASP.NET Core service provider and bootstraps SquidStd. The root directory is
+taken from the host environment automatically, so you only set the config name.
+
+[!code-csharp[](../../samples/SquidStd.Samples.AspNetCore/Program.cs#step-1)]
+
+### 2. Bridge the health checks
+
+`AddSquidStdHealthChecks` registers every SquidStd `IHealthCheck` as a standard ASP.NET Core health check. Call it
+after `UseSquidStd`.
+
+[!code-csharp[](../../samples/SquidStd.Samples.AspNetCore/Program.cs#step-2)]
+
+### 3. Build the app and map endpoints
+
+Build the app, expose the health checks with the standard `MapHealthChecks`, add a root endpoint, and run.
+
+[!code-csharp[](../../samples/SquidStd.Samples.AspNetCore/Program.cs#step-3)]
+
+## Run it
+
+```bash
+dotnet run --project samples/SquidStd.Samples.AspNetCore
+```
+
+Browse to `/` for the "SquidStd up" message and to `/health` for the aggregated health-check status.
+
+## How it works
+
+`UseSquidStd` creates an owned DryIoc container, registers it through `DryIocServiceProviderFactory`, and hooks the
+SquidStd lifecycle into the ASP.NET Core host via a hosted service. `AddSquidStdHealthChecks` resolves the SquidStd
+`IHealthCheck` instances from that container and adapts each one into the standard health-check pipeline, so
+`MapHealthChecks` reports them like any other ASP.NET Core check.
+
+## See also
+
+- [SquidStd.AspNetCore reference](../articles/aspnetcore.md)
+- Previous: [Getting started](getting-started.md)

docs/tutorials/caching.md

@@ -0,0 +1,52 @@
+# Caching (in-memory + Redis)
+
+Cache typed values with a TTL, then swap the in-memory backend for Redis without changing your code.
+
+## What you'll build
+
+A host that resolves `ICacheService` (`SquidStd.Caching.Abstractions`) backed by the in-memory provider
+(`SquidStd.Caching`), and the one-line change to use Redis (`SquidStd.Caching.Redis`) instead.
+
+## Prerequisites
+
+- .NET 10 SDK
+- `dotnet add package SquidStd.Caching` (and `SquidStd.Caching.Redis` for the Redis backend)
+- For Redis: `docker run -p 6379:6379 redis`
+
+## Steps
+
+### 1. Register the in-memory cache
+
+[!code-csharp[](../../samples/SquidStd.Samples.Caching/Program.cs#step-1)]
+
+### 2. Set and get typed values
+
+`ICacheService` stores typed values with an optional TTL; `GetAsync<T>` returns `null` on a miss.
+
+[!code-csharp[](../../samples/SquidStd.Samples.Caching/Program.cs#step-2)]
+
+### 3. Switch to Redis
+
+Replace the registration with the Redis backend — the `ICacheService` usage is identical:
+
+```csharp
+container.AddRedisCache("redis://localhost:6379");
+```
+
+## Run it
+
+```bash
+dotnet run --project samples/SquidStd.Samples.Caching
+```
+
+Prints `hello`.
+
+## How it works
+
+`ICacheService` is the typed facade over an `ICacheProvider`; the provider is the swappable backend (in-memory or
+Redis). Values are serialized with the shared `IDataSerializer`, so the same code works on either backend.
+
+## See also
+
+- [SquidStd.Caching reference](../articles/caching.md)
+- [SquidStd.Caching.Redis reference](../articles/caching-redis.md)

docs/tutorials/database.md

@@ -0,0 +1,52 @@
+# Database (FreeSql + SQLite)
+
+Persist a typed entity and read it back with paging, using SQLite with no external database.
+
+## What you'll build
+
+A host that registers the database subsystem (`SquidStd.Database`) and resolves the generic data access
+`IDataAccess<TEntity>` (`SquidStd.Database.Abstractions`) to insert and page over a simple entity. It runs against a
+local SQLite file out of the box.
+
+## Prerequisites
+
+- .NET 10 SDK
+- `dotnet add package SquidStd.Database`
+- No external database: the default connection string is `sqlite://squidstd.db`, and the schema is auto-migrated on
+  startup.
+
+## Steps
+
+### 1. Register the database service
+
+`RegisterDatabase` wires the `database` config section, the `IDatabaseService` (which owns the FreeSql instance), and
+the open-generic `IDataAccess<>`. Starting the bootstrap starts the database service and auto-creates the schema.
+
+[!code-csharp[](../../samples/SquidStd.Samples.Database/Program.cs#step-1)]
+
+### 2. Insert and page over an entity
+
+Resolve `IDataAccess<Product>` for any `BaseEntity`-derived type. `InsertAsync` assigns the id and timestamps;
+`GetPagedAsync` returns a `PagedResultData<T>` with items and paging metadata.
+
+[!code-csharp[](../../samples/SquidStd.Samples.Database/Program.cs#step-2)]
+
+## Run it
+
+```bash
+dotnet run --project samples/SquidStd.Samples.Database
+```
+
+Prints the two inserted products ordered by price, with the total count and page metadata.
+
+## How it works
+
+`IDatabaseService` builds a single FreeSql ORM from the URI-style connection string (the scheme selects the provider:
+`sqlite`, `postgres`, `mysql`, `sqlserver`). `IDataAccess<TEntity>` is the generic repository over any
+`BaseEntity`: it exposes CRUD, bulk operations, a composable `Query()` (FreeSql `ISelect`), and `GetPagedAsync` for
+page + total-count reads. Every entity gets a `Guid` id plus UTC `Created`/`Updated` timestamps from `BaseEntity`.
+
+## See also
+
+- [SquidStd.Database reference](../articles/database.md)
+- [SquidStd.Database.Abstractions reference](../articles/database-abstractions.md)

docs/tutorials/email.md

@@ -0,0 +1,60 @@
+# Email: receive, send, and queue
+
+Poll a mailbox for inbound mail, send outbound mail over SMTP, and queue mail for background delivery.
+
+## What you'll build
+
+A host using `SquidStd.Mail.MailKit` and `SquidStd.Mail.Queue`: an IMAP poller that raises a `MailReceivedEvent`
+for each new email, an SMTP sender (`IMailSender`), and a fire-and-forget send queue (`IMailQueue`) backed by
+messaging. The contracts live in `SquidStd.Mail.Abstractions`.
+
+## Prerequisites
+
+- .NET 10 SDK
+- `dotnet add package SquidStd.Mail.MailKit`
+- `dotnet add package SquidStd.Mail.Queue`
+- Real IMAP/SMTP credentials are only needed to actually connect; the sample compiles and runs without them.
+
+## Steps
+
+### 1. Receive: poll a mailbox
+
+`AddMail` registers an IMAP/POP3 poller; each received message is published as a `MailReceivedEvent`, which an
+`IAsyncEventListener<MailReceivedEvent>` handles.
+
+[!code-csharp[](../../samples/SquidStd.Samples.Email/Program.cs#step-1)]
+
+### 2. Send: outbound SMTP
+
+`AddMailSender` registers `IMailSender`; build an `OutgoingMailMessage` and call `SendAsync`.
+
+[!code-csharp[](../../samples/SquidStd.Samples.Email/Program.cs#step-2)]
+
+### 3. Queue: background delivery
+
+`AddInMemoryMessaging` plus `AddMailQueue` register `IMailQueue`; `EnqueueAsync` hands the message to a
+background consumer that sends it via the SMTP sender.
+
+[!code-csharp[](../../samples/SquidStd.Samples.Email/Program.cs#step-3)]
+
+## Run it
+
+```bash
+dotnet run --project samples/SquidStd.Samples.Email
+```
+
+It registers the poller, sender, and queue, registers the received-mail listener, and enqueues a message.
+Pass `--send` to also attempt a synchronous SMTP send (requires a reachable server).
+
+## How it works
+
+The poller runs on the timer wheel, fetches new messages over IMAP/POP3 with MailKit, and publishes a
+`MailReceivedEvent` on the event bus. `IMailSender` maps `OutgoingMailMessage` to a MIME message and sends it.
+`AddMailQueue` layers a queue over `SquidStd.Messaging`: `EnqueueAsync` publishes to the queue and a background
+consumer (`MailSendConsumerService`) drains it through `IMailSender`, decoupling request latency from delivery.
+
+## See also
+
+- [SquidStd.Mail.MailKit reference](../articles/mail-mailkit.md)
+- [SquidStd.Mail.Queue reference](../articles/mail-queue.md)
+- [SquidStd.Mail.Abstractions reference](../articles/mail-abstractions.md)

docs/tutorials/events-jobs-scheduling.md

@@ -0,0 +1,58 @@
+# Events, jobs and scheduling
+
+Publish in-process events, run work on a thread pool, and schedule recurring jobs with cron.
+
+## What you'll build
+
+A host that uses three core services from `SquidStd.Services.Core`: the `IEventBus` (publish/subscribe), the
+`IJobSystem` (thread-pool work), and the `ICronScheduler` (cron-based recurring jobs).
+
+## Prerequisites
+
+- .NET 10 SDK
+- `dotnet add package SquidStd.Services.Core`
+
+The cron scheduler and timer wheel are opt-in — enable them with `RegisterSchedulerServices()`:
+
+[!code-csharp[](../../samples/SquidStd.Samples.EventsJobsScheduling/Program.cs#step-1)]
+
+## Steps
+
+### 1. Publish and handle an event
+
+Implement `IAsyncEventListener<T>`, register it, and publish an `IEvent`. Every registered listener is awaited.
+
+[!code-csharp[](../../samples/SquidStd.Samples.EventsJobsScheduling/Program.cs#step-1)]
+
+### 2. Run work on the job system
+
+`IJobSystem.ScheduleAsync` runs an `Action` on a worker thread and returns a `Task` that completes when it finishes.
+
+[!code-csharp[](../../samples/SquidStd.Samples.EventsJobsScheduling/Program.cs#step-2)]
+
+### 3. Schedule a cron job
+
+`ICronScheduler.Schedule` takes a name, a 5-field cron expression (UTC), and an async handler invoked on each
+occurrence.
+
+[!code-csharp[](../../samples/SquidStd.Samples.EventsJobsScheduling/Program.cs#step-3)]
+
+## Run it
+
+```bash
+dotnet run --project samples/SquidStd.Samples.EventsJobsScheduling
+```
+
+You'll see `received: hello`, `job ran on a worker thread`, and—if you let it run across a 5-minute boundary—
+`cron tick`.
+
+## How it works
+
+The event bus dispatches to sync and async listeners; the job system is a fixed-size worker-thread pool; the cron
+scheduler is driven by the timer wheel (registered by `RegisterSchedulerServices`).
+
+## See also
+
+- [SquidStd.Services.Core reference](../articles/services-core.md)
+- [SquidStd.Core reference](../articles/core.md)
+- Previous: [Getting started](getting-started.md)

docs/tutorials/getting-started.md

@@ -0,0 +1,56 @@
+# Getting started: your first SquidStd host
+
+Build a minimal SquidStd application: a bootstrapper that loads config, configures logging, and runs the
+registered services until shutdown.
+
+## What you'll build
+
+A console host on top of `SquidStdBootstrap` (from `SquidStd.Services.Core`, which brings in `SquidStd.Core`
+and `SquidStd.Abstractions`). It loads its config, wires the default services, and runs until you stop it.
+
+## Prerequisites
+
+- .NET 10 SDK
+- `dotnet add package SquidStd.Services.Core`
+
+## Steps
+
+### 1. Create the bootstrapper
+
+`SquidStdBootstrap.Create` takes a `SquidStdOptions` (config name + root directory) and registers the core
+services (config, logging, event bus, jobs, timers…) into an owned DryIoc container.
+
+[!code-csharp[](../../samples/SquidStd.Samples.GettingStarted/Program.cs#step-1)]
+
+### 2. Start the services
+
+`StartAsync` starts every registered `ISquidStdService` in priority order.
+
+[!code-csharp[](../../samples/SquidStd.Samples.GettingStarted/Program.cs#step-2)]
+
+### 3. Run until shutdown
+
+`RunAsync` starts (if not already started), waits for cancellation, then stops the services cleanly. Use either
+`StartAsync` plus your own loop, or just `RunAsync`.
+
+[!code-csharp[](../../samples/SquidStd.Samples.GettingStarted/Program.cs#step-3)]
+
+## Run it
+
+```bash
+dotnet run --project samples/SquidStd.Samples.GettingStarted
+```
+
+The host starts, logs the service lifecycle, and waits until you press Ctrl+C.
+
+## How it works
+
+`SquidStdBootstrap` is the composition root: it builds the container, registers the core services, loads the
+config sections, and orchestrates the `ISquidStdService` lifecycle. Every other SquidStd module plugs into this
+container through its `Add…` extension methods.
+
+## See also
+
+- [SquidStd.Services.Core reference](../articles/services-core.md)
+- [SquidStd.Core reference](../articles/core.md)
+- Next: [Events, jobs and scheduling](events-jobs-scheduling.md)