DEV Community: Mark Jack

mjm.local.docs: Open Source Local Knowledge Base with MCP

Mark Jack — Fri, 20 Feb 2026 13:29:37 +0000

The Problem

You are mid-session with Claude Code or another AI coding assistant. You ask:

"How does authentication work in our system?"
"What was the decision behind using event sourcing in the orders module?"

The AI does its best, guessing from the code it can see. But the real answer is buried in a Word document, a PDF architecture diagram, or a Markdown ADR (Architecture Decision Record) that lives somewhere on your disk.

mjm.local.docs solves this.

It is an open-source, locally-deployed knowledge base server that exposes your documents through both:

A Blazor Web UI
A full Model Context Protocol (MCP) server

This allows your AI assistant to search, read, and even update your documentation directly from chat.

Built on .NET 10, it runs entirely on your machine:

No mandatory cloud dependency
No data leaving your environment
Full support for pluggable embedding models
Pluggable vector storage backends

GitHub:
https://github.com/markjackmilian/mjm.local.docs

What Is mjm.local.docs?

mjm.local.docs is a self-hosted semantic document search server.

At its core, it:

Ingests documents — PDF, Word (.docx), Markdown, plain text, and more
Chunks and embeds them using a configurable embedding provider (local or cloud-based)
Stores embeddings in a configurable vector store (SQLite, HNSW index, SQL Server, or in-memory)
Exposes search and management through:
- A Blazor web interface
- An MCP HTTP endpoint

Clean Architecture

Mjm.LocalDocs.Core           ← Domain models, interfaces (zero external dependencies)
Mjm.LocalDocs.Infrastructure ← Implementations: embeddings, readers, vector stores
Mjm.LocalDocs.Server         ← ASP.NET Core host, Blazor UI, MCP tools

Everything is wired together via standard .NET dependency injection.

Every major component is swappable via configuration:

Embedding provider
Vector store
File storage

Deploy Locally in Minutes

Clone and run:

git clone https://github.com/markjackmilian/mjm.local.docs.git
cd mjm.local.docs/mjm.local.docs
dotnet run --project src/Mjm.LocalDocs.Server/Mjm.LocalDocs.Server.csproj

Web UI:

http://localhost:5024

Default credentials:

admin / admin

(Change them in appsettings.json.)

MCP endpoint:

http://localhost:5024/mcp

No Docker required.
No cloud account needed.

Out of the box:

In-memory vector store
Deterministic fake embedding generator
No API key required

Perfect for local development.

Pluggable Embedding Providers

Embedding generation is fully pluggable via the IEmbeddingService interface.

Configured in appsettings.json.

Provider	Provider Value	Dimension	Notes
Fake	Fake	1536	Deterministic word-hash vectors. Dev/test only.
OpenAI	OpenAI	1536	Uses `text-embedding-3-small`. API key required.
Azure OpenAI	AzureOpenAI	1536	Azure-hosted OpenAI.
Ollama	Ollama	768	Fully local embeddings.

All providers implement:

IEmbeddingGenerator<string, Embedding<float>>

You can bring your own implementation easily.

Running 100% Locally with Ollama

Example configuration:

{
  "LocalDocs": {
    "Embeddings": {
      "Provider": "Ollama",
      "Dimension": 768,
      "Ollama": {
        "Endpoint": "http://localhost:11434",
        "Model": "nomic-embed-text"
      }
    }
  }
}

Popular models:

Model	Dimension	Trade-off
nomic-embed-text	768	Balanced quality/speed
mxbai-embed-large	1024	Higher quality, slower
all-minilm	384	Fastest, lower quality

Storage Options: From SQLite to SQL Server

Configured via:

LocalDocs:Storage:Provider

Provider	Description	Vector Search	Best For
InMemory	RAM only	O(n) brute-force	Dev/testing
Sqlite	EF Core + BLOB embeddings	O(n) cosine	Small/medium KB
SqliteHnsw	SQLite + HNSW index file	O(log n) approx	Larger KB
SqlServer	SQL Server 2025+ VECTOR type	DiskANN	Enterprise/Azure

Connection string examples:

// SQLite
"ConnectionStrings": { "LocalDocs": "Data Source=localdocs.db" }

// SQL Server
"ConnectionStrings": { "LocalDocs": "Server=myserver.database.windows.net;Database=localdocs;..." }

Vector Search Under the Hood

Brute-Force (SQLite)

Embeddings stored as BLOBs
Cosine similarity against every chunk
O(n)
Reliable for thousands of documents

HNSW (SqliteHnsw)

Adds a persisted HNSW graph:

{
  "LocalDocs": {
    "Storage": {
      "Provider": "SqliteHnsw",
      "Hnsw": {
        "MaxConnections": 16,
        "EfConstruction": 200,
        "EfSearch": 50,
        "AutoSaveDelayMs": 5000
      }
    }
  }
}

Approximate O(log n).
Ideal for tens of thousands of chunks.

SQL Server DiskANN

CREATE TABLE [dbo].[chunk_embeddings] (
    chunk_id NVARCHAR(255) PRIMARY KEY,
    embedding VECTOR(1536) NOT NULL
);

CREATE VECTOR INDEX vec_idx_chunk_embeddings
ON [dbo].[chunk_embeddings](embedding)
WITH (metric = 'cosine');

Supported metrics:

cosine
euclidean
dotproduct

Document Processing

Supported Formats

Format	Reader	Notes
.pdf	PdfPig	Native text only (no OCR)
.docx	NPOI	Modern .docx only
.md	Markdown reader	Preserves syntax
.txt	Plain text	UTF-8
.html, .json, .xml, .csv	Fallback UTF-8	Raw extraction

Chunking

{
  "LocalDocs": {
    "Chunking": {
      "MaxChunkSize": 3000,
      "OverlapSize": 300
    }
  }
}

Chunk IDs follow the format:

{DocumentId}_chunk_{index}

Document Versioning

Old version marked IsSuperseded = true
Old chunks removed from search
Full history preserved
Version chain visible in UI

No silent history loss.

The Blazor Web UI

Built with:

Blazor Server
MudBlazor

Features

Dashboard

Total projects
Total documents
Storage usage

Project Management

Drag-and-drop multi-file upload
Inline Markdown editor ("Add Know How")
Version history navigation
Edit, delete, download

MCP Config Page

Generates ready-to-use MCP config snippet

API Token Management

Named Bearer tokens
Optional expiry
Tokens shown once
Revocable anytime

MCP: Let Your AI Navigate Your Knowledge Base

Exposes 10 MCP tools.

Tool	Description
search_docs	Semantic search
add_document	Add new document
update_document	Create new version
get_document_content	Full extracted text
list_projects	List projects
create_project	Create project
get_project	Project details
delete_project	Delete project
list_documents	List documents
get_document	Metadata + preview
delete_document	Delete document

Connecting Claude Code / OpenCode

.claude/mcp.json:

{
  "mcpServers": {
    "local-docs": {
      "type": "http",
      "url": "http://localhost:5024/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

UI vs MCP

Task	Best Via
Initial setup	Web UI
Bulk upload	Web UI
Version review	Web UI
Token management	Web UI
Inline authoring	Web UI
Semantic search	MCP
AI-driven updates	MCP
Programmatic ingestion	MCP

Configuration Reference

Production with Ollama + HNSW

{
  "ConnectionStrings": {
    "LocalDocs": "Data Source=localdocs.db"
  },
  "LocalDocs": {
    "Authentication": {
      "Username": "admin",
      "Password": "your-secure-password"
    },
    "Mcp": {
      "RequireAuthentication": true
    },
    "Embeddings": {
      "Provider": "Ollama",
      "Dimension": 768,
      "Ollama": {
        "Endpoint": "http://localhost:11434",
        "Model": "nomic-embed-text"
      }
    },
    "Storage": {
      "Provider": "SqliteHnsw"
    }
  }
}

Environment variables supported:

OPENAI_API_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_API_KEY
AZURE_STORAGE_CONNECTION_STRING

Key Packages

Package	Purpose
Microsoft.SemanticKernel	AI orchestration
Microsoft.Extensions.AI	Embedding abstraction
ModelContextProtocol.AspNetCore	MCP server
EF Core	Persistence
MudBlazor	UI
PdfPig	PDF extraction
NPOI	Word extraction
Azure.Storage.Blobs	Blob storage
Serilog	Logging
xunit + NSubstitute	Testing

Contributing

Open source and actively developed.

Contributions welcome:

New embedding providers
Storage backends
Document readers
MCP tools

Repository:

https://github.com/markjackmilian/mjm.local.docs

Conclusion

mjm.local.docs fills a growing gap in AI-assisted development:

Your AI assistant needs access to your knowledge, not just your code.

By combining:

A Blazor UI for humans
A full MCP server for AI

It bridges your team's accumulated knowledge with your AI tools — fully local if you choose.

Give it a try.
Star the repo.
Open a PR.

If you found this article helpful, follow me on GitHub, Twitter, and Bluesky.

Thanks for reading!

From Zero to Scheduled: TickerQ for .NET

Mark Jack — Fri, 04 Jul 2025 11:05:17 +0000

🔧 Introducing TickerQ – A Modern .NET Scheduler

As a .NET dev who’s tried just about every job scheduler out there, I wanted to share why TickerQ has quickly become my go-to. It’s fast, clean, and built with devs in mind. Here’s a quick dive into what it offers and how to get started.

TickerQ is a high-performance, reflection‑free background task scheduler for .NET. It leverages source generators, offers cron and time‑based execution, supports EF Core persistence, and includes a real-time dashboard UI—all with minimal overhead.

Key features include:

Source‑generator discovery (no reflection)
TimeTickers (one-time) and CronTickers (recurring)
EF Core integration for persistence of jobs, states, and history
Dashboard UI built with SignalR and Tailwind (Vue.js-based)
Retry policies, throttling, cooldowns
Distributed coordination, priorities, DI support

🚀 Installing & Configuring

Use the following NuGet packages. While only the core TickerQ package is required, in this example we will also set up optional packages for EF Core persistence and the real-time dashboard:

dotnet add package TickerQ
dotnet add package TickerQ.EntityFrameworkCore
dotnet add package TickerQ.Dashboard

In `Program.cs`

builder.Services.AddTickerQ(options =>
{
    options.SetMaxConcurrency(4);
    options.SetExceptionHandler<MyExceptionHandler>();
    options.AddOperationalStore<MyDbContext>(efOpt =>
    {
        efOpt.UseModelCustomizerForMigrations(); // Design-time migrations only
        efOpt.CancelMissedTickersOnApplicationRestart();
    });
    options.AddDashboard(basePath: "/tickerq-dashboard");
    options.AddDashboardBasicAuth();
});

app.UseTickerQ();

🎯 Defining and Scheduling Jobs

TickerQ uses a [TickerFunction] attribute and compile‑time source generation. You can define multiple scheduled functions with different triggers:

[TickerFunction("CleanupLogs")]
public static async Task CleanupLogs(TickerRequest req, CancellationToken ct)
{
    // Do cleanup work...
}

[TickerFunction("CleanupTempFiles","0 */6 * * *")]
public static Task CleanupTempFiles(TickerRequest req, CancellationToken ct)
{
    Console.WriteLine("Cleaning temporary files...");
    return Task.CompletedTask;
}

▶️ TimeTicker example (one‑off or delayed)

await timeTickerManager.AddAsync(new TimeTicker
{
  Function = "SendWelcomeEmail",
  Request = new { UserId = 123 },
  RunAt = DateTime.UtcNow.AddMinutes(5),
  Retries = 3,
  RetryIntervals = new[] { 60, 120, 300 }
});

🔁 CronTicker example (recurring)

await cronTickerManager.AddAsync(new CronTicker
{
  Function = "CleanupLogs",
  CronExpression = "0 */6 * * *",
  Retries = 2,
  RetryIntervals = new[] { 60, 300 }
});

🗔️ Persistence with EF Core

To enable persistence, you'll need to create the necessary tables using EF Core migrations.

TickerQ’s EF Core provider persists tickers, execution history, and job states into your DbContext.

There are two integration methods:

Using UseModelCustomizerForMigrations(): Best for projects that want to avoid cluttering their DbContext class with extra config. This approach automatically wires in the schema only during EF Core design-time operations (e.g., dotnet ef migrations add). At runtime, it won't interfere with your model.
Manual configuration: Required if you want full control or need schema visibility in your runtime model. This requires directly applying the necessary configurations in your OnModelCreating method.

protected override void OnModelCreating(ModelBuilder builder)
{
    base.OnModelCreating(builder);
    builder.ApplyConfiguration(new TimeTickerConfigurations());
    builder.ApplyConfiguration(new CronTickerConfigurations());
    builder.ApplyConfiguration(new CronTickerOccurrenceConfigurations());
}

Apply migrations:

dotnet ef migrations add AddTickerQTables
dotnet ef database update

🌐 Dashboard UI & Real‑Time Monitoring

The TickerQ Dashboard is a modern Vue.js-based web UI powered by SignalR and Tailwind CSS. It provides live updates and comprehensive control over job scheduling and monitoring.

Setup

builder.Services.AddTickerQ(opt =>
{
    opt.AddOperationalStore<MyDbContext>();
    opt.SetInstanceIdentifier("MyAppTickerQ");
    opt.AddDashboard(basePath: "/tickerq-dashboard");
    opt.AddDashboardBasicAuth();
});

app.UseTickerQDashboard();

Add credentials in appsettings.json:

"TickerQBasicAuth": {
  "Username": "admin",
  "Password": "admin"
}

Features

System Overview: throughput, active nodes, concurrency.
Job Status Breakdown: Done, DueDone, Failed, Pending.
CronTickers View: timeline, manual trigger, duplication, deletion.
TimeTickers View: execution history, live retry/cancel/edit/delete options.
Add/Edit Job: intuitive UI to define function, payload, retry policy.

🔐 Distributed Locking via EF Core

To safely run TickerQ across multiple nodes—without overlapping job executions—TickerQ uses EF Core-based distributed locking.

How It Works

A node picks up a job and marks itself as OwnerNode in the database.
Row-level locking (e.g., SELECT ... FOR UPDATE) ensures mutual exclusion.
Failed jobs release locks automatically, enabling retry by others.
Cooldowns and expiry provide safety against zombie tasks.

builder.Services.AddTickerQ(options =>
{
  options.AddOperationalStore<MyDbContext>(efOpt =>
  {
    efOpt.CancelMissedTickersOnApplicationRestart();
  });
});

What You Get

Feature	Description
Single ownership	Only one node can process a job at a time
Failover safety	Locks are released on restart or timeout
Coordination simplicity	No external lock store needed
EF Core-friendly	Leverages your existing DB and transaction logic

Use this if you scale horizontally and want safe, DB-driven coordination. For very high throughput or cross-cluster workloads, consider Redis or Zookeeper.

⚖️ How TickerQ Stacks Up

Compared to classic schedulers like Hangfire or Quartz.NET:

Feature	TickerQ	Hangfire	Quartz.NET
Reflection-free	✅ source gen	❌ reflection	❌ reflection
Time + cron jobs	✅ both	✅ cron, limited delayed	✅ both
EF Core persistence	✅ built-in	✅	✅
Dashboard UI	✅ real-time first-party	⚠️ basic	⚠️ third-party UI req'd
Retries & cooldowns	✅ advanced	⚠️ basic	⚠️ manual config req'd
Distributed locking	✅ via EF Core	⚠️ partial	✅
DI support	✅ native	⚠️ type-based limited	⚠️ manual config
Performance	✅ low overhead	⚠️ storage-bound	⚠️ thread-blocking

✅ When to Choose TickerQ

Choose TickerQ if you:

Prefer compile-time safety over runtime reflection
Need a lightweight, fast scheduler
Want cron and time jobs with retries/cooldowns
Use EF Core or need distributed coordination
Value a first-party, real-time dashboard

Limitations to Consider

No Redis or distributed cache persistence (yet)
No node-specific routing or tag-based job targeting
Throttling and job chaining features are in progress

🔺 Conclusion

TickerQ offers a modern, efficient, and developer-friendly background scheduler featuring:

Reflection-free architecture via source generation
Cron and time-based scheduling
Robust EF Core persistence
Real-time dashboard with live updates

It's especially suitable for applications that care about performance, visibility, and maintainability. For deeper dives, visit the official docs and check out the benchmarks on Medium.

If you found this article helpful, follow me on GitHub, Twitter and Bluesky.

Thanks for reading!

[Boost]

Mark Jack — Sat, 24 May 2025 13:03:30 +0000

Mark Jack

May 24 '25

Who’s Afraid of the Liskov Substitution Principle?

#designpatterns #dotnet #cleancode #oop

Comments

4 min read

Who’s Afraid of the Liskov Substitution Principle?

Mark Jack — Sat, 24 May 2025 13:03:03 +0000

Let Φ(x) be a property provable about objects x of type T. Then Φ(y) should be true for objects y of type S where S is a subtype of T.

Okay... this could be scary. Let's make it simpler.

The Liskov Substitution Principle (LSP) is one of the five SOLID principles of object-oriented programming. Often overlooked or misunderstood, it’s actually fundamental for writing maintainable, extensible, and truly “object-oriented” code.

What is the Liskov Substitution Principle?

Formulated by Barbara Liskov in 1987, the principle states:

“If S is a subtype of T, then objects of type T may be replaced with objects of type S without altering any of the desirable properties of that program (correctness, task performed, etc.).”

Put simply: a subclass should be usable anywhere its superclass is expected, without causing unexpected behaviors. If this doesn’t happen, inheritance is being misused.

Why is it important?

Violating the Liskov Substitution Principle leads to bugs that are hard to find, fragile code, and systems that are difficult to evolve. Respecting LSP, instead, lets you fully leverage the power of polymorphism.

A Bad Example in C#
Let’s try modeling rectangles and squares:

public class Rectangle
{
    public virtual int Width { get; set; }
    public virtual int Height { get; set; }
    public int Area()
    {
        return Width * Height;
    }
}

public class Square : Rectangle
{
    public override int Width
    {
        get { return base.Width; }
        set { base.Width = base.Height = value; }
    }
    public override int Height
    {
        get { return base.Height; }
        set { base.Width = base.Height = value; }
    }
}

At first glance, it seems reasonable: a square is just a special kind of rectangle, right? But let’s see what happens when we use these classes:

Rectangle rect = new Square();
rect.Width = 5;
rect.Height = 10;
Console.WriteLine(rect.Area()); // What do we expect?

You might expect 5×10=50, but the result will be 100!The Square class forces width and height to always be equal, breaking the expectations set by the Rectangle base class. This is a classic violation of the Liskov Substitution Principle.

Refactor: How to Respect the Principle

To respect the principle, avoid inheritance where it doesn’t make sense. Rectangle and Square are siblings, not parent/child. You can instead have them inherit from a common abstract base class:

public abstract class Shape
{
    public abstract int Area();
}

public class Rectangle : Shape
{
    public int Width { get; set; }
    public int Height { get; set; }
    public override int Area()
    {
        return Width * Height;
    }
}

public class Square : Shape
{
    public int Side { get; set; }
    public override int Area()
    {
        return Side * Side;
    }
}

Now you can use rectangles and squares polymorphically, with no unexpected behaviors:

Shape shape1 = new Rectangle { Width = 5, Height = 10 };
Shape shape2 = new Square { Side = 5 };
Console.WriteLine(shape1.Area()); // 50
Console.WriteLine(shape2.Area()); // 25

Ehi.. wait! But isn’t a square just a special type of rectangle?

From a mathematical perspective, yes: a square is a particular kind of rectangle (four right angles and all sides equal). So, conceptually, the relationship “Square is a Rectangle” seems to make sense.

However, in object-oriented programming (OOP), this relationship can cause practical problems. The issue isn’t mathematics, but rather behavior.

Why shouldn’t Square inherit from Rectangle in OOP?

When you create a subclass in OOP, the Liskov Substitution Principle requires that everything true for the base class must remain true for the subclass. In our example:

A Rectangle lets you set Width and Height independently.

A Square must always have Width == Height.

If you inherit, you’re forced into an awkward situation where changing Width in a Square also changes Height (and vice versa), since all sides must be equal. But this means the Square no longer behaves like a regular Rectangle!

When does inheritance make sense?

If the subclass does not alter the invariants or rules of the base class (i.e., it doesn’t change pre-conditions, post-conditions, or invariants), then yes, inheritance is fine.

Let's enhance the article with another practical example:

Bad example:

public class Bird
{
    public virtual void Fly()
    {
        Console.WriteLine("I'm flying!");
    }
}

public class Penguin : Bird
{
    // The Fly method is inherited, but it makes no sense for a penguin!
}

public class Program
{
    public static void MakeItFly(Bird bird)
    {
        bird.Fly();
    }

    public static void Main()
    {
        Bird tweety = new Bird();
        Penguin pingu = new Penguin();

        MakeItFly(tweety); // Output: I'm flying!
        MakeItFly(pingu);  // Output: I'm flying! (Semantic error)
    }
}

Good Example:

public abstract class Bird
{
    // All common properties
}

public class FlyingBird : Bird
{
    public virtual void Fly()
    {
        Console.WriteLine("I'm flying");
    }
}

public class Penguin : Bird
{

}

public class Sparrow : FlyingBird
{

}

public class Program
{
    public static void MakeItFly(FlyingBird bird)
    {
        bird.Fly();
    }

    public static void Main()
    {
        Sparrow sparrow = new Sparrow();
        Penguin pingu = new Penguin();

        MakeItFly(sparrow); // Output: I'm flying!
        // MakeItFly(pingu); // Compilation error! (GOOD!)
    }
}

Conclusions

The Liskov Substitution Principle isn’t just theory: ignoring it makes code fragile and unpredictable. When modeling class hierarchies, always ask yourself: “Can I substitute the base class with the subclass without breaking anything?” If the answer is no, you’re probably heading for design trouble.

If you found this article helpful follow me on GitHub, Twitter and Bluesky for more content.

Thanks for reading!

YASA - Yet another S.O.L.I.D. article

Mark Jack — Sun, 11 May 2025 17:24:49 +0000

Understanding SOLID Principles in .NET: Write Better, Scalable, and Maintainable Code

The SOLID principles are the cornerstone of good software design. Whether you're building small applications or large enterprise systems in .NET, applying these principles can help you write code that is easier to understand, maintain, and extend.

In this article, we'll explore each of the SOLID principles with practical C# examples in the .NET ecosystem.

🧱 What is SOLID?

SOLID is an acronym for five object-oriented design principles:

S – Single Responsibility Principle
O – Open/Closed Principle
L – Liskov Substitution Principle
I – Interface Segregation Principle
D – Dependency Inversion Principle

These principles were introduced by Robert C. Martin and have become a standard for writing clean and maintainable software.

1. Single Responsibility Principle (SRP)

"A class should have only one reason to change."

This means that a class should only have one job or responsibility.

❌ Bad Example

public class Invoice
{
    public void CalculateTotal() { /* ... */ }
    public void SaveToDatabase() { /* ... */ }
    public void PrintInvoice() { /* ... */ }
}

Here, Invoice is doing too much — it calculates, persists data, and handles printing.

✅ Good Example

public class InvoiceCalculator
{
    public void CalculateTotal() { /* ... */ }
}

public class InvoiceRepository
{
    public void SaveToDatabase() { /* ... */ }
}

public class InvoicePrinter
{
    public void PrintInvoice() { /* ... */ }
}

Each class now has a single responsibility.

2. Open/Closed Principle (OCP)

"Software entities should be open for extension, but closed for modification."

This principle promotes the use of abstractions so that the behavior of a module can be extended without modifying its source code.

❌ Bad Example

public class Discount
{
    public double CalculateDiscount(string customerType)
    {
        if (customerType == "Regular") return 0.1;
        if (customerType == "Premium") return 0.2;
        return 0;
    }
}

✅ Good Example

public interface IDiscountStrategy
{
    double GetDiscount();
}

public class RegularCustomerDiscount : IDiscountStrategy
{
    public double GetDiscount() => 0.1;
}

public class PremiumCustomerDiscount : IDiscountStrategy
{
    public double GetDiscount() => 0.2;
}

Now you can add new strategies without modifying existing code.

3. Liskov Substitution Principle (LSP)

"Derived classes must be substitutable for their base classes."

This principle asserts that objects of a superclass should be replaceable with objects of its subclasses without altering the correctness of the program. In simpler terms, subclasses should enhance, not weaken or break, the behavior promised by the base class.

Violating LSP often introduces unexpected behavior, especially in polymorphic code, and can lead to fragile systems.

❌ Bad Example

public class Bird
{
    public virtual void Fly() { /* default flying logic */ }
}

public class Ostrich : Bird
{
    public override void Fly()
    {
        throw new NotImplementedException();
    }
}

In this example, Ostrich inherits from Bird and overrides the Fly method by throwing an exception. This violates LSP because any code that expects a Bird to fly safely might crash or behave incorrectly when passed an Ostrich.

✅ Better Design

public interface IBird { }

public interface IFlyingBird : IBird
{
    void Fly();
}

public class Sparrow : IFlyingBird
{
    public void Fly() { /* flying logic */ }
}

public class Ostrich : IBird
{
    // No Fly method; ostriches do not fly
}

This approach respects LSP by not requiring Ostrich to implement functionality it does not possess. Clients depending on IFlyingBird know all implementations can fly, while those dealing with general IBird don't make assumptions about flying.

🧠 Key Takeaways

Avoid forcing subclasses to override or disable base class functionality.
Design with appropriate abstractions that reflect real capabilities.
Ensure derived classes honor the expectations set by the base class.

By following LSP, you ensure that components remain interchangeable, reducing bugs and making your code more robust and extensible.

4. Interface Segregation Principle (ISP)

"Clients should not be forced to depend on interfaces they do not use."

❌ Bad Example

public interface IWorker
{
    void Work();
    void Eat();
}

public class Robot : IWorker
{
    public void Work() { /* ... */ }
    public void Eat() => throw new NotImplementedException();
}

✅ Good Example

public interface IWorkable
{
    void Work();
}

public interface IEatable
{
    void Eat();
}

public class Human : IWorkable, IEatable
{
    public void Work() { /* ... */ }
    public void Eat() { /* ... */ }
}

public class Robot : IWorkable
{
    public void Work() { /* ... */ }
}

Separate interfaces make code more flexible.

5. Dependency Inversion Principle (DIP)

"Depend on abstractions, not on concretions."

High-level modules should not depend on low-level modules. Both should depend on abstractions.

❌ Bad Example

public class EmailService
{
    public void SendEmail(string message) { /* ... */ }
}

public class Notification
{
    private EmailService _emailService = new EmailService();
    public void Send(string message)
    {
        _emailService.SendEmail(message);
    }
}

✅ Good Example

public interface IMessageService
{
    void Send(string message);
}

public class EmailService : IMessageService
{
    public void Send(string message) { /* ... */ }
}

public class Notification
{
    private readonly IMessageService _messageService;

    public Notification(IMessageService messageService)
    {
        _messageService = messageService;
    }

    public void Notify(string message)
    {
        _messageService.Send(message);
    }
}

Now Notification is not tightly coupled to EmailService.

✅ Final Thoughts

Applying the SOLID principles in .NET helps you build:

Modular and testable components
Easier-to-understand codebases
Scalable applications ready for change

While not every class needs to follow all principles strictly, being mindful of SOLID will gradually elevate the quality of your code.

If you found this article helpful follow me on GitHub, Twitter and Bluesky for more content.

Thanks for reading!

b-state behaviours and processors

Mark Jack — Sun, 11 May 2025 09:39:14 +0000

A clean, composable way to handle cross-cutting concerns in Blazor with BState

In the previous article, I introduced B-State, a lightweight and elegant state management library designed for Blazor. We looked at how B-State treats actions as first-class citizens and how dispatching them affects state updates predictably.

Now, let’s explore how B-State allows us to structure cross-cutting concerns like logging, exception handling, or validation using a pipeline of behaviours and processors.

🧱 The Pipeline Architecture

In B-State, actions flow through a processing pipeline that supports:

Behaviours
Preprocessors
Postprocessors

This architecture is inspired by the middleware pattern commonly seen in ASP.NET Core and MediatR, but tailored to the Blazor component model and optimized for state flow.

The goal is to decouple concerns such as logging, validation, or side-effects from the core business logic, contributing to a clean, maintainable architecture.

Let’s break it down.

🔁 Behaviours

Behaviours are like middleware. They wrap around the action execution and have full control over what happens before and after the action handler runs.

Here’s a logging behaviour:

class LogBehaviour : IBehaviour
{
    public async Task Run(IAction parameter, Func<IAction, Task> next)
    {
        Console.WriteLine($"{parameter.GetType().Name} started");
        await next(parameter);
        Console.WriteLine($"{parameter.GetType().Name} ended");
    }
}

Behaviours are global. They are registered once and wrap every action unless filtered internally.

⏮️ Preprocessors

Preprocessors run before the action handler is invoked.
Example: A global preprocessor for all actions:

class AllRequestPreprocessor<TAction> : IPreProcessor<TAction>
where TAction : IAction
{
    public Task Run(IAction parameter)
    {
        Console.WriteLine("AllRequestPreprocessor");
        return Task.CompletedTask;
    }
}

You can also conditionally execute preprocessors based on action interfaces. For example, if you tag long-running operations with ILongAction:

// Marker interface
public interface ILongAction { }

class ALongActionPreProcessor<TRequest> : IPreProcessor<TRequest>
where TRequest : ILongAction
{
    public Task Run(IAction parameter)
    {
        Console.WriteLine("This is a long action... please wait!");
        return Task.CompletedTask;
    }
}

This preprocessor is activated only when IAction implements ILongAction. This feature provides great flexibility when building the pipeline to manage your requests.

⏭️ Postprocessors

Postprocessors work exactly like preprocessors, but are executed after the action handler runs. Use them for tasks like:

Cleanup
Logging results
Updating external systems

To implement one:

class MyPostProcessor<TAction> : IPostProcessor<TAction>
where TAction : IAction
{
    public Task Run(IAction parameter)
    {
        Console.WriteLine("Action completed.");
        return Task.CompletedTask;
    }
}

🧩 Putting It Together

builder.Services.AddBState(configuration =>
{
    configuration.RegisterFrom(Assembly.GetExecutingAssembly());

    configuration.AddBehaviour<ExceptionBehaviour>();
    configuration.AddBehaviour<LogBehaviour>();

    configuration.AddOpenRequestPreProcessor(typeof(AllRequestPreprocessor<>));
    configuration.AddOpenRequestPreProcessor(typeof(ALongActionPreProcessor<>));
    // configuration.AddOpenRequestPostProcessor(typeof(MyPostProcessor<>));
});

With behaviours, preprocessors, and postprocessors, B-State introduces a powerful yet elegantly simple pipeline model for handling cross-cutting concerns in Blazor applications. Instead of embedding logging, error handling, loading indicators, or validation logic directly into your components or action handlers, you delegate them to modular units that wrap or surround the core logic. This keeps your actions focused on business rules, while the supporting concerns remain isolated, reusable, and composable.

The key principle here is composability. Each behaviour or processor is independently testable, context-agnostic, and easily replaceable, enabling teams to iterate faster without fear of regressions or side effects. Whether you’re building large enterprise applications or small Blazor components, this structure brings clarity, separation of concerns, and scalability.

B-State’s pipeline architecture provides more than just state management — it offers a clean, extensible framework to handle the complexities that naturally emerge as your application grows. By leveraging behaviours and processors, you gain precise control over how actions are prepared, executed, and handled, while keeping your application logic lean and expressive.

For a repo example of this tutorial see HERE, for a more complete example HERE
If you found this article helpful, leave a ⭐️ on the library’s repository on GitHub and follow me on GitHub, Twitter and Bluesky for more content.

Thanks for reading!

b-state Blazor state manager

Mark Jack — Tue, 06 May 2025 10:31:28 +0000

When building modern web applications, managing state efficiently becomes crucial. In Blazor, as in other front-end frameworks, state management is key to ensuring that UI updates are predictable, scalable, and easy to maintain. That’s where b.state comes in — a lightweight, pipeline-based state manager designed specifically for Blazor applications.
b.state introduces a fresh, structured approach to handling state by organizing the flow of state changes through a customizable pipeline architecture. This design not only improves clarity and modularity but also enables the use of middleware, allowing developers to inject logic (such as logging, validation, or side-effects) at different stages of the state update process.

If you’re familiar with the Flux pattern (or Redux in the React ecosystem), you’ll find many familiar concepts in b.state, adapted to the Blazor architecture. Both follow a unidirectional data flow and rely on actions to describe state changes. In the table below, you can see a side-by-side comparison to help map concepts between the two approaches.

In this article, we’ll dive into how b.state works, why a pipeline-based model makes sense for state management, and how you can integrate middleware to build more robust and maintainable Blazor applications.

b-state Github Repo

In this introductory tutorial, we’ll replace the default Counter page from the Blazor template using BState. Let’s begin by creating a new Blazor WebAssembly project and adding the following NuGet package:

dotnet add package b-state

In your Program.cs add a basic bstate startup (an advanced setup will be shown in the next story):

builder.Services.AddBState(configuration =>
{
    configuration.RegisterFrom(typeof(Program).Assembly);
});

The RegisterFrom method ensure that all Actions and States are automatically registered into application services.
Create a new state called CounterState:

public partial class CounterState(IActionBus actionChannel) : BState(actionChannel)
{
    public int Counter { get; private set; } = 100;
}

Thanks to the bstate.analyzer project, your IDE will show any discrepancies from project conventions as warnings:

Setters must be private inside bstate derived classes
IAction implementation must be subclasses of a bstate class

The next step is to define the Actions that can modify the CounterState, to do this, I added a CounterState.Actions.cs file with the partial class that contains all the state edit actions, in this case the only possible action is Add

public partial class CounterState
{
    record AddAction : IAction;
}

Now it’s time to create the action that will modify the state, i created a new file called CounterState.AddAction.cs:

public partial class CounterState
{
    class AddActionHandler(CounterState counterState) : IActionHandler<AddAction>
    {
        public Task Execute(AddAction request)
        {
            counterState.Counter++;
            return Task.CompletedTask;
        }
    }

    public Task Add() => this.ActionChannel.Send(new AddAction());
}

I implemented IActionHandler as a private class, incrementing the counter in the Execute method.
I also added a public Add() method that internally sends the AddAction.

bstate pipeline flow

When an IAction is executed through the ActionChannel, a pipeline is built to correctly manage the action.
Several elements are added to this pipeline: behaviors (which we will cover next time), preprocessors (also covered next time), the action executor (IActionHandler), and post-processors (which we will discuss later as well).
Once the pipeline execution is complete, a notification process is triggered to inform all components that use the part of the state affected by the action.

bstate component

Now, for the final step of this tutorial, we will create the component.
The component should inherit from BStateComponent and access one or more states by using the UseState method.
This will allow the component to automatically react to any changes in the state and update itself accordingly.

@using bstate.tutorial.Features.Counter
@inherits bstate.core.Components.BStateComponent

<p role="status">Current count: @State.Counter</p>

<button class="btn btn-primary" @onclick="Increment">Click me</button>

@code {
    CounterState State => this.UseState<CounterState>();
    Task Increment() => this.State.Add();
}

This tutorial is just the first step in introducing how to implement state management using BState in a Blazor application.
In the next parts, we will explore more advanced topics, such as how to use behaviors, processors, and lifecycle extensions to further enhance the capabilities and flexibility of your components.

Thanks for reading!

DEV Community: Mark Jack

mjm.local.docs: Open Source Local Knowledge Base with MCP

The Problem

What Is mjm.local.docs?

Clean Architecture

Deploy Locally in Minutes

Pluggable Embedding Providers

Running 100% Locally with Ollama

Storage Options: From SQLite to SQL Server

Vector Search Under the Hood

Brute-Force (SQLite)

HNSW (SqliteHnsw)

SQL Server DiskANN

Document Processing

Supported Formats

Chunking

Document Versioning

The Blazor Web UI

Features

MCP: Let Your AI Navigate Your Knowledge Base

Connecting Claude Code / OpenCode

UI vs MCP

Configuration Reference

Production with Ollama + HNSW

Key Packages

Contributing

Conclusion

From Zero to Scheduled: TickerQ for .NET

🔧 Introducing TickerQ – A Modern .NET Scheduler

🚀 Installing & Configuring

In Program.cs

🎯 Defining and Scheduling Jobs

▶️ TimeTicker example (one‑off or delayed)

🔁 CronTicker example (recurring)

🗔️ Persistence with EF Core

🌐 Dashboard UI & Real‑Time Monitoring

Setup

Features

🔐 Distributed Locking via EF Core

How It Works

What You Get

⚖️ How TickerQ Stacks Up

✅ When to Choose TickerQ

Limitations to Consider

🔺 Conclusion

[Boost]

Who’s Afraid of the Liskov Substitution Principle?

Who’s Afraid of the Liskov Substitution Principle?

YASA - Yet another S.O.L.I.D. article

Understanding SOLID Principles in .NET: Write Better, Scalable, and Maintainable Code

🧱 What is SOLID?

1. Single Responsibility Principle (SRP)

❌ Bad Example

✅ Good Example

2. Open/Closed Principle (OCP)

❌ Bad Example

✅ Good Example

3. Liskov Substitution Principle (LSP)

❌ Bad Example

✅ Better Design

🧠 Key Takeaways

4. Interface Segregation Principle (ISP)

❌ Bad Example

✅ Good Example

5. Dependency Inversion Principle (DIP)

❌ Bad Example

✅ Good Example

✅ Final Thoughts

b-state behaviours and processors

b-state Blazor state manager

In `Program.cs`