Improve this page

Prague

Prague is a compile-time-safe, in-memory event cache for .NET (net9.0 and net10.0). You annotate a partial POCO with [DataCache], [DataCacheKey], [DataCacheIndex] and [DataCacheForeignKey<T>]; a Roslyn source generator emits a typed cache with secondary indices, a fluent query API that the compiler checks, foreign-key joins, and prepared queries that plan once and execute at zero allocations. Prague.Kafka keeps those caches hydrated from compacted Kafka topics inside your process. No network hop, no reflection, no eviction.

Every C# block on this site is pulled from the compiled samples project and runs as a test, so what you read is what compiles against the current release.

Start here

• Introduction — what Prague is and is not, and how data flows from a topic into a queryable cache.
• Installation — packages, project setup, platform requirements.
• Quick Start — a working cache in three steps.
• Tutorial: Build an Order Service — thirty minutes from annotated POCOs to an HTTP service that queries, joins and pages orders out of Kafka-fed caches, reacts to live shipments and reports health.

Core concepts

• Index Types — Unique, Many, Range, symmetric variants and predicate key-set indices, and what each costs.
• Query Engine — WithXxx lanes, intersection, Or, Where, pooled versus allocating execution.
• Sorted Paging — Sort versus SortBounded: which plan to pick for a page and why ties matter.
• Prepared and Frozen Queries — Prepare()…Build() and BuildFrozen(): describe once, plan once, execute at 0 B.
• Conditional Updates — how CacheEquals decides the UpdateType your handlers see.
• Joins — JoinWith{Other} and InnerJoinWith{Other} across foreign keys, 1:1 and 1:N, chained.

How-to guides

Task-shaped pages: a prerequisite, the steps, the pitfalls.

• Page an API — a sorted, paged list endpoint with offset or cursor pages.
• Incremental Sync — send only what changed since a client's watermark.
• Write a Filter — header, key and value filters; soft deletes; predicates with DI state.
• React to Changes — ICacheAfterHandler and every UpdateType.
• Host with DI — registration, options binding, topic placeholders, several clusters, clean shutdown.
• Inspect over HTTP — Prague.Api endpoints and query-string syntax.
• Map, Clone, Batch — project results, copy rows, read many keys at once.
• Test without a Broker — unit-test code that reads caches.
• Health and Metrics — liveness, readiness and the OpenTelemetry meter.

Kafka and operations

• Kafka Integration — topic settings, wiring caches to topics, filters, after-handlers, producer, health, OpenTelemetry.
• Global Last Update Index — cross-cache change tracking.
• Performance Tuning — hot-path guidance.

Explanation

• How Prague Works — attributes → generated code → store and indices → planning → the three frozen executors → pooled results, with the allocation table.
• The Concurrency Contract — one writer, lock-free readers: what a query can observe mid-write and what is safe to share.
• Ordering and Determinism — when the row order is a promise and when it is only a mechanism.

Reference

• Attributes and Generated Code — every attribute, its parameters and defaults, and exactly what the generator emits.
• Generator Diagnostics — every CACHExxx diagnostic with an example and a fix.
• Benchmarks — the latest measured numbers per benchmark family, traced to the log.
• Release Notes — every release, newest first.
• API browser — generated from the XML doc comments of Prague, Prague.Core, Prague.Kafka, Prague.Attributes and Prague.Codegen.

Elsewhere

• GitHub repository — source, issues, contributing.
• NuGet — Prague, Prague.Kafka, Prague.Api, Prague.Api.UI.
• llms.txt and llms-full.txt — machine-readable summaries for coding assistants.