![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_198/workflow-overview.png\")
\n ASP.NET Core request timeouts can be configured globally or per endpoint with the built-in middleware in .NET 8 and later.\nThe middleware uses cooperative cancellation, so downstream work must observe HttpContext.RequestAborted.
ASP.NET Core does not apply an application timeout to incoming requests by default.\nThe built-in request timeout middleware adds a deadline, but it only cancels HttpContext.RequestAborted.\nYour endpoint must pass that token into the work you want to stop.
A reverse proxy might return its own timeout first, but then it controls the deadline and response instead of your application.
\nA slow database query or stalled API call can keep consuming resources after its response is no longer useful.\n.NET 8 introduced request timeout middleware to give request processing a cooperative deadline.
\nLet's wire it up.
\nRegister the middleware and apply a three-second timeout in Program.cs:
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddRequestTimeouts();\n\nvar app = builder.Build();\n\napp.UseRequestTimeouts();\n\napp.MapGet("/reports", async (\n CancellationToken cancellationToken) =>\n{\n await Task.Delay(\n TimeSpan.FromSeconds(10),\n cancellationToken);\n\n return Results.Ok("Ready");\n})\n.WithRequestTimeout(TimeSpan.FromSeconds(3));\n\napp.Run();\nAddRequestTimeouts only registers the required services.\nIt does not configure a limit by itself.
WithRequestTimeout gives this endpoint three seconds.\nMinimal APIs bind the CancellationToken parameter to HttpContext.RequestAborted.
After three seconds, Task.Delay observes cancellation and throws.\nIf that exception reaches the middleware before the response starts, the default response is an empty 504 Gateway Timeout.
Test this without an attached debugger because the timeout does not trigger while a debugger is attached.
\nThe middleware does not abort a thread or call HttpContext.Abort().\nIt cancels a token and keeps waiting for the endpoint.
Remove cancellationToken from the Task.Delay call above and the handler waits the full ten seconds before returning 200 OK.\nThere is no immediate 504 because no cancellation exception reaches the middleware.
A trace-style span waterfall makes the difference visible:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_209/timeout_trace_waterfall.png\")
\nThe same rule applies to real dependencies.\nPass the token through your application service and into EF Core:
\npublic Task<Order?> GetByIdAsync(\n Guid id,\n CancellationToken cancellationToken)\n{\n return dbContext.Orders\n .AsNoTracking()\n .SingleOrDefaultAsync(\n order => order.Id == id,\n cancellationToken);\n}\nEF Core forwards the token to the database provider, which decides whether the operation can be canceled.\nThe token has to cross every boundary before the provider can see it:
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_209/cancellation_propagation.png\")
\nPass it into HttpClient, messaging clients, and other asynchronous work where abandoning the operation is safe.
\nThe same token is canceled when the client disconnects.\nFlowing it through the entire call chain matters even before you add a timeout.\nWhen a dependency honors cancellation, timed-out work stops instead of piling up under load.
\nNot every endpoint should share the same limit.\nA small API read and a report export have different latency budgets, so give them different policies.
\nReplace the parameterless registration with named policies, then attach each one when mapping the endpoint:
\nbuilder.Services.AddRequestTimeouts(options =>\n{\n options.AddPolicy("api-read", TimeSpan.FromSeconds(3));\n options.AddPolicy("report-export", TimeSpan.FromSeconds(30));\n});\n\napp.MapGet("/orders/{id:guid}", GetOrder)\n .WithRequestTimeout("api-read");\n\napp.MapGet("/reports/{id:guid}", ExportReport)\n .WithRequestTimeout("report-export");\n\napp.MapGet("/events", StreamEvents)\n .DisableRequestTimeout();\nSmall reads get three seconds, report exports get 30 seconds, and the streaming endpoint opts out.
\nServer-Sent Events, WebSockets, long polling, and large uploads usually need a longer policy or .DisableRequestTimeout().\nOnce a streaming response starts, the middleware cannot replace it with a clean 504.
If an operation genuinely needs minutes, return 202 Accepted and finish it in the background, as described in scaling long-running API requests.
A 504 from the middleware tells you that cancellation reached it.\nIt does not prove that every downstream operation stopped.
Start with one endpoint that calls EF Core or HttpClient.\nSet a realistic limit and force a slow call past it without a debugger attached.\nUse logs or a trace to verify that the dependency observed cancellation.
Thanks for reading.
\nAnd stay awesome!
\nA good SQL index comes from the queries your application runs, not from the table schema.\nComposite indexes need the right column order: equality columns first, then the column you sort or range on.\nEXPLAIN ANALYZE is how you verify it: a sequential scan over 1 million comments takes 17ms, and the right composite index answers in 0.04ms.
What does a good SQL index look like?
\nThe answer will vary based on your queries and access paths.\nThe only way to confidently know is to examine the query plans with EXPLAIN ANALYZE and figure out from there which index might help.
So let's do exactly that.\nI seeded a Postgres 18 instance in Docker with an issue tracker: 100 users, 10,000 issues, and 1 million comments.\nBy the end, one query drops from 436ms to half a millisecond.
\nAn index stores your chosen columns in sorted order, with every entry pointing back to its full row.\nThe default kind in every major database is the B-tree: a shallow tree, a few levels deep even at millions of rows.\nA sequential scan reads all 1 million comments; an index scan descends those few levels and fetches only the matches.
\n![\"Side](\"https://milanjovanovic.tech/blogs/mnw_208/seq_scan_vs_index_walk.png\")
\nYou don't pick indexes by staring at the schema; they come from the queries your application actually runs.
\nMy comments table serves three access patterns:
The first pattern, with no index beyond the primary key:
\nEXPLAIN ANALYZE\nSELECT COUNT(*)\nFROM comments\nWHERE user_id = 1;\n\n---\nFinalize Aggregate\n -> Gather\n -> Partial Aggregate\n -> Parallel Seq Scan on comments (actual time=0.010..11.727 rows=3356.67 loops=3)\n Filter: (user_id = 1)\n Rows Removed by Filter: 329977\nExecution Time: 17.066 ms\nEXPLAIN ANALYZE runs the query for real and prints the plan Postgres used: a Parallel Seq Scan reads all 1 million rows to count 10,070, in 17ms.
Create the index and rerun the query:
\nCREATE INDEX ix_comments_user_id\nON comments (user_id);\nAggregate\n -> Index Only Scan using ix_comments_user_id on comments (actual time=0.024..0.348 rows=10070.00 loops=1)\n Index Cond: (user_id = 1)\n Heap Fetches: 0\nExecution Time: 0.612 ms\n17ms down to 0.6ms.\nIt's an Index Only Scan because the index alone can answer a COUNT(*): Postgres never touches the table.
The third access pattern is the interesting one:
\nSELECT *\nFROM comments\nWHERE issue_id = 10\n AND user_id = 29\n AND created_at >= NOW() - INTERVAL '1 month'\nORDER BY created_at DESC;\nWith no index, it's another sequential scan: 16.6ms.\nWith single-column indexes on issue_id and user_id, Postgres intersects them with a BitmapAnd and still sorts the survivors: 0.6ms, in three steps.
A composite index answers the whole query in one motion:
\nCREATE INDEX ix_comments_issue_user_date\nON comments (issue_id, user_id, created_at DESC);\nIndex Scan using ix_comments_issue_user_date on comments (actual time=0.019..0.026 rows=2.00 loops=1)\n Index Cond: ((issue_id = 10) AND (user_id = 29) AND (created_at >= (now() - '1 mon'::interval)))\nExecution Time: 0.039 ms\nAll three conditions moved into the Index Cond, and the Sort is gone: the index already returns rows ordered by created_at DESC.\nRuntime: 0.04ms, over 400x faster.
A composite index sorts by its first column, then the second within equal values, then the third.\nPostgres jumps straight to the issue_id = 10, user_id = 29 section and reads it in order.
Column order also decides what else the index can serve: issue_id alone works, issue_id plus user_id works, but user_id alone doesn't (its values are scattered across the whole tree).\nThis is the leftmost prefix rule, and it's why the index on user_id stays.
The rule of thumb: equality columns first, then the column you sort or range on.
\nEvery issue tracker runs this dashboard query: the 25 newest open issues, each with its latest comment, fetched by a LATERAL subquery:
SELECT i.id, c.body, c.created_at\nFROM issues i\nCROSS JOIN LATERAL (\n SELECT body, created_at\n FROM comments\n WHERE issue_id = i.id\n ORDER BY created_at DESC\n LIMIT 1\n) c\nWHERE i.status = 'open'\nORDER BY i.created_at DESC\nLIMIT 25;\nNested Loop (actual time=0.790..352.076 rows=6537.00 loops=1)\n -> Seq Scan on issues i (rows=6537.00 loops=1)\n -> Limit (rows=1.00 loops=6537)\n -> Sort (actual time=0.053..0.053 rows=1.00 loops=6537)\n -> Bitmap Index Scan on ix_comments_issue_user_date (loops=6537)\nExecution Time: 435.794 ms\nThe composite index gets used, but its entries are sorted by user_id before created_at, so a Sort runs 6,537 times, once per open issue: 436ms.
Column order strikes again.\nFor this access path, created_at must come right after issue_id:
CREATE INDEX ix_comments_issue_date\nON comments (issue_id, created_at DESC);\nEach probe becomes a one-row index scan: 25ms.\nBut the LIMIT still can't stop the loop, because issues arrive unsorted.\nOne more index streams them newest-first:
CREATE INDEX ix_issues_status_date\nON issues (status, created_at DESC);\nLimit (actual time=0.086..0.465 rows=25.00 loops=1)\n -> Nested Loop (actual time=0.085..0.463 rows=25.00 loops=1)\n -> Index Scan using ix_issues_status_date on issues i (rows=25.00 loops=1)\n -> Limit (rows=1.00 loops=25)\n -> Index Scan using ix_comments_issue_date on comments (rows=1.00 loops=25)\nExecution Time: 0.489 ms\nEvery node reads only what it returns: 25 issues, 25 probes, one comment each.\n0.5ms, nearly 900x faster.
\nEvery insert, update, and delete now maintains every index, so each one you add slows writes a little.\nThey take disk space, too:
\nSELECT indexrelname AS index_name,\n pg_size_pretty(pg_relation_size(indexrelid)) AS size\nFROM pg_stat_user_indexes\nWHERE relname = 'comments';\nEach composite index weighs 30 MB for 1 million comments, against about 7 MB per single-column one.\nAnd (issue_id, created_at DESC) makes the plain issue_id index redundant, so drop it.\nIndex the queries you actually run, not the ones you might run someday.
An index only helps if the query can use it: wrap the indexed column in a function and Postgres ignores it, a failure mode I covered in Why Postgres Ignores Your Index.
\nLIMIT only helps when an index feeds it rows already in order.EXPLAIN ANALYZE is the proof. Read the plan, not just the timing.Once the indexes are right, cursor pagination is the natural next step, built on exactly these composite indexes.
\nThanks for reading.
\nAnd stay awesome!
\nA home feed starts as fan-out on read: query the posts of every account you follow, merge, sort, return a page.\nThat work moves to write time once reads outnumber writes, with workers appending post ids to a per-follower timeline cache.\nCelebrity accounts break that too, and hybrid fan-out merges their posts in at read time instead.
\nEvery social app has a home feed, and it looks like the easiest feature in the product.
\nFetch the recent posts from every account the user follows, merge them, sort by time, return the first page.\nYou could ship it in an afternoon.
\nFeeds are a classic system design problem because the obvious version does the work at read time, and the version that survives production does it at write time.\nLet's build one and watch where each version breaks.
\nThe naive feed computes everything at read time: fan-out on read.
\nThe feed is a query.\nWhen a user opens the app, the Feed API runs the merge live, against the posts of every account they follow.\nA user following 800 accounts turns one page view into an 800-way merge that runs before anything renders, and pull-to-refresh throws the result away and runs it again.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_207/feed_read_storm.png\")
\nTo be fair to the naive design: with a composite index on (author_id, created_at), that merge is a single query that returns in milliseconds, and it stays fine well past the point most products ever reach.\nIf your users follow a few hundred accounts and you serve hundreds of feed reads per second, ship the query and move on.
The problem is the ratio.\nTwitter published its numbers years ago: roughly 300,000 home timeline reads per second against about 5,000 new tweets.\nSixty reads for every write is the ratio that justifies moving the work to the write side.
\nBefore fixing reads, the write path needs one property: a single writer.
\nPublic traffic enters through an API gateway, and only the Post API writes the post store.\nThe gateway already handles authentication.\nWhat the single writer buys is one transactional boundary: committing a post and recording its event happen atomically, in commit order.
\nSplit posting across two services and you get two event streams with no shared order, where a delete can race ahead of the create it refers to.\nIt also gives your invariants one home.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_207/write_path.png\")
\nFan-out on write depends on this: every committed post produces exactly one event.
\nThe first fix most teams reach for is caching the merged page per user with a short TTL, and it does absorb repeat refreshes.\nBut a feed cache entry serves exactly one user, so the hit rate is only as good as how often that user reloads within the window, and every expiry brings back the full merge.\nFan-out on write is that cache with the timer removed: kept correct by writes instead of rebuilt on expiry, and populated for every follower whether or not they ever read.
\nWhen an author publishes a post:
\nThe Feed API serves a feed with one timeline lookup and a batched fetch to hydrate the ids into posts.\nScroll past the cap and the feed falls back to the query path.\nAlmost nobody does.
\n![\"An](\"https://milanjovanovic.tech/blogs/mnw_207/fan_out_on_write.png\")
\nFive decisions make this hold up in production:
\nThe tradeoff: eventual consistency.\nThe first user to notice is the author: they publish, refresh, and their own post is missing.
\nThe fix is read-your-own-writes at the feed edge: the Feed API merges the reader's own recent posts in at read time.\nFollowers seeing a post a few seconds late is the part nobody notices.
\nFan-out on write has a multiplier hiding in step 3: every publish costs one timeline write per follower.
\nFor an account with 300 followers, that's 300 small cache appends.\nCheap.
\nBut follower counts follow a power-law distribution.\nAn account with 50 million followers publishes once, and the workers now owe the cache 50 million writes.
\nThe 60-to-1 ratio justified paying per write because writes were rare and each append was cheap.\nA post that becomes 50 million appends, most of them into timelines nobody will open, breaks both premises.\nEven the expansion is heavy: 50 million follower rows paged out of the graph store just to know where to write.
\nWhile the workers grind through it, two things go wrong for everyone else:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_207/write_amplification.png\")
\nTwo mitigations come before a redesign.\nFan out only to followers who were active recently, and rebuild dormant timelines on their next visit (the disposable projection already paid for that path).\nRoute the biggest accounts to their own queue, so ordinary posts stop waiting behind them.
\nWhat neither does is shrink the work: the biggest accounts still owe millions of writes per post, and the cache pressure lands regardless.
\nNo single strategy serves both ends of a power-law distribution.
\nOrdinary authors keep fan-out on write.\nBounded follower sets make write-time work cheap, and reads stay one lookup.
\nCelebrity authors switch to a narrow form of fan-out on read.\nTheir posts are appended to a compact celebrity index, keyed by author, and publishing becomes one write regardless of follower count.
\nAt read time, the Feed API merges the user's materialized timeline with recent candidates from the celebrity indexes they follow, deduplicates, and hydrates.\nA follower-count threshold or cost model decides which path an author uses.
\n![\"Ordinary](\"https://milanjovanovic.tech/blogs/mnw_207/hybrid_feed.png\")
\nTwitter described this same architecture publicly years ago: home timelines materialized in Redis by fan-out workers, with the highest-follower accounts merged in at read time.
\nThe tradeoffs:
\nEverything so far assumes reverse-chronological order, which is the feed that Twitter talk describes.\nNone of the big networks ship that as the default anymore.
\nA ranked feed keeps the same plumbing and adds a funnel on the read path:
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_207/ranked_feed_funnel.png\")
\nWhen Twitter open-sourced its recommendation algorithm in 2023, this was the shape: roughly half the candidates in-network, half out-of-network, funneled through a light ranker into a neural "heavy ranker" that predicts engagement.
\nNone of it replaces the fan-out machinery.\nThe timeline you materialized is still there; it became one candidate source among several, and the merge became a scoring stage.
\nMost of this system is asynchronous, so operating it means watching lag rather than error rates.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_207/pipeline_metrics.png\")
\nThe whole progression:
\nIf you'd rather design this than read about it, I just launched System Design Studio on Katabench.\nYou wire components on a canvas, and a grader checks your topology, then explains what it can and cannot prove.
\nThe three challenges behind this article (the write path, timeline fan-out, celebrity fan-out) are free.\nStart with the celebrity fan-out, and hit reply if the grader disagrees with you.
\nThanks for reading.
\nAnd stay awesome!
\nEF Core does not need public setters or a public parameterless constructor.\nIt builds entities through a private constructor and reads and writes state through backing fields, so a fully encapsulated aggregate loads and saves like any other entity.\nStrongly typed IDs, private collections, value objects, and domain events are all handled in configuration classes the domain never references.
\nWhenever I write about refactoring an anemic domain model into a rich one, one objection reliably appears in the replies:
\n\n\nNice in theory, but EF Core needs public setters and a public parameterless constructor. The ORM forces the anemic model on us.
\n
It was true a decade ago.\nIt is not true now: EF Core will happily persist a fully encapsulated aggregate, and the payoff is a domain model that enforces its invariants in one place while the ORM quietly does its job.
\n![\"An](\"https://milanjovanovic.tech/blogs/mnw_206/anemic_vs_rich_aggregate.png\")
\nLet's map one aggregate end to end and hit every place where EF Core and encapsulation supposedly collide.
\nThe domain is home brewing, because order aggregates have been done to death.\nA Batch ferments, you take gravity readings, and once the gravity holds steady you bottle.\nBottle too early, while the yeast is still eating sugar, and you get bottle bombs.
Here's the Batch written the way I actually want it: no public setters, creation through a factory, and state changes that go through methods.
public sealed class Batch\n{\n private readonly List<FermentationReading> _readings = [];\n private readonly List<IDomainEvent> _domainEvents = [];\n private DateTime? _bottledAtUtc;\n\n private Batch() { } // For EF Core\n\n private Batch(BatchId id, RecipeId recipeId, Volume volume)\n {\n Id = id;\n RecipeId = recipeId;\n Volume = volume;\n Status = BatchStatus.Fermenting;\n }\n\n public BatchId Id { get; private set; }\n public RecipeId RecipeId { get; private set; }\n public BatchStatus Status { get; private set; }\n public Volume Volume { get; private set; }\n\n public IReadOnlyCollection<FermentationReading> Readings => _readings.AsReadOnly();\n public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents.AsReadOnly();\n\n public static Batch Start(RecipeId recipeId, Volume volume) =>\n new(new BatchId(Guid.CreateVersion7()), recipeId, volume);\n\n public void AddReading(Gravity gravity, DateTime takenAtUtc)\n {\n if (Status != BatchStatus.Fermenting)\n {\n throw new DomainException("Readings only make sense while the batch is fermenting.");\n }\n\n _readings.Add(new FermentationReading(gravity, takenAtUtc));\n }\n\n public void Bottle(TimeProvider timeProvider)\n {\n if (Status != BatchStatus.Fermenting)\n {\n throw new DomainException("Only a fermenting batch can be bottled.");\n }\n\n Gravity[] lastTwo = _readings\n .OrderBy(r => r.TakenAtUtc)\n .TakeLast(2)\n .Select(r => r.Gravity)\n .ToArray();\n\n if (lastTwo.Length < 2 || lastTwo[0] != lastTwo[1])\n {\n throw new DomainException(\n "Gravity must hold steady across two readings before bottling.");\n }\n\n Status = BatchStatus.Bottled;\n _bottledAtUtc = timeProvider.GetUtcNow().UtcDateTime;\n _domainEvents.Add(new BatchBottled(Id));\n }\n\n public void ClearDomainEvents() => _domainEvents.Clear();\n}\nThe supporting types are records, so value equality comes for free:
\npublic readonly record struct BatchId(Guid Value);\npublic readonly record struct RecipeId(Guid Value);\npublic readonly record struct Gravity(decimal Value);\n\npublic sealed record Volume(decimal Amount, string Unit);\nThree choices here come straight from aggregate design: RecipeId references another aggregate by ID only, FermentationReading is a child entity that lives and dies with the batch, and _bottledAtUtc is a private field with no property at all.\nEvery one of those supposedly "breaks" EF Core, so let's map them piece by piece.
When EF Core materializes an entity, it doesn't use your public API.\nIt calls the private parameterless constructor and writes to properties through their backing fields, private setters and all.\nThat's the whole reason private Batch() { } exists, and it's the one concession the domain model makes to the ORM.
Loading and changing a batch looks like any other EF code:
\nBatch batch = await context.Batches\n .SingleAsync(b => b.Id == batchId);\n\nbatch.AddReading(new Gravity(1.012m), timeProvider.GetUtcNow().UtcDateTime);\n\nawait context.SaveChangesAsync();\nChange tracking reads the same backing fields, so private setters hide nothing from SaveChanges.
EF can even bind a parameterized constructor, matching parameters to mapped properties by name and type, private or not.\nThe catch: navigations can't be constructor-bound, so an aggregate with a collection still needs the parameterless one.\nEF also skips your factory's validation when loading, which is correct: re-running rules during materialization would make historical rows unloadable the first time a rule changes.
\nBatchId and RecipeId are strongly typed IDs, mapped with value conversions inside an IEntityTypeConfiguration<Batch>:
public sealed class BatchConfiguration : IEntityTypeConfiguration<Batch>\n{\n public void Configure(EntityTypeBuilder<Batch> builder)\n {\n builder.ToTable("batches");\n\n builder.HasKey(b => b.Id);\n\n builder.Property(b => b.Id)\n .HasConversion(id => id.Value, value => new BatchId(value))\n .ValueGeneratedNever();\n\n builder.Property(b => b.RecipeId)\n .HasConversion(id => id.Value, value => new RecipeId(value));\n\n // Collections, value objects, and domain events: next sections.\n }\n}\nValueGeneratedNever matters: value generation behind converters is a documented limitation area, so generate IDs in code (Guid.CreateVersion7() in the factory) and tell EF to keep its hands off.
Notice what RecipeId is not: a Recipe navigation property.\nThe recipe is its own aggregate, and you don't need its grain bill to take a gravity reading.\nThe foreign key column still exists, but the domain model doesn't traverse it.
By convention, EF finds the _readings backing field for a navigation named Readings, but I configure it explicitly so the mapping survives a rename:
builder.HasMany<FermentationReading>("_readings")\n .WithOne()\n .HasForeignKey("batch_id");\n\nbuilder.Navigation("_readings")\n .UsePropertyAccessMode(PropertyAccessMode.Field)\n .AutoInclude();\nPropertyAccessMode.Field tells EF to read and write the field and never touch the public view.\nAutoInclude is my default for aggregates: the Bottle invariant reads the readings, so a half-loaded Batch is unsafe to use.\nWithOne() with no arguments means the child has no navigation back to Batch; the batch_id foreign key lives only as a shadow property.
_bottledAtUtc has no property, only a private field, and EF maps it anyway:
builder.Property<DateTime?>("_bottledAtUtc")\n .HasColumnName("bottled_at_utc");\nThe cost shows up on the query side: filtering on the field means writing EF.Property<DateTime?>(b, "_bottledAtUtc") in the LINQ query.\nMy rule: private setters for state that queries filter on, field-only mapping for state only the aggregate itself needs.
var bottledThisWeek = await context.Batches\n .Where(b => EF.Property<DateTime?>(b, "_bottledAtUtc") >= weekAgo)\n .ToListAsync();\nVolume is a value object, and multi-property value objects map as complex types, which store their members inline in the owner's table (no join, no separate identity):
builder.ComplexProperty(b => b.Volume, volume =>\n{\n volume.Property(v => v.Amount).HasColumnName("volume_amount");\n volume.Property(v => v.Unit).HasColumnName("volume_unit");\n});\nComplex types were a v1 feature in EF Core 8 (no optional properties, no collections); EF Core 10 lifted both.\nOn EF 8 or 9, a collection of value objects (say the batch kept its HopAddition schedule) falls back to owned types, which work everywhere but carry a hidden shadow key, because EF treats them as entities pretending to be values:
builder.OwnsMany(b => b.HopAdditions, hop =>\n{\n hop.ToTable("hop_additions");\n hop.WithOwner().HasForeignKey("batch_id");\n});\nThe enum takes a plain conversion, stored as text so the database stays readable:
\nbuilder.Property(b => b.Status)\n .HasConversion<string>()\n .HasMaxLength(20);\nAll converted properties share one caveat: LINQ operates on the provider type, so sorting by Status gives alphabetical order (Bottled, Dumped, Fermenting) rather than lifecycle order.
IDomainEvent is no entity, so tell EF to leave the DomainEvents collection alone:
builder.Ignore(b => b.DomainEvents);\nThe events still need to go somewhere, and a SaveChangesInterceptor is the natural place:
public sealed class DomainEventsInterceptor(IDomainEventsDispatcher dispatcher)\n : SaveChangesInterceptor\n{\n public override async ValueTask<int> SavedChangesAsync(\n SaveChangesCompletedEventData eventData,\n int result,\n CancellationToken cancellationToken = default)\n {\n var domainEvents = eventData.Context!.ChangeTracker\n .Entries<Batch>()\n .SelectMany(entry =>\n {\n var events = entry.Entity.DomainEvents.ToList();\n entry.Entity.ClearDomainEvents();\n return events;\n })\n .ToList();\n\n await dispatcher.DispatchAsync(domainEvents, cancellationToken);\n\n return await base.SavedChangesAsync(eventData, result, cancellationToken);\n }\n}\nIDomainEventsDispatcher is the strongly typed dispatcher I built in building a custom domain events dispatcher, with no MediatR dependency; that post also covers dispatching before the save when handlers must share the transaction.
Every mapping snippet so far lives in BatchConfiguration, none of it in Batch: no mapping attributes, no ORM base class.\nThat's persistence ignorance, and the fluent configuration API is what makes it possible.\nThe DbContext sits in the infrastructure layer and picks up every configuration from its own assembly:
public sealed class BreweryDbContext(DbContextOptions<BreweryDbContext> options)\n : DbContext(options)\n{\n public DbSet<Batch> Batches => Set<Batch>();\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.ApplyConfigurationsFromAssembly(\n typeof(BreweryDbContext).Assembly);\n }\n}\nThe "EF Core forces anemic models" objection expired years ago.\nA private constructor, backing fields, value conversions, and complex types cover everything a fully encapsulated aggregate needs, and all of it lives in configuration classes the domain never sees.\nThe real limits come down to two: navigations can't be constructor-bound, and converted or field-only members translate through the provider type in queries.
\nThe ORM was never the thing keeping your domain model anemic.\nIt's a mapping exercise, done once per aggregate, and the encapsulation holds from then on.
\nIf you want to go deeper into modeling aggregates, value objects, and rich behavior across a real system, that's what I teach in Pragmatic Domain-Driven Design.
\nThanks for reading.
\nAnd stay awesome!
\nSplit into microservices only when you can point at concrete drivers: measurably different scaling needs, teams blocking each other in one release process, a data boundary you can draw cleanly, or a real need for independent failure or release.\nYou also have to afford the platform tax.\nWith two or three yes answers, build a modular monolith instead.
\nI've helped teams adopt microservices, and I've helped teams dig themselves out of microservices.\nThe second group is bigger.
\nIn almost every failure case, the decision to split came before the reasons did.\nThe app might need to scale someday.\nThe monolith feels messier every sprint.\nA conference talk made independent deployments look easy.\nNone of those are reasons to take on a distributed system.
\nMeanwhile, the actual trade is brutal and specific: microservices exchange local complexity for distributed complexity.\nA method call becomes a network hop.\nA transaction becomes a saga.\nA stack trace becomes a distributed trace across three services and a queue.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_205/method_call_vs_distributed.png\")
\nSometimes that trade is worth it.\nI've made it myself, and I'd make it again in the right situation.\nThe five questions below are how I find out.\nAnswer them honestly and the decision usually makes itself.
\nI don't mean needs you might have someday.\nI mean needs you can measure today: one part of the system handles 100x the traffic of the rest, or needs a GPU, or eats memory in a way that forces you to size the whole deployment for its peak.
\nThat's a real reason.\nExtracting a hot path so it can scale (and fail) independently is one of the best arguments for a service boundary.
\n![\"Three](\"https://milanjovanovic.tech/blogs/mnw_205/hot_path_scaling.png\")
\nBut check the honest version first: most .NET monoliths scale out fine behind a load balancer.\nIf your whole app comfortably runs on three instances, you don't have a scaling problem worth a service boundary.
\nMicroservices are an organizational tool as much as a technical one.\nThe strongest version of this signal looks like: multiple teams, one codebase, and a release process where team A's half-finished feature delays team B's hotfix.\nDeploy trains, release freezes, merge queues that take a day.
\n![\"Three](\"https://milanjovanovic.tech/blogs/mnw_205/deploy_train_vs_independent.png\")
\nIf that's your life, independent deployability has real value.
\nIf you're a team of six, it isn't.\nOne team doesn't step on itself hard enough to justify operating a distributed system.\nI'd go as far as saying: below roughly two full teams, the organizational argument for microservices is zero.
\nThis is the question that kills most splits, and it's the one people skip.
\nEach service must own its data outright.\nOwning it means no other service reads its tables directly, not even for one convenient join.\nIf two candidate services constantly need each other's data to answer basic queries, they aren't two services.\nThey're one service you're about to cut in half.
\n![\"Two](\"https://milanjovanovic.tech/blogs/mnw_205/data_boundary_entanglement.png\")
\nI learned this one the hard way, and wrote about it in the modular monolith boundary I couldn't take back: a boundary that looks clean on the org chart can be hopelessly entangled at the data level.\nThe entanglement doesn't go away when you add a network between the halves.\nIt gets worse, because now every "join" is an API call, and keeping the data boundaries intact becomes a distributed problem.
\nSome parts of a system carry requirements the rest doesn't:
\nThese are legitimate isolation requirements, and a service boundary is a clean way to express them.\nNotice how specific they are.\nA general wish for isolation is not on the list.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_205/independent_failure_isolation.png\")
\nBefore the first microservice delivers any value, you need: a container platform, CI/CD per service, centralized logging, distributed tracing, a message broker, and the reliability patterns that make inter-service communication safe (outbox, idempotent consumers, retries with backoff).
\nThat's the entry fee, paid in engineer-months, before benefit number one.
\n![\"Iceberg:](\"https://milanjovanovic.tech/blogs/mnw_205/platform_tax_iceberg.png\")
\nA team that can't spare that capacity doesn't get a cheaper version of microservices.\nIt gets a distributed monolith with none of the benefits and all of the costs.
\nThe rule I use:
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_205/five_questions_scoring.png\")
\nThe teams that regret microservices almost never got the technology wrong.\nThey got this checklist wrong, eighteen months earlier, in the meeting where the split was decided before the reasons existed.\nRun the five questions before your version of that meeting.
\nThanks for reading.
\nAnd stay awesome!
\nKatabench runs on three Hetzner servers inside one private VPN, with nothing public except ports 80 and 443.\nThe API publishes each submission to NATS, a worker on a separate server picks it up, and the code runs in a throwaway container sandbox with no network access.\nAuth and payments are the only pieces I buy instead of self-host.
\nFor the past few months, I've been building the most fun system of my career: one that takes C# code from strangers, compiles it, and runs it on my own servers.
\nIt's called Katabench, a hands-on coding platform for .NET developers, and it's what came out of the urge to build something I wrote about in January.\nYou write code in the browser, across challenges for algorithms, EF Core, raw SQL, architecture tests, refactoring, secure coding, and test writing.
\nNothing is simulated.\nA database challenge runs against a live Postgres instance, and you get back real execution numbers: allocated memory, query speed, the SQL your code produced.
\nBut this isn't a product tour.\nThe system design is the part you can steal.\n"Run untrusted code safely on hardware you own" sounds like a big-company problem. It turned out to fit on three servers.
\nHere's what we'll cover:
\nLet's dive in.
\nKatabench is three applications: a marketing website, the app itself, and the backend.
\nThe marketing site is Astro, for the same reason this website runs on Astro: nothing beats it for static content and SEO.\nThe app is React with Vite and TypeScript. It's a stack I'm familiar with, and you can build pretty much anything with it.\nBoth are static builds served through Cloudflare, which costs me exactly $0 and includes the DNS, CDN, and DDoS protection I'd otherwise be paying for.
\nThe backend is .NET, and that's where it gets interesting.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_204/katabench_system_design.png\")
\nEverything inside the big box runs on three Hetzner VPSs:
\nThe rest of the stack: Headscale for the VPN,\nDokploy for deployments, Traefik as the reverse proxy,\nand Grafana for observability.\nAuth is Clerk and payments are Paddle; both decisions get their own section at the end.
\nThe first design decision wasn't about the application at all: all of my servers are part of the same private network (VPN), and nothing is exposed to the public internet except ports 80 and 443.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_204/katabench_vpn.png\")
\nMy desktop PC is on the same VPN, and so is a Mac Mini that runs agent loops for me.\nThat's how I reach Dokploy, Grafana, and the database.\nThere's no public admin endpoint exposed.
\nThe two public ports lead to Traefik, the reverse proxy that Dokploy manages for me, and Traefik routes traffic to the API.\nEverything else (Postgres, Redis, NATS, Grafana, Dokploy's own dashboard) is reachable only over the VPN.
\nA few weeks ago, I showed you how to build your own VPN with Tailscale.\nKatabench runs on the same idea, except the control plane is Headscale, an open-source, self-hosted implementation of Tailscale's coordination server, with Headplane as its admin UI.\nUnderneath it's still a WireGuard mesh. What changes is that I run the coordination server myself.
\nHeadscale's ACLs decide what each machine is allowed to reach, so the worker server can't open a connection to the database even though they share a network.\nIf Headscale goes down, existing tunnels keep working, but new machines can't join until I fix it.\nI can live with that: users never notice, and Headscale costs nothing.
\nWhy Hetzner? Price.\nThey raised their prices recently (my timing was impeccable to miss grandfathering the old prices...), but the math still beats every managed alternative.
\nThe API server runs the .NET API and the Postgres database right next to it.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_204/katabench_api.png\")
\nIf you're used to running everything in the cloud, a database on the same box as the API looks wrong.\nHere's why I did it anyway:
\nThe real price is that backups are my problem now.\nEvery night, a cron job ships a pg_dump to Cloudflare R2, the exact setup I showed in last week's issue.
Also on this box:
\nThis is the part of the system I spent the most time on, because this is where strangers run arbitrary C# on my hardware.\nEvery decision here starts from one assumption: someone will eventually try to break out.
\nWhen you hit Submit, the API doesn't execute anything.\nIt publishes a message to NATS and moves on.
\nThe worker, on its own server, picks up the message. This is the classic queue with competing consumers setup: scaling out just means adding another consumer.\nIf submissions pile up, I create another worker server, join it to the VPN, connect it to Dokploy, and it starts pulling from the same stream.
\nThe worker has no database connection string or API credential.\nIts ACL also prevents it from reaching the database, limiting what a sandbox escape could expose.
\nAnd the worker doesn't run your code either.\nIt hands it to a sandbox: an isolated, throwaway environment that compiles and executes a single submission.\nA sandbox can't touch another sandbox, and it can't reach anything else in the system.\nI'll write more about the specifics of the sandbox in a future issue, but the high-level idea is that it runs inside a container with no network access and a strict resource limit.
\nBecause a sandbox can't touch anything, it's free to spin up whatever a challenge needs inside itself, like the throwaway Postgres instance your EF Core code runs against.\nThat's how Katabench hands you back the SQL your code actually executed.\nSome challenges go further and inspect the query plan to check that your solution uses the right index.
\nIt's also the basis for something bigger I'm working on: long-lived sandboxes where you build out a complete system, like a modular monolith, in an in-browser IDE.\nMore on that another time.
\nThe third server never serves a user request.\nIt exists to manage and observe the other two.
\nDokploy runs here.\nIt's a self-hosted PaaS that gives me the Azure App Service experience on my own machines: push code, get a deployment, and Traefik routing is handled for me.\nThe feature that sold me is remote server management: one Dokploy instance deploys to the whole fleet.
\nThe other half of this server is the Grafana observability stack:
\nThe OpenTelemetry collectors on the other two servers run in agent mode and stream telemetry to a gateway collector here, which feeds that stack.
\n![\"Telemetry](\"https://milanjovanovic.tech/blogs/mnw_204/katabench_platform.png\")
\nMy applications never talk to the monitoring backend directly; they hand everything to the local agent and stay decoupled from wherever the data ends up.
\nIs a dedicated observability server overkill for a brand-new SaaS?\nI don't think so.\nWhen your system executes other people's code, "what exactly happened here" is not a question you want to answer by grepping docker logs across three servers.
\nEverything so far is self-hosted, which will surprise nobody who saw my side project tech stack video earlier this year.\nTwo pieces of Katabench went the other way: auth and payments.
\nAuth first: I chose Clerk over Keycloak.\nI've shown you how to integrate Keycloak with ASP.NET Core, and it's still what I recommend when you want full control over your identity setup.
\nBut full control means all of it is my job: running the service and its database, building the sign-in forms and emails, and wiring up every external identity provider by hand.\nClerk makes all of that someone else's job: sign-in components that drop into my React app, transactional emails, social logins that take minutes to enable, and users synced back to my backend.
\nThe tradeoff: a per-user bill as you grow, and a dependency I don't control.\nAt Katabench's current stage, getting to an MVP faster is worth more than the long-term cost of running my own auth service.
\nPayments follow the same logic, with one extra constraint.\nPaddle is a merchant of record, meaning they are legally the seller and handle global sales tax and VAT.\nAs a solo developer selling worldwide, I'd rather give up a percentage than file tax returns in countries I couldn't place on a map.
\nAnd the constraint: I run my business from Serbia, and Stripe isn't available here.\nPaddle is.
\nThe pattern behind both decisions: I'll self-host infrastructure, but not auth or payments.\nEverything else stays on my own servers, where the monthly bill stays the same no matter how much traffic shows up.
\nEvery box in the diagram hides decisions worth an issue of its own: hardening Headscale, building the sandbox, wiring the OpenTelemetry pipeline, running a Dokploy fleet.
\nHit reply and tell me which part you want me to zoom in on first.\nYour questions will shape the next few issues and videos.
\nAnd if you're curious how all of this feels from the other side of the sandbox, Katabench is live.\nGive it a try and tell me what breaks.
\nThanks for reading.
\nAnd stay awesome!
\nI moved this site from Netlify to Cloudflare Pages without downtime by deploying to both hosts from the same GitHub Actions build, verifying the Pages copy on its own URL, then flipping a single DNS record.\nNetlify kept serving production until that flip, so rolling back meant repointing one record.\nThe new hosting bill is $0.
\nEarlier this month, I migrated this website from Netlify to Cloudflare.\nThe site was down for zero seconds, no reader noticed a thing, and the hosting bill went from $19 a month to $0.\nThat's $228 a year, for one afternoon of work.
\nMigrations like this have a scary reputation, so I want to show you the playbook I used:
\nLet's dive in.
\nThis is not a Netlify hate story.\nNetlify served this site reliably for years, and the developer experience is genuinely good.
\n![\"Netlify](\"https://milanjovanovic.tech/blogs/mnw_203/netlify_bandwidth.png\")
\nBut the setup had quietly become redundant.\nThis site compiles to static files, and my GitHub Actions pipeline already does the building.\nNetlify's job, at the end of all that, was to put a folder of files behind a CDN.
\nServing static files is a commodity in 2026.\nCloudflare Pages does it for free, with unmetered bandwidth, on one of the largest edge networks in the world.
\nThe hard part is switching without breaking the wiring a website accumulates over the years: DNS records, email authentication, redirects, comment auth.
\nThe whole migration hangs on one principle:
\nThe old host keeps serving production until a single DNS change flips traffic to the new one.
\nEverything else is preparation that can't affect the live site:
\nAt every point, a working version of the site is one DNS record away.
\nCloudflare Pages can clone and build your repo itself, but I skipped that option.\nMy build already runs in GitHub Actions, with environment variables and secrets wired up there, and I didn't want to move the build and the hosting in the same step.
\nSo CI keeps building, and wrangler (Cloudflare's CLI) uploads the finished dist/ folder.\nCloudflare calls this a direct upload deployment, and it turned the migration into one extra step in the workflow:
- name: Build 🏗\n run: npm run build\n\n- name: Deploy to Netlify 💫\n run: npx netlify deploy --prod --dir=dist\n\n# Temporary: dual-deploy during the migration so the Pages copy\n# can be verified against live Netlify. Delete after the cutover.\n- name: Deploy to Cloudflare Pages 💫\n run: npx wrangler@4 pages deploy dist --project-name=mjtech --branch=main\nReaders kept hitting Netlify.\nMeanwhile, I had a complete, always-current copy of production at mjtech.pages.dev to click through: the blog, search, course pages, the RSS feed, redirects.
![\"GitHub](\"https://milanjovanovic.tech/blogs/mnw_203/dual_deploy.png\")
\nTwo GitHub secrets make it work (CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID), and the first deploy creates the Pages project.\nIf your site has auth, add the new domain to your provider's authorized list (Firebase, in my case), or sign-ins will fail only on the new host.
![\"Cloudflare](\"https://milanjovanovic.tech/blogs/mnw_203/cf_pages_deployments.png\")
\nThe domain never left my registrar.\nOnly the nameservers changed, which hands DNS hosting to Cloudflare.
\nBefore touching anything, I inventoried every DNS record.\nThe website records are the easy ones: if they're wrong, you notice within seconds.\nThe dangerous ones are the MX records for email, the SPF, DKIM, and DMARC TXT records, domain verifications, and the newsletter sending domain.\nBreak a DKIM record, and your emails quietly start landing in spam folders until someone tells you.
\nCloudflare imports your existing records when you add the domain, but the import isn't guaranteed to be complete.\nIn fact, in my case it missed a few important DNS records, so I had to add them manually.\nCheck it against your inventory, record by record, and keep email and verification records DNS only (the grey cloud).
\nThen the nameserver change at the registrar.\nThe imported records still pointed the domain at Netlify, so DNS hosting moved to Cloudflare while the live site kept serving from Netlify, unaffected.
\n![\"Before](\"https://milanjovanovic.tech/blogs/mnw_203/dns_cutover.png\")
\nWith DNS on Cloudflare and the Pages copy verified, the migration moment itself is one click: add your domain as a custom domain on the Pages project.\nCloudflare repoints the DNS record and provisions a certificate, and the moment it activates, your traffic is served by Cloudflare.\n(I used the occasion to make the apex domain the canonical host, with www redirecting to it.)
The rollback is what makes this step safe.\nProxied DNS changes on Cloudflare take effect in seconds, and Netlify still held the latest deploy thanks to the dual-deploy step.\nIf anything had looked wrong, repointing one record would have brought the old setup back within a minute.
\nCutover day was July 6.\nThe dual-deploy step went into CI at 3:43 PM.\nAt 6:47 PM, traffic was on Cloudflare and the Netlify step was deleted from the pipeline.\nThree hours, most of them spent double-checking.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_203/cf_custom_domains.png\")
\nEvery migration has one.
\nMy netlify.toml contained a redirect from /sitemap.xml to /sitemap-index.xml (the generator produces the latter, search engines ask for the former).\nI ported the redirect rules I remembered, and this one, added years ago, wasn't in the group.\nIt 404'd after the cutover.
Cloudflare Pages reads redirects from a _redirects file in your build output, so the fix was one line:
/sitemap.xml /sitemap-index.xml 301\nBefore you decommission a host, read its config file line by line and ask where each rule lives now.
\nThe $0 bill would have justified the move on its own, but it came with upgrades:
\n<branch>.mjtech.pages.dev. The issue you're reading was proofread on one of those URLs.www to apex redirect lives).The trade-off is more eggs in one basket: Cloudflare is now my DNS, CDN, and host.\nAnd Pages' own build system is weaker than Netlify's, which I sidestep by building in GitHub Actions and treating Pages as dumb file hosting.
\nWhile I was in the Cloudflare dashboard anyway, I gave R2, their S3-compatible object storage, a real job.
\nThe free tier includes 10 GB of storage and, unique among the big clouds, zero egress fees.\nDownloading your data costs nothing, which is exactly the property you want for backups.
\nI use it for Katabench, the coding platform I'm building.\nEvery night, a cron job on the server dumps the production Postgres database and ships it to an R2 bucket with rclone:
\nstamp=$(date -u +%Y%m%dT%H%M%SZ)\n\n# Dump, ship to R2, prune to 30 days of nightlies\ndocker exec appdb pg_dump -Fc -U postgres coderunner > "appdb-${stamp}.dump"\nrclone copyto "appdb-${stamp}.dump" "r2:backups/prod/appdb-${stamp}.dump"\nrclone delete --min-age 30d r2:backups/prod/\nThirty days of nightly backups, off the server, on the free tier.\nTo rclone, R2 is just S3 with a Cloudflare endpoint.
\nIf you self-host anything, don't skip this piece.\nA backup on the same box as the database has the same blast radius as the database.
\nThe playbook, in five lines:
\nTotal cost: one afternoon.\nTotal savings: $228 a year, plus branch previews and free off-site backups.
\nThe best migrations are the ones nobody notices.
\nThanks for reading.
\nAnd stay awesome!
\nTest a slice through its public entrance: a real HTTP request in, and assertions on the response plus the rows it wrote.\nWebApplicationFactory hosts the app in-memory while Testcontainers gives you a real Postgres in Docker, both started once per test class.\nAnything you own, including the database, stays real in the test.
Whenever I write about vertical slice architecture, the same question shows up in my inbox: "OK, but how do I test it?"
\nIt's a fair question, because the testing habits most of us learned grew up alongside layered architecture.\nMock the repository, test the service, assert the service called the repository.\nIn VSA there is no service layer to test and often no repository to mock.\nThe slice is a request, a handler, and the database work, living together in one place.
\nPeople read that and conclude vertical slices are hard to test.\nIt's the opposite.\nYou just have to stop testing layers and start testing what the slice actually is: a feature.
\nA vertical slice has a natural contract: a request goes in at the top, and an observable outcome comes out the bottom (a response, plus rows in a database, plus maybe a message on a bus).
\nSo test exactly that contract:
\nOne slice = one focused set of tests that exercise it from the endpoint to the database.
\nNot a handler test with a mocked DbContext.\nNot an endpoint test with a mocked handler.\nThe whole slice, through its public entrance, against a real database.
![\"A](\"https://milanjovanovic.tech/blogs/mnw_202/slice_test_boundary.png\")
\nIf you're coming from layered architecture, this feels like "just integration tests".\nIt is, and that's the point: the test pyramid is a lie for this kind of code.\nA slice test catches broken SQL, broken mapping, broken validation, and broken routing in one go, none of which a mocked-out unit test can see.
\nTwo pieces make slice tests fast enough to run constantly: WebApplicationFactory to host the app in-memory, and Testcontainers for real infrastructure in Docker.\nMy examples use Postgres, but the same approach covers Redis, a message broker, or anything else the slice touches.
The shared fixture boots both once for the whole test class:
\npublic class ApiFixture : WebApplicationFactory<Program>, IAsyncLifetime\n{\n private readonly PostgreSqlContainer _db = new PostgreSqlBuilder()\n .WithImage("postgres:17-alpine")\n .Build();\n\n protected override void ConfigureWebHost(IWebHostBuilder builder)\n {\n builder.UseSetting("ConnectionStrings:Database", _db.GetConnectionString());\n\n // Fake only what you don't own (payment gateways, email providers)\n builder.ConfigureTestServices(services =>\n services.AddSingleton<IEmailSender, FakeEmailSender>());\n }\n\n public async Task InitializeAsync()\n {\n await _db.StartAsync();\n\n // Create the schema once the container is up. If your app already\n // migrates on startup, drop this and let the host do it.\n using var scope = Services.CreateScope();\n await scope.ServiceProvider\n .GetRequiredService<AppDbContext>()\n .Database.MigrateAsync();\n }\n\n public new Task DisposeAsync() => _db.DisposeAsync().AsTask();\n}\nAnd a slice test reads like a description of the feature:
\nusing AwesomeAssertions;\n\npublic class CreateShipmentTests(ApiFixture api) : IClassFixture<ApiFixture>\n{\n [Fact]\n public async Task Creates_shipment_and_persists_it()\n {\n var client = api.CreateClient();\n var orderId = Guid.NewGuid();\n\n var response = await client.PostAsJsonAsync("/shipments", new\n {\n OrderId = orderId,\n Address = "123 Main Street"\n });\n\n response.StatusCode.Should().Be(HttpStatusCode.Created);\n\n // A fresh scope, so we read what actually persisted.\n using var scope = api.Services.CreateScope();\n var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();\n var shipment = await db.Shipments.SingleAsync(s => s.OrderId == orderId);\n shipment.Status.Should().Be(ShipmentStatus.Pending);\n }\n\n [Fact]\n public async Task Rejects_a_shipment_without_an_address()\n {\n var client = api.CreateClient();\n var orderId = Guid.NewGuid();\n\n var response = await client.PostAsJsonAsync("/shipments",\n new { OrderId = orderId, Address = "" });\n\n response.StatusCode.Should().Be(HttpStatusCode.BadRequest);\n\n // The 400 is only half the contract; make sure nothing slipped through.\n using var scope = api.Services.CreateScope();\n var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();\n (await db.Shipments.AnyAsync(s => s.OrderId == orderId)).Should().BeFalse();\n }\n}\nTwo small choices in the assertion carry weight.\nIt reads through a fresh scope, so you see what actually persisted, not what EF Core's change tracker still holds in memory.\nAnd it filters by the OrderId you sent instead of grabbing "the one row", which keeps the test truthful even when it isn't the only thing writing to the database.
Notice what the test doesn't know: whether the slice uses MediatR or plain endpoints, EF Core or Dapper, one file or three.\nThat ignorance is the payoff.\nYou can refactor everything inside the slice without touching a single test.\nTests coupled to layers punish refactoring; tests coupled to behavior enable it.
\nA note on speed, because it's the usual objection: the container and the host start once per test class, not per test.\nOn my machine a suite like this runs in seconds, and my Testcontainers best practices cover the reuse tricks that keep it that way as the suite grows.
\nThat database is shared, though, and it's worth saying out loud: every test in the class writes to the same Postgres, and the state carries over.\nFiltering by OrderId (like above) keeps individual assertions honest, but anything that counts rows or checks ordering wants a clean slate.\nA small helper on the fixture wipes the tables between runs, no extra libraries required:
public async Task ResetAsync()\n{\n using var scope = Services.CreateScope();\n var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();\n\n // Add each table the slice touches.\n await db.Shipments.ExecuteDeleteAsync();\n}\nThen call it at the top of each test.\nxUnit runs the tests in a class sequentially, so a reset at the start hands each one a clean slate:
\n[Fact]\npublic async Task Creates_shipment_and_persists_it()\n{\n await api.ResetAsync();\n\n // ... arrange, act, assert\n}\nNow each test starts from a known state.
\nMost slices are thin: validate, load, mutate, save.\nSlice tests cover those completely, and unit testing a thin handler through mocks just restates the implementation.
\nBut some slices contain real logic: pricing rules, state machines, date math around business calendars.\nWhen that happens, don't test the logic through HTTP.\nExtract it into the domain (a method on the entity, a domain service, a plain class) and unit test it there, exhaustively, with no infrastructure in sight.
\nThe split is clean:
\nIf a slice has no interesting logic, it gets no unit tests.
\nOne more failure mode: tests pass, features work, and six months later every slice quietly references three others.\nSlice independence is the property that makes VSA worth having, so put it under test too, with architecture tests:
\n[Fact]\npublic void Slices_should_not_reference_other_slices()\n{\n var result = Types.InAssembly(typeof(Program).Assembly)\n .That().ResideInNamespace("Features.Shipments")\n .ShouldNot().HaveDependencyOn("Features.Invoicing")\n .GetResult();\n\n result.IsSuccessful.Should().BeTrue();\n}\nCheap to write, and it turns "please don't couple slices" from a code-review plea into a failing build.
\nTesting vertical slice architecture stops being confusing the moment you pick the right unit:
\nWebApplicationFactory + Testcontainers.The result is a suite that describes features instead of layers, survives refactoring, and catches the bugs that actually reach production.
\nThanks for reading.
\nAnd stay awesome!
\nTailscale connects your own machines into a single private, encrypted network called a tailnet, built on WireGuard.\nEvery device dials outward only, so you can bind Postgres or Grafana to the machine's tailnet IP and close every inbound firewall port.\nPrivate services need no TLS certificates or reverse proxies, because WireGuard already encrypts every byte.
\nRight now, a bot is scanning the internet for your database.\nNot yours in particular. Every database, on every server with a public IP, around the clock.\nThe moment something on your VPS gets a public port, you're in that game whether you meant to join or not.
\nAnd most of what runs on a server was never built to play it.\nThe database.\nThe admin panel.\nThe metrics dashboard.\nThe internal API only your other services call.
\nNone of that is meant for the public.\nYet the standard tutorial hands each one a public port anyway, and with it a second job: certificates, login pages, IP allowlists, and bots probing around the clock.
\nThere's a better default: keep those services private, reachable only by you and by each other, and expose nothing.\nThis issue shows you how, using Tailscale.
\nA VPN (virtual private network) is an encrypted tunnel between machines over the public internet.\nTraffic inside it stays private, even across networks you don't control.
\nTailscale uses that idea to connect your own machines (PCs, servers, phones) into a single private network only your devices can see, called a tailnet.\nIt runs on WireGuard, a modern, heavily audited encryption protocol, and manages all the keys and addresses for you.
\nThe shape is what sets it apart from an old-school VPN.\nA traditional VPN is hub and spoke: every device dials one central server, and all traffic funnels through it.\nTailscale builds a mesh, where every device connects directly to every other device over its own encrypted tunnel.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_201/hub_and_spoke_vs_mesh.png\")
\nNo server sits in the traffic path.\nYour app-to-database traffic takes the shortest route between the boxes, and there's nothing to babysit.
\nHow do devices find each other with no server in the middle?\nTailscale splits the job: a coordination server keeps a directory of your devices and their keys (a phone book), while your actual data flows directly between devices, encrypted end to end.
\n![\"Tailscale\"](\"https://milanjovanovic.tech/blogs/mnw_201/coordination_vs_data_plane.png\")
\nThe key property: devices only ever dial outward, to the coordination server and to each other.\nNothing has to connect inward, which is what lets us close every firewall port next.
\nInstalling Tailscale is two commands per machine (plus the app on your PC):
\ncurl -fsSL https://tailscale.com/install.sh | sh\nsudo tailscale up\nOpen the login URL it prints, approve the device, and it joins your tailnet with a stable private IP (in the 100.x.y.z range) and a name that never change, on any network.
Here's the setup we'll build:
\nvps-app (100.64.0.2) runs a .NET API in Docker.vps-data (100.64.0.3) runs Postgres and Grafana in Docker.![\"A](\"https://milanjovanovic.tech/blogs/mnw_201/private_apps_over_tailnet.png\")
\nClose the firewall.\nBecause Tailscale only dials outward, your cloud firewall needs no inbound rules to reach these boxes.\nConfirm SSH works over the tailnet, then delete the public port-22 rule so SSH stops existing as far as the internet is concerned.
\nBind services to the tailnet IP.\nThis is the step that makes "zero open ports" true.\nPublishing a Docker port the usual way (-p 5432:5432) binds it to 0.0.0.0, every interface.\nPublish private services on the tailnet IP only instead. On vps-data:
services:\n postgres:\n image: postgres:18\n restart: unless-stopped\n environment:\n POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}\n ports:\n - '100.64.0.3:5432:5432' # tailnet IP, not 0.0.0.0\n volumes:\n - pgdata:/var/lib/postgresql/data\n\n grafana:\n image: grafana/grafana:12.1.0\n restart: unless-stopped\n ports:\n - '100.64.0.3:3000:3000'\n volumes:\n - grafana:/var/lib/grafana\n\nvolumes:\n pgdata:\n grafana:\nNow Postgres has no public endpoint at any layer, yet every device on your tailnet reaches it.
\nWire the app to the other box with an ordinary connection string pointed at the data box's stable tailnet IP:
\nservices:\n api:\n image: ghcr.io/milanjovanovic/api:latest\n restart: unless-stopped\n ports:\n - '100.64.0.2:8080:8080'\n environment:\n ConnectionStrings__AppDb: 'Host=100.64.0.3;Port=5432;Database=app;Username=app;Password=${POSTGRES_PASSWORD}'\nThen from your PC, on any network:
\ncurl http://vps-app:8080/health\npsql -h vps-data -p 5432 -U app app\nLook back at everything this setup let you skip.\nWireGuard encrypts every byte, so TLS certificates never entered the picture.\nGrafana went up without a reverse proxy or a login page, and you reached each service by its tailnet name instead of a DNS record.\nThe services run, but the internet can't see them.
\nOnce your machines share one private network, every internal service (databases, queues, dashboards, admin panels, service-to-service APIs) stops being a public endpoint you have to defend.\nIt becomes a private address you simply connect to.
\nThis is the exact pattern I run for Katabench, the coding platform I'm building.\nOne reverse proxy on 80 and 443 is public, because users load the app through it.\nEverything else (the deployment panel, Postgres, the message queue, Grafana, all the telemetry) lives on the tailnet with no public hostname at all.
\nThe mental model that makes it stick: a public hostname is something a service has to earn, and only when an outside party genuinely must reach it.\nEverything else stays private by default.
\nFifteen minutes of setup, zero open ports, and your infrastructure disappears from the public internet without losing an ounce of convenience.
\nThanks for reading.
\nAnd stay awesome!
\nNATS is a messaging system that runs as a single Go binary, and JetStream is the persistence layer that turns a subject into a durable queue with at-least-once delivery.\nIn .NET you add the NATS.Net client, publish from an endpoint, and consume in a BackgroundService.\nThe handler has to be idempotent, because a crash before the ack causes a redelivery.
When .NET developers need a message queue, they reach for RabbitMQ, Azure Service Bus, or a Postgres table.
\nNATS almost never comes up.\nThat's a shame: it's quietly become one of my favorite tools for this.
\nNATS is a messaging system written in Go that runs as a single binary with no external dependencies.\nJetStream, its durable layer, turns it into a real queue with at-least-once delivery.\nAnd the .NET client is a pleasure to work with.
\nNATS has two layers, and the difference matters.
\nCore NATS is fire-and-forget pub/sub.\nYou publish to a subject, and whoever is subscribed at that moment gets it.\nIf no one is listening, the message is gone, which suits live notifications but not a work queue.
\nJetStream is the persistence layer on top.\nIt captures messages published to a subject into a stream on disk, so a consumer can read them later, even after a restart.\nThat persistence is what turns a subject into a durable queue.
\n![\"Core](\"https://milanjovanovic.tech/blogs/mnw_200/core_nats_vs_jetstream.png\")
\nA few things stood out coming from the usual brokers:
\nYou need the server and two NuGet packages.
\nRun the server with JetStream enabled.\n-js turns it on, and -sd points it at a directory so streams survive a restart:
# docker-compose.yml\nnats:\n image: nats:2.14-alpine\n command: ['-js', '-sd', '/data']\n ports: ['4222:4222']\n volumes:\n - nats-data:/data\n restart: unless-stopped\nAdd the client and its dependency-injection integration:
\ndotnet add package NATS.Net\ndotnet add package NATS.Extensions.Microsoft.DependencyInjection\nThen wire it into Program.cs.\nAddNatsClient registers one multiplexed, self-reconnecting connection, and the next line exposes a JetStream context to inject anywhere:
// Program.cs\nbuilder.Services.AddNatsClient(nats =>\n nats.ConfigureOptions(opts => opts with { Url = "nats://localhost:4222" }));\n\nbuilder.Services.AddSingleton(sp =>\n sp.GetRequiredService<INatsConnection>().CreateJetStreamContext());\nWith the JetStream context in DI, a Minimal API endpoint publishes in one call.\nJob is a plain record, and NATS.Net serializes it to JSON for you, so you work with typed messages, no extra setup.\nEnsureSuccess throws if the stream didn't store the message:
app.MapPost("/jobs", async (CreateJob request, INatsJSContext js, CancellationToken ct) =>\n{\n var job = new Job(Guid.NewGuid(), request.Payload);\n\n PubAckResponse ack = await js.PublishAsync("jobs.work", job, cancellationToken: ct);\n ack.EnsureSuccess();\n\n return Results.Accepted($"/jobs/{job.Id}");\n});\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_200/nats_job_pipeline.png\")
\nA BackgroundService is the natural home for the consumer.\nIt creates the stream and durable consumer on startup, then pulls messages in a loop.\nEvery running instance shares the workers consumer, so they compete for jobs and each runs once:
public class JobWorker(INatsJSContext js) : BackgroundService\n{\n protected override async Task ExecuteAsync(CancellationToken ct)\n {\n await js.CreateStreamAsync(new StreamConfig("JOBS", ["jobs.work"])\n {\n Retention = StreamConfigRetention.Workqueue, // a queue: acked messages are removed\n Storage = StreamConfigStorage.File // durable: survives a restart\n }, ct);\n\n var consumer = await js.CreateOrUpdateConsumerAsync("JOBS", new ConsumerConfig("workers")\n {\n AckPolicy = ConsumerConfigAckPolicy.Explicit,\n AckWait = TimeSpan.FromSeconds(30), // must exceed your worst-case processing time\n MaxDeliver = 5 // drop a poison message after 5 tries\n }, ct);\n\n await foreach (var msg in consumer.ConsumeAsync<Job>(cancellationToken: ct))\n {\n await ProcessAsync(msg.Data, ct); // the side effect\n await msg.AckAsync(cancellationToken: ct); // then ack\n }\n }\n}\nRegister it with builder.Services.AddHostedService<JobWorker>().\nThe worker is a singleton, so resolve scoped dependencies like DbContext through IServiceScopeFactory.
Two stream settings shape how the queue behaves.
\nStorage is File (on disk, survives restarts) or Memory (faster, but gone on restart).
Retention controls when a message leaves the stream:
Limits (the default) keeps every message until it hits an age, size, or count limit. The stream is a replayable log, and reading a message doesn't remove it.Workqueue drops a message the moment a consumer acks it, so the stream itself is the queue. Messages are delivered in publish order, oldest first (FIFO).Interest keeps a message only while a consumer still needs it, then drops it once every interested consumer acks.For a job queue: Workqueue on File, as in the worker above.
Look closely at the worker loop: it processes first, then acks.\nThat order is the rule that makes JetStream reliable, and most quickstarts skip it.
\nAcknowledge the message after the side effect, never before.
\nJetStream gives you at-least-once delivery.\nIf a worker runs a job and crashes before acking, JetStream redelivers it.\nBut ack before the work is finished, and a crash leaves the job marked done with nothing to show for it.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_200/ack_after_side_effect.png\")
\nThe flip side is that a job can run more than once, so your handler has to be idempotent.\nThe usual fix is to track the messages you've already handled and skip duplicates, in the same transaction as the side effect.\nI covered the full pattern in The Idempotent Consumer Pattern in .NET.\nAt-least-once delivery only holds up when the handler reading the stream is idempotent.
\nNATS JetStream gives you a durable, at-least-once work queue from a single 18 MB binary, and it slots into an ASP.NET Core app cleanly: publish from an endpoint, process in a BackgroundService, ack after the work is done.
I went in skeptical, half-expecting to miss RabbitMQ.\nIt won me over: easy to operate, no surprises, and it clusters with Raft-based replication when a bigger load calls for it.\nIt's now the first thing I reach for when I need a queue and don't want to think much about the broker.\nIt runs my own production job queue today, and I wrote up that design (two streams, competing consumers, publish-before-ack) in how I use NATS JetStream as a job queue in .NET.
\nIf you haven't tried it, spin up the container and publish a message.\nThat's all there is to getting started.
\nThanks for reading.
\nAnd stay awesome!
\nI separated an order collaboration module from the product catalog, and a year of ordinary feature work wove the two back together.\nYou draw module boundaries when you know the least about the domain, so let consistency requirements decide where the line goes.\nSplitting a coarse module later is cheap, and merging two is the expensive direction.
\nWe built the system the way you're supposed to: a modular monolith, one module per business domain, modules talking to each other through events so nothing was tightly coupled.
\nThe system let dealers and customers build an order together on a showroom floor.\nSo giving that order-building collaboration its own module, separate from the product catalog, was an easy decision to defend.\nThey were two distinct domains, and separating them into modules is textbook.
\nIt took about a year, and a piece of business context none of us had at the start, for that decision to quietly stop being reversible.
\nThis was the 40-year-old system I wrote about rewriting.\nThe backend is a manufacturing ERP, with the dealer ordering tool layered on top.
\nTwo areas felt obviously distinct.\nThe Catalog module owned products, configurations, options, and pricing.\nThe Collaboration module owned the back-and-forth of building an order: drafts, comments, approvals, revisions.\nIt looked like a clean separation: different responsibilities, different parts of the team.
\n![\"Day](\"https://milanjovanovic.tech/blogs/mnw_199/clean_boundary_day_one.png\")
\nSplitting them was the deliberate call, not a reflex, and every choice that followed held up on its own.
\nThe trouble started as ordinary feature work.
\nA collaboration screen needed product options, so it read from the catalog.\nThen it needed live pricing too.\nThen a requirement landed: an order had to reflect catalog changes immediately.\nNone of them looked like an architecture decision.
\nBut every one of them added a thread between Collaboration and Catalog.\nThe two modules I had carefully separated were weaving themselves back together, one feature at a time.\nThe boundary was still there in the folder structure.\nIt had stopped being there in any way that mattered.
![\"Catalog](\"https://milanjovanovic.tech/blogs/mnw_199/coupling_a_year_later.png\")
\nThe deeper problem was the communication style, and it's the decision I'd still defend hardest.\nAcross the whole rewrite, modules communicated asynchronously, through events.\nIt kept modules decoupled during a high-stakes migration and let us replace the legacy system one piece at a time.\nCatalog publishes an event, Collaboration reacts when it gets to it, and the two stay independent.
\nThat held up right until the business needed an order to be correct now.\nA dealer changes a configuration, and the price has to be right the instant they hit save.\nEventual consistency had been the right assumption for every requirement we knew about.\nThe requirement that broke it didn't exist yet when we drew the boundary.
\n![\"Eventual](\"https://milanjovanovic.tech/blogs/mnw_199/eventual_vs_immediate_consistency.png\")
\nYou can't bolt immediate consistency onto an asynchronous boundary.\nSo we did what everyone does: synchronous calls, shared transactions, and workarounds to paper over the gap.\nFix by fix, the system was telling us that, given the consistency the business now needed, these two belonged in one module.
\nIn hindsight, the signals were all there.\nAt the time, not one of them looked like a signal.
\nAny one of these is invisible.\nTogether, over a year, they're the whole story.
\nA module boundary is a guess, so treat it like one.\nYou're guessing - so keep testing the guess instead of filing it away as settled.
\nStart with fewer, coarser modules.\nYou can always split a module once the seam is obvious.\nWhen you're unsure, keep things together and let a module earn its independence.\nIt's the same instinct as waiting for the third repetition before you extract an abstraction.
\n![\"Splitting](\"https://milanjovanovic.tech/blogs/mnw_199/split_is_cheap_merge_is_expensive.png\")
\nLet consistency draw your boundaries.\nEventual consistency across a boundary is a bet that they never will.\nMake that bet on purpose, not by default.
\nWatch the cheap decisions, not the expensive ones.\nWe pour deliberation into decisions that are easy to reverse and wave through the ones that quietly aren't.\nA module boundary feels cheap, because on the day you draw it, it is.\nThe cost shows up later, compounding, which is exactly why nobody's watching when it does.
\nNone of this means modular monoliths are a trap, or that async messaging is a mistake.\nI'd build it as a modular monolith again tomorrow.\nEvery call was sound for the context we had, and that context was incomplete in a way nobody could see yet.
\nThe lesson is smaller and harder to sit with: the boundaries you draw earliest are the ones most likely to be invalidated by what you learn later, and the least likely to be revisited once they are.\nThe door wasn't one-way when I walked through it.\nIt became one-way behind me, one reasonable feature at a time.
\nIf you want a structured way to design module boundaries, and the judgment for when to keep modules together or split them apart, that's exactly what I teach in Modular Monolith Architecture.
\nThanks for reading.
\nAnd stay awesome!
\nDapr Workflow lets you write a long-running business process as ordinary C# code, and the sidecar makes it durable by replaying it from a state store after a crash.\n.NET Aspire runs the app, the sidecar, and the state store with a single aspire run command.\nAnything non-deterministic, like DateTime.Now or I/O, has to live in an activity.
Most real business processes don't finish in a single request.
\nAn order gets placed, inventory gets checked, a payment gets charged, stock gets reserved, and the customer gets notified.\nEach step can fail, time out, or need a retry.\nAnd the whole thing has to survive a process restart without losing its place or charging someone twice.
\nWe usually solve this with a pile of queues, a state table, and a lot of defensive code to track where each process is.\nIt works, but the business logic ends up scattered across handlers and database rows, and nobody can read the flow top to bottom anymore.
\nDapr (a graduated CNCF project) has a building block for exactly this: Workflow.\nYou write the process as ordinary C# code, and Dapr makes it durable.\nIf the host crashes halfway through, the workflow picks up right where it left off.
\nIn this article, we'll build a small Dapr Workflow, run it with .NET Aspire, and inspect its state with the Diagrid Dev Dashboard.\nIf you'd rather learn this hands-on, there's also a free Dapr University track built around this exact stack.
\nLet's dive in.
\nYou define a workflow that orchestrates a process, and activities that do the actual work (call a database, hit an API, send an email).\nThis is orchestration rather than choreography: one place drives the process instead of services reacting to each other's events.
\nThe definitions live in your app; the workflow engine that executes them runs in the Dapr sidecar:
\n\n The key idea is durable execution.\nDapr records every step to a state store, so the workflow can be replayed from history at any time.\nA crash, a deployment, or a scale-out event doesn't lose progress, and a workflow can run for seconds or for months.
\nOne rule follows from this: workflow code must be deterministic.\nNo DateTime.Now, no random values, no I/O - anything non-deterministic goes into an activity.\nEven logging is affected: use context.CreateReplaySafeLogger<T>() inside a workflow, or every replay will repeat your log lines.
Under the hood, this all runs on Dapr actors, which is why the state store must support actors. More on that in a moment.
\nThe quickest starting point is the Aspire CLI's starter template:
\naspire new aspire-starter -n OrderProcessing\nIt generates the app host, an API service, and a ServiceDefaults project that wires up OpenTelemetry and health checks (that's where the AddServiceDefaults call comes from later).\nIf you're on Claude Code, the Dapr Skills plugin can scaffold the entire workflow project from a prompt and review it for determinism mistakes.\nEverything we build here is also in a working sample on my GitHub, so you can clone it and follow along.
The API service needs the Dapr.Workflow package:
<PackageReference Include="Dapr.Workflow" Version="1.18.1" />\nA workflow derives from Workflow<TInput, TOutput> and reads top to bottom like a normal method, even though every step is durably persisted:
using Dapr.Workflow;\n\nnamespace OrderApi.Workflows;\n\ninternal sealed class OrderProcessingWorkflow : Workflow<OrderPayload, OrderResult>\n{\n public override async Task<OrderResult> RunAsync(\n WorkflowContext context,\n OrderPayload order)\n {\n // 1. Check inventory\n var inventory = await context.CallActivityAsync<InventoryResult>(\n nameof(CheckInventoryActivity),\n order);\n\n if (!inventory.InStock)\n {\n return new OrderResult(order.OrderId, "Rejected: out of stock");\n }\n\n // 2. Charge the customer\n await context.CallActivityAsync(\n nameof(ProcessPaymentActivity),\n new PaymentRequest(order.OrderId, order.TotalAmount));\n\n // 3. Reserve the stock\n await context.CallActivityAsync(\n nameof(UpdateInventoryActivity),\n order);\n\n // 4. Notify the customer\n await context.CallActivityAsync(\n nameof(NotifyCustomerActivity),\n order.CustomerId);\n\n return new OrderResult(order.OrderId, "Completed");\n }\n}\nCallActivityAsync doesn't invoke the activity directly.\nIt schedules the work with the workflow engine, which records the result once the activity completes.\nIf the process dies after the payment step, Dapr replays the workflow, feeds it the recorded results for completed steps, and resumes at the inventory update.\nThe customer never gets charged twice.
This is the task chaining pattern.\nDapr Workflow also supports fan-out/fan-in, external events, timers, and child workflows - all in plain C# (fan-out is just Select plus Task.WhenAll).\nIf you want to build the richer patterns hands-on, the free Build Dapr Workflows in .NET with Aspire track has you fan out to parallel activities and aggregate the results.
One production caveat: the recorded history is tied to the shape of your code, so changing a workflow while instances are in flight breaks their replay.\nThat's solved with workflow versioning; we're staying on version one here.
\nAn activity is where the real work happens, and the only place you're allowed to be non-deterministic.\nIt derives from WorkflowActivity<TInput, TOutput> and supports constructor injection:
using Dapr.Workflow;\n\nnamespace OrderApi.Activities;\n\ninternal sealed class CheckInventoryActivity(IInventoryService inventory)\n : WorkflowActivity<OrderPayload, InventoryResult>\n{\n public override async Task<InventoryResult> RunAsync(\n WorkflowActivityContext context,\n OrderPayload order)\n {\n bool inStock = await inventory.HasStockAsync(order.ProductId, order.Quantity);\n\n return new InventoryResult(inStock);\n }\n}\nThe other activities follow the same shape: charge the card, decrement stock, send the confirmation email.\nEach one is isolated, so Dapr can retry a failed activity without re-running the whole workflow.\nAnd since every input and output gets serialized to the state store, simple JSON-friendly records are the right tool for these types.
\nRegister the workflow and its activities in the API service's Program.cs:
builder.Services.AddDaprWorkflow(options =>\n{\n options.RegisterWorkflow<OrderProcessingWorkflow>();\n\n options.RegisterActivity<CheckInventoryActivity>();\n options.RegisterActivity<ProcessPaymentActivity>();\n options.RegisterActivity<UpdateInventoryActivity>();\n options.RegisterActivity<NotifyCustomerActivity>();\n});\nThis also registers a DaprWorkflowClient we can use to start and query workflow instances:
app.MapPost("/orders", async (\n OrderPayload order,\n DaprWorkflowClient workflowClient) =>\n{\n string instanceId = await workflowClient.ScheduleNewWorkflowAsync(\n name: nameof(OrderProcessingWorkflow),\n instanceId: order.OrderId,\n input: order);\n\n return Results.Accepted($"/orders/{instanceId}", new { instanceId });\n});\n\napp.MapGet("/orders/{instanceId}", async (\n string instanceId,\n DaprWorkflowClient workflowClient) =>\n{\n WorkflowState? state = await workflowClient.GetWorkflowStateAsync(instanceId);\n\n if (state is null || !state.Exists)\n {\n return Results.NotFound();\n }\n\n return Results.Ok(new\n {\n RuntimeStatus = state.RuntimeStatus.ToString(),\n Output = state.ReadOutputAs<OrderResult>()\n });\n});\nScheduleNewWorkflowAsync returns immediately and the workflow runs in the background.\nIt's the same idea as scaling long-running API requests: return 202 Accepted and let the client poll for status.\nTwo SDK quirks worth knowing: GetWorkflowStateAsync returns null for an instance it has never seen, and RuntimeStatus is an enum that serializes as a bare number without the ToString().
Here's where Aspire earns its keep.\nA Dapr Workflow needs a sidecar and a state store running alongside the app, and Aspire orchestrates all of it from one place.
\n![\"Architecture](\"https://milanjovanovic.tech/blogs/mnw_198/workflow-app-aspire.png\")
\n The app host needs two packages.\nThe Dapr integration lives in the Aspire Community Toolkit these days; the original Aspire.Hosting.Dapr package is deprecated.
<PackageReference Include="CommunityToolkit.Aspire.Hosting.Dapr" Version="13.0.0" />\n<PackageReference Include="Aspire.Hosting.Valkey" Version="13.4.3" />\nThen the app host:
\nusing CommunityToolkit.Aspire.Hosting.Dapr;\n\nvar builder = DistributedApplication.CreateBuilder(args);\n\nbuilder.AddDapr();\n\n// Pin the password. Aspire generates a random one on every run otherwise,\n// and the Dapr component file below has to know it.\nvar statePassword = builder.AddParameter(\n "statestore-password", "state-store-123", secret: true);\n\n// Valkey (a Redis fork) as the workflow state store\nvar statestore = builder\n .AddValkey("statestore", 16379, statePassword)\n .WithDataVolume();\n\nbuilder.AddProject<Projects.OrderApi>("order-api")\n .WithDaprSidecar(new DaprSidecarOptions\n {\n ResourcesPaths = ["./Resources"]\n })\n .WaitFor(statestore);\n\nbuilder.Build().Run();\nWithDaprSidecar runs a Dapr sidecar next to order-api, and ResourcesPaths points it at the Dapr component files (relative paths resolve against the app host directory).
The one component the workflow needs is a state store - a statestore.yaml in the app host's Resources folder:
apiVersion: dapr.io/v1alpha1\nkind: Component\nmetadata:\n name: workflowstore\nspec:\n type: state.redis\n version: v1\n metadata:\n - name: redisHost\n value: 'localhost:16379'\n - name: redisPassword\n value: 'state-store-123'\n - name: actorStateStore\n value: 'true'\nThat actorStateStore: "true" line is the one people forget.\nDapr Workflow runs on top of actors, so without it, workflows won't run.\nNotice the application never sees any of this: swapping Valkey for Postgres means editing this YAML file, not your C# code.
Install the Dapr CLI and run dapr init once (that's where the sidecar binary comes from), then start everything with a single command:
aspire run\nAspire spins up Valkey, the Dapr sidecar, and the API, with logs, traces, and health in one dashboard.\nGrab the API's port from there and post an order:
\ncurl -X POST http://localhost:5555/orders \\\n -H "Content-Type: application/json" \\\n -d '{"orderId":"order-001","customerId":"cust-42","productId":"pro-plan","quantity":2,"totalAmount":49.99}'\nPoll the status endpoint and you'll see the workflow march through its activities (if the first request returns a 500, give the sidecar a few more seconds to connect to the placement service):
curl http://localhost:5555/orders/order-001\n{\n "runtimeStatus": "Completed",\n "output": {\n "orderId": "order-001",\n "status": "Completed"\n }\n}\nEach activity shows up as a span in the distributed trace:
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_198/aspire_distributed_trace_order_creation.png\")
\nThe Aspire dashboard shows you the request flow, but not the workflow's internal state: which step it's on, what each activity returned, and the full execution history.\nFor that, there's the Diagrid Dev Dashboard: a free, local-only tool that reads your workflow state store (Redis-compatible, Postgres, or SQLite) and visualizes every instance.\nIt comes from Diagrid, the company founded by the creators of the Dapr OSS project, which also provides enterprise Dapr support.
\nSince the whole point of this setup is that one command starts everything, let's add it to the app host:
\nbuilder.AddContainer("diagrid-dashboard", "ghcr.io/diagridio/diagrid-dashboard:latest")\n .WithBindMount("./Resources", "/app/components")\n .WithEnvironment("COMPONENT_FILE", "/app/components/dashboard-store.yaml")\n .WithEnvironment("APP_ID", "diagrid-dashboard")\n .WithHttpEndpoint(targetPort: 8080)\n .WaitFor(statestore);\nWhy a second component file? Networking.\nThe sidecar runs as a host process, so localhost:16379 works for it.\nThe dashboard runs in a container, where localhost means the container itself, so its dashboard-store.yaml reaches the host through host.docker.internal\n(on Linux without Docker Desktop, use the bridge gateway IP instead):
apiVersion: dapr.io/v1alpha1\nkind: Component\nmetadata:\n name: dashboardstore\nspec:\n type: state.redis\n version: v1\n metadata:\n - name: redisHost\n value: 'host.docker.internal:16379'\n - name: redisPassword\n value: 'state-store-123'\n - name: actorStateStore\n value: 'true'\nscopes:\n - diagrid-dashboard\nThe scopes field keeps the API's sidecar from picking up this component, since both files sit in the same Resources folder.
Run aspire run again and open the dashboard's endpoint from the Aspire resources view.\nEvery workflow instance is listed with its status, app ID, and duration:
![\"Diagrid](\"https://milanjovanovic.tech/blogs/mnw_198/diagrid_dashboard_workflows.png\")
\nClicking an instance shows the exact input the workflow received and the output it produced:
\n![\"Workflow](\"https://milanjovanovic.tech/blogs/mnw_198/diagrid_dashboard_workflow_instance.png\")
\nBelow that sits the full execution history - the ground truth of what your workflow actually did.\nExpand a TaskScheduled event to see an activity's input, or a TaskCompleted event to see its input and output:
![\"Execution](\"https://milanjovanovic.tech/blogs/mnw_198/diagrid_dashboard_workflow_history.png\")
\nBeing able to see the workflow's actual state, not just guess at it from logs, is what makes local workflow development feel sane.\nThere's also a Diagrid.Aspire.Hosting.Dashboard package that wraps this container setup into a single AddDiagridDashboard call.
Dapr Workflow gives you durable execution for long-running processes without dragging a heavy orchestration engine into your code:
\nYou can grab the complete source code for this article on my GitHub, including Aspire integration tests for the workflow.
\nIf you want to go deeper, the free Build Dapr Workflows in .NET with Aspire track on Dapr University is the natural next step.\nYou'll build a fan-out/fan-in workflow on this exact stack in a hosted sandbox, with nothing to install.\nThe Dapr Workflow track covers the remaining patterns in standalone examples.
\nThanks for reading.
\nAnd stay awesome!
\nThe original DRY rule is about knowledge, not code that looks the same.\nA fact like a tax rule should have one authoritative home, while two blocks that only resemble each other are separate concepts that will drift.\nExtract on the third occurrence, and only when both copies must change together.
\nEvery developer learns DRY early, and almost everyone learns it wrong.
\nDon't Repeat Yourself.\nSee two pieces of code that look the same, extract a method, delete the duplicate.\nI did this for years and wrote some of the worst code I've ever had to maintain:
\nEvery one started as an innocent attempt to not repeat myself.
\nHere's the part most people skip.\nThe original definition, from Andy Hunt and Dave Thomas in The Pragmatic Programmer,\nsays nothing about code:
\n\n\nEvery piece of knowledge must have a single, unambiguous, authoritative representation within a system.
\n
It's about knowledge. A single fact about your domain, like a tax rule or the format of an invoice number,\nshould live in exactly one place.\nWhen that fact changes, you change it once instead of hunting for seven copies.
\nTwo pieces of code can look identical and represent completely different knowledge.
\nSay you validate two addresses.\nOne is a customer's shipping address, the other is a warehouse address.\nToday the rules are identical:
\npublic bool IsValid(Address address) =>\n !string.IsNullOrWhiteSpace(address.Street) &&\n !string.IsNullOrWhiteSpace(address.City) &&\n !string.IsNullOrWhiteSpace(address.PostalCode);\nThe DRY reflex says extract one validator and call it from both places.\nBut these are different concepts that happen to share rules this week.\nThe day the warehouse needs a loading-dock code,\nyou're back in the shared method bolting on a flag to keep the other caller working:
\npublic bool IsValid(Address address, bool requireDockCode = false) =>\n !string.IsNullOrWhiteSpace(address.Street) &&\n !string.IsNullOrWhiteSpace(address.City) &&\n !string.IsNullOrWhiteSpace(address.PostalCode) &&\n (!requireDockCode || !string.IsNullOrWhiteSpace(address.DockCode));\nThat boolean is the tell.\nThe first time a shared method grows a flag so one caller behaves differently, you didn't have duplication.\nYou had two things that looked alike and glued them together.\nGive it a year and the signature has three more flags,\neach one a place where the two concepts were never actually the same.
\nDuplication is far cheaper than the wrong abstraction.
\nCopy-paste is visible and local.\nYou can see both copies, and if they drift apart, that was always allowed.\nThe wrong abstraction is invisible and global.\nEvery caller depends on one shape and bends it to fit, the flags pile up,\nand you end up afraid to touch a method you no longer understand.\nI've spent more time deleting bad abstractions than I ever saved writing them.
\nThis is the hidden coupling cost I wrote about in the abstractions piece,\nand DRY-by-reflex is one of the most common ways it sneaks in.
\nInside one class, a bad helper is annoying. Across module boundaries, it's structural damage.
\nPicture a modular monolith with a Billing module and a Shipping module.\nBoth have an Order.\nA well-meaning engineer notices the two classes share fields and pulls them into a shared type both modules reference:
// Shared.Orders, referenced by both Billing and Shipping\npublic class Order\n{\n public Guid Id { get; set; }\n public string CustomerName { get; set; }\n public decimal Total { get; set; }\n // ...whatever either module happens to need\n}\nNow Billing and Shipping can't evolve independently.\nA change to billing's order forces a recompile, re-test, and redeploy of shipping.\nYou took two bounded contexts that were supposed to be decoupled and welded them together to save a few properties.
\nTwo modules each owning their own Order is the whole point of keeping data inside its boundaries. The shapes are allowed to be similar, modeling the same real-world thing from two points of view that drift over time. It's the same reason vertical slices\ntolerate a little repetition, so each slice can change on its own.
I don't deduplicate the second time I see something.\nI wait for the third, and I ask one question: if this rule changes, do both copies have to change together?
\nLet the code repeat until the right abstraction becomes obvious,\nbecause good abstractions are discovered from concrete cases, not guessed up front.\nSome people call this AHA, for "Avoid Hasty Abstractions."
\nA practical tell: extract when you can name the concept.\nA real domain name like Money, TaxRate, or InvoiceNumber is probably knowledge worth a value object.\nIf the best name you can find is Helper, Utils, or ProcessData, you're abstracting shape, not knowledge.
Applied correctly, DRY is invaluable.\nA business rule belongs in exactly one place.\nWatch what happens when "an order over $1,000 needs manager approval" gets copy-pasted across three services:
\n// OrderService\nif (order.Total > 1000) { /* require approval */ }\n\n// CheckoutService\nif (order.Total > 1000m) { /* require approval */ }\n\n// AdminController - someone bumped the limit here, and only here\nif (order.Total > 5000) { /* require approval */ }\nYou will eventually update two of them and ship a bug.\nThat drifted third copy is exactly how it happens.\nPush the rule into the domain model where it has one home:
\npublic bool RequiresManagerApproval() => Total > 1000;\nThat's the single authoritative representation DRY is actually about.
\nThe next time you're about to delete a duplicate, don't ask whether the code looks the same.\nAsk whether it means the same.\nThat one question will save you more maintenance pain than DRY ever saved you typing.
\nIf you want to see how I draw these boundaries in a real system,\nwith independent modules and abstractions that earn their place, that's the heart of Pragmatic Clean Architecture.
\nThanks for reading.
\nAnd stay awesome!
\nC# 15, shipping with .NET 11, adds union types as a preview feature.\nA union declares a closed set of types, so a method can return a User or a NotFound and nothing else.\nPattern matching over it is exhaustive, so the compiler flags every switch that misses a case.
Every backend developer eventually hits the same wall: a method that can return one of several things.
\nA parse that either gives you a number or an error.\nA lookup that returns a value or "not found".\nAn operation that succeeds or fails.\nIn C#, we've never had a clean way to model "this is an A or a B".\nSo we faked it - with marker interfaces, abstract base classes, tuples, nullable returns, exceptions,\nor the excellent OneOf library.
C# 15 (shipping with .NET 11) finally adds union types to the language.\nI've wanted this for years, so let me give you a quick tour.
\nLet's dive in.
\nSay a method can return a user or fail because they don't exist. Today you'd reach for something like this:
\n// Throw for the "failure" case - control flow via exceptions\npublic User GetUser(int id) =>\n _users.TryGetValue(id, out var user)\n ? user\n : throw new UserNotFoundException(id);\nThe signature says it returns a User, but that's a lie - it might throw instead. The caller has no way to know that without reading the body. The other usual workarounds (a bool TryGet with an out parameter, a custom Result class with nullable fields, or a OneOf<User, NotFound>) all add ceremony to express one simple idea.
What you actually want is a closed set of types. That's exactly what a union is.
\nThe syntax is delightfully small. You list a name and the case types:
\npublic union Result<T>(T, Exception);\nThat's it. A Result<T> is now either a T or an Exception - and nothing else. The types don't even need to be related, which is the whole point.
Here's a more concrete example with unrelated record types:
\npublic record CreditCard(string Last4, string Brand);\npublic record PayPal(string Email);\npublic record BankTransfer(string Iban);\n\npublic union PaymentMethod(CreditCard, PayPal, BankTransfer);\nThere's an implicit conversion from each case type, so you just assign the value directly:
\nPaymentMethod method = new CreditCard("4242", "Visa");\nTry to assign a type that isn't in the set, and it's a compile error. The set is closed.
\nThis is where it shines. Pattern matching just works, and the compiler checks the inner value for you:
\nstring Describe(PaymentMethod method) => method switch\n{\n CreditCard card => $"{card.Brand} ending {card.Last4}",\n PayPal paypal => $"PayPal ({paypal.Email})",\n BankTransfer ach => $"Bank transfer to {ach.Iban}",\n}; // No `_` or `default` needed\nNotice there's no discard _ and no default arm. Because the union is closed, the compiler knows all three cases are covered. Forget one, and you get a warning at compile time:
warning CS8509: The switch expression does not handle all possible values\nof its input type (it is not exhaustive). For example, the pattern 'BankTransfer'\nis not covered.\nThat exhaustiveness check is the feature I'm most excited about. Add a new case to the union later, and the compiler points you at every switch you forgot to update.
Remember our lying GetUser method from earlier? Let's fix it with a union.
First, declare what the method can actually return - a User or a NotFound:
public record NotFound(int Id);\n\npublic union UserResult(User, NotFound);\nNow the signature tells the truth, and there are no exceptions for control flow:
\npublic UserResult GetUser(int id) =>\n _users.TryGetValue(id, out var user)\n ? user\n : new NotFound(id);\nAnd the caller has to handle both outcomes - the compiler won't let them forget:
\nIResult response = GetUser(42) switch\n{\n User user => Results.Ok(user),\n NotFound found => Results.NotFound($"No user with id {found.Id}"),\n};\nThat's the whole pitch. The return type tells you the truth: here are exactly the shapes you'll get back, and you can't ignore one by accident. No more reading the method body to discover what it might throw.
\nThis is still a preview/experimental feature. A few things to keep in mind:
\nstruct that boxes value-type cases and stores the contents as a single object?. There's a non-boxing path for performance-sensitive code, but the default is simple.A or a B), not a full discriminated union with named cases yet. It covers the vast majority of what I reach for OneOf for today.Union types close a gap that's been open in C# for a very long time.
\npublic union Name(A, B, C);.default arm required.It's a small syntax with a big payoff: your method signatures finally tell the truth about what they return, and the compiler keeps every switch honest.
I'll explore this feature more in the future, but I wanted to share this quick tour now that it's available in preview.
\nThanks for reading.
\nAnd stay awesome!
\nA long-running endpoint should accept the work instead of doing it.\nValidate the input, persist a job row with a Pending status, and return 202 Accepted with an ID the client can poll.\nWhen the in-process worker starts competing with your API for CPU and connections, move it behind a queue so the two sides scale independently.
Every system I've worked on eventually grows an endpoint that takes minutes to finish (or longer).\nA report that aggregates years of data. A bulk import. A workflow that fans out to three external services and a database before it can answer.
\nYou end up with two problems at once.\nYour users sit on a spinner for several minutes, and your API holds that request open the entire time - burning a thread, a connection, and a slot in your concurrency budget.\nA small traffic spike on that one endpoint could potentially take the rest of the API down with it.
\nI want to walk through the progression I use to fix this.\nIt's the same path the diagram below traces, from "the request just blocks" to a fully decoupled,\nqueue-backed worker pool - the shape I usually call an async API.
\nDepending on your requirements, you might stop at any point along the way - but I want to make sure you understand the full path and the trade-offs at each step.
\n![\"System](\"https://milanjovanovic.tech/blogs/mnw_195/scaling_long_running_requests.png\")
\nA user sends a request. The application server does the work. The work takes five minutes. The connection stays open the whole time.
\nThere is nothing wrong with this approach - it's just paying for correctness with availability.\nThe user experience is bad, and the blast radius is large: every long request you accept is a request you can't accept somewhere else.
\nThe first realization you need to internalize is that the response time and the work duration don't have to be the same thing.
\n![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_195/blocking_api_request.png\")
\nThe first move is to stop doing the work inside the request.
\nI add a jobs table that represents the work I intend to do. The API endpoint now does three things:
jobs with status Pending.202 Accepted with a job ID.A background processor running inside the same API picks up Pending rows and works through them.\nThe client either polls a GET /jobs/{id} endpoint or - better - I push updates via SignalR,\nServer-Sent Events, or email when the job is done.
![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_195/202_accepted_background_processor.png\")
\nThis already buys you a lot.\nThe endpoint returns in milliseconds, the user gets a job ID they can track, and a spike of incoming requests just becomes a spike of rows in a table.\nThat table is cheap to write to.
\nBut there's a ceiling here, and it's easy to hit.
\nThe background processor in Step 1 still lives inside your API process.\nIt competes for the same CPU, memory, and connection pool as your real endpoints.\nIf processing gets heavy or slow, your API starts feeling it - the very thing you were trying to avoid.
\nThe fix is to pull the background processor out into its own deployable, and put a queue between the two.
\nThe API now publishes a message to the queue (and optionally writes the job row for tracking).\nA pool of background workers consumes from the queue and does the actual work - the same shape I covered in event-driven architecture with RabbitMQ.\nThis is the competing consumers pattern, and it gives you something the previous step couldn't: independent scaling.
\n![\"System](\"https://milanjovanovic.tech/blogs/mnw_195/scaling_long_running_requests_final.png\")
\nThree things change once you cross this line:
\nYou also get retryability, pause/resume, structured error handling, and a dead-letter queue for poison messages - effectively for free, because the queue infrastructure already provides them.
\nI'd be lying if I said this was a free upgrade.
\nYou're now running a queue, a worker fleet, and a notification path. That's more moving parts to deploy, monitor, and alert on.\nYour "is this done yet?" semantics are no longer obvious from the HTTP response - the client has to ask, or you have to tell them.\nAnd every job needs to be idempotent, because at-least-once delivery means your workers will see duplicates.
\nIf you only have one slow endpoint and modest traffic, this is overkill.\nA simple "fire-and-forget with status polling" inside the same process is fine.\nDon't reach for a queue until the pain justifies it.
\nYou don't always need to assemble this from parts. A few alternatives I would consider:
\nThe trade-off is the usual one: less operational work, more vendor coupling, and a pricing model you need to model carefully when throughput grows.
\nThe progression is simple, and it generalizes:
\n202.This isn't a microservices argument. It's a separation between accepting work and doing work - two concerns that have very different scaling profiles and very different failure modes.
\nIf you want the full implementation walkthrough, the video version is here.
\nThanks for reading.
\nAnd stay awesome!
\nA use case is not a transaction.\nOnce it touches more than one system, some side effects can succeed while others fail, and you have to design for that.\nClassify every side effect as transactional, external and reversible, or external and irreversible, then commit the transactional work last and push irreversible work through the outbox.
\nOne of the recurring bugs I've chased over the years is the "duplicate charge" support ticket.
\nThe customer was charged once, but our system thought the payment had failed.\nThe payment provider had taken the money, the order had rolled back to a draft state, and the user had received a "Payment failed, please retry" email on top of it.\nA single user action left every subsystem with a different opinion about what actually happened.
\nA use case looks like a transaction because it sits behind a single method call.\nBut the moment it touches more than one system, you are dealing with partial failure.
\nHere's how I think about it:
\nLet's dive in.
\nHere's a typical "place an order" use case.\nI've written this exact shape a hundred times, and so have you.
\ninternal sealed class PlaceOrder(\n IOrderRepository orders,\n IPaymentService payments,\n IEmailService emails,\n IUnitOfWork unitOfWork)\n{\n public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)\n {\n var order = Order.Create(request.CustomerId, request.Items);\n orders.Insert(order);\n\n await payments.ChargeAsync(order.Id, order.Total, ct);\n\n await emails.SendOrderConfirmationAsync(order.Id, ct);\n\n await unitOfWork.SaveChangesAsync(ct);\n return Result.Success();\n }\n}\nThere are three side effects in this method, sitting behind what looks like a single transactional boundary, with no coordination between them.
\nIf SaveChangesAsync throws after ChargeAsync succeeded, you've taken the customer's money and lost the order.\nIf SendOrderConfirmationAsync throws, the order saves and the charge goes through, but no email is sent.\nAnd if you naively retry, you double-charge.
The use case "works" until it doesn't, and when it doesn't, it tends to fail in a different way every time.
\nBefore you write a single line of recovery code, classify every side effect into one of three buckets:
\nThe category determines the strategy. There is no single "handle errors properly" rule that covers all three.
\nThe first move is mechanical.\nAnything transactional should commit last, after all external calls have either succeeded or been explicitly tolerated.
\npublic async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)\n{\n var order = Order.Create(request.CustomerId, request.Items);\n\n var charge = await payments.ChargeAsync(order.Id, order.Total, ct);\n if (charge.IsFailure) return charge;\n order.MarkPaid(charge.Value.TransactionId);\n\n orders.Insert(order);\n\n await unitOfWork.SaveChangesAsync(ct);\n return Result.Success();\n}\nYou can't always do this - sometimes you need a database ID before calling the external service.\nThat's fine.\nThe point isn't ordering for its own sake. It's making sure that if you commit, you've already done the work the commit promises.
\nThis is where the Outbox pattern earns its keep.
\nInstead of sending the email directly, raise an OrderPlaced domain event and let an outbox dispatcher pick it up after the transaction commits.
public async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)\n{\n var order = Order.Create(request.CustomerId, request.Items);\n\n var charge = await payments.ChargeAsync(order.Id, order.Total, ct);\n if (charge.IsFailure) return charge;\n order.MarkPaid(charge.Value.TransactionId);\n\n orders.Insert(order);\n order.Raise(new OrderPlacedEvent(order.Id));\n await unitOfWork.SaveChangesAsync(ct);\n\n return Result.Success();\n}\nThe email is no longer the use case's problem.\nIf the transaction commits, the event commits with it inside the same write.\nIf it doesn't, the event never escapes the database and no email is ever sent.\nA separate worker turns events into emails, with its own retries and its own idempotency guarantees.
\nThe payment call is the dangerous one.\nIf it succeeds and your transaction rolls back, you've taken money you can't account for.
\nWhat you do not do is silently swallow the failure:
\ntry\n{\n await payments.ChargeAsync(order.Id, order.Total, ct);\n}\ncatch\n{\n // shrug\n}\nThe symptom disappears from your logs, the money stays gone, and the next time the user retries you charge them again.
\nThere are two approaches I actually use, and they compose well together.
\nMost serious payment providers (Stripe, Adyen, Braintree) let you attach an idempotency key to a charge.\nA retry with the same key is a no-op on their side and returns the original result.\nThe natural key here is the order ID:
\nvar charge = await payments.ChargeAsync(\n new ChargeRequest\n {\n OrderId = order.Id,\n Amount = order.Total,\n IdempotencyKey = order.Id.ToString()\n },\n ct);\nNow it's safe to retry the use case.\nIf the previous attempt charged the customer and crashed before committing, the next attempt gets the same charge back from the provider instead of creating a new one, and the order finally gets persisted.
\nIdempotency keys only help when you can replay with the same inputs.\nSometimes you can't - the user gave up, the request was cancelled, or the failure is permanent.
\nIn that case, the money is real and needs to come back.\nMake the failure itself a first-class event and refund out-of-band:
\npublic async Task<Result> ExecuteAsync(PlaceOrderRequest request, CancellationToken ct)\n{\n var order = Order.Create(request.CustomerId, request.Items);\n\n var charge = await payments.ChargeAsync(order.Id, order.Total, ct);\n if (charge.IsFailure) return charge;\n order.MarkPaid(charge.Value.TransactionId);\n\n try\n {\n orders.Insert(order);\n order.Raise(new OrderPlacedEvent(order.Id));\n await unitOfWork.SaveChangesAsync(ct);\n }\n catch (Exception ex)\n {\n await outbox.PublishAsync(\n new PaymentFailedEvent(\n order.Id,\n charge.Value.TransactionId,\n order.Total,\n Reason: ex.Message),\n ct);\n throw;\n }\n\n return Result.Success();\n}\nA background consumer subscribes to PaymentFailedEvent and issues the refund, using the transaction ID as its own idempotency key.\nThis turns a scary cross-process compensation into a normal, observable, retryable message handler.
In practice, I use Approach A for transient failures and Approach B for permanent ones. They aren't mutually exclusive.
\nThe strategies above work when one use case coordinates a small number of side effects in a single service.\nOnce the work spans multiple services and needs to survive process restarts, you're in saga territory.
\nThe rule I use: if you can fit the recovery logic in your head, a well-designed use case is enough. If you can't, reach for a saga.
\nA use case is a unit of intent, not a unit of atomicity.
\nMost of the production bugs I've debugged in event-driven systems come down to a use case that lied about whether it succeeded.\nStop lying, and the system gets a lot easier to reason about.
\nIf you want to see this kind of thinking applied across a full system, that's exactly what I build inside Modular Monolith Architecture.
\nThanks for reading.
\nAnd stay awesome!
\nVersion an API only when the old and new semantics cannot safely coexist.\nMost breaking changes are avoidable: add a new field or a new operation next to the old one, leave shipped behavior alone, and keep new request data optional.\nThen deprecate the old shape with runtime headers and usage telemetry before removing it.
\nI've written before about implementing API versioning in ASP.NET Core.
\nBut the more important question isn't how to version an API.\nIt's when.
\nEvery API team eventually reaches for the same escape hatch:
\n\n\nJust create
\nv2.
It sounds responsible.\nExcept now you maintain two APIs, two sets of docs, two behaviors, and a migration project clients will postpone for as long as possible.
\nI also touched on this briefly in my REST API design mistakes article, but I want to make the point more directly today:
\nVersioning is a compatibility tool. It is not a design strategy.
\nMost API changes do not require a new version.\nThey require better change management.
\nAnd that distinction matters.
\nIf you treat every contract change as a versioning problem, you end up cloning APIs.\nIf you treat it as a change management problem, you start asking better questions:
\nThat mindset leads to APIs that age much better.
\nBreaking changes usually aren't about the URL alone.
\nClients break when you:
\nThis breaks a client just as surely as deleting an endpoint:
\n// Before\n{ "total": 100 }\n\n// After\n{ "total": { "amount": 100, "currency": "USD" } }\nYou didn't change the path.\nYou didn't rename the endpoint.\nYou still broke clients.
\nSo instead of asking, "Should this be v2?", ask, "Can the old and new contract safely coexist?"
\nI'll use a simple orders API as the running example for the rest of the article.
When I want an API to age well, I keep four rules in mind:
\nThese map directly onto the four rules from Z. Nemec's API Change Management article: don't take anything away, don't change processing rules, don't make optional things required, and anything you add must be optional.
\nIf you follow those rules, many "versioning problems" turn back into ordinary contract evolution.
\nThe safest change is usually an additive one.
\nLet's say your original GET /orders/{id} response looked like this:
{\n "id": "ord_123",\n "status": "paid",\n "total": 100\n}\nInstead of replacing total, add a new field:
{\n "id": "ord_123",\n "status": "paid",\n "total": 100,\n "totalMoney": {\n "amount": 100,\n "currency": "USD"\n }\n}\nExisting clients keep using total.\nNew clients can migrate to totalMoney.\nYou mark the old field as deprecated and remove it only after a real migration window.
The same idea applies beyond fields.\nIf you need richer semantics, don't mutate a field into a different shape.\nAdd a new field, a new link, or a new operation that carries the new meaning explicitly.
\nSometimes an ugly contract is the price of compatibility.
\nA well-behaved client should not explode because the server added a field it doesn't understand.
\nIf the response evolves from this:
\n{\n "id": "ord_123",\n "status": "paid"\n}\nto this:
\n{\n "id": "ord_123",\n "status": "paid",\n "estimatedDeliveryDate": "2026-05-29"\n}\nolder clients should ignore the extra property and keep working.
\nIn .NET, System.Text.Json helps because unknown properties are ignored by default.\nThe real risk is usually overly strict generated SDKs or contract tests that assert exact JSON equality.
This is one of the most common self-inflicted problems I see.\nTeams say they want backward compatibility, then generate client models that reject any unexpected field in the response.
\nThat is not a compatibility strategy.\nThat is a trap.
\nYour server should be free to add optional data.\nYour clients should be resilient enough to ignore what they don't understand.
\nFields and shapes get most of the attention in compatibility discussions, but the most dangerous breaking changes hide in behavior.
\nThe URL is the same.\nThe request body is the same.\nThe response shape is the same.\nWhat the operation does on the server is different.
\nTake DELETE /orders/{id}.
When the API shipped, that endpoint was a soft delete.\nThe order moved into an archived state, stayed in the database, still showed up in audit reports, and could be restored by support.
The contract that clients built on wasn't just the HTTP verb and the path.\nIt was the full behavior:
\nMonths later, the team decides soft-delete is messy.\nThe "fix" turns DELETE /orders/{id} into a hard delete:
No client noticed at code-review time.\nThe SDK call still compiles.\nThe response is still 204 No Content.\nA support tool that used to call DELETE and then "undo" it now silently destroys data.
This is exactly the kind of change Z. Nemec's rules call out:\nyou must not change the processing rules of an existing operation.\nOnce clients have integrated, the behavior is the contract, even if it was never written down anywhere.
\nThe same pattern shows up in subtler ways:
\nPOST /orders used to be idempotent on a client-supplied key, then quietly stops beingPOST /orders/{id}/cancel used to refund automatically, then stops issuing refunds because "refunds should be a separate call"PUT /orders/{id} used to be a full replace, then becomes a partial mergeEach of these keeps the URL, the verb, and the JSON shape stable.\nEach one breaks every existing integration in a way that won't show up in a schema diff.
\nThe safe move is the same as before: add, don't mutate.
\nIf you want a hard delete, expose it as a new operation and leave the old one alone:
\nDELETE /orders/{id} # still soft-delete, unchanged\nDELETE /orders/{id}?purge=true # new, opt-in hard delete\nOr introduce a new resource entirely (DELETE /orders/{id}/purge) so the destructive behavior has its own name and its own permissions.
The rule is simple: once an operation ships, its behavior is part of the contract.\nYou can add new operations next to it.\nYou can deprecate it.\nYou cannot quietly change what it does.
\nThis one is underrated.
\nThere are two flavors of the same mistake:
\nBoth break older clients in exactly the same way.\nThe endpoint path doesn't move, but requests that used to succeed now get rejected.
\nHere's a simple example using POST /orders.
Yesterday this request was valid:
\n{\n "customerId": "cus_123",\n "currency": "USD"\n}\nToday the API requires a country for tax calculation:
\n{\n "customerId": "cus_123",\n "currency": "USD",\n "country": "US"\n}\nWhether country was previously optional or didn't exist at all, the result is the same: every existing integration starts failing at runtime.
A safer path is to accept missing values for older clients, infer defaults where possible, or introduce a new operation for the stricter workflow.
\nFor example:
\ncountry during a transition windowPOST /checkout-sessions flow that requires the richer request modelResponse changes usually get careful design review.\nRequest validation changes deserve the same scrutiny.\nAnd the underlying rule is the one that catches both flavors: anything you add to the contract has to be optional, and anything that was optional has to stay optional.
\nSometimes the use case really did change enough that piling more flags and optional parameters onto an existing endpoint becomes confusing.
\nThis is what a bad evolution path looks like:
\nPOST /orders?validateOnly=true&includeTaxEstimate=true&reserveInventory=true\nAt that point you don't have one clean operation.\nYou have multiple workflows hiding behind one endpoint.
\nThat's when I prefer a new operation or resource over a whole API version.
\nPOST /orders\nPOST /orders/quote\nPOST /checkout-sessions\nThis keeps the old contract stable while giving the new behavior a clean home.
\nPOST /orders stays the simple "place an order" endpoint.\nPOST /orders/quote becomes the "tell me what this would cost" operation.\nPOST /checkout-sessions can support a richer, more guided flow without contaminating the original contract.
That is usually much cheaper than creating /v2/orders and dragging the rest of your API along with it.
This is the missing half of API change management.
\nMost deprecations are fake.\nThey exist in docs, but nothing operational happens.
\nA real deprecation process should include four things:
\nIf you're on HTTP, runtime signaling can be as simple as response headers like these:
\nDeprecation: true\nSunset: Wed, 31 Dec 2026 23:59:59 GMT\nLink: <https://docs.example.com/migrations/orders-total>; rel="deprecation"\nNow the deprecation is visible in the docs, visible in live traffic, and connected to an actual migration guide.
\nAnd this is where telemetry matters.\nIf you don't know which clients still use the deprecated field or endpoint, you are not managing change.\nYou are guessing.
\nTrack usage by client ID, API key, tenant, or application name.\nThen wait until usage is effectively gone before removing anything.
\nI am not anti-versioning.
\nVersion when the old and new semantics cannot coexist safely.\nVersion when the resource model changed fundamentally.\nVersion when compatibility rules would force you into a contract nobody can reason about.
\nIn those cases, version deliberately.
\nAnd deliberate versioning means choosing the smallest break you can justify.
\nSometimes that's a new endpoint shape.\nSometimes it's a representation variant.\nSometimes, especially for public APIs, it's straightforward URL versioning because it is explicit and easy to communicate.
\nThe key is not which mechanism you pick.\nThe key is that you reached for it because coexistence failed, not because it was the first idea on the table.
\nAnd if you do version, pair it with an actual deprecation process:
\nThe real work is not creating v2.\nThe real work is getting consumers off v1.
The best API version is often the one you never have to create.
\nIf you want a simple decision rule, use this:
\nIf the answer is yes, you probably don't need a new version.
\nIf the answer is no, and the old and new worlds genuinely cannot live side by side, version deliberately.
\nThat's the real point.
\nDesign contracts to evolve.\nTreat clients as long-lived integrations, not just today's code.\nAnd reserve versioning for the cases where compatibility truly runs out.
\nIf you want to go deeper on designing and evolving HTTP APIs, check out Pragmatic REST APIs.\nIt's where I cover the patterns, trade-offs, and implementation details I use when building APIs that need to survive real clients and real change.
\nThanks for reading.
\nAnd stay awesome!
\nAn invariant is a business rule that an object must satisfy at all times, not only at the point where some handler or validator checks it.\nThe cleanest place to enforce one is the domain model: block construction of invalid objects, put state changes behind methods that own the rules, and keep aggregate-wide rules on the root.
\nA lot of the "DDD-ish" .NET code I review scatters business rules across handlers, validators,\nand controllers, and barely puts any on the domain model itself.
\nEach copy of the same rule drifts a little over time, and whether a given object is valid starts to depend on which path the caller took to reach it.
\nYou can absolutely build a working system this way.\nI've shipped plenty of procedural code with enough if-checks to keep things in line.\nBut there's a cleaner way to think about it, and it starts with a single idea.
An invariant is a rule about an object that must hold true for as long as the object exists.
\nNot just when you save it, or when a validator happens to run.\nThe rule has to hold every time you touch the object, no matter how it got into memory.
\nA few examples:
\nCourse always has a non-empty title.Order total always equals the sum of its line items.Subscription is in exactly one state: Trial, Active, PastDue, or Canceled.None of these mention validation, persistence, or HTTP.\nThey're statements about the domain, and they should be true regardless of how the object got loaded.
\nTake a simple Course written the way most CRUD-ish .NET apps still write it:
public class Course\n{\n public string Title { get; set; }\n public CourseStatus Status { get; set; }\n public DateTime? PublishedOn { get; set; }\n public decimal Price { get; set; }\n}\nThere's no constructor and every property has a public setter, so the class is willing to accept any combination of values.
\nTo keep the data correct, the rules end up scattered across the application:
\nCreateCourseValidator checks the title isn't empty.PublishCourseHandler sets Status and PublishedOn, and remembers to check the course isn't already published.ChangePriceHandler checks the course isn't archived.Every rule lives in a place that just happens to be on the path the request took.\nNothing on the Course itself prevents it from drifting into an invalid state.
That's the real cost of an anemic model.\nIt isn't that there's no behavior on the class.\nIt's that the class makes no promises, so every caller has to enforce the rules itself.
\nThe shift I want to make is simple: the model never accepts an invalid state.
\nIf you're holding a Course reference, you can trust it.\nYou don't need an if (course.Title is null) somewhere down the call stack, you don't need a parallel validator double-checking, and you don't need to hope the handler remembered the right guard.
Three moves get you there.
\nA Course without a title shouldn't exist, so the easiest fix is to make it impossible to construct.
public class Course\n{\n private Course(CourseId id, string title, Money price)\n {\n Id = id;\n Title = title;\n Price = price;\n Status = CourseStatus.Draft;\n }\n\n public static Result<Course> Create(string title, Money price)\n {\n if (string.IsNullOrWhiteSpace(title))\n {\n return CourseErrors.TitleRequired;\n }\n\n return new Course(CourseId.New(), title, price);\n }\n}\nA private constructor with a static factory gives you a single, well-known place where a Course can come into existence, and that's where the validation runs.\nFrom that point on, any code holding a Course reference can assume it has a valid title.
Value objects like Money apply the same idea at a smaller scope, so a Money can't be negative or be missing its currency by the time you're using it.
Once construction is locked down, the next leak is state changes.\nThe class should control how it changes, instead of leaving that up to whoever has a reference to it.\nNo setters, and every change goes through a method that knows the rules.
\npublic Result Publish(IDateTimeProvider clock)\n{\n if (Status != CourseStatus.Draft)\n {\n return CourseErrors.AlreadyPublished;\n }\n\n if (_lessons.Count == 0)\n {\n return CourseErrors.CannotPublishWithoutLessons;\n }\n\n Status = CourseStatus.Published;\n PublishedOn = clock.UtcNow;\n return Result.Success();\n}\nThe handler doesn't need to know whether the course was already published, and it doesn't need to remember to check for empty lessons.\nIt calls Publish and propagates whatever result comes back.\nThe rule lives next to the state it protects, in one place.
Some rules span multiple entities inside the same boundary.\nThe aggregate root is the right place to enforce those, because it's the transactional boundary.
\nTake this rule: a published course must have at least one lesson, and lessons can't be removed once it's published.
\nThe wrong way is to expose Lessons as a mutable collection and rely on the application service to remember the rule everywhere it's used.\nThe right way is to keep the collection private and force every change through the root:
public sealed class Course\n{\n private readonly List<Lesson> _lessons = [];\n public IReadOnlyCollection<Lesson> Lessons => _lessons.AsReadOnly();\n\n public Result RemoveLesson(LessonId id)\n {\n if (Status == CourseStatus.Published)\n {\n return CourseErrors.CannotModifyPublishedLessons;\n }\n\n var lesson = _lessons.FirstOrDefault(l => l.Id == id);\n if (lesson is null)\n {\n return CourseErrors.LessonNotFound;\n }\n\n _lessons.Remove(lesson);\n return Result.Success();\n }\n}\nWhen a rule needs to span two aggregates instead of one, that's a different problem, and I'd reach for a domain event rather than letting one aggregate reach into another.
\nYou can write the same system procedurally, and it can work well.\nThe thing you give up is trust.
\nIn a procedural system, every caller shares responsibility for not breaking the rules.\nIn an always-valid model, that responsibility lives on the domain model.\nThe difference compounds over time:
\nThe model goes from being a passive data carrier to being the smallest, sharpest place where the business rules live.
\nFundamentally, this is about encapsulation.\nThe model encapsulates the rules that govern its state, and the rest of the system interacts with it through a well-defined interface.\nThat leads to cleaner code, fewer bugs, and a more maintainable system overall.
\nAn invariant is a rule that must always hold true while the object exists, and the cleanest place to enforce it is on the object itself.
\nThe tradeoff is that you give up the freedom to write procedural code that could be easier to understand in the short term,\nbut you get a model that you can trust to always be valid.
\nIf you want to go deeper into modeling aggregates, value objects, and rich behavior across a real system,\nI think you will enjoy Pragmatic Domain-Driven Design.
\nSee you next week.
\nThe test pyramid assumes integration tests are slow and expensive, which stopped being true once Testcontainers and the Aspire test host arrived.\nI ship 15-25% unit tests on pure domain logic, 60-70% integration tests against real infrastructure, and under 10% end-to-end tests for business-critical flows.
\nI'll be honest. For years, my projects didn't look like the test pyramid.
\nA wide base of unit tests, a narrow middle of integration tests, a tiny sliver of end-to-end tests at the top.\nI'd nod along in conference talks, then go back to my own code and do something different.
\nA thin layer of unit tests for the things worth unit-testing.\nA thick slab of integration tests against real PostgreSQL, real RabbitMQ, real HTTP.\nA handful of end-to-end tests for the flows that would get me fired if they broke.
\nAnd I shipped with more confidence that way, not less.\nHere's why, and here's the shape I actually use.
\nThe pyramid was popularized by Mike Cohn in 2009, when integration tests meant a shared database server, flaky CI, and 20-minute builds.\nUnit tests with mocks were the pragmatic compromise.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_191/test_pyramid.png\")
\nThat world is gone.\nWith Testcontainers, I can spin up PostgreSQL, Redis, and RabbitMQ in a fresh container per test class in a few seconds.\nThe Aspire test host takes this further by wiring up your entire application graph.\nThe argument that real dependencies are too expensive mostly doesn't apply anymore.
\nBut the advice didn't update.
\nA few years ago I had a service with 94% unit test coverage. All green.
\nA user reported that deleting an account didn't actually delete their data.\nThe bug was three lines long:
\npublic async Task Handle(DeleteAccountCommand command, CancellationToken ct)\n{\n var account = await _repository.GetByIdAsync(command.AccountId, ct);\n account.MarkAsDeleted();\n // Missing: await _unitOfWork.SaveChangesAsync(ct);\n}\nThe honest diagnosis is that the test for this case was never written.\nYou can absolutely verify SaveChangesAsync was called with a mock.\nBut in a codebase where that test is one of hundreds of handler tests, each with its own mock setup and its own verification list, it's the kind of assertion people forget.\nI forgot.
A single integration test against a real database would have caught it without anyone having to remember.\nThat's the point: the fewer invariants your test style forces you to remember, the fewer bugs slip through.
\nThat was the last week I took the test pyramid seriously.
\nI still write unit tests. Just not many.
\nThey earn their keep when the logic is non-trivial, pure (no I/O, no time, no randomness), and hard to exercise end-to-end.\nThat's a specific set of code: value objects and rich domain models, pricing and tax calculations, parsers, mappers, serializers.
\nNotice what's not on that list: application services, handlers, controllers, repositories, infrastructure.\nThose live at the seams, and the seams are where real bugs live.
\nHere's the shape I've settled on for a typical .NET service or modular monolith.
\nMaybe 15-25% of the test count. All domain logic.\nNo mocks of collaborators. If a unit test needs a mock, I usually pull the test up to the integration layer instead.
\n[Fact]\npublic void Confirm_WhenPending_TransitionsToConfirmed()\n{\n var order = Order.Create(CustomerId.New(), Money.Usd(100));\n\n order.Confirm();\n\n order.Status.Should().Be(OrderStatus.Confirmed);\n order.DomainEvents.Should().ContainSingle(e => e is OrderConfirmedEvent);\n}\nNo container or mocks.\nMicroseconds per test.\nThis is what unit tests are for.
\nThe majority. Maybe 60-70% of the suite.\nEvery command and query handler, every HTTP endpoint, every message consumer gets a test that runs against real infrastructure inside Testcontainers.\nIn a modular monolith, this is where you verify that modules talk to each other correctly across their public APIs.
\npublic class DeleteAccountTests(IntegrationTestWebAppFactory factory)\n : BaseIntegrationTest(factory)\n{\n [Fact]\n public async Task DeleteAccount_WhenAccountExists_MarksAccountAsDeleted()\n {\n var account = await CreateAccountAsync();\n\n var response = await HttpClient.DeleteAsync($"/accounts/{account.Id}");\n\n response.StatusCode.Should().Be(HttpStatusCode.NoContent);\n\n var stored = await DbContext.Accounts\n .IgnoreQueryFilters()\n .SingleAsync(a => a.Id == account.Id);\n\n stored.IsDeleted.Should().BeTrue();\n }\n}\nThat test exercises the HTTP layer, routing, model binding, authorization, the handler, the unit of work, EF Core, and PostgreSQL.\nIt proves the thing you actually care about: when I call this endpoint, the row changes.\nAnd it does it without anyone having to remember to assert SaveChangesAsync was called.
Under 10%. Only the flows where a silent failure would be a commercial or compliance problem.\nSignup, payment, refund, password reset, two-factor enrollment.\nThey're slow and occasionally flaky, but they catch the one failure mode everything else misses: the system as a whole still works.
\nOften forgotten, but they're part of the suite.\nArchitecture tests enforce layering and module boundaries.\nContract tests verify that message schemas and API shapes don't drift.\nThey run in milliseconds and catch the "six months from now, someone will break this without realizing" kind of bug.
\nThe shape that comes out of this is closer to Kent C. Dodds' testing trophy than a pyramid.\nThe fat middle is deliberate. That's where my confidence comes from.
\n"Integration tests are slow."\nMy typical integration suite runs in 2-4 minutes in CI with Testcontainers reuse and test-class parallelization.\nSlower than unit tests, yes. Faster than finding the bug in production.
\n"Mocks are fine if you're disciplined."\nMaybe. But every large codebase I've audited that leaned heavily on mocks had the same pathology: tests that pass after a refactor even though the refactor broke production.\nThat's not discipline failing. That's the tool being pointed in the wrong direction.
\nThe test pyramid was good advice for 2009 infrastructure and poor advice for 2026 infrastructure.\nTestcontainers and Aspire changed the economics, and the fastest feedback loop that still tells you the truth is now an integration test against real dependencies.\nUnit tests still belong on pure domain logic. Everything at the seams belongs in the integration layer.
\nIf you want to see how I wire this into a real system, with the integration test harness, module boundaries, and the full Clean Architecture setup, check out Pragmatic Clean Architecture.\nIt's the same approach I use on my own projects.
\nThanks for reading.
\nAnd stay awesome!
\nPrimary constructors let you declare dependencies on the class declaration and use them anywhere in the class body, which removes the fields, the constructor, and the assignments from a typical service class.\nThe catch is that captured parameters are mutable variables, not readonly fields, so nothing stops you from reassigning one.
I'll be honest. I resisted primary constructors for a while.
\nWhen C# 12 extended them from record types to regular classes and structs, my first reaction was skepticism.\nAn implicit mutable capture instead of explicit readonly fields?\nThat felt like trading safety for convenience.
But after using them across several projects, I changed my mind.\nThe boilerplate they eliminate in DI service classes is significant, and the pitfall I was worried about is manageable once you know about it.
\nHere's what convinced me to switch, and the one thing you need to watch out for.
\nHere's what my service classes used to look like:
\npublic class OrderService\n{\n private readonly IOrderRepository _orderRepository;\n private readonly ILogger<OrderService> _logger;\n\n public OrderService(\n IOrderRepository orderRepository,\n ILogger<OrderService> logger)\n {\n _orderRepository = orderRepository;\n _logger = logger;\n }\n\n public async Task<Order?> GetOrderAsync(Guid id)\n {\n _logger.LogInformation("Fetching order {OrderId}", id);\n\n return await _orderRepository.GetByIdAsync(id);\n }\n}\nAnd here's what they look like now:
\npublic class OrderService(\n IOrderRepository orderRepository,\n ILogger<OrderService> logger)\n{\n public async Task<Order?> GetOrderAsync(Guid id)\n {\n logger.LogInformation("Fetching order {OrderId}", id);\n\n return await orderRepository.GetByIdAsync(id);\n }\n}\nThe field declarations, the constructor body, the assignments. All gone.\nThe parameters are captured and available throughout the class body.
\nThis is the most common use case for primary constructors: dependency injection in service classes.\nYou declare what you need, and use it directly.
\nThe place where primary constructors sold me is ASP.NET Core service classes.\nThis is where I spend most of my time, and the boilerplate savings add up fast.
\nHere's a more realistic example from a checkout flow:
\npublic class CheckoutService(\n IPaymentProcessor paymentProcessor,\n IOrderRepository orderRepository,\n ILogger<CheckoutService> logger,\n IOptions<CheckoutOptions> options)\n{\n public async Task<CheckoutResult> ProcessAsync(\n Cart cart,\n CancellationToken ct = default)\n {\n var settings = options.Value;\n\n if (cart.Total < settings.MinimumOrderAmount)\n {\n logger.LogWarning("Order below minimum: {Total}", cart.Total);\n return CheckoutResult.BelowMinimum;\n }\n\n var order = Order.Create(cart);\n\n await paymentProcessor.ChargeAsync(order, ct);\n await orderRepository.SaveAsync(order, ct);\n\n logger.LogInformation("Checkout complete for order {OrderId}", order.Id);\n\n return CheckoutResult.Success;\n }\n}\nFour dependencies, zero boilerplate.\nThe class reads top-to-bottom without any noise.
\nThis pattern works well because service classes typically don't need to validate or transform their dependencies.\nThe DI container provides them, and you use them.\nPrimary constructors are a perfect fit for this.
\nI also started using primary constructors for domain entities and value objects where you want to enforce required parameters at construction time:
\npublic class Order(Guid customerId, Money total)\n{\n public Guid Id { get; } = Guid.NewGuid();\n public Guid CustomerId { get; } = customerId;\n public Money Total { get; } = total;\n public OrderStatus Status { get; private set; } = OrderStatus.Pending;\n public DateTime CreatedAt { get; } = DateTime.UtcNow;\n\n public void Confirm()\n {\n if (Status != OrderStatus.Pending)\n {\n throw new InvalidOperationException(\n $"Cannot confirm order in {Status} status.");\n }\n\n Status = OrderStatus.Confirmed;\n }\n}\nThere's no way to create an Order without a customerId and total.\nThe primary constructor makes this constraint visible at the type declaration level.
Notice the key difference from the service class pattern: here, I'm assigning primary constructor parameters to properties with initializers (= customerId).\nThis is important, and it leads to the biggest pitfall.
This was the reason I held off for so long.
\nPrimary constructor parameters are not readonly fields.
When you use a primary constructor parameter directly in the class body (like we did in the service class), the compiler captures it as a mutable variable.\nThere's no readonly backing field generated behind the scenes.
This means you can accidentally reassign a parameter:
\npublic class OrderService(\n IOrderRepository orderRepository,\n ILogger<OrderService> logger)\n{\n public async Task<Order?> GetOrderAsync(Guid id)\n {\n logger.LogInformation("Fetching order {OrderId}", id);\n\n return await orderRepository.GetByIdAsync(id);\n }\n\n public void SomeOtherMethod()\n {\n // This compiles. No warning. No error.\n orderRepository = null!;\n logger = null!;\n }\n}\nThis compiles without any warning.
\nWith a traditional constructor and private readonly fields, the compiler would stop you immediately.\nWith primary constructors, it stays silent.
If you need immutability guarantees, explicitly assign the parameter to a readonly field:
public class OrderService(\n IOrderRepository orderRepository,\n ILogger<OrderService> logger)\n{\n private readonly IOrderRepository _orderRepository = orderRepository;\n private readonly ILogger<OrderService> _logger = logger;\n\n public async Task<Order?> GetOrderAsync(Guid id)\n {\n _logger.LogInformation("Fetching order {OrderId}", id);\n\n return await _orderRepository.GetByIdAsync(id);\n }\n}\nBut now you've lost most of the benefit of primary constructors.\nYou're back to field declarations and assignments, just with a different syntax.
\nIn practice, I've never actually hit this bug in a DI service class.\nYou're unlikely to accidentally reassign logger in the middle of a method.\nBut it can bite you in entity classes or value types where immutability actually matters.\nThat's the one place where I still stay cautious.
I haven't switched everything over.\nHere are the cases where I stick with the traditional approach:
\nComplex validation logic. If you need to validate parameters before assigning them, you need a constructor body:
\npublic class EmailAddress\n{\n private readonly string _value;\n\n public EmailAddress(string value)\n {\n if (string.IsNullOrWhiteSpace(value) || !value.Contains('@'))\n {\n throw new ArgumentException(\n "Invalid email address.", nameof(value));\n }\n\n _value = value;\n }\n}\nPrimary constructors don't give you a place to put validation logic before the class body runs.
\nMultiple constructor overloads. Primary constructors support one constructor signature.\nIf you need overloads, you'll have to chain secondary constructors with this(...), which gets messy fast.
Too many parameters. Once you hit 5+ dependencies, the primary constructor line becomes hard to read.\nAt that point, your class probably has too many responsibilities, and refactoring it is a better solution than formatting tricks.
\nHere's what I've settled on after using primary constructors across several projects:
\nreadonly fields. This is the one thing you need to know.The switch was worth it.\nMy service classes are shorter, easier to scan, and the pitfall is manageable with the right tooling.
\nThat's all for today.\nSee you next week.
\nA saga in Wolverine is a class that extends Saga with a Handle method per message type, returning new messages to move the workflow forward.\nWolverine persists the state and correlates each message to the right saga instance by convention.\nA message extending TimeoutMessage schedules the compensation path if the expected event never arrives.
Long-running business processes don't fit neatly into a single request.
\nThink about user onboarding: you register the user, send a verification email, wait for them to verify, and then send a welcome email.\nEach step depends on the previous one.\nIf the user never verifies, you need a way to handle that.
\nThe Saga pattern breaks this into a sequence of steps, each with its own message and handler.\nIf a step fails or times out, the saga runs compensation logic instead of leaving the system in a broken state.
\nI've covered sagas with MassTransit and Rebus before.\nBoth work well, but their state machine DSLs come with a fair amount of ceremony.\nSince MassTransit moved to a commercial license, more teams have been exploring Wolverine as an alternative.
\nWolverine takes a different approach - you write a class that extends Saga, define Handle methods for each message type, and cascade new messages from return values.\nWolverine handles routing, persistence, and correlation automatically.
We need RabbitMQ for message transport and PostgreSQL for durable saga state and messaging.
\nvar connectionString = builder.Configuration.GetConnectionString("user-mgmt");\n\nbuilder.Host.UseWolverine(options =>\n{\n options.UseRabbitMqUsingNamedConnection("rmq")\n .AutoProvision()\n .UseConventionalRouting();\n\n options.Policies.DisableConventionalLocalRouting();\n\n options.PersistMessagesWithPostgresql(connectionString!);\n});\nAutoProvision creates RabbitMQ exchanges and queues automaticallyUseConventionalRouting routes messages to queues based on message type namesDisableConventionalLocalRouting forces all messages through RabbitMQ instead of in-process handlingPersistMessagesWithPostgresql stores saga state and messages in PostgreSQL. Wolverine uses lightweight saga storage to create a table per saga type, and the durable messaging infrastructure ensures nothing is lost if the process crashesWolverine gives you three ways to persist saga state.\nLightweight storage (what we're using) serializes saga state as JSON in a per-saga table with zero ORM config.\nMarten stores sagas as Marten documents with optimistic concurrency and strong-typed IDs.\nEF Core maps sagas into a flat, queryable table and lets you commit saga state with other data in a single transaction.\nIf you just need saga state management, lightweight storage is the simplest path.
\nRequired packages:
\n<PackageReference Include="WolverineFx" Version="5.16.2" />\n<PackageReference Include="WolverineFx.Postgresql" Version="5.16.2" />\n<PackageReference Include="WolverineFx.RabbitMQ" Version="5.16.2" />\nBefore building the saga, let's define all the messages it will work with:
\npublic record SendVerificationEmail(Guid UserId, string Email);\npublic record VerificationEmailSent(Guid Id);\n\npublic record VerifyUserEmail(Guid Id);\n\npublic record SendWelcomeEmail(Guid UserId, string Email, string FirstName);\npublic record WelcomeEmailSent(Guid Id);\n\npublic record OnboardingTimedOut(Guid Id) : TimeoutMessage(5.Minutes());\nOnboardingTimedOut extends Wolverine's TimeoutMessage, which automatically schedules a delayed delivery.\nWhen the saga starts, Wolverine will deliver this message after 5 minutes.\nIf the user hasn't verified by then, the saga compensates.
Here's how the saga transitions between states:
\n![\"Saga](\"https://milanjovanovic.tech/blogs/mnw_189/saga_pattern_state_diagram.png\")
\nHere's the complete saga class:
\npublic class UserOnboardingSaga : Saga\n{\n public Guid Id { get; set; }\n public string Email { get; set; } = string.Empty;\n public string FirstName { get; set; } = string.Empty;\n public string LastName { get; set; } = string.Empty;\n public bool IsVerificationEmailSent { get; set; }\n public bool IsEmailVerified { get; set; }\n public bool IsWelcomeEmailSent { get; set; }\n public DateTime StartedAt { get; set; }\n\n // Step 1: Start the saga when UserRegistered is published\n public static (\n UserOnboardingSaga,\n SendVerificationEmail,\n OnboardingTimedOut) Start(\n UserRegistered @event,\n ILogger<UserOnboardingSaga> logger)\n {\n logger.LogInformation(\n "Starting onboarding for user {UserId}", @event.Id);\n\n var saga = new UserOnboardingSaga\n {\n Id = @event.Id,\n Email = @event.Email,\n FirstName = @event.FirstName,\n LastName = @event.LastName,\n };\n\n return (\n saga,\n new SendVerificationEmail(saga.Id, saga.Email),\n new OnboardingTimedOut(saga.Id));\n }\n\n // Step 2: Verification email was sent\n public void Handle(\n VerificationEmailSent @event,\n ILogger<UserOnboardingSaga> logger)\n {\n logger.LogInformation(\n "Verification email sent for user {UserId}", Id);\n\n IsVerificationEmailSent = true;\n }\n\n // Step 3: User verified their email\n public SendWelcomeEmail Handle(\n VerifyUserEmail command,\n ILogger<UserOnboardingSaga> logger)\n {\n logger.LogInformation("Email verified for user {UserId}", Id);\n\n IsEmailVerified = true;\n\n return new SendWelcomeEmail(Id, Email, FirstName);\n }\n\n // Step 4: Welcome email sent - onboarding complete\n public void Handle(\n WelcomeEmailSent @event,\n ILogger<UserOnboardingSaga> logger)\n {\n logger.LogInformation("Onboarding complete for user {UserId}", Id);\n\n IsWelcomeEmailSent = true;\n\n MarkCompleted();\n }\n\n // Compensation: timeout handler\n public void Handle(\n OnboardingTimedOut timeout,\n ILogger<UserOnboardingSaga> logger)\n {\n if (IsEmailVerified)\n {\n logger.LogInformation(\n "Timeout ignored - email already verified for user {UserId}",\n Id);\n return;\n }\n\n logger.LogWarning(\n "Onboarding timed out for user {UserId} - email not verified",\n Id);\n\n MarkCompleted();\n }\n\n // NotFound: messages arriving for completed/deleted sagas\n public static void NotFound(\n VerifyUserEmail command,\n ILogger<UserOnboardingSaga> logger)\n {\n logger.LogWarning(\n "Verify email received but saga {Id} no longer exists",\n command.Id);\n }\n\n public static void NotFound(\n OnboardingTimedOut timeout,\n ILogger<UserOnboardingSaga> logger)\n {\n logger.LogInformation(\n "Timeout received for already-completed saga {Id}",\n timeout.Id);\n }\n}\nA few things worth calling out.
\nStarting the saga. Start is a static factory that returns a tuple: the saga instance, a SendVerificationEmail command, and a scheduled OnboardingTimedOut message. Wolverine persists the saga and delivers the messages for you.
Handling messages. Wolverine correlates messages to the correct saga instance by looking for a [SagaIdentity] attribute, then {SagaTypeName}Id, then Id. Return void to update state silently, or return a message to cascade a new command.
\n\nWarning: Do not call
\nIMessageBus.InvokeAsync()within a saga handler to execute a command on that same saga. You'll be acting on stale or missing data. Use cascading messages (return values) for subsequent work.
Completing the saga. MarkCompleted() tells Wolverine to delete the saga state from PostgreSQL.
Concurrency. Wolverine applies optimistic concurrency control to saga state by default. If two messages for the same saga arrive at the same time, one succeeds and the other retries automatically.
\nTimeout and compensation. OnboardingTimedOut fires 5 minutes after the saga started. If the user verified, we ignore it. Otherwise, we compensate and end the saga. This is the key advantage over fire-and-forget workflows.
NotFound handlers. Static NotFound methods handle messages for sagas that no longer exist. You must have one for any message type that could arrive after the saga is deleted. The timeout NotFound handler matters most: in the happy path, the saga completes before the timeout fires.
Here's the happy path where the user verifies before the timeout:
\n![\"Saga](\"https://milanjovanovic.tech/blogs/mnw_189/saga_pattern_sequence_diagram.png\")
\nIf the user never verifies, the VerifyUserEmail message never arrives.\nAfter 5 minutes, OnboardingTimedOut fires and the saga compensates.
Wolverine's Saga base class gives you a convention-driven way to implement long-running workflows:
Start methods create and initialize the saga from a triggering eventHandle methods process messages and cascade new commands via return valuesTimeoutMessage schedules delayed compensation without external schedulersMarkCompleted() cleans up the saga state when the workflow is doneNotFound handlers gracefully handle messages for sagas that no longer existThe Saga pattern shines when you have multi-step processes with potential failures.\nInstead of hoping everything goes right, you design for the cases where it doesn't.
\nWhat I really like about Wolverine's approach is how little code you need.\nYou skip the state machine DSL and explicit correlation config entirely.
\nIf you want to go deeper on orchestrating distributed workflows and building real-world sagas,\ncheck out Modular Monolith Architecture.
\nHope this was useful. See you next week.
\nMost message brokers deliver at least once, so your consumer will eventually see the same message twice.\nThe Inbox pattern writes every incoming message to an inbox table keyed by message id, so duplicates are ignored on insert.\nA separate processor picks up the unprocessed rows in batches and gives you control over retries.
\nThe Outbox pattern gets a lot of attention, and rightly so.\nBut what about the consumer side?
\nYour publisher reliably sends a message.\nThe broker delivers it.\nYour consumer processes it.\nThen something goes wrong. A timeout, a crash, a network blip.\nThe broker redelivers the same message.\nYour consumer runs the same logic twice.\nThis is a problem.
\nThe Inbox pattern is the counterpart to the Outbox.\nThe Outbox ensures reliable publishing. The Inbox ensures reliable consumption.\nEach incoming message is processed exactly once, even when the broker retries.
\nHere's how to implement it.
\nMost message brokers provide at-least-once delivery.\nThe broker guarantees every message will be delivered,\nbut it doesn't guarantee each message arrives only once.
\nHere's a common failure path:
\nYou could make each handler idempotent.\nThat works, but it means every consumer needs to check a deduplication table before doing any work.\nThe Inbox centralizes this into a single mechanism at the infrastructure level.\nI will talk more about the trade-offs between the Inbox and the Idempotent Consumer at the end.
\nThe idea:
\nThis decouples reception from processing.\nThe consumer becomes a thin persistence layer that can't produce duplicates.
\n![\"Inbox](\"https://milanjovanovic.tech/blogs/mnw_188/inbox_pattern_sequence_diagram.png\")
\nThe inbox_messages table stores every incoming message:
CREATE TABLE IF NOT EXISTS inbox_messages (\n id UUID PRIMARY KEY,\n type VARCHAR(255) NOT NULL,\n content JSONB NOT NULL,\n received_on_utc TIMESTAMP WITH TIME ZONE NOT NULL,\n processed_on_utc TIMESTAMP WITH TIME ZONE NULL,\n error TEXT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_inbox_messages_unprocessed\nON public.inbox_messages (received_on_utc, processed_on_utc)\nINCLUDE (id, type, content)\nWHERE processed_on_utc IS NULL;\nThe structure mirrors the Outbox pattern's outbox_messages table.\nThe id enables idempotent inserts via ON CONFLICT DO NOTHING.\nThe filtered index keeps the index small since processed messages drop out automatically.
Messages between services use a shared IntegrationEvent base record:
public abstract record IntegrationEvent(Guid MessageId);\n\npublic sealed record OrderCreatedIntegrationEvent(Guid OrderId)\n : IntegrationEvent(Guid.CreateVersion7());\nThe consumer is a MassTransit IConsumer<T>.\nInstead of processing the message, it writes it to the inbox table and returns.\nThat's it.
We can make this generic so it works for any integration event:
\ninternal sealed class InboxConsumer<T>(NpgsqlDataSource dataSource)\n : IConsumer<T> where T : IntegrationEvent\n{\n public async Task Consume(ConsumeContext<T> context)\n {\n await using var connection = await dataSource.OpenConnectionAsync(\n context.CancellationToken);\n\n const string sql =\n @"""\n INSERT INTO public.inbox_messages (id, type, content, received_on_utc)\n VALUES (@Id, @Type, @Content::jsonb, @ReceivedOnUtc)\n ON CONFLICT (id) DO NOTHING;\n """;\n\n await connection.ExecuteAsync(sql, new\n {\n Id = context.Message.MessageId,\n Type = typeof(T).FullName,\n Content = JsonSerializer.Serialize(context.Message),\n ReceivedOnUtc = DateTime.UtcNow\n });\n }\n}\nON CONFLICT (id) DO NOTHING is doing the heavy lifting.\nIf the broker delivers the same message twice, the second insert is silently ignored.\nCrash after insert but before ACK? The next delivery is safely deduplicated.
The processor runs in a background service\nor a scheduled job,\nfetching unprocessed messages in batches and dispatching them for handling.
\ninternal sealed class InboxProcessor(\n NpgsqlDataSource dataSource,\n IEventDispatcher eventDispatcher,\n ILogger<InboxProcessor> logger)\n{\n private const int BatchSize = 1000;\n\n public async Task<int> Execute(CancellationToken cancellationToken = default)\n {\n await using var connection =\n await dataSource.OpenConnectionAsync(cancellationToken);\n await using var transaction =\n await connection.BeginTransactionAsync(cancellationToken);\n\n var messages = (await connection.QueryAsync<InboxMessage>(\n @"""\n SELECT id AS Id, type AS Type, content AS Content\n FROM inbox_messages\n WHERE processed_on_utc IS NULL\n ORDER BY received_on_utc\n LIMIT @BatchSize\n FOR UPDATE SKIP LOCKED\n """,\n new { BatchSize },\n transaction: transaction)).AsList();\n\n var processedAt = DateTime.UtcNow;\n var results = new List<(Guid Id, DateTime ProcessedAt, string? Error)>(\n messages.Count);\n\n foreach (var message in messages)\n {\n try\n {\n var messageType = Type.GetType(message.Type)!;\n var deserialized = JsonSerializer.Deserialize(\n message.Content, messageType)!;\n\n await eventDispatcher.DispatchAsync(deserialized, cancellationToken);\n\n results.Add((message.Id, processedAt, null));\n }\n catch (Exception ex)\n {\n logger.LogError(ex, "Failed to process inbox message {Id}", message.Id);\n results.Add((message.Id, processedAt, ex.ToString()));\n }\n }\n\n if (results.Count > 0)\n {\n await connection.ExecuteAsync(\n @"""\n UPDATE inbox_messages\n SET processed_on_utc = v.processed_on_utc,\n error = v.error\n FROM UNNEST(@Ids, @ProcessedAts, @Errors)\n AS v(id, processed_on_utc, error)\n WHERE inbox_messages.id = v.id\n """,\n new\n {\n Ids = results.Select(r => r.Id).ToArray(),\n ProcessedAts = results.Select(r => r.ProcessedAt).ToArray(),\n Errors = results.Select(r => r.Error).ToArray()\n },\n transaction: transaction);\n }\n\n await transaction.CommitAsync(cancellationToken);\n\n return messages.Count;\n }\n}\nFOR UPDATE SKIP LOCKED lets multiple processor instances run concurrently\nwithout contention. I covered this in scaling the Outbox pattern.UNNEST writes all results in a single round-trip\nusing the same bulk update approach.If the process crashes mid-batch, the transaction rolls back\nand messages get picked up on the next run.
\nTable growth.\nThe inbox table grows indefinitely.\nDelete processed messages after a retention period,\nor partition by time range and drop old partitions.\nYou can also archive them to another table if you need to keep a history.
\nPoison messages.\nIf a message consistently fails, it gets marked with an error each time.\nConsider a max retry count. After N failures, dead-letter it and alert.
\nOrdering.\nORDER BY received_on_utc gives you rough arrival-time ordering.\nBut with SKIP LOCKED and multiple processors, strict ordering is not guaranteed.\nIf you need per-aggregate ordering,\nyou'll need additional coordination.
Monitoring.\nTrack the lag between received_on_utc and processed_on_utc.\nIf this gap grows, increase the batch size, decrease the polling interval,\nor scale out more processor instances.
Both the Inbox and the Idempotent Consumer prevent duplicate processing.\nThe difference is when processing happens and who controls retries.
\nThe Idempotent Consumer processes messages inline.\nIt checks a deduplication table, does the work, and records the dedup entry in the same transaction.\nIf processing fails, the transaction rolls back, no dedup record is written,\nand the broker redelivers the message on its own schedule.\nYou don't control retry timing or backoff.
\nThe Inbox separates reception from processing.\nThe consumer writes the message and ACKs immediately. The broker is done.\nIf the processor fails, it records the error and moves on.\nRetries are your responsibility: reset processed_on_utc to NULL for messages under a retry threshold,\nor run a separate loop that picks up failed messages after a delay.
Use the Idempotent Consumer when your side effects are transactional\nand broker-managed retries are good enough.\nUse the Inbox when you need batching, custom retry policies,\nor horizontal scaling via FOR UPDATE SKIP LOCKED.
The Inbox pattern is the consumer-side counterpart to the Outbox pattern.
\nON CONFLICT DO NOTHING makes consumer inserts idempotentFOR UPDATE SKIP LOCKED enables horizontal scaling of the processorUNNEST minimize database round-tripsIf you want to see how I build event-driven systems with these patterns,\ncheck out Modular Monolith Architecture.
\nThanks for reading.
\nAnd stay awesome!
\nVector search in .NET does not require a dedicated vector database.\nThe pgvector extension gives PostgreSQL a native vector column, and you query it with the cosine distance operator <=>.\nAn HNSW index keeps those lookups fast once the table grows past a few hundred rows.
Not every AI feature needs a dedicated vector database.
\nDedicated vector databases like Pinecone, Qdrant, and Weaviate get all the attention.\nBut if your data already lives in PostgreSQL, you don't need another moving part.
\npgvector is a PostgreSQL extension that adds vector storage and similarity search directly to your existing database.\nYou enable the extension, create a vector column, and start querying.
\nIn this week's issue, I'll walk you through:
\nLet's dive in.
\nTraditional database queries work with exact matches.\nYou search for "authentication" and get rows containing that exact word.\nBut what about rows that mention "login", "sign-in", or "identity verification"?\nThose are semantically similar, but a LIKE query won't find them.
Vector search solves this by comparing meaning instead of text.
\nYou convert text into an array of numbers (called an embedding) using a machine learning model.\nSemantically similar text produces similar arrays.\nThen, instead of matching keywords, you find the vectors that are closest to your query vector.
\nWhen would you use this?
\nThe key insight is that you don't need a specialized database for this.\nIf you're already on PostgreSQL, pgvector gives you all of this as an extension.
\nWe'll use .NET Aspire\nto provision a pgvector-enabled PostgreSQL container and an Ollama\ninstance with the qwen3-embedding embedding model.
\nvar builder = DistributedApplication.CreateBuilder(args);\n\nvar ollama = builder.AddOllama("ollama")\n .WithLifetime(ContainerLifetime.Persistent)\n .WithDataVolume()\n .WithGPUSupport();\n\nvar embeddingModel = ollama.AddModel("qwen3-embedding:0.6b");\n\nvar postgres = builder.AddPostgres("postgres", port: 6432)\n .WithLifetime(ContainerLifetime.Persistent)\n .WithDataVolume()\n .WithImage("pgvector/pgvector", "pg17")\n .AddDatabase("articles");\n\nbuilder.AddProject<Projects.PgVector_Articles>("pgvector-articles")\n .WithReference(embeddingModel)\n .WithReference(postgres)\n .WaitFor(embeddingModel)\n .WaitFor(postgres);\n\nbuilder.Build().Run();\nThe pgvector/pgvector:pg17 image is PostgreSQL 17 with the pgvector extension pre-installed.\nWithLifetime(ContainerLifetime.Persistent) keeps the containers running across app restarts so you don't lose data during development.\nWaitFor ensures the database and model are ready before the API starts.
If you're not using Aspire, you can run the same pgvector/pgvector:pg17 image via docker compose and point to it with a regular connection string.
The API project needs a few packages:
\ndotnet add package Aspire.Npgsql\ndotnet add package Pgvector.Dapper\ndotnet add package CommunityToolkit.Aspire.OllamaSharp\nPgvector.Dapper provides the Dapper type handler for the Vector type.\nOther than Pgvector.Dapper, there are also libraries for Npgsql and EF Core if you prefer those instead.
Register the services in Program.cs:
builder.AddOllamaApiClient("ollama-qwen3-embedding")\n .AddEmbeddingGenerator();\n\nbuilder.AddNpgsqlDataSource("articles", configureDataSourceBuilder: b =>\n{\n b.UseVector();\n});\n\nSqlMapper.AddTypeHandler(new VectorTypeHandler());\nAddEmbeddingGenerator() registers an IEmbeddingGenerator<string, Embedding<float>> using the Microsoft.Extensions.AI abstraction.\nUseVector() enables pgvector type mapping on the Npgsql data source.\nThe VectorTypeHandler lets Dapper serialize and deserialize Vector parameters.
Before storing vectors, we need to enable the pgvector extension and create a table.
\napp.MapPost("/init", async (NpgsqlDataSource dataSource) =>\n{\n await using var conn = await dataSource.OpenConnectionAsync();\n\n await using var enableExt = new NpgsqlCommand(\n "CREATE EXTENSION IF NOT EXISTS vector", conn);\n await enableExt.ExecuteNonQueryAsync();\n\n conn.ReloadTypes();\n\n await conn.ExecuteAsync(\n """\n CREATE TABLE IF NOT EXISTS articles (\n id SERIAL PRIMARY KEY,\n url TEXT NOT NULL,\n title TEXT NOT NULL,\n embedding vector(1024) NOT NULL\n )\n """);\n\n await conn.ExecuteAsync(\n """\n CREATE INDEX IF NOT EXISTS articles_embedding_idx\n ON articles USING hnsw (embedding vector_cosine_ops)\n """);\n\n return Results.Ok("Database initialized.");\n});\nA few things to note:
\nCREATE EXTENSION IF NOT EXISTS vector enables pgvector in the databaseembedding vector(1024) defines a vector column with 1024 dimensions, matching the Ollama embedding model's output (qwen3-embedding:0.6b)conn.ReloadTypes() refreshes Npgsql's type cache so it recognizes the new vector typevector_cosine_ops enables fast approximate nearest-neighbor search using cosine distance.HNSW (Hierarchical Navigable Small World) is a graph-based algorithm that builds a multi-layer structure for efficient similarity lookups.
\nWithout the index, pgvector does a sequential scan over every row.\nThat's fine for hundreds of rows, but HNSW keeps queries fast as the dataset grows.
\nNow we generate embeddings for our content and store them alongside the data.
\napp.MapPost("/embeddings/generate", async (\n BlogService blogService,\n IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator,\n NpgsqlDataSource dataSource,\n ILogger<Program> logger) =>\n{\n await using var conn = await dataSource.OpenConnectionAsync();\n conn.ReloadTypes();\n\n int count = 0;\n\n foreach (var articleUrl in File.ReadAllLines("sitemap_urls.txt"))\n {\n var (title, content) = await blogService.GetTitleAndContentAsync(articleUrl);\n\n var embedding = await embeddingGenerator.GenerateAsync(content);\n\n await conn.ExecuteAsync(\n "INSERT INTO articles (url, title, embedding) VALUES (@url, @title, @embedding)",\n new\n {\n url = articleUrl,\n title,\n embedding = new Vector(embedding.Vector.ToArray())\n });\n\n count++;\n logger.LogInformation("Processed ({Count}): {Url}", count, articleUrl);\n }\n\n return Results.Ok(new { processed = count });\n});\nembeddingGenerator.GenerateAsync(content) sends the text to the Ollama model and returns a vector.\nWe wrap it in a Pgvector.Vector and Dapper handles the rest.
The IEmbeddingGenerator is provider-agnostic.\nIf you want to swap Ollama for OpenAI or Azure OpenAI later, only the registration in Program.cs changes.\nYour endpoint code stays the same.
This is where it gets interesting.\nTo search, we embed the query text and find the closest vectors in the database.
\napp.MapGet("/search", async (\n string query,\n IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator,\n NpgsqlDataSource dataSource,\n int limit = 5) =>\n{\n var searchEmbedding = await embeddingGenerator.GenerateAsync(query);\n\n await using var con = await dataSource.OpenConnectionAsync();\n con.ReloadTypes();\n\n var embedding = new Vector(searchEmbedding.Vector.ToArray());\n\n var results = await con.QueryAsync<SearchResult>(\n @"""\n SELECT title, url, embedding <=> @embedding as distance\n FROM articles\n ORDER BY embedding <=> @embedding\n LIMIT @limit\n """,\n new { embedding, limit });\n\n return Results.Ok(new { query, results });\n});\n\nrecord SearchResult(string Title, string Url, double Distance);\nThe <=> operator is pgvector's cosine distance function, where lower values mean more similar.\nWe order by distance ascending and take the top N matches.
The critical part: the query text must be embedded with the same model that produced the stored embeddings.\nDifferent models produce vectors in different embedding spaces, and comparing them would be meaningless.
\nThere are also shared embedding spaces models that can embed text and images into compatible vectors, but that's a more advanced topic.\nOne example is the Voyage 4 model family.
\nA query like "how to secure an API" will surface articles about authentication, JWT validation, and authorization, even if they don't contain those exact words.
pgvector supports three distance operators:
\n<-> - L2 (Euclidean) distance, uses vector_l2_ops<=> - Cosine distance, uses vector_cosine_ops<#> - Inner product (negative), uses vector_ip_opsCosine distance is the most common choice for text embeddings.
\nYou don't need a dedicated vector database to add semantic search to your application.\nIf you're already running PostgreSQL, pgvector gives you vector storage and similarity search without adding new infrastructure.
\nHere's what we covered:
\nvector column typeqwen3-embedding via IEmbeddingGenerator<=>) to find the closest matchesYour vectors live right next to your relational data, so you can join, filter, and paginate just like any other query without syncing between databases or managing extra infrastructure.
\nIf you want to explore more advanced scenarios like building semantic search with S3 Vectors and Semantic Kernel, I've covered that in a previous article.
\nThanks for reading.
\nAnd stay awesome!
\nEach SignalR server only knows about the connections it accepted, so once you scale out, messages for clients on another instance are silently dropped.\nA Redis backplane fixes that by publishing every message to a shared channel that all instances subscribe to.\nYou still need sticky sessions, and nothing is buffered while Redis is down.
\nI ran into this one the hard way.
\nI built a real-time notification feature with SignalR, tested it locally, everything worked great.\nThen I scaled to two instances behind a load balancer, and notifications started disappearing for some users.
\nThe code was fine.\nThe problem was that SignalR connections are bound to the server process that accepted them.\nEach instance only knows about its own connections.\nSo when an API request lands on Server 1 but the user is connected to Server 2, the notification just... doesn't get delivered.
\nThis is the SignalR scale-out problem, and it bites almost everyone who goes from one instance to more.
\nWith a single instance, everything just works.
\n![\"SignalR](\"https://milanjovanovic.tech/blogs/mnw_186/signalr_single_server.png\")
\nThe server holds the full map of who's connected, so sending a message to a user, a group, or all clients works because that map is complete.
\nBut scale out to two or more instances, and that map fractures.
\n![\"SignalR](\"https://milanjovanovic.tech/blogs/mnw_186/signalr_multi_server.png\")
\nServer 1 has no idea Client 3 or Client 4 even exist.\nSo when an order status change happens on Server 1 and needs to reach Client 3, Server 1 checks its connection map, finds nothing, and the message is quietly dropped.
\nThe fix is a backplane - a shared messaging layer that sits between all your server instances.
\nEvery server publishes outgoing messages to a central channel, and every server subscribes to that same channel.\nWhen a message comes in, each server checks if any of its local connections should receive it.
\n![\"SignalR](\"https://milanjovanovic.tech/blogs/mnw_186/signalr_backplane.png\")
\nWhen Server 1 wants to notify Client 3:
\nFrom your code's perspective, it looks like every server can see every connection.\nRedis works really well for this because its Pub/Sub delivers messages to all subscribers in near real-time.\nAnd if you're already using Redis for distributed caching, you don't even need to spin up anything new.
\nLet me walk through how I set this up in an order notification system.\nClients connect to a SignalR hub, authenticate via JWT, and get real-time status updates when an order changes.
\ndotnet add package Microsoft.AspNetCore.SignalR.StackExchangeRedis\nChain .AddStackExchangeRedis() onto your AddSignalR() call:
builder.Services.AddSignalR()\n .AddStackExchangeRedis(builder.Configuration.GetConnectionString("cache")!);\nIf you're running with .NET Aspire,\nyou will have the Redis connection string registered via environment variables, so you can just pull it from configuration.\nReference the same named connection:
\nbuilder.AddRedisDistributedCache("cache");\n\nbuilder.Services.AddSignalR()\n .AddStackExchangeRedis(builder.Configuration.GetConnectionString("cache")!);\nIf you have multiple SignalR apps sharing the same Redis instance, you'll want to add a channel prefix.\nOtherwise, messages from one app will reach subscribers in every app on that Redis server.
\nbuilder.Services.AddSignalR()\n .AddStackExchangeRedis(connectionString, options =>\n {\n options.Configuration.ChannelPrefix = RedisChannel.Literal("OrderNotifications");\n });\nThe nice thing is that your IHubContext<> call site doesn't change at all.\nClients.User(...) works the same whether you have one instance or ten - the backplane handles routing behind the scenes.
When I tested this with two replicas in .NET Aspire, I tagged each notification with the sending instance's ID.\nA client on Replica 1 received a notification stamped with Replica 2's ID, which confirmed the message was crossing instances through Redis.
\nThis is something you should know before you set up the backplane: you still need sticky sessions.
\nThe Redis backplane solves message routing, but it does not remove the need for sticky sessions.
\nSignalR's connection negotiation is a two-step process:
\nPOST to /hub/negotiate to obtain a connection tokenBoth requests must land on the same server.\nIf your load balancer routes the negotiation to Server 1 but the WebSocket upgrade to Server 2, the connection fails.
\n![\"SignalR](\"https://milanjovanovic.tech/blogs/mnw_186/sticky_sessions.png\")
\nMake sure sticky sessions are enabled in your load balancer.\nMost load balancers support this via IP hash or cookie affinity - check the docs for whichever you're using.
\nOne thing worth knowing: SignalR does not buffer messages when Redis is unavailable.
\nIf Redis stops responding, any messages sent during the outage are simply lost.\nSignalR may throw exceptions, but your existing WebSocket connections stay open - clients don't get disconnected.\nOnce Redis comes back, SignalR reconnects automatically.
\nFor most real-time scenarios like order updates or live dashboards, this is fine.\nThe next state change triggers a fresh notification anyway, or the user can just reload.\nIf you're dealing with something more critical (financial data, operational alerts), you'll want a reconciliation strategy on reconnect or a durable queue running alongside.
\nIf you're on Azure, the managed Azure SignalR Service is worth considering.\nIt proxies all client connections through the service, so sticky sessions aren't required and your servers only hold a small number of constant connections to the service.
\nThe Redis backplane is the better fit when you're self-hosted, latency-sensitive, or already running Redis.\nFor everything else, Azure SignalR Service is the cleaner option.
\nHonestly, the Redis backplane is almost too simple to set up.\nOne method call on AddSignalR() and your app goes from silently dropping messages to routing them across every instance.\nYou don't need to make changes to your hub code, client code, or application logic.
Just remember two things:
\nGet those two right and SignalR scales out just as smoothly as the rest of your stack.
\nIf you want to go deeper on building real-time features and APIs in .NET,\ncheck out my Pragmatic REST APIs course.
\nHope this was useful. See you next week.
\nWhat makes a bulk update slow is the number of round-trips to the database.\nUpdating 10,000 rows with one UPDATE per row took 2,414ms in my benchmark, while UNNEST with array parameters and a temp table loaded by binary COPY both finished in 41ms.\nThose two keep the query text constant no matter how large the batch gets.
Every outbox processor, job queue, and batch pipeline hits the same problem at some point:\nmark a set of rows as done in bulk.
\nI went through this recently while optimizing an outbox processor.\nI measured seven different approaches against 1,000, 10,000, and 25,000 rows in PostgreSQL.\nAt 10,000 rows the slowest approach took 2,414ms and the fastest took 41ms.\nThe bottleneck was almost never the SQL.\nIt was how many times the code was talking to the database.
\nThe scenario: mark a batch of orders as processed by setting a status and a unique processed_at timestamp per row.\nThat uniqueness constraint is what makes it tricky.\nYou can't use a simple UPDATE ... WHERE id IN (...) with a single value because every row gets a different timestamp.
Let's go through each approach.
\nA table of orders, each needing two updates: a status change to "Processed" and a unique processed_at timestamp.
CREATE TABLE orders (\n id UUID NOT NULL PRIMARY KEY,\n customer_name TEXT NOT NULL,\n status TEXT NOT NULL DEFAULT 'Pending',\n processed_at TIMESTAMPTZ\n);\nThe update payload is a simple record pairing each order with its timestamp:
\nrecord OrderUpdate(Guid Id, DateTime ProcessedAt);\nWith 10,000 of these, here's how each approach plays out.
\nThe first thing you'd try: loop through the list and fire one UPDATE per row.
await using var connection = new NpgsqlConnection(connectionString);\nawait connection.OpenAsync();\nawait using var transaction = await connection.BeginTransactionAsync();\n\nforeach (var update in updates)\n{\n await connection.ExecuteAsync(\n """\n UPDATE orders\n SET processed_at = @ProcessedAt,\n status = 'Processed'\n WHERE id = @Id\n """,\n new { update.Id, update.ProcessedAt },\n transaction: transaction);\n}\n\nawait transaction.CommitAsync();\n10,000 rows means 10,000 round-trips to the database.\nEach ExecuteAsync call sends the SQL, waits for PostgreSQL to respond, then moves on to the next one.\nAt 10,000 rows this took 2,414ms in my benchmark. At 25,000 rows it was over 6 seconds.\nOver a real network it would be worse.\nThe database is not slow. The constant back-and-forth is.
EF Core batches the generated SQL statements to cut down on round-trips.\nWith MaxBatchSize set high enough, you can push all 10,000 updates in far fewer network calls.\nThe default batch size is 42, in case you were wondering.\nYou can read more about this in the EF Core efficient updating docs.
var options = new DbContextOptionsBuilder<AppDbContext>()\n .UseNpgsql(connectionString, o => o.MinBatchSize(5000).MaxBatchSize(10000))\n .Options;\n\nawait using var db = new AppDbContext(options);\n\nvar ids = updates.Select(u => u.Id).ToHashSet();\nvar orders = await db.Orders\n .Where(o => ids.Contains(o.Id))\n .ToListAsync();\n\nvar updateMap = updates.ToDictionary(u => u.Id);\n\nforeach (var order in orders)\n{\n order.Status = "Processed";\n order.ProcessedAt = updateMap[order.Id].ProcessedAt;\n}\n\nawait db.SaveChangesAsync();\nIt's a meaningful improvement over the loop.\nAt 10,000 rows it came in at 1,030ms, roughly half the time of Approach 1.\nBut there's hidden cost in two places: the upfront SELECT to load all 10,000 entities into the change tracker,\nand the fact that EF Core still generates 10,000 individual UPDATE statements.\nThey're packed into fewer round-trips, but the SQL is all still there.
Instead of sending N separate statements, you can send a single UPDATE that supplies all the new values inline\nusing a derived VALUES table:
UPDATE orders\nSET processed_at = v.processed_at,\n status = 'Processed'\nFROM (VALUES\n (@Id0, @ProcessedAt0),\n (@Id1, @ProcessedAt1),\n ...\n) AS v(id, processed_at)\nWHERE orders.id = v.id::uuid\nHere's the C# code to build and execute that:
\nawait using var connection = new NpgsqlConnection(connectionString);\nawait connection.OpenAsync();\nawait using var transaction = await connection.BeginTransactionAsync();\n\nconst string updateTemplate =\n @"""\n UPDATE orders\n SET processed_at = v.processed_at,\n status = 'Processed'\n FROM (VALUES\n {0}\n ) AS v(id, processed_at)\n WHERE orders.id = v.id::uuid\n """;\n\nvar paramNames = string.Join(\n ",\\n ",\n updates.Select((_, i) => $"(@Id{i}, @ProcessedAt{i})"));\n\nvar sql = string.Format(updateTemplate, paramNames);\n\nvar parameters = new DynamicParameters();\nfor (int i = 0; i < updates.Count; i++)\n{\n parameters.Add($"Id{i}", updates[i].Id.ToString());\n parameters.Add($"ProcessedAt{i}", updates[i].ProcessedAt);\n}\n\nawait connection.ExecuteAsync(sql, parameters, transaction: transaction);\n\nawait transaction.CommitAsync();\nPostgreSQL receives one statement, builds one execution plan, and updates all rows in a single pass.\nOne round-trip total.\nThis dropped from 2,414ms down to 89ms at 10,000 rows.
\nThere is a trade-off: the SQL string grows with the batch size.\nAt 10,000 rows you end up with 10,000 parameter pairs in the query text.\nPostgreSQL allows a maximum of 65,535 parameters, so you have headroom,\nbut it is something to be aware of at very large batch sizes.\nApproaches 6 and 7 avoid this entirely.
\nThe SQL here is exactly the same as Approach 3.\nThe reason to use this instead is if you're already working inside an EF Core DbContext and want your bulk update to share the same transaction as other EF Core operations.
await using var db = new AppDbContext(options);\nawait using var transaction = await db.Database.BeginTransactionAsync();\n\nvar paramEntries = new List<NpgsqlParameter>();\nvar valueClauses = new List<string>();\n\nfor (int i = 0; i < updates.Count; i++)\n{\n valueClauses.Add($"(@Id{i}::uuid, @ProcessedAt{i})");\n paramEntries.Add(new NpgsqlParameter($"Id{i}", updates[i].Id.ToString()));\n paramEntries.Add(new NpgsqlParameter($"ProcessedAt{i}", updates[i].ProcessedAt));\n}\n\nvar sql = string.Format(updateTemplate, string.Join(",\\n ", valueClauses));\n\nawait db.Database.ExecuteSqlRawAsync(sql, paramEntries);\n\nawait transaction.CommitAsync();\nThe performance is the same as Approach 3 since it's the same SQL hitting the database.\nIn my benchmark it came in at 166ms at 10,000 rows, a bit slower than Approach 3's 89ms.\nThe small gap is likely overhead from the EF Core transaction wrapper rather than the SQL itself.\nWhat you get is the ability to mix change-tracked operations with raw SQL inside the same EF Core transaction.\nDapper and EF Core are not mutually exclusive.
\nOne thing to watch out for: ExecuteSqlRawAsync doesn't accept Dapper's DynamicParameters.\nYou have to use NpgsqlParameter objects directly.\nIf you want a full overview of EF Core's raw SQL options,\nI covered them in this article.
This is a variation on Approach 3 that wraps the same VALUES data in a named CTE instead of an inline derived table:
WITH updates(id, processed_at) AS (\n VALUES\n (@Id0::uuid, @ProcessedAt0),\n (@Id1::uuid, @ProcessedAt1),\n ...\n)\nUPDATE orders\nSET processed_at = updates.processed_at,\n status = 'Processed'\nFROM updates\nWHERE orders.id = updates.id\nAnd here's the C# code to execute it:
\nawait using var connection = new NpgsqlConnection(connectionString);\nawait connection.OpenAsync();\nawait using var transaction = await connection.BeginTransactionAsync();\n\nvar valueClauses = string.Join(\n ",\\n ",\n updates.Select((_, i) => $"(@Id{i}::uuid, @ProcessedAt{i})"));\n\nvar sql =\n @$"""\n WITH updates(id, processed_at) AS (\n VALUES\n {valueClauses}\n )\n UPDATE orders\n SET processed_at = updates.processed_at,\n status = 'Processed'\n FROM updates\n WHERE orders.id = updates.id\n """;\n\nvar parameters = new DynamicParameters();\nfor (int i = 0; i < updates.Count; i++)\n{\n parameters.Add($"Id{i}", updates[i].Id.ToString());\n parameters.Add($"ProcessedAt{i}", updates[i].ProcessedAt);\n}\n\nawait connection.ExecuteAsync(sql, parameters, transaction: transaction);\n\nawait transaction.CommitAsync();\nStill a single statement and a single round-trip.\nPostgreSQL materializes the CTE once and joins against it for the update.\nIn the benchmark it came in at 103ms at 10,000 rows, slightly behind the plain VALUES approach at 89ms.\nThe performance difference is small enough that this is really a style choice.\nSome teams prefer the CTE form when the update logic is more involved and they want to name the data source explicitly.
If you're on PostgreSQL, there's a cleaner option: UNNEST.\nInstead of building @Id0 through @Id9999 dynamically, you pass two arrays as parameters and let PostgreSQL expand them:
await using var connection = new NpgsqlConnection(connectionString);\nawait connection.OpenAsync();\nawait using var transaction = await connection.BeginTransactionAsync();\n\nvar ids = updates.Select(u => u.Id).ToArray();\nvar processedAts = updates.Select(u => u.ProcessedAt).ToArray();\n\nawait connection.ExecuteAsync(\n @"""\n UPDATE orders\n SET processed_at = v.processed_at,\n status = 'Processed'\n FROM UNNEST(@Ids, @ProcessedAts) AS v(id, processed_at)\n WHERE orders.id = v.id\n """,\n new { Ids = ids, ProcessedAts = processedAts },\n transaction: transaction);\n\nawait transaction.CommitAsync();\nThis is my preferred approach when working with PostgreSQL:
\nstring.Format, no growing parameter lists.@Ids and @ProcessedAts.\nNpgsql maps Guid[] and DateTime[] directly to PostgreSQL array types.The catch: UNNEST is PostgreSQL-specific.\nIf you're targeting multiple databases, stick with the VALUES approach from Approach 3, 4, or 5.\nOr you can research the equivalent array expansion functions in your other database of choice.
All the previous approaches pass data as SQL parameters.\nAt extreme batch sizes that starts to become a constraint, both from the 65,535 parameter limit and from the overhead of building large parameter lists.
\nA completely different path: skip parameters altogether.\nCreate a temporary staging table, bulk-load the data using Npgsql's binary COPY, then run a single UPDATE ... FROM.
await using var connection = new NpgsqlConnection(connectionString);\nawait connection.OpenAsync();\nawait using var transaction = await connection.BeginTransactionAsync();\n\nawait connection.ExecuteAsync(\n @"""\n CREATE TEMP TABLE temp_updates (\n id UUID NOT NULL,\n processed_at TIMESTAMPTZ NOT NULL\n ) ON COMMIT DROP\n """,\n transaction: transaction);\n\nawait using (var writer = await connection.BeginBinaryImportAsync(\n "COPY temp_updates (id, processed_at) FROM STDIN (FORMAT BINARY)"))\n{\n foreach (var u in updates)\n {\n await writer.StartRowAsync();\n await writer.WriteAsync(u.Id, NpgsqlTypes.NpgsqlDbType.Uuid);\n await writer.WriteAsync(u.ProcessedAt, NpgsqlTypes.NpgsqlDbType.TimestampTz);\n }\n await writer.CompleteAsync();\n}\n\nawait connection.ExecuteAsync(\n @"""\n UPDATE orders\n SET processed_at = t.processed_at,\n status = 'Processed'\n FROM temp_updates t\n WHERE orders.id = t.id\n """,\n transaction: transaction);\n\nawait transaction.CommitAsync();\nBinary COPY is Npgsql's most efficient data loading path.\nIt bypasses the SQL parameter system and streams rows directly in PostgreSQL's binary wire format.\nThe ON COMMIT DROP means the temp table is cleaned up automatically when the transaction ends.
The trade-off is complexity: you create a table, stream data into it, then fire the update.\nIt is technically two operations (COPY + UPDATE), but both are efficient.\nAt 10,000 rows it came in at 41ms, matching UNNEST.\nAt larger batch sizes (say, 100k+ rows), binary COPY would likely pull ahead further since the data payload grows but the query text stays constant and there are no parameter limits to worry about.
\nHere are the numbers across all three batch sizes:
\n| Approach | 1,000 rows | 10,000 rows | 25,000 rows |\n| ------------------------------------------ | ---------- | ----------- | ----------- |\n| Approach 1: Naive Dapper | 317ms | 2,414ms | 6,283ms |\n| Approach 2: EF Core SaveChanges | 575ms | 1,030ms | 1,767ms |\n| Approach 3: Dapper + VALUES table | 19ms | 89ms | 233ms |\n| Approach 4: EF Core ExecuteSqlRaw + VALUES | 58ms | 166ms | 282ms |\n| Approach 5: Dapper + CTE | 13ms | 103ms | 251ms |\n| Approach 6: Dapper + UNNEST | 12ms | 41ms | 92ms |\n| Approach 7: Temp table + binary COPY | 11ms | 41ms | 93ms |\nA few things stand out.\nEF Core SaveChanges is actually faster than naive Dapper at 10,000+ rows because its batching cuts down round-trips significantly.\nBut both are far behind the single-statement approaches.\nThe biggest jump in the table is from Approach 2 to Approach 3.\nApproach 5 (CTE) is essentially the same performance as Approach 3 (VALUES), confirming it is a style choice rather than a performance one.\nApproaches 6 and 7 are the fastest at every scale, and the gap over CTE and VALUES widens as batch size grows.
The takeaway from this exercise is simple: round-trips are expensive and individual SQL statements add up fast.
\nReducing 10,000 database calls to 1 is where all the gains come from.\nEverything else is secondary.
\nA few things worth keeping in mind:
\nSaveChanges is not a bulk update tool.\nIt reduces round-trips through batching, but it still generates N individual UPDATE statements\nand requires a SELECT to load the change tracker.\nFor bulk mutations, raw SQL is a better fit.\nThe same logic applies to inserts - I covered that in\nFast SQL Bulk Inserts with C# and EF Core.UNNEST and binary COPY are the best options at scale.\nBoth use a fixed query text that doesn't grow with batch size and have no parameter count limits.\nVALUES and CTE are solid choices for smaller batches or when you need to stay closer to portable SQL.If you want to go deeper on SQL performance more broadly,\nI recently wrote about a common myth around filter and join ordering in SQL queries\nthat trips up a lot of developers.
\nThat's all for today.
\nSee you next week.
\nArchitecture tests turn rules like layer boundaries, naming conventions, and dependency direction into xUnit tests that fail the build when someone breaks them.\nYou write them with ArchUnitNET using a fluent API, and they run in milliseconds without any infrastructure.\nThe five I add to every .NET project cover layer dependencies, naming, colocation, visibility, and third-party dependency guards.
Every project starts with good intentions.\nYou agree on layer boundaries, naming conventions, dependency direction.\nThe diagram goes on Confluence.
\nSix months later, someone moves a domain service into the Infrastructure project because it needs database access.\nOr a handler gets named ProcessPaymentService because the dev didn't know the convention.\nOr a class that should be internal is public because that's the default.\nNobody catches it in code review.
Architecture tests stop this from happening.\nThey turn your architectural rules into automated tests that run in CI.\nIf someone violates a rule, the build fails.
\nHere are 5 types of architecture tests I add to every .NET project.
\nArchUnitNET is the .NET port of the Java ArchUnit library.\nIt lets you write architecture rules\nusing a fluent API and run them as regular xUnit tests.
\n# there are other test frameworks supported, but I use xUnit\ndotnet add package TngTech.ArchUnitNET.xUnit\nYou need a base class that loads all the assemblies you want to test.\nEach layer gets an "anchor type" to grab a reference to the assembly at compile time:
\npublic abstract class BaseTest\n{\n protected static readonly Assembly DomainAssembly = typeof(User).Assembly;\n protected static readonly Assembly ApplicationAssembly = typeof(ICommand).Assembly;\n protected static readonly Assembly InfrastructureAssembly = typeof(ApplicationDbContext).Assembly;\n protected static readonly Assembly PresentationAssembly = typeof(Program).Assembly;\n\n protected static readonly Architecture Architecture = new ArchLoader()\n .LoadAssemblies(\n DomainAssembly,\n ApplicationAssembly,\n InfrastructureAssembly,\n PresentationAssembly)\n .Build();\n}\nThe ArchLoader scans these assemblies and builds an in-memory model of all types and their dependencies.\nEvery test class inherits from BaseTest.
The most important rule in Clean Architecture is the dependency rule.\nInner layers must not reference outer layers.\nAll dependencies point inward.
\nIn most Clean Architecture setups, the project references already prevent the obvious violations.\nYou can't add a reference from Application to Infrastructure\nbecause Infrastructure already references Application, and the compiler won't allow circular dependencies.
So why bother with these tests?
\nBecause project references aren't the only way dependencies leak in.\nA NuGet package used in Infrastructure might expose types that bleed into Application through transitive references.\nSomeone could reorganize the solution and change the project reference graph.\nOr you might move to a modular monolith\nwhere multiple layers share an assembly, and the compiler can't help you at all.
\nThese tests are a safety net.\nAnd they double as living documentation of the intended architecture.
\nusing static ArchUnitNET.Fluent.ArchRuleDefinition;\n\npublic class LayerTests : BaseTest\n{\n private static readonly IObjectProvider<IType> DomainLayer =\n Types().That().ResideInAssembly(DomainAssembly).As("Domain layer");\n\n private static readonly IObjectProvider<IType> ApplicationLayer =\n Types().That().ResideInAssembly(ApplicationAssembly).As("Application layer");\n\n private static readonly IObjectProvider<IType> InfrastructureLayer =\n Types().That().ResideInAssembly(InfrastructureAssembly).As("Infrastructure Layer");\n\n private static readonly IObjectProvider<IType> PresentationLayer =\n Types().That().ResideInAssembly(PresentationAssembly).As("Presentation Layer");\n\n [Fact]\n public void DomainLayer_ShouldNotDependOn_ApplicationLayer()\n {\n Types().That().Are(DomainLayer).Should()\n .NotDependOnAny(ApplicationLayer)\n .Check(Architecture);\n }\n\n [Fact]\n public void DomainLayer_ShouldNotDependOn_InfrastructureLayer()\n {\n Types().That().Are(DomainLayer).Should()\n .NotDependOnAny(InfrastructureLayer)\n .Check(Architecture);\n }\n\n [Fact]\n public void DomainLayer_ShouldNotDependOn_PresentationLayer()\n {\n Types().That().Are(DomainLayer).Should()\n .NotDependOnAny(PresentationLayer)\n .Check(Architecture);\n }\n\n [Fact]\n public void ApplicationLayer_ShouldNotDependOn_InfrastructureLayer()\n {\n Types().That().Are(ApplicationLayer).Should()\n .NotDependOnAny(InfrastructureLayer)\n .Check(Architecture);\n }\n\n [Fact]\n public void ApplicationLayer_ShouldNotDependOn_PresentationLayer()\n {\n Types().That().Are(ApplicationLayer).Should()\n .NotDependOnAny(PresentationLayer)\n .Check(Architecture);\n }\n\n [Fact]\n public void InfrastructureLayer_ShouldNotDependOn_PresentationLayer()\n {\n Types().That().Are(InfrastructureLayer).Should()\n .NotDependOnAny(PresentationLayer)\n .Check(Architecture);\n }\n}\nSix tests, one for each illegal dependency direction.
\nThe fluent API reads like English:\n"Types that are in the Domain layer should not depend on any types in the Application layer".\nWhen a violation happens, the test tells you exactly which type depends on which.
\nThis is the first architecture test I add to any project.\nIf you only add one type from this list, make it this one.
\nYou can also extend this further.\nFor example, I sometimes add tests that specific namespaces within a layer can't reference each other\n(like Application.Orders shouldn't depend on Application.Users).\nThis can be great for enforcing a vertical slice architecture\nwhere each feature is self-contained, or inside a modular monolith\nwhere modules shouldn't depend on each other.
This one might seem minor, but it adds up fast.
\nWhen you have 50 command handlers and 3 of them are named CreateOrderService or ProcessPaymentUseCase,\nsearching the codebase becomes unreliable. You search for CommandHandler and miss three handlers.
ArchUnitNET lets you enforce naming rules by selecting classes based on the interfaces they implement:
\nusing static ArchUnitNET.Fluent.ArchRuleDefinition;\n\npublic class NamingConventionTests : BaseTest\n{\n [Fact]\n public void CommandHandlers_ShouldHave_NameEndingWith_CommandHandler()\n {\n Classes().That()\n .ImplementInterface(typeof(ICommandHandler<>))\n .Or()\n .ImplementInterface(typeof(ICommandHandler<,>))\n .And().DoNotResideInNamespace("Application.Abstractions.Behaviors")\n .Should().HaveNameEndingWith("CommandHandler")\n .Check(Architecture);\n }\n\n [Fact]\n public void QueryHandlers_ShouldHave_NameEndingWith_QueryHandler()\n {\n Classes().That()\n .ImplementInterface(typeof(IQueryHandler<,>))\n .And().DoNotResideInNamespace("Application.Abstractions.Behaviors")\n .Should().HaveNameEndingWith("QueryHandler")\n .Check(Architecture);\n }\n\n [Fact]\n public void Validators_ShouldHave_NameEndingWith_Validator()\n {\n Classes().That()\n .HaveNameEndingWith("Validator")\n .Should().ResideInAssembly(ApplicationAssembly)\n .Check(Architecture);\n }\n}\nOne gotcha here: decorators like ValidationBehavior implement handler interfaces too.\nThey're decorators in the pipeline, not domain-specific handlers.\nThe DoNotResideInNamespace("Application.Abstractions.Behaviors") filter excludes them.\nI learned this the hard way when every behavior started failing the naming check.
The validator test works in the opposite direction.\nIt says "classes ending with Validator should live in the Application assembly".\nI've seen validators accidentally placed in the Infrastructure project.\nThis catches that.
This is the test I wish I had earlier in my career.
\nWhen you use CQRS,\nyou end up with pairs: a command (or query) and its handler.\nI keep them in the same namespace so everything for a use case lives together.\nApplication.TodoItems.Create would contain both CreateTodoItemCommand and CreateTodoItemCommandHandler.
But nothing stops someone from putting the handler in a completely different namespace:
\npublic class ColocationTests : BaseTest\n{\n [Theory]\n [MemberData(nameof(GetHandlerAndCommandPairs))]\n public void Handlers_ShouldResideInSameNamespace_AsTheirCommandOrQuery(\n Type handlerType,\n Type commandOrQueryType)\n {\n handlerType.Namespace.ShouldBe(\n commandOrQueryType.Namespace,\n $"{handlerType.Name} should be in the same namespace as {commandOrQueryType.Name}");\n }\n\n public static TheoryData<Type, Type> GetHandlerAndCommandPairs()\n {\n Type[] handlerInterfaces =\n [\n typeof(ICommandHandler<>),\n typeof(ICommandHandler<,>),\n typeof(IQueryHandler<,>)\n ];\n\n var pairs = new TheoryData<Type, Type>();\n\n IEnumerable<Type> handlers = ApplicationAssembly\n .GetTypes()\n .Where(t => t is { IsClass: true, IsAbstract: false, IsGenericTypeDefinition: false })\n .Where(t => t.DeclaringType is null);\n\n foreach (Type handler in handlers)\n {\n foreach (Type iface in handler.GetInterfaces())\n {\n if (!iface.IsGenericType)\n {\n continue;\n }\n\n Type genericDef = iface.GetGenericTypeDefinition();\n\n if (!handlerInterfaces.Contains(genericDef))\n {\n continue;\n }\n\n Type commandOrQueryType = iface.GetGenericArguments()[0];\n pairs.Add(handler, commandOrQueryType);\n }\n }\n\n return pairs;\n }\n}\nThis test doesn't use ArchUnitNET.\nIt uses raw reflection combined with xUnit's [Theory] and [MemberData].\nArchUnitNET can't express a rule like\n"this class should be in the same namespace as the generic type argument of its interface".\nSo we drop down to reflection.
The GetHandlerAndCommandPairs method scans the Application assembly,\nfinds all classes implementing a handler interface,\nextracts the command/query type from the generic argument,\nand returns pairs for the test to assert on.
This enforces a vertical slice style of organizing code.\nWhen a new developer joins the team, they can find everything for a use case in one folder.
\nYou can expand this to cover request and response types, validators, or anything else that should be colocated.
\nCommand and query handlers are implementation details.\nThey get resolved through DI, not referenced directly.
\nBut most developers make them public by default.\nIt's just muscle memory.\nThe problem is that a public handler can be referenced directly from another layer,\nbypassing the abstractions you set up.
using static ArchUnitNET.Fluent.ArchRuleDefinition;\n\npublic class VisibilityTests : BaseTest\n{\n [Fact]\n public void CommandHandlers_ShouldBeInternal()\n {\n Classes().That()\n .ImplementInterface(typeof(ICommandHandler<>))\n .Or()\n .ImplementInterface(typeof(ICommandHandler<,>))\n .Should().BeInternal()\n .Check(Architecture);\n }\n\n [Fact]\n public void QueryHandlers_ShouldBeInternal()\n {\n Classes().That()\n .ImplementInterface(typeof(IQueryHandler<,>))\n .Should().BeInternal()\n .Check(Architecture);\n }\n}\nIf you're worried about DI not finding internal classes, don't be.\nAssembly scanning discovers them just fine.
You could extend this to other types too.\nI've thought about enforcing that EF Core configurations are internal as well,\nsince there's no reason for OrderConfiguration to be visible outside of Infrastructure.
Layer tests guard against references to your own assemblies.\nBut infrastructure libraries can leak in through transitive NuGet references.
\nYour Domain layer shouldn't know about Entity Framework. Your Application layer shouldn't know about Npgsql.\nThe compiler won't stop this if the package is transitively available.
\nusing static ArchUnitNET.Fluent.ArchRuleDefinition;\n\npublic class DependencyGuardTests : BaseTest\n{\n [Fact]\n public void DomainLayer_ShouldNotDependOn_EntityFramework()\n {\n Types().That().ResideInAssembly(DomainAssembly).Should()\n .NotDependOnAnyTypesThat()\n .ResideInNamespace("Microsoft.EntityFrameworkCore")\n .Check(Architecture);\n }\n\n [Fact]\n public void ApplicationLayer_ShouldNotDependOn_EntityFramework()\n {\n Types().That().ResideInAssembly(ApplicationAssembly).Should()\n .NotDependOnAnyTypesThat()\n .ResideInNamespace("Microsoft.EntityFrameworkCore")\n .Check(Architecture);\n }\n}\nAdd whatever libraries make sense for your project.
\nArchitectural rules that only exist in documentation will be violated.\nIt's not a question of if, it's when.
\nAll of these tests run in milliseconds and don't require any infrastructure to run.\nThey sit right next to your unit tests and run on every build.
\nArchitecture tests are a safety net that catches violations before they reach production.
\nStart with layer dependency tests.\nThey take five minutes to set up and catch the most damaging violations.\nThen add the rest as your codebase grows.
\nIf you need rules these five can't express, like proving your feature slices contain no dependency cycles, I covered that in architecture fitness functions with ArchUnitNET.
\nIf you want to see how I structure Clean Architecture projects with these guardrails,\ncheck out Pragmatic Clean Architecture.
\nThanks for reading.
\nAnd stay awesome!
\nTwo-factor authentication in ASP.NET Core comes down to TOTP: generate a random secret with Otp.NET, encode it as Base32, and render an otpauth:// URI as a QR code the user scans.\nActivate 2FA only after the user submits a valid first code, and encrypt the secret at rest.
I got hit with a security incident recently.\nSomeone accessed an account of mine that had a strong, unique password.\nBut no second factor.
\nIt was a wake-up call.\nPasswords alone are not enough.\nThey get phished, leaked in breaches, or brute-forced.\nA second factor changes the equation entirely.
\nTwo-Factor Authentication (2FA) adds an extra verification step beyond the password.\nEven if an attacker steals the password, they still can't get in without the second factor.\nIt's one of the most effective security measures you can implement, and it's not that hard to build.
\nIn this article, I'll walk you through implementing 2FA in .NET using Time-based One-Time Passwords (TOTP) with QR codes and authenticator apps like Google Authenticator.
\nWe'll cover:
\nLet's dive in.
\nTOTP (Time-based One-Time Password) is the algorithm behind apps like Google Authenticator, Microsoft Authenticator, and Authy.
\nThe idea is simple: a shared secret is established between the server and the user's authenticator app.\nBoth sides use that secret combined with the current time to generate a 6-digit code that changes every 30 seconds.
\nHere's the flow:
\n![\"TOTP](\"https://milanjovanovic.tech/blogs/mnw_183/totp_flow.png\")
\nBecause both sides compute the code independently, there's no network call to validate.\nThe server just checks: "given this secret and the current time, does the code match?"
\nThis makes TOTP fast, offline-capable, and resistant to replay attacks (each code is only valid for a short window).
\nEvery user needs their own unique secret key.\nThis key is the foundation of the entire 2FA system, so it must be cryptographically random.
\nWe'll use the Otp.NET library for TOTP operations:
\ndotnet add package Otp.NET\nGenerate a secret key for a user:
\nusing OtpNet;\n\nbyte[] secretKey = KeyGeneration.GenerateRandomKey(); // 20 bytes by default (SHA-1)\nstring base32Secret = Base32Encoding.ToString(secretKey);\nKeyGeneration.GenerateRandomKey() produces a cryptographically secure random key.\nWe encode it as Base32 because that's what the otpauth URI scheme expects.
This secret must be stored securely.\nIt's the equivalent of a password.\nIf an attacker gets the secret, they can generate valid codes.\nI'll cover encrypting it at rest later in this article.
\nTo set up 2FA, the user needs to scan a QR code with their authenticator app.\nThe QR code encodes an otpauth:// URI that contains the secret key and metadata.
Install the QRCoder library:
\ndotnet add package QRCoder\nHere's how to generate the QR code:
\nusing QRCoder;\n\nconst string issuer = "MyApp";\nconst string user = "user@example.com";\n\nstring escapedIssuer = Uri.EscapeDataString(issuer);\nstring escapedUser = Uri.EscapeDataString(user);\n\nstring otpUri =\n $"otpauth://totp/{escapedIssuer}:{escapedUser}" +\n $"?secret={base32Secret}" +\n $"&issuer={escapedIssuer}" +\n $"&digits=6" +\n $"&period=30";\n\nusing var qrGenerator = new QRCodeGenerator();\nusing var qrCodeData = qrGenerator.CreateQrCode(otpUri, QRCodeGenerator.ECCLevel.Q);\nusing var qrCode = new PngByteQRCode(qrCodeData);\nbyte[] qrCodeImage = qrCode.GetGraphic(10);\nLet's unpack the otpauth:// URI parameters:
secret - The Base32-encoded shared secretissuer - Your application name (shown in the authenticator app)digits - Number of digits in the code (standard is 6)period - How often the code rotates in seconds (standard is 30)The ECCLevel.Q gives us a good balance between error correction and QR code size.\nIt means the QR code can still be scanned even if about 25% of it is damaged or obscured.
Here's what the generated QR code looks like:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_183/qr_code_example.png\")
\nAnd once the user scans it, the entry appears in their authenticator app:
\n![\"Google](\"https://milanjovanovic.tech/blogs/mnw_183/google_authenticator_entry.png\")
\nYou can also display the base32Secret string alongside the QR code.\nSome users prefer to type it in manually.
Getting the setup flow right is critical.\nIf you enable 2FA the moment the user requests it, before they've even scanned the QR code, you've locked them out.
\nHere's the correct flow:
\nThe key insight is step 3.\nNever enable 2FA until the user has confirmed they can generate valid codes.\nOtherwise, you'll end up with users who have 2FA "enabled" but no way to generate codes.
\n![\"Sequence](\"https://milanjovanovic.tech/blogs/mnw_183/setup_flow.png\")
\nHere's what the API endpoints look like.\nAll 2FA endpoints must be protected, the user has to be authenticated first.\nThe best practice is to use .RequireAuthorization() on each endpoint:
app.MapPost("2fa/setup", async (HttpContext context, UserService userService) =>\n{\n var userId = context.User.GetUserId();\n\n byte[] secretKey = KeyGeneration.GenerateRandomKey();\n string base32Secret = Base32Encoding.ToString(secretKey);\n\n // Store the pending secret (encrypted) - NOT yet active\n await userService.StorePendingTwoFactorSecret(userId, base32Secret);\n\n string otpUri =\n $"otpauth://totp/{Uri.EscapeDataString("MyApp")}:{Uri.EscapeDataString(userId)}" +\n $"?secret={base32Secret}" +\n $"&issuer={Uri.EscapeDataString("MyApp")}" +\n $"&digits=6&period=30";\n\n using var qrGenerator = new QRCodeGenerator();\n using var qrCodeData = qrGenerator.CreateQrCode(otpUri, QRCodeGenerator.ECCLevel.Q);\n using var qrCode = new PngByteQRCode(qrCodeData);\n byte[] qrCodeImage = qrCode.GetGraphic(10);\n\n return Results.File(qrCodeImage, "image/png");\n})\n.RequireAuthorization();\nAnd the confirmation endpoint:
\napp.MapPost("2fa/confirm", async (\n ConfirmTwoFactorRequest request,\n HttpContext context,\n UserService userService) =>\n{\n var userId = context.User.GetUserId();\n\n string? pendingSecret = await userService.GetPendingTwoFactorSecret(userId);\n if (pendingSecret is null)\n {\n return Results.BadRequest("No pending 2FA setup found.");\n }\n\n byte[] secretKey = Base32Encoding.ToBytes(pendingSecret);\n var totp = new Totp(secretKey);\n\n bool isValid = totp.VerifyTotp(\n request.Code,\n out _,\n VerificationWindow.RfcSpecifiedNetworkDelay);\n\n if (!isValid)\n {\n return Results.BadRequest("Invalid code. Please try again.");\n }\n\n // Code is valid - activate 2FA\n await userService.ActivateTwoFactor(userId, pendingSecret);\n\n // Generate recovery codes\n var recoveryCodes = await userService.GenerateRecoveryCodes(userId);\n\n return Results.Ok(new { recoveryCodes });\n})\n.RequireAuthorization();\n\ninternal record ConfirmTwoFactorRequest(string Code);\nThis two-step approach guarantees you never activate 2FA for a user who can't actually use it.\nIf the user abandons the setup halfway through, the pending secret gets cleaned up and nothing breaks.
\nHere's a critical point that's easy to get wrong: don't issue a full access token until the user passes the 2FA check.
\nIf a user has 2FA enabled and you issue a JWT after they enter their password, you've already given them full access.\nThe 2FA step becomes meaningless.
\nThe correct approach is a two-step login:
\n2fa/validate endpointapp.MapPost("auth/login", async (LoginRequest request, UserService userService) =>\n{\n var user = await userService.ValidateCredentials(request.Email, request.Password);\n if (user is null)\n {\n return Results.Unauthorized();\n }\n\n if (user.TwoFactorEnabled)\n {\n // Issue a short-lived, limited token that only permits 2FA validation\n var limitedToken = TokenService.GenerateLimitedToken(user.Id, purpose: "2fa");\n\n return Results.Ok(new { requiresTwoFactor = true, token = limitedToken });\n }\n\n // No 2FA - issue full access token\n var accessToken = TokenService.GenerateAccessToken(user);\n\n return Results.Ok(new { accessToken });\n});\nThe limited token should have a short expiration (2-3 minutes) and a claim or scope that restricts it to the 2fa/validate endpoint only.\nYour authorization policy on the validation endpoint can check for this specific claim.
This way, a stolen password alone never results in a full access token.
\nOnce 2FA is active, you need to validate codes during login.\nHere's the validation logic:
\napp.MapPost("2fa/validate", async (\n ValidateOtpRequest request,\n HttpContext context,\n UserService userService) =>\n{\n var userId = context.User.GetUserId();\n\n string? secret = await userService.GetTwoFactorSecret(userId);\n if (secret is null)\n {\n return Results.BadRequest("2FA is not enabled.");\n }\n\n byte[] secretKey = Base32Encoding.ToBytes(secret);\n var totp = new Totp(secretKey);\n\n bool isValid = totp.VerifyTotp(\n request.Code,\n out long timeStepMatched,\n VerificationWindow.RfcSpecifiedNetworkDelay);\n\n return Results.Ok(new { isValid });\n})\n.RequireAuthorization();\n\ninternal record ValidateOtpRequest(string Code);\nThe VerificationWindow.RfcSpecifiedNetworkDelay parameter is important.\nIt allows a small window of tolerance around the current time step.\nThis accounts for clock drift between the server and the user's device.
Without a verification window, a code that was valid 2 seconds ago might be rejected because the server crossed into the next 30-second period.\nThe RFC-specified window typically allows one time step before and after the current one.
\nOne subtle but important point: a TOTP code should only be accepted once.
\nIf an attacker intercepts a valid code (e.g., through shoulder surfing), they shouldn't be able to reuse it.\nThe timeStepMatched output parameter tells you which time step the code belongs to.\nYou can store the last used time step and reject any code from the same or earlier step:
bool isValid = totp.VerifyTotp(\n request.Code,\n out long timeStepMatched,\n VerificationWindow.RfcSpecifiedNetworkDelay);\n\nif (isValid)\n{\n long? lastUsedTimeStep = await userService.GetLastUsedTimeStep(userId);\n\n if (lastUsedTimeStep.HasValue && timeStepMatched <= lastUsedTimeStep.Value)\n {\n return Results.BadRequest("Code already used.");\n }\n\n await userService.UpdateLastUsedTimeStep(userId, timeStepMatched);\n}\nThis prevents replay attacks within the verification window.
\nThe validation endpoint is a brute-force target.\nA 6-digit code has only 1,000,000 possible combinations.\nWithout rate limiting, an attacker could try all of them in minutes.
\nAt a minimum, you should:
\nASP.NET Core has a built-in rate limiting middleware that makes this straightforward to add.
\nThe TOTP secret key is the most sensitive piece of data in your 2FA system.\nIf someone dumps your database, they shouldn't be able to generate valid codes for your users.
\nNever store TOTP secrets in plain text.
\nEncrypt them before writing to the database and decrypt only when you need to verify a code.\nI covered this in detail in my article on implementing AES encryption with C#.
\nHere's the general approach:
\npublic class UserService\n{\n private readonly IEncryptionService _encryptionService;\n\n public async Task StorePendingTwoFactorSecret(string userId, string secret)\n {\n string encryptedSecret = _encryptionService.Encrypt(secret);\n\n // Store encryptedSecret in the database\n await _dbContext.Users\n .Where(u => u.Id == userId)\n .ExecuteUpdateAsync(u => u\n .SetProperty(x => x.PendingTwoFactorSecret, encryptedSecret));\n }\n\n public async Task<string?> GetTwoFactorSecret(string userId)\n {\n var user = await _dbContext.Users.FindAsync(userId);\n if (user?.TwoFactorSecret is null) return null;\n\n return _encryptionService.Decrypt(user.TwoFactorSecret);\n }\n}\nThe encryption key itself should live in a key management service like\nAzure Key Vault,\nAWS KMS, or\nHashiCorp Vault.\nNever store it in your appsettings.json or source code.
What happens when a user loses their phone?
\nWithout a recovery mechanism, they're permanently locked out of their account.\nRecovery codes solve this.\nThey're one-time-use codes generated when the user enables 2FA.
\npublic async Task<List<string>> GenerateRecoveryCodes(string userId, int count = 8)\n{\n var codes = new List<string>();\n\n for (int i = 0; i < count; i++)\n {\n // Generate a cryptographically random code\n var bytes = RandomNumberGenerator.GetBytes(5);\n var code = Convert.ToHexString(bytes).ToLower();\n codes.Add(code);\n }\n\n // Hash the codes before storing (same as passwords - one-way)\n var hashedCodes = codes\n .Select(c => BCrypt.Net.BCrypt.HashPassword(c))\n .ToList();\n\n await _dbContext.RecoveryCodes\n .Where(rc => rc.UserId == userId)\n .ExecuteDeleteAsync();\n\n _dbContext.RecoveryCodes.AddRange(\n hashedCodes.Select(h => new RecoveryCode\n {\n UserId = userId,\n CodeHash = h,\n IsUsed = false\n }));\n\n await _dbContext.SaveChangesAsync();\n\n // Return plain text codes to show the user ONCE\n return codes;\n}\nA few important details:
\nbcrypt (e.g. Bcrypt.Net) or similar.When validating a recovery code, check each stored hash until you find a match:
\npublic async Task<bool> ValidateRecoveryCode(string userId, string code)\n{\n var storedCodes = await _dbContext.RecoveryCodes\n .Where(rc => rc.UserId == userId && !rc.IsUsed)\n .ToListAsync();\n\n var matchingCode = storedCodes\n .FirstOrDefault(rc => BCrypt.Net.BCrypt.Verify(code, rc.CodeHash));\n\n if (matchingCode is null) return false;\n\n matchingCode.IsUsed = true;\n await _dbContext.SaveChangesAsync();\n\n return true;\n}\nHere's a minimal but complete setup showing the full 2FA flow.\nI'm using a route group with .RequireAuthorization() so every endpoint underneath is protected:
using OtpNet;\nusing QRCoder;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddAuthentication().AddJwtBearer();\nbuilder.Services.AddAuthorization();\n\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\n\nvar twoFactorGroup = app.MapGroup("2fa").RequireAuthorization();\n\ntwoFactorGroup.MapPost("setup", async (HttpContext context, UserService userService) =>\n{\n var userId = context.User.GetUserId();\n\n byte[] secretKey = KeyGeneration.GenerateRandomKey();\n string base32Secret = Base32Encoding.ToString(secretKey);\n\n await userService.StorePendingTwoFactorSecret(userId, base32Secret);\n\n string otpUri =\n $"otpauth://totp/{Uri.EscapeDataString("MyApp")}:{Uri.EscapeDataString(userId)}" +\n $"?secret={base32Secret}" +\n $"&issuer={Uri.EscapeDataString("MyApp")}" +\n $"&digits=6&period=30";\n\n using var qrGenerator = new QRCodeGenerator();\n using var qrCodeData = qrGenerator.CreateQrCode(otpUri, QRCodeGenerator.ECCLevel.Q);\n using var qrCode = new PngByteQRCode(qrCodeData);\n byte[] qrCodeImage = qrCode.GetGraphic(10);\n\n return Results.File(qrCodeImage, "image/png");\n});\n\ntwoFactorGroup.MapPost("confirm", async (\n ConfirmTwoFactorRequest request,\n HttpContext context,\n UserService userService) =>\n{\n var userId = context.User.GetUserId();\n\n string? pendingSecret = await userService.GetPendingTwoFactorSecret(userId);\n if (pendingSecret is null)\n {\n return Results.BadRequest("No pending 2FA setup found.");\n }\n\n byte[] secretKey = Base32Encoding.ToBytes(pendingSecret);\n var totp = new Totp(secretKey);\n\n bool isValid = totp.VerifyTotp(\n request.Code,\n out _,\n VerificationWindow.RfcSpecifiedNetworkDelay);\n\n if (!isValid)\n {\n return Results.BadRequest("Invalid code. Please try again.");\n }\n\n await userService.ActivateTwoFactor(userId, pendingSecret);\n var recoveryCodes = await userService.GenerateRecoveryCodes(userId);\n\n return Results.Ok(new { recoveryCodes });\n});\n\ntwoFactorGroup.MapPost("validate", async (\n ValidateOtpRequest request,\n HttpContext context,\n UserService userService) =>\n{\n var userId = context.User.GetUserId();\n\n string? secret = await userService.GetTwoFactorSecret(userId);\n if (secret is null)\n {\n return Results.BadRequest("2FA is not enabled.");\n }\n\n byte[] secretKey = Base32Encoding.ToBytes(secret);\n var totp = new Totp(secretKey);\n\n bool isValid = totp.VerifyTotp(\n request.Code,\n out long timeStepMatched,\n VerificationWindow.RfcSpecifiedNetworkDelay);\n\n if (isValid)\n {\n long? lastUsedTimeStep = await userService.GetLastUsedTimeStep(userId);\n if (lastUsedTimeStep.HasValue && timeStepMatched <= lastUsedTimeStep.Value)\n {\n return Results.BadRequest("Code already used.");\n }\n\n await userService.UpdateLastUsedTimeStep(userId, timeStepMatched);\n }\n\n return Results.Ok(new { isValid });\n});\n\napp.Run();\n\ninternal record ConfirmTwoFactorRequest(string Code);\ninternal record ValidateOtpRequest(string Code);\nIf you don't need full control, Keycloak and\nASP.NET Core Identity\nboth support TOTP-based 2FA out of the box.\nBut building it yourself is worth it when you need a custom flow or\nwant to understand what's happening under the hood.
\n2FA is one of the highest-impact security features you can add to an application.\nTOTP with authenticator apps is a solid choice because it's offline-capable, widely supported, and doesn't depend on SMS (which is vulnerable to SIM swapping).
\nThe important parts to get right:
\nIf you're building APIs that handle sensitive operations, adding 2FA significantly raises the bar for attackers.\nIt's not bulletproof, but it stops the vast majority of credential-based attacks.
\nIf you're looking for a deep dive into building secure APIs with authentication and encryption,\ncheck out my Pragmatic REST APIs course.
\nHope this was useful. See you next week.
\nModules and vertical slices solve different problems.\nA module is a bounded context that owns its data and exposes a public API, while a vertical slice groups the request, handler, validation, and data access for one use case.\nModules are the macro decision, and each module independently picks its micro architecture, which is where vertical slices fit.
\nMost teams get the macro architecture right.\nThey build a modular monolith with clear module boundaries, public APIs, and proper data isolation.
\nBut then they stop thinking about architecture.\nEvery module gets the same internal structure, usually some form of layered architecture.
\nThe thing is, Clean Architecture and Vertical Slice Architecture aren't as far apart as people think.\nBoth focus on use cases and maximizing cohesion.\nClean Architecture just adds a rule for the direction of dependencies, which often leads to more abstractions and ceremony.\nMy Pragmatic Clean Architecture approach takes a middle ground, and it's quite similar to VSA in nature.
\nThe real question isn't which one is "better".\nIt's where each one shines inside your modular monolith.\nAnd the beautiful part is: you can mix and match.
\nThere are two architectural decisions you need to make when building a modular monolith:
\nMost articles about modular monoliths focus entirely on the macro level.\nAnd for good reason.\nGetting module boundaries wrong is expensive to fix.
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_182/modular_monolith.png\")
\nBut the micro level is equally important.\nIt determines how easy it is to add features, navigate code, and onboard new developers within a module.\nIt's the architecture your team interacts with every day.
\nThe key insight is this:
\n\n\nThe macro architecture constrains how modules interact.\nThe micro architecture is a local decision each module can make independently.
\n
Your Ticketing module doesn't have to follow the same internal structure as your Notifications module.\nThe modular boundary gives you this freedom.
I've seen people conflate vertical slices with modules.\nOn the macro level, a module can look like a "vertical slice" of the business domain.\nBut that analogy breaks down at the application level.
\nA module is a bounded context.\nIt owns its data, exposes a public API, and encapsulates a business capability.\nA vertical slice is a feature implementation pattern.\nIt groups the request, handler, validation, and data access for a single use case.
\nModules and vertical slices operate at different levels.\nModules define the boundaries of the system.\nVertical slices organize the code within those boundaries.
\n![\"Vertical](\"https://milanjovanovic.tech/blogs/mnw_182/vertical_slices.png\")
\nVertical Slice Architecture\norganizes code by feature instead of by technical layer.\nEach feature is a self-contained unit: request, handler, validation, data access, all in one place.
\nInside a modular monolith module, this is a natural fit.\nThe module boundary already enforces separation from the rest of the system.\nYou don't need layers to protect you.\nThe module's public API does that.
\nHere's what a Ticketing module looks like with vertical slices using one file per feature:
📁 Modules/\n|__ 📁 Ticketing\n |__ 📁 Features\n |__ 📁 AddItemToCart\n |__ #️⃣ AddItemToCart.cs\n |__ 📁 SubmitOrder\n |__ #️⃣ SubmitOrder.cs\n |__ 📁 GetOrder\n |__ #️⃣ GetOrder.cs\n |__ 📁 CancelOrder\n |__ #️⃣ CancelOrder.cs\n |__ 📁 RefundPayment\n |__ #️⃣ RefundPayment.cs\n |__ 📁 Data\n |__ #️⃣ TicketingDbContext.cs\n |__ 📁 Entities\n |__ #️⃣ Order.cs\n |__ #️⃣ Ticket.cs\n |__ #️⃣ ITicketingModule.cs\n |__ #️⃣ TicketingModule.cs\nYou can also use separate files per component if you prefer more granularity:
\n📁 Modules/\n|__ 📁 Ticketing\n |__ 📁 Features\n |__ 📁 SubmitOrder\n |__ #️⃣ SubmitOrderRequest.cs\n |__ #️⃣ SubmitOrderResponse.cs\n |__ #️⃣ SubmitOrderHandler.cs\n |__ #️⃣ SubmitOrderValidator.cs\n |__ #️⃣ SubmitOrderEndpoint.cs\n |__ 📁 GetOrder\n |__ #️⃣ GetOrderRequest.cs\n |__ #️⃣ GetOrderResponse.cs\n |__ #️⃣ GetOrderHandler.cs\n |__ #️⃣ GetOrderEndpoint.cs\n |__ 📁 Data\n |__ 📁 Entities\n |__ #️⃣ ITicketingModule.cs\n |__ #️⃣ TicketingModule.cs\nBoth approaches keep everything for a feature in one folder.\nCompare this to having Application, Domain, and Infrastructure\nfolders with dozens of files scattered across layers.\nThe vertical slice version is flat, scannable, and easy to navigate.
Here's a concrete example using a static class to group the feature components:
\npublic static class SubmitOrder\n{\n public record Request(string CartId);\n public record Response(string OrderId, decimal Total);\n\n public class Validator : AbstractValidator<Request>\n {\n public Validator()\n {\n RuleFor(x => x.CartId).NotEmpty();\n }\n }\n\n public class Endpoint : IEndpoint\n {\n public void MapEndpoint(IEndpointRouteBuilder app)\n {\n app.MapPost("orders", Handler).WithTags("Ticketing");\n }\n\n public static async Task<IResult> Handler(\n Request request,\n IValidator<Request> validator,\n TicketingDbContext context)\n {\n var result = validator.Validate(request);\n if (!result.IsValid)\n {\n return Results.BadRequest(result.Errors);\n }\n\n var cart = await context.Carts\n .Include(c => c.Items)\n .FirstOrDefaultAsync(c => c.Id == request.CartId);\n\n if (cart is null)\n {\n return Results.NotFound();\n }\n\n var order = Order.Create(cart);\n\n context.Orders.Add(order);\n await context.SaveChangesAsync();\n\n return Results.Ok(\n new Response(order.Id, order.Total));\n }\n }\n}\nAdding a new feature means adding a new folder.\nYou're not touching shared code across layers.\nYou're not worrying about side effects.
\nA common misconception is that VSA is only for simple modules and Clean Architecture is for complex ones.\nThat's not how it works.
\nVertical slices work great with rich domain models.\nYou can have domain entities, value objects, and domain events inside a vertical slice.\nThe slice organizes the entry point and orchestration. The domain model handles the business rules.\nAs the slice grows in complexity, you push logic into the domain\njust like you would in Clean Architecture.
\nSimilarly, Pragmatic Clean Architecture works well for simpler modules too.\nThe structure is lightweight when the domain is simple.
\nSo the decision isn't about complexity.\nIt's about what your team is comfortable with and what gives you the most clarity.
\nHere are a few things I consider:
\nDomain layer can make that sharing explicit.\nWith VSA, you'd extract shared logic into a separate folder, which also works.The modular boundary protects the rest of the system regardless of what you choose inside the module.\nSo pick what makes your team most productive and be willing to change as the module evolves.
\nModular Monolith answers the macro question:\nhow to decompose the system into modules with clear boundaries.\nVertical Slice Architecture answers the micro question:\nhow to organize code by feature inside those modules.
\nThey operate at different levels.\nModular Monolith gives you high cohesion within each module and helps you manage coupling between modules.\nVertical Slice Architecture gives you high cohesion within each feature inside a module.
\nYou don't have to pick one internal architecture for the entire system.\nEach module can choose what works best for its context.\nSome modules will use Pragmatic Clean Architecture.\nOthers will use vertical slices.\nA well-defined module boundary makes this safe.
\nIf you want to see how I build modular monoliths with this approach,\ncheck out Modular Monolith Architecture.
\nSee you next week.
\nYou can run a vision model locally with Ollama and talk to it from .NET through Microsoft.Extensions.AI.\nAttach the image bytes as DataContent on a ChatMessage, then call GetResponseAsync<T> to get a strongly typed C# object back instead of raw JSON.\nMost of the accuracy work happens in the system prompt.
I wanted to see how well a vision model (LLM) could parse grocery receipts into structured data.
\nAnd I don't just mean describe what it sees.\nI want to be able to actually extract line items, quantities, and prices into clean JSON.\nRunning entirely on my machine with Ollama and a llama3.2-vision model.
\nIt started as a quick experiment. I ended up spending a whole evening on it.
\nIn this week's issue, I'll walk you through:
\nLet's dive in.
\nOllama lets you run large language models locally.\nYou pull a model the same way you'd pull a Docker image, and it runs on your hardware.
\nollama pull llama3.2-vision:latest\n\n# Then run the model locally\nollama run llama3.2-vision:latest\nOn the .NET side, Microsoft.Extensions.AI\nprovides a unified IChatClient interface for talking to any LLM provider.\nCombined with OllamaSharp, the setup is minimal:
var builder = Host.CreateApplicationBuilder();\n\nbuilder.Services.AddChatClient(\n new OllamaApiClient(\n new Uri("http://localhost:11434"),\n "llama3.2-vision:latest"));\n\nvar app = builder.Build();\n\nvar chatClient = app.Services.GetRequiredService<IChatClient>();\nThat gives us an IChatClient backed by a local vision model.\nYou don't have to manage any API keys or cloud dependencies.
The nice thing about IChatClient is that it's provider-agnostic.\nIf you want to swap Ollama for OpenAI or Azure later, your application code doesn't change.
The simplest thing to try: send a receipt image and ask what's in it.
\nvar message = new ChatMessage(\n ChatRole.User, "What's in this image?");\n\nmessage.Contents.Add(\n new DataContent(\n File.ReadAllBytes("receipts/receipt_1.png"),\n "image/png"));\n\nvar response = await chatClient.GetResponseAsync([message]);\n\nConsole.WriteLine(response.Text);\nYou read the image bytes, wrap them in a DataContent with the appropriate MIME type, and attach it to a ChatMessage.
Here's the receipt I used for testing.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_181/receipt_1.png\")
\nAnd here's the raw text response from the model:
\nThis image appears to be a receipt or invoice in a foreign language, likely Russian or another\nSlavic language. The document is in black and white and features a large QR code at the bottom.\nThe text is in a blocky, old-style font and includes several columns of numbers and words.\nThe top of the page has a header with some information in a foreign language, followed by a\nseries of columns with various details such as date, time, and product information. The document\nalso includes some calculations and a total at the bottom. The overall design and layout suggest\nthat this is a receipt or invoice from a store or restaurant, but the specific details and\nlanguage make it difficult to understand without further context or translation.\nThe model correctly identified it as a receipt and listed the items on it.\nThat's impressive for a first try with zero fine-tuning.\nBut it's not very useful if we want to extract structured data.
\nThe good thing is we can refine our prompt and ask for a more specific output format.
\nA text description isn't very useful programmatically. So I asked for structured JSON instead:
\nvar message = new ChatMessage(ChatRole.User,\n @"""\n Extract all line items from this receipt.\n Respond in JSON format with this structure:\n {\n "items": [\n {\n "name": "item name",\n "quantity": 1.500,\n "unitPrice": 0.00,\n "totalPrice": 0.00\n }\n ],\n "subtotal": 0.00\n }\n """);\nmessage.Contents.Add(\n new DataContent(\n File.ReadAllBytes("receipts/receipt_1.png"),\n "image/png"));\n\nvar response = await chatClient.GetResponseAsync([message]);\n\nConsole.WriteLine(response.Text);\nHere's the new response from the model:
\nHere is the receipt in JSON format with all line items extracted:\n\n{\n "items": [\n {\n "name": "limun /kg (A)",\n "quantity": 280.00,\n "unitPrice": 1.105,\n "totalPrice": 309.40\n },\n {\n "name": "salata /kom (A)",\n "quantity": 70.00,\n "unitPrice": 3.00,\n "totalPrice": 210.00\n },\n {\n "name": "susam 100g trpeza /kom (A)",\n "quantity": 90.00,\n "unitPrice": 1.00,\n "totalPrice": 90.00\n }\n ],\n "subtotal": 609.40\n}\nThis worked surprisingly well on the first try.\nThe model returned a JSON blob with item names, quantities, and prices.\nSome quantities were slightly off but the structure was correct.
\nFor zero fine-tuning, I was impressed.
\nHere's what I found: when the model misreads a digit or rounds a number, you don't fix a bug in C#.\nYou refine the system prompt.
\nWhat is a system prompt?\nIt's the initial instruction you give the model to set the context for the conversation.\nNotice the ChatRole.System in the code below.\nConversely, we use ChatRole.User for the message where we ask the question.
After a few rounds of this, my system prompt ended up reading like a specification document:
\nvar systemMessage = new ChatMessage(ChatRole.System,\n @"""\n You are a receipt parsing assistant. Extract all line items from the receipt image.\n For each line item, extract the name, quantity, unit price, and total price.\n Quantity can be a decimal number (e.g. weight in kg like 0.550 or 1.105).\n Extract the subtotal which is the final total amount shown on the receipt.\n IMPORTANT: Read every digit exactly as printed on the receipt.\n Pay very close attention to each decimal digit - do NOT round or approximate.\n For example, if the receipt shows 1.105, report exactly 1.105, not 1.1 or 1.2.\n Verify that quantity * unitPrice = totalPrice for each line item.\n Don't invent items that aren't on the receipt.\n\n DECIMAL FORMAT: Receipts may use different number formats depending on locale.\n - Some use period as decimal separator: 7,499.00\n - Some use comma as decimal separator: 7.499,00\n First, detect which format the receipt uses by examining the numbers on it.\n Then, always output numbers in the JSON using a period as the decimal separator.\n For example: 7499.00, not 7.499,00 or 7,499.00.\n """);\nEvery instruction in that prompt exists because the model got something wrong.
\n"Read every digit exactly as printed": it was rounding 1.105 to 1.1.
"Don't invent items": it hallucinated a line item that wasn't on the receipt.
\nThe entire decimal format section: my receipts use commas as decimal separators (European locale),\nand the model kept confusing thousands separators with decimal points.
\nEach prompt iteration is like a debugging session with words instead of code.\nIt's not the most fun part, but it's necessary to get accurate results.
\nAnd to think we used to write code to tell computers what to do.\nNow we write prompts to tell models how to think.\nI digress...
\nThis is where Microsoft.Extensions.AI gets interesting.
Instead of parsing raw JSON strings yourself, you can call GetResponseAsync<T> and get back a strongly typed object:
var response = await chatClient.GetResponseAsync<Receipt>(\n [systemMessage, message],\n new ChatOptions { Temperature = 0 });\n\nif (response.Result is { } receipt)\n{\n Console.WriteLine(\n $"\\nExtracted {receipt.Items.Count} line items:");\n\n foreach (var item in receipt.Items)\n {\n Console.WriteLine(\n $" {item.Name} - " +\n $"Qty: {item.Quantity} x {item.UnitPrice:C}" +\n $" = {item.TotalPrice:C}");\n }\n\n Console.WriteLine($" Subtotal: {receipt.Subtotal:C}");\n}\nThe Receipt and LineItem classes are plain C# objects:
public class Receipt\n{\n public List<LineItem> Items { get; set; } = [];\n public decimal Subtotal { get; set; }\n}\n\npublic class LineItem\n{\n public string Name { get; set; } = string.Empty;\n public decimal Quantity { get; set; }\n public decimal UnitPrice { get; set; }\n public decimal TotalPrice { get; set; }\n}\nThe library generates the JSON schema, sends it to the model, and deserializes the response.\nYou get back a Receipt object directly.
I also set Temperature = 0 to make the output as deterministic as possible.\nFor data extraction, you want accuracy.\nThis isn't foolproof, but it helps.
Here's the object we get back from the model in Visual Studio:
\n![\"Visual](\"https://milanjovanovic.tech/blogs/mnw_181/chat_client_typed_response_in_vs.png\")
\nOne thing I wanted to verify: if I send the same receipt with the same prompt five times, do I get the same result?
\nconst int runs = 5;\nConsole.WriteLine($"\\n--- Consistency test ({runs} runs) ---");\n\nvar results = new List<Receipt>();\nfor (int i = 0; i < runs; i++)\n{\n Console.WriteLine($"\\nRun {i + 1}...");\n var testResponse = await chatClient.GetResponseAsync<Receipt>(\n [systemMessage, message],\n new ChatOptions { Temperature = 0 });\n\n if (testResponse.Result is { } r)\n {\n results.Add(r);\n Console.WriteLine(\n $" Items: {r.Items.Count}, " +\n $"Subtotal: {r.Subtotal:C}");\n\n foreach (var item in r.Items)\n {\n Console.WriteLine(\n $" {item.Name} - " +\n $"Qty: {item.Quantity} x {item.UnitPrice:C}" +\n $" = {item.TotalPrice:C}");\n }\n }\n}\nThen I compare every run against the baseline:
\nvar baseline = results[0];\nfor (int i = 1; i < results.Count; i++)\n{\n bool match = baseline.Subtotal == results[i].Subtotal\n && baseline.Items.Count == results[i].Items.Count\n && baseline.Items.Zip(results[i].Items).All(pair =>\n pair.First.Name == pair.Second.Name\n && pair.First.Quantity == pair.Second.Quantity\n && pair.First.UnitPrice == pair.Second.UnitPrice\n && pair.First.TotalPrice == pair.Second.TotalPrice);\n\n Console.WriteLine(\n $" Run 1 vs Run {i + 1}: " +\n $"{(match ? "MATCH" : "DIFFERENT")}");\n}\nTemperature 0 helps, but vision models aren't perfectly deterministic.\nMost runs matched. Some didn't.\nThe differences were usually small - a misread digit, a slightly different item name.
\nThis is worth keeping in mind when working with LLMs.\nThey're probabilistic systems.\nEven with temperature 0, the same input can produce slightly different output.\nIf you need guaranteed accuracy, you'll want validation layers on top of this.
\nThe receipt scanner is a starting point.\nOnce you have structured data from receipt images, you can build on top of it.
\nI've been thinking about extending this into a personal finance tracker.\nScan receipts, store the data, and use the same LLM to categorize purchases.\nGroceries, household, electronics - let the model figure it out.
\nFrom there, you could generate weekly and monthly spending summaries.\nHow much did I spend on groceries this month?\nHow does that compare to last month?
\nYou could also do multi-receipt aggregation for business trips.\nScan a stack of receipts and generate an expense report.
\nOr price tracking over time - detect when items at your usual store go up in price.
\nWe could defintiely build semantic search\non top of this too.\nSearch through your past receipts for specific items or price ranges.\nThis works by embedding the structured data and using vector search\nto find relevant entries.
\nThe vision model handles the hard part: turning unstructured images into structured data.\nEverything after that is regular application development.
\nI might build some of this out. We'll see.
\nRunning a vision model locally with Ollama is straightforward to set up.\nMicrosoft.Extensions.AI and OllamaSharp make the .NET integration clean.\nYou get a provider-agnostic IChatClient with support for strongly typed responses.\nYou could also run this with Aspire and GitHub models\nif you want to keep everything in the Microsoft ecosystem.
The system prompt is where most of the work happens.\nEvery line in mine was the result of the model getting something wrong and me adding a corrective instruction.
\nIf you want to try this yourself:
\nollama pull llama3.2-vision:latestOllamaSharp and Microsoft.Extensions.AI NuGet packagesHope this was useful. See you next week.
\nYou can hand authentication to Keycloak instead of building it: run it as a container, create a realm with a public client, and point your .NET API at its metadata endpoint.\nSwagger UI drives the OAuth 2.0 Authorization Code flow with PKCE, and the API validates the resulting JWT locally against Keycloak's cached signing keys.
\nAuthentication is one of those things that's easy to get wrong and expensive to fix later.\nRolling your own auth system means dealing with password hashing, token management, session handling,\nand a never-ending stream of security patches.
\nI was never a fan of this...
\nWhat if you could outsource all of that to a battle-tested identity provider?
\nKeycloak is an open-source identity and access management solution.\nIt handles user authentication, authorization, and identity brokering (social logins, enterprise SSO) out of the box.\nYou get a polished admin console, built-in support for OAuth 2.0 and OpenID Connect, and it runs anywhere Docker does.
\nWe'll spin up Keycloak as a container, create a realm with a public client,\nand wire up Swagger UI to authenticate using the OAuth 2.0 Authorization Code flow.\nThen we'll add JWT validation to our .NET backend and\ntrace the entire authentication flow using the Aspire Dashboard.
\nThe fastest way to spin up Keycloak is with Docker>).\nWe'll run it in development mode, which disables HTTPS and uses an embedded H2 database.\nThis is perfect for local development but not suitable for production (more on that later).
\nHere's a minimal docker-compose.yml:
services:\n keycloak:\n image: quay.io/keycloak/keycloak:26.5.2\n container_name: keycloak\n environment:\n - KC_BOOTSTRAP_ADMIN_USERNAME=admin\n - KC_BOOTSTRAP_ADMIN_PASSWORD=admin\n ports:\n - '8080:8080'\n command: start-dev\nStart it with:
\ndocker compose up -d\nOnce Keycloak is running, navigate to http://localhost:8080 and log in with admin / admin.
![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_admin_login.png\")
\nYou should see the Keycloak admin console.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_admin_console.png\")
\nKeycloak organizes everything into realms.\nA realm is a space where you manage users, roles, and applications.\nThe master realm is reserved for Keycloak administration, so we'll create a new one for our application.
keycloak-demo) and click Create![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_create_realm_dialog.png\")
\nNow we need to register our application.\nIn OAuth 2.0 terms, this is a client.\nSince Swagger UI runs in the browser, we'll create a public client (no client secret).
\ndemo-apiOpenID Connect![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_create_client_step1.png\")
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_create_client_step2.png\")
\nhttps://localhost:5001/* (your API's Swagger URL)https://localhost:5001![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_create_client_step3.png\")
\nWe need a user to authenticate with.
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_180/keycloak_create_user.png\")
\nYou're now ready to authenticate users against Keycloak!
\nBefore we dive into code, let's understand what happens when a user authenticates.\nThe Authorization Code flow is the recommended OAuth 2.0 flow for browser-based applications.
\nThere's an important security enhancement called PKCE (Proof Key for Code Exchange)\nthat prevents authorization code interception attacks.\nIt works by having the client generate a random secret (the code verifier) and deriving a hash (the code challenge) sent in the initial authorization request.\nWhen exchanging the authorization code for tokens, the client must present the original code verifier.
\nHere's the sequence:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_180/authorization_code_flow.png\")
\nThe beauty of this flow is that credentials never touch your application.\nThe user authenticates directly with Keycloak, and your API only sees signed tokens.
\nNow let's set up our .NET API to use Swagger UI as our OAuth 2.0 test client.
\nFirst, install the required packages:
\ndotnet add package Swashbuckle.AspNetCore\nConfigure Swagger in your Program.cs:
var keycloakAuthority = builder.Configuration["Keycloak:Authority"]!;\nvar keycloakClientId = builder.Configuration["Keycloak:ClientId"]!;\n\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen(options =>\n{\n options.SwaggerDoc("v1", new OpenApiInfo\n {\n Title = "Demo API",\n Version = "v1"\n });\n\n // Define the OAuth 2.0 security scheme\n options.AddSecurityDefinition(nameof(SecuritySchemeType.OAuth2), new OpenApiSecurityScheme\n {\n Type = SecuritySchemeType.OAuth2,\n Flows = new OpenApiOAuthFlows\n {\n AuthorizationCode = new OpenApiOAuthFlow\n {\n AuthorizationUrl = new Uri($"{keycloakAuthority}/protocol/openid-connect/auth"),\n TokenUrl = new Uri($"{keycloakAuthority}/protocol/openid-connect/token"),\n Scopes = new Dictionary<string, string>\n {\n { "openid", "OpenID Connect scope" },\n { "profile", "User profile" }\n }\n }\n }\n });\n\n // Apply security to all operations\n options.AddSecurityRequirement(doc => new OpenApiSecurityRequirement\n {\n {\n new OpenApiSecuritySchemeReference(nameof(SecuritySchemeType.OAuth2), doc),\n []\n }\n });\n});\nAnd configure the Swagger UI middleware:
\nif (app.Environment.IsDevelopment())\n{\n app.UseSwagger();\n app.UseSwaggerUI(options =>\n {\n options.OAuthClientId(keycloakClientId); // Default Client ID\n options.OAuthUsePkce(); // Proof Key for Code Exchange (security enhancement)\n });\n}\nYour appsettings.Development.json:
{\n "Keycloak": {\n "Authority": "http://localhost:8080/realms/keycloak-demo",\n "ClientId": "demo-api",\n "Audience": "account",\n "Issuer": "http://localhost:8080/realms/keycloak-demo",\n // Here we use the Docker service name for Keycloak\n "MetadataAddress": "http://keycloak:8080/realms/keycloak-demo/.well-known/openid-configuration"\n }\n}\nNow when you open Swagger UI, you'll see an Authorize button.\nClicking it opens the OAuth flow, redirecting you to Keycloak to log in.
\n![\"Swagger](\"https://milanjovanovic.tech/blogs/mnw_180/swagger_authorize_form.png\")
\nAt this point, Swagger UI can obtain tokens, but our API isn't validating them yet.\nLet's add JWT Bearer authentication.
\nInstall the authentication package:
\ndotnet add package Microsoft.AspNetCore.Authentication.JwtBearer\nConfigure authentication in Program.cs:
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)\n .AddJwtBearer(options =>\n {\n options.MetadataAddress = builder.Configuration["Keycloak:MetadataAddress"]!;\n options.Audience = builder.Configuration["Keycloak:Audience"];\n\n options.TokenValidationParameters = new TokenValidationParameters\n {\n ValidIssuer = builder.Configuration["Keycloak:Issuer"]\n };\n\n // Required for HTTP in development (Keycloak uses HTTP by default in dev mode)\n options.RequireHttpsMetadata = !builder.Environment.IsDevelopment();\n });\n\nbuilder.Services.AddAuthorization();\nThe default TokenValidationParameters will validate the token signature, expiration, issuer, and audience.
Add the middleware:
\napp.UseAuthentication();\napp.UseAuthorization();\nCreate a protected endpoint:
\napp.MapGet("users/me", (ClaimsPrincipal user) =>\n{\n return Results.Ok(new\n {\n UserId = user.FindFirstValue(ClaimTypes.NameIdentifier),\n Email = user.FindFirstValue(ClaimTypes.Email),\n Name = user.FindFirstValue("preferred_username"),\n Claims = user.Claims.Select(c => new { c.Type, c.Value })\n });\n})\n.RequireAuthorization();\nWhen a request hits your protected endpoint, here's what happens under the hood:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_180/jwt_validation_flow.png\")
\nAuthorization: Bearer <token> headerClaimsPrincipal is populatedHttpContext.UserThe key insight here is that your API never contacts Keycloak to validate individual tokens.\nIt fetches the signing keys once and validates tokens locally.\nThis is what makes JWT-based authentication so fast.
\nIf you're using Aspire, you can observe the entire authentication flow in the distributed traces.
\nHere's what a successful authentication looks like:
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_180/aspire_auth_trace.png\")
\nYou can see:
\nusers/me (with the Bearer token).well-known/openid-configuration endpointOn subsequent requests, you won't see the JWKS call because the keys are cached.
\nThis is why JWT validation adds virtually no latency after the initial key fetch.
\nWhat we've built is great for development.\nFor production, you'll want to address a few things:
\n1. HTTPS Everywhere
\nKeycloak should run behind HTTPS.\nSet KC_HOSTNAME and configure TLS certificates.
2. Persistent Storage
\nReplace the embedded H2 database with PostgreSQL or MySQL:
\nenvironment:\n - KC_DB=postgres\n - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak\n - KC_DB_USERNAME=keycloak\n - KC_DB_PASSWORD=secret\n3. Require HTTPS Metadata
\nRemove options.RequireHttpsMetadata = false in production.
In about 10 minutes, we've set up:
\nWhat I really like about Keycloak is how easy it is to extend.\nWant Google login? Configure it in Keycloak.\nNeed enterprise SSO? Add a SAML provider.\nYour API code stays exactly the same because it just validates tokens.
\nIf you want to see how I integrate Keycloak in a real-world system with role-based access control,\ncheck out Pragmatic Clean Architecture and\nModular Monolith Architecture.
\nSee you next week.
\nSince .NET 7, the SDK can publish an application straight to a container image, so you don't need a Dockerfile.\nRun dotnet publish --os linux --arch x64 /t:PublishContainer and the SDK builds the app, picks a base image, and loads it into Docker.\nYou customize the image through MSBuild properties in the .csproj.
Containers have become the standard for deploying modern applications.\nBut if you've ever written a Dockerfile, you know it can be tedious.\nYou need to understand multi-stage builds, pick the right base images, configure the right ports, and remember to copy files in the correct order.
\nWhat if I told you that you don't need a Dockerfile at all?
\nSince .NET 7, the SDK has built-in support for publishing your application directly to a container image.\nYou can do this with a single dotnet publish command.
In this week's newsletter, we'll explore:
\nBefore we look at the SDK approach, let's see what we're replacing.
\nA typical multi-stage Dockerfile for a .NET application looks like this:
\nFROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base\nWORKDIR /app\nEXPOSE 8080\nEXPOSE 8081\n\nFROM mcr.microsoft.com/dotnet/sdk:10.0 AS build\nARG BUILD_CONFIGURATION=Release\nWORKDIR /src\nCOPY ["src/MyApi/MyApi.csproj", "src/MyApi/"]\nRUN dotnet restore "src/MyApi/MyApi.csproj"\n\nCOPY . .\nWORKDIR "/src/src/MyApi"\nRUN dotnet build "MyApi.csproj" -c $BUILD_CONFIGURATION -o /app/build\n\nFROM build AS publish\nARG BUILD_CONFIGURATION=Release\nRUN dotnet publish "MyApi.csproj" -c $BUILD_CONFIGURATION -o /app/publish\n\nFROM base AS final\nWORKDIR /app\nCOPY --from=publish /app/publish .\nENTRYPOINT ["dotnet", "MyApi.dll"]\nThis works, but there's a learning curve and maintenance overhead:
\nThe .NET SDK approach eliminates all of this.
\nIf you're running on .NET 10, you don't need to do anything special to enable container publishing.\nThis will work for ASP.NET Core apps, worker services, and console apps.
\nYou can publish directly to a container image:
\ndotnet publish --os linux --arch x64 /t:PublishContainer\nThat's it. The .NET SDK will:
\nThe most popular option is Docker, but it also works with Podman.
\n![\"An](\"https://milanjovanovic.tech/blogs/mnw_179/dotnet_publish_container.png\")
\nThe SDK provides sensible defaults, but you'll often want to customize the image.\nFor a more comprehensive list of options, see the official docs.
\nI'll cover the most common customizations here.
\nThe ContainerRepository property sets the image name (repository).\nThe ContainerImageTags property sets one or more tags (separated by semicolons).\nIf you want a single tag, you can use ContainerImageTag instead.
<PropertyGroup>\n <ContainerRepository>ghcr.io/USERNAME/REPOSITORY</ContainerRepository>\n <ContainerImageTags>1.0.0;latest</ContainerImageTags>\n</PropertyGroup>\nFrom .NET 8 and onwards, when a tag isn't provided the default is latest.
By default, the SDK uses the following base images:
\nmcr.microsoft.com/dotnet/runtime-deps for self-contained appsmcr.microsoft.com/dotnet/aspnet image for ASP.NET Core appsmcr.microsoft.com/dotnet/runtime for other casesYou can switch to a smaller or different image:
\n<PropertyGroup>\n <!-- Use the Alpine-based image for smaller size -->\n <ContainerBaseImage>mcr.microsoft.com/dotnet/aspnet:10.0-alpine</ContainerBaseImage>\n</PropertyGroup>\nYou could also do this by setting ContainerFamily to alpine, and letting the rest be inferred.
Here's the size difference between the default and Alpine images for an ASP.NET Core app:
\n![\"An](\"https://milanjovanovic.tech/blogs/mnw_179/container_image_size.png\")
\n| Base Image | Size (MB) |\n| ------------------------------------------- | --------- |\n| mcr.microsoft.com/dotnet/aspnet:10.0 | 231.73 |\n| mcr.microsoft.com/dotnet/aspnet:10.0-alpine | 122.65 |\nYou can see a significant size reduction by switching to alpine.
For web applications, the default exposed ports are 8080 and 8081 for HTTP and HTTPS.\nThese are inferred from ASP.NET Core environment variables (ASPNETCORE_URLS, ASPNETCORE_HTTP_PORT, ASPNETCORE_HTTPS_PORT).\nThe Type attribute can be tcp or udp.
<ItemGroup>\n <ContainerPort Include="8080" Type="tcp" />\n <ContainerPort Include="8081" Type="tcp" />\n</ItemGroup>\nPublishing locally is useful for development, but you'll want to push to a registry for deployment.\nYou can specify the target registry during publishing.
\nHere's an example publishing to GitHub Container Registry:
\ndotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerRegistry=ghcr.io\nAuthentication: The SDK uses your local Docker credentials.\nMake sure you've logged in with docker login before publishing to a remote registry.
However, I don't use the above approach.\nI prefer using docker CLI for the publishing step, as it gives me more control over authentication and tagging.
\nHere's what I'm doing in my GitHub Actions workflow to build and push my .NET app container.\nI left out the boring bits of seting up the .NET environment and checking out code.
\nThis will build the container image, tag it, and push it to GitHub Container Registry:
\n- name: Publish\n run: dotnet publish "${{ env.WORKING_DIRECTORY }}" --configuration ${{ env.CONFIGURATION }} --os linux -t:PublishContainer\n# Tag the build for later steps\n- name: Log in to ghcr.io\n run: echo "${{ env.DOCKER_PASSWORD }}" | docker login ghcr.io -u "${{ env.DOCKER_USERNAME }}" --password-stdin\n- name: Tag Docker image\n run:\n docker tag ${{ env.IMAGE_NAME }}:${{ github.sha }} ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:${{ github.sha }} |\n docker tag ${{ env.IMAGE_NAME }}:latest ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:latest\n- name: Push Docker image\n run:\n docker push ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:${{ github.sha }} |\n docker push ghcr.io/${{ env.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:latest\nOnce my images are up in the registry, I can deploy them to my VPS.
\nI'm using Dokploy (a simple but powerful deployment tool for Docker apps) to pull the latest image and restart my service.
\ndeploy:\n runs-on: ubuntu-latest\n needs: build-and-publish\n steps:\n - name: Trigger deployment\n run: |\n curl -X POST ${{ env.DEPLOYMENT_TRIGGER_URL }} \\\n -H 'accept: application/json' \\\n -H 'Content-Type: application/json' \\\n -H 'x-api-key: ${{ env.DEPLOYMENT_TRIGGER_API_KEY }}' \\\n -d '{\n "applicationId": "${{ env.DEPLOYMENT_TRIGGER_APP_ID }}"\n }'\nThis kicks off a deployment on my VPS, pulling the latest image and restarting the container.
\n![\"An](\"https://milanjovanovic.tech/blogs/mnw_179/dokploy_deployment.png\")
\nBy the way, I'm running my VPS on Hetzner Cloud - highly recommended if you're looking for affordable and reliable VPS hosting.
\nThe SDK container support is powerful, but it doesn't cover every scenario.
\nYou'll still need a Dockerfile when:
\nlibgdiplus for image processing)For most web APIs and background services, the SDK approach is sufficient.
\nThe .NET SDK's built-in container support removes the friction of containerization.
\nYou get:
\n.csprojdotnet runsThe days of copy-pasting Dockerfiles between projects are over.
\nJust enable the feature, customize what you need, and publish.
\nThanks for reading.
\nAnd stay awesome!
\nPassword hashing is one-way, so you cannot upgrade stored hashes in place.\nThe zero-downtime approach is migration on login: verify with the new algorithm first, fall back to the legacy one, and re-hash the password with the new algorithm as soon as the legacy check succeeds.
\nSecurity requirements evolve.\nWhat was considered "secure enough" five years ago might not pass a security audit today.
\nYou need to upgrade to a modern algorithm like Argon2 or Bcrypt.\nBut here is the problem: hashing is a one-way operation.\nYou cannot reverse-engineer the existing hashes to "upgrade" them.
\nIf you simply swap your IPasswordHasher implementation, you break the application.\nEvery single existing user who tries to log in will fail authentication because your new hasher doesn't understand the old format.
In this article, I want to demo a zero-downtime migration concept in practice.
\nReal systems have more constraints (and you should not build auth from scratch).\nBut this is a clean example of a pattern you can reuse for database migrations:
\nLet's dive in.
\nLet's imagine you have a simple authentication system.\nYou want to replace your legacy PBKDF2 hasher with a standard Argon2 implementation.
You might think, "I'll just register the new implementation in the dependency injection container."
\n// Switching from LegacyHasher to ModernHasher\nbuilder.Services.AddSingleton<IPasswordHasher, ModernHasher>();\nHere is the failure scenario:
\nModernHasher tries to verify the PBKDF2 hash.\nIt fails immediately, returning 401 Unauthorized.You have inadvertently locked out your entire user base.\nWe need a way to support both algorithms simultaneously without making the login code a mess.
\nThe strategy is simple: we don't migrate the database in a batch job.\nWe migrate users lazily when they prove their identity.
\nThe flow looks like this:
\nFuture logins for this user will now succeed via the standard flow.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_178/migration_on_login_flow.png\")
\nIn .NET 8, Microsoft introduced Keyed Services, which are perfect for this scenario.\nThey allow us to register multiple implementations of the same interface and retrieve them by name.
\nWe register both hashers in our Program.cs, assigning them unique keys:
// Register the implementations with specific keys\nbuilder.Services.AddKeyedSingleton<IPasswordHasher, Pbdkf2PasswordHasher>("legacy");\nbuilder.Services.AddKeyedSingleton<IPasswordHasher, Argon2PasswordHasher>("modern");\n\n// (Optional) Register the modern one as the default for other services\nbuilder.Services.AddSingleton<IPasswordHasher, Argon2PasswordHasher>();\nNow we implement the migration logic.\nWe inject both hashers using the [FromKeyedServices] attribute.
public class LoginCommandHandler(\n IUserRepository userRepository,\n [FromKeyedServices("modern")] IPasswordHasher newHasher,\n [FromKeyedServices("legacy")] IPasswordHasher legacyHasher)\n{\n public async Task<AuthenticationResult> Handle(LoginCommand command)\n {\n var user = await userRepository.GetByEmailAsync(command.Email);\n if (user is null)\n {\n return AuthenticationResult.Fail();\n }\n\n // 1. Try the new algorithm first (Happy Path)\n if (newHasher.Verify(user.PasswordHash, command.Password))\n {\n return AuthenticationResult.Success(user);\n }\n\n // 2. Fallback: Check if it's a legacy hash\n if (legacyHasher.Verify(user.PasswordHash, command.Password))\n {\n // 3. MIGRATION STEP: Re-hash and save\n var newHash = newHasher.Hash(command.Password);\n\n user.UpdatePasswordHash(newHash);\n await userRepository.SaveChangesAsync();\n\n return AuthenticationResult.Success(user);\n }\n\n return AuthenticationResult.Fail();\n }\n}\n\nThis code ensures that active users are automatically upgraded.\nAfter a few months, the vast majority of your user base will be on the new algorithm.
\nWhile the implementation above works, here are two improvements to make it production-ready.
\nRelying on "trial and error" verification works, but it's cleaner to know exactly which algorithm was used to create a hash.
\nStandard algorithms often include a prefix (e.g., Bcrypt starts with $2a$ or $2b$).\nYou can use this to route the request efficiently:
public bool IsLegacyHash(string hash)\n{\n // This assumes we're storing a prefix for PBKDF2 hashes. Something to consider.\n return hash.StartsWith("pbkdf2$");\n}\nAnother benefit this unlocks is being able to query the database for users still on the legacy format.
\nPerforming a database write during a login request adds latency.\nIf you have high traffic, you might want to control this roll-out.
\nBy wrapping the migration logic behind a Feature Flag, you can disable the "write" step if your database comes under load,\nwhile still allowing users to log in via the read-only fallback.
\nif (await featureManager.IsEnabledAsync(FeatureFlags.MigratePasswords) &&\n legacyHasher.Verify(user.PasswordHash, command.Password))\n{\n // Perform migration...\n}\nAfter you run this for a while (usually a few months), most active accounts will be upgraded.\nYou can then run a cleanup script to identify any remaining legacy hashes and force those users to reset their passwords on the next login attempt.
\nAt that point, you can remove:
\nAnd the migration is complete.
\nA "simple" hashing upgrade is really a data migration.\nThis article is about the migration pattern.\nNot about reinventing auth.
\nThe zero-downtime pattern looks like this:
\nBy allowing the old and new formats to coexist for a period of time, you achieve a seamless transition.\nOnce your monitoring shows that 99% of active users have migrated,\nyou can identify the users on the legacy format and force a password reset on their next attempt.
\nIf you want to see a practical demo of this, check out this video I made.
\nHope this was helpful!
\nHybridCache in .NET 9 shipped without a built-in backplane, so updating data on one node leaves the other nodes serving stale data from their local L1 cache.\nThe fix is a Redis Pub/Sub backplane: the node that changes data publishes the cache key, and every node evicts that key locally.
Distributed systems are great for scalability, but they introduce a whole new class of problems.\nOne of the hardest problems to solve is cache invalidation.
\nIn .NET 9, Microsoft introduced HybridCache to simplify caching.\nIt's a fantastic library that combines the speed of in-memory caching (L1) with the durability of distributed caching (L2) like Redis.\nIt also handles "cache stampede" protection out of the box.
However, there is a catch.
\nWhen you run multiple instances of your application, HybridCache doesn't automatically synchronize the local L1 cache across all nodes.\nIf you update data on Node A, Node B will continue serving stale data from its in-memory cache until the entry expires.
While HybridCache is a massive step forward, the lack of a built-in backplane for invalidation is a known limitation.\nIn fact, there is an active discussion on the dotnet/extensions GitHub repository tracking this exact feature request.\nUntil that ships, we have to roll our own solution.
\nIn this week's newsletter, we'll explore:
\nHybridCache doesn't solve this aloneLet's dive in.
\nLet's imagine a typical production scenario.\nYou have an API running on multiple servers (or pods) behind a load balancer.
\nTo improve performance, you introduce caching.\nYou want the speed of local memory, so you use HybridCache.
Here is the failure scenario:
\nHybridCache.![\"A](\"https://milanjovanovic.tech/blogs/mnw_177/hybridcache_out_of_sync_scenario.png\")
\nWhy Not Just Shorten the Cache Duration?
\nA common "hack" to solve this is to simply reduce the L1 cache duration (TTL).\nFor example, setting the local cache to expire every 10 seconds.
\nWhile this reduces the window of inconsistency, it doesn't solve the problem.\nIt just masks it.
\nThis approach introduces two new issues:
\nFor things like user permissions, feature flags, or pricing, "mostly correct" is often not good enough. You need immediate consistency.
\nTo solve this, we need a backplane.\nIt's a communication channel that connects all our application nodes.
\nWhen a cache entry is removed or updated on one node, we publish a message to the backplane.\nAll other nodes subscribe to this channel and, upon receiving the message, remove the corresponding key from their local cache.
\nRedis is already a popular choice for the L2 cache, so it makes perfect sense to use its Pub/Sub feature\nfor this signaling mechanism.
\nIt works like this:
\ncache-invalidation message with the cache key.HybridCache.RemoveAsync(key).![\"A](\"https://milanjovanovic.tech/blogs/mnw_177/cache_invalidation_message_fanout.png\")
\nWe will need the StackExchange.Redis library to handle the messaging.
Let's start by defining a simple service to handle the publishing.\nThis service will be responsible for notifying the rest of the system that a key has changed.
\npublic interface ICacheInvalidator\n{\n Task InvalidateAsync(string key, CancellationToken cancellationToken = default);\n}\n\npublic class RedisCacheInvalidator(\n IConnectionMultiplexer connectionMultiplexer,\n ILogger<RedisCacheInvalidator> logger)\n : ICacheInvalidator\n{\n private const RedisChannel Channel = RedisChannel.Literal("cache-invalidation");\n\n public async Task InvalidateAsync(string key, CancellationToken cancellationToken = default)\n {\n var subscriber = connectionMultiplexer.GetSubscriber();\n\n await subscriber.PublishAsync(Channel, new RedisValue(key));\n\n logger.LogInformation("Published invalidation for key: {Key}", key);\n }\n}\nNow, whenever you update an entity in your Command Handler or Service, you just call ICacheInvalidator.InvalidateAsync.
public class UpdateUserProfileHandler(\n AppDbContext dbContext,\n ICacheInvalidator cacheInvalidator,\n ILogger<UpdateUserProfileHandler> logger)\n{\n public async Task Handle(int userId, string newName, CancellationToken ct)\n {\n // 1. Update the database\n var user = await dbContext.Users.FindAsync([userId], ct);\n if (user is null)\n {\n return;\n }\n\n user.Name = newName;\n await dbContext.SaveChangesAsync(ct);\n\n // 2. Invalidate the cache (Distributed)\n var cacheKey = $"user:{userId}";\n await cacheInvalidator.InvalidateAsync(cacheKey, ct);\n\n logger.LogInformation("Updated user and invalidated cache for {UserId}", userId);\n }\n}\nNext, we need a background service that runs on every node.\nIt will subscribe to the Redis channel and evict keys from the local HybridCache.
A quick note on self-publishing:\nBecause Redis Pub/Sub broadcasts to everyone subscribed, the node that published the invalidation will also receive the message.\nIn this implementation, we simply remove the key again.\nIt's redundant but harmless, and it keeps the code simple.
\nNote that we are injecting HybridCache directly into our background service.\nAn alternative is using IMemoryCache, since that is the L1 cache inside HybridCache.
public class CacheInvalidationService(\n IConnectionMultiplexer connectionMultiplexer,\n HybridCache hybridCache,\n ILogger<CacheInvalidationService> logger)\n : BackgroundService\n{\n private const RedisChannel Channel = RedisChannel.Literal("cache-invalidation");\n\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n var subscriber = connectionMultiplexer.GetSubscriber();\n\n await subscriber.SubscribeAsync(Channel, (channel, value) =>\n {\n string key = value.ToString();\n\n logger.LogInformation("Invalidating local cache for: {Key}", key);\n\n // This removes the item from the local L1 cache\n var task = hybridCache.RemoveAsync(key, stoppingToken);\n\n if (!task.IsCompleted)\n {\n task.GetAwaiter().GetResult();\n }\n });\n }\n}\n\nFinally, we need to register these services in our DI container.
\nbuilder.Services.AddSingleton<IConnectionMultiplexer>(sp =>\n ConnectionMultiplexer.Connect("<REDIS_CONNECTION_STRING>"));\n\n// Register HybridCache (defaults generally work fine for L1)\nbuilder.Services.AddHybridCache();\n\n// Register our invalidation services\nbuilder.Services.AddSingleton<ICacheInvalidator, RedisCacheInvalidator>();\nbuilder.Services.AddHostedService<CacheInvalidationService>();\n\nNow, when Node A calls InvalidateAsync("user:123"), Redis pushes that message to Node B, Node C, and so on.\nThey all trigger hybridCache.RemoveAsync("user:123"), ensuring the next request fetches fresh data from the source (or the shared L2).
If building your own backplane feels like reinventing the wheel, you should look at FusionCache.
\nFusionCache is a mature, battle-tested library that has solved this exact problem for years.\nIt has a built-in backplane feature that automatically handles the Pub/Sub messaging for you.
\nEven better, FusionCache recently added an implementation of the HybridCache abstract class.\nThis means you can swap it in without changing much of your existing code.
\n// Using FusionCache's implementation of HybridCache\nbuilder.Services.AddFusionCache()\n .WithBackplane(\n new RedisBackplane(new RedisBackplaneOptions { Configuration = "<REDIS_CONNECTION_STRING>" }))\n .AsHybridCache();\nHybridCache is a powerful addition to the .NET ecosystem, effectively merging the benefits of IMemoryCache and IDistributedCache.\nHowever, for multi-node setups requiring high consistency, you still need a mechanism to synchronize the local caches.
Redis Pub/Sub offers a lightweight, effective solution to this problem.
\nBy implementing a simple "bus" for invalidation messages, you get the best of both worlds:\nthe extreme performance of local caching and the data consistency of a distributed system.
\nGood luck out there, and see you next week.
\nGlobal message ordering is rarely what you need.\nWhat you actually need is per-aggregate ordering: events for the same OrderId or CustomerId handled in sequence.\nThat means only one handler can process events for a given aggregate at a time, and following that requirement leads you to a saga.
Most systems don't need global message ordering.
\nThey need something simpler and more useful: events must be handled in order per aggregate.
\nPer OrderId, per InvoiceId, per CustomerId, or whatever your aggregate boundary is.\nYou can make this as broad or as narrow as you need.
This starts as an eventing problem, but if you follow the requirements to their logical conclusion, you'll end up with a workflow.\nAnd that workflow has a name: a saga.
\nDomain events are attractive because they come from first principles:
\nYou also get a nice mental model:
\n\n\nState change → Event → Reaction
\n
A typical example:
\nOrderPlacedPaymentCapturedOrderShippedBut there's a catch.
\nDomain events are brittle when you try to use them for integration.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_176/domain_events_flow.png\")
\nIf you publish directly from your transaction, you're coupling business correctness to an unreliable side effect:
\nSo we keep the model, but harden the delivery.
\nWith an Outbox, we store outgoing events in the same transaction as the aggregate update.
\nThen a background publisher reads the Outbox and pushes events to a queue.
\nThis fixes the reliability problem:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_176/outbox_flow.png\")
\nNow we've made event publishing reliable.
\nBut we haven't made event handling ordered.
\nThe moment events hit a queue, we usually scale with the simplest lever: competing consumers.
\nMultiple instances consume from the same queue to increase throughput.
\nThat works… until ordering matters.
\nTwo events for the same OrderId can be processed at the same time:
PaymentCapturedOrderPlacedEven if the events were published in order, retries and redelivery can scramble processing order.
\nAnd now you have a subtle bug that only appears under load.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_176/competing_consumers.png\")
\nThat's the key realization: queues scale work.\nThey don't preserve your invariants.
\nYou don't need one ordered line for everything.
\nYou need many independent ordered lines, one per aggregate.
\nThat usually holds true because:
\nIf we could guarantee that only one handler processes events for a given aggregate at a time, most of the problem disappears.
\nThe most direct solution is also the simplest: use a single consumer for the whole stream.
\nThat enforces ordering, assuming events are published in order.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_176/single_consumer.png\")
\nBut it has an obvious drawback.
\nOne consumer means:
\nEven if your events are lightweight, you're artificially bottlenecking the system.
\nSo we want:
\nThis is where teams often "invent" the next step.
\nIf competing consumers break ordering, one natural idea is:
\n\n\nDon't let the queue decide what's next, we decide.
\n
Instead of dumping all events into the queue and letting consumers race, we move to a chained approach:
\nNow, the system processes a single message at a time per aggregate.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_176/choreographed_saga.png\")
\nThis is the key moment:
\nYou've stopped building "event handlers".
\nYou've started building a workflow.
\nAnd that workflow is… a saga.
\nA choreographed saga is a workflow where:
\nThere isn't a single central coordinator.
\nInstead, we have a chain of events: "when X happens, do Y, then publish Z".
\nThis pattern naturally fits your new requirement:
\nIt also forces a useful discipline:
\nBut choreography has a limitation: control is distributed, so tracking progress and handling exceptions can get messy.
\nSo we take the final step.
\nWhen the workflow becomes important, you often want:
\nThat's when you move from choreography to orchestration via a state machine saga:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_176/state_machine.png\")
\nThis doesn't replace the Outbox, by the way.
\nYou still want reliable publishing.
\nYou've just made the workflow explicit.
\nIt's worth calling out that you don't always have to build this yourself.
\nMany popular message brokers provide technical primitives for ordered processing per key (your aggregate ID):
\nThese features can eliminate the most common failure mode of competing consumers: concurrent handling of messages for the same aggregate.
\nBut even with perfect per-aggregate ordering, you still need patterns around it to keep the system correct:
\nSo broker-level ordering is a great foundation.\nIt reduces accidental complexity.\nIt just doesn't remove the need to model long-running work explicitly when the business demands it.
\nIf you follow the problem from first principles:
\nSo you didn't reinvent something by accident.
\nYou discovered that "ordered handling per aggregate at scale" is not a queue feature.
\nIt's a workflow. And sagas are how we model workflows in distributed systems.
\nOnce you see it that way, you stop fighting queues for ordering guarantees.
\nYou design the workflow the business actually needs.
\nHope this was helpful!
\nThere is a specific kind of restlessness that only developers understand.\nIt's a quiet, persistent itch.\nA mental "background process" that runs while you're eating, showering, or trying to sleep.\nI call it the urge to build.
\nLooking back at my GitHub contribution graphs from the last few years, I see more than just green squares.\nI see a timeline of my own evolution.
\nI was chasing that dream many developers have: build a small product, ship it, get users, maybe turn it into a business.\nMost of those ideas didn't become a successful SaaS.
\nBut that wasn't the point.
\nThe point was that I was building constantly.\nLearning constantly.\nShipping constantly.
\nAnd I loved it.
\nBack in 2020, my contribution graph shows the classic "burst" pattern.\nI was chasing the indiehacker dream.\nYou know the one: build a SaaS, get to ramen profitability, escape the 9-to-5, tweet about your MRR milestones.\nI consumed every bootstrapper podcast, every "I made $10K/month" blog post, every ProductHunt launch breakdown.
\nI was working on a project called Expensely.\nI spent late nights pouring myself into this "genius" idea: a budgeting app.
\nNothing revolutionary.\nThe world didn't need another expense tracker.\nBut I needed to build it.
\nLooking back now, it was far from genius.\nBut at the time, I was convinced that this was the one.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/github_contributions_2020.png\")
\nIn 2021, that momentum stayed steady for five months before life (or perhaps reality) intervened.\nThose green squares represent the fun periods.\nThey represent the thrill of architecting an application, the satisfaction of a passing test suite,\nand the hope that you're building something that might change your life.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/github_contributions_2021.png\")
\nExpensely never became a business.\nMost side projects don't.\nBut here's what I've come to understand: the outcome wasn't the point.
\nEven though those projects didn't become the next big SaaS, they were the forge where my skills were sharpened.\nYou don't "waste" time building something that fails.\nYou only waste time when you don't build at all.\nAnd I mean this both metaphorically and literally.\nHumans are meant to create.\nWhen we stop creating, we stagnate.
\nWhen you build something from scratch - when you own every decision from the database schema to the button colors - you learn differently.\nThere's no senior developer to ask.\nNo established patterns to follow.\nEvery problem is yours to solve.
\nYou can use Railway-Oriented Programming if you want to, because who is going to stop you?
\nJokes aside, functional programming is very useful. You should learn it.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/rop_sample_code.png\")
\nThrough my side projects, I wrestled with authentication, background jobs, payment integrations, deployment pipelines.\nI made mistakes and spent late nights fixing them.\nI built features nobody asked for and skipped features everyone needed.
\nThere is one thing side projects can't teach you (unless you get users): dealing with the consequences of your decisions.\nWhen you build for yourself, the only person affected by your mistakes is you.\nWhen you build for users, every bug, every outage, every poor design choice has real consequences.
\nBy mid 2021, the project had wound down.\nI was settling into a comfortable routine at my day job, working as a senior engineer at a big corporation.\nThere was no time left for side projects.
\nBy 2022, something changed.\nMy contribution graph exploded to over 1,600 commits.\nBut the focus shifted.\nI wasn't building a product anymore.\nI was building something more meaningful.\nThe repositories shifted to my tech blog and YouTube projects.
\nI had discovered content creation.
\nThe urge to build hadn't disappeared.\nI found a new outlet.\nInstead of building products for users, I was building educational content for developers.\nInstead of SaaS metrics, I was tracking video views and newsletter subscribers.\nTo me it was something new, something exciting.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/github_contributions_2022.png\")
\nI discovered that while I loved building software, I loved explaining it even more.\nI transitioned from an aspiring founder to a software engineering educator.\nAt first it was just me writing and recording things I wish someone had explained to me earlier.
\nThen something interesting happened.
\nPeople started reading.\nWatching.\nReplying.\nAsking questions.\nMore people showed up.\nAnd then even more.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/youtube_milanjovanovictech.png\")
\nToday, I get to help thousands of developers around the world improve their careers.\nIt is, without a doubt, the most rewarding work I've ever done.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/pca_testimonials.png\")
\n\n This is genuinely fulfilling work.\nWhen someone messages me saying my content helped them land a job\nor finally understand a concept they'd struggled with for years, that feeling is hard to describe.\nI'm doing something meaningful.
\nAnd yet.
\nThe urge to build something still remains.
\nIt's not dissatisfaction.\nIt's not that content creation isn't "real" building, it absolutely is.\nIt's a different kind of building, certainly.\nBut this feeling I have is something more fundamental.\nA part of my brain that wants to work on a fresh project.\nThat wants to solve a problem nobody has asked me to solve.\nThat wants to take an idea from nothing to something.
\nThat's why I have a Hetzner server sitting idle right now.\nNever know when I might need it.\nRight?\nAlso, I'm getting a great deal for €3.29/month.\nCan't argue with that.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_175/hetzner_server.png\")
\nI think this urge never fully goes away for people like us.\nWe can channel it, redirect it, find new outlets for it.\nBut it's always there, lingering.\nAnd maybe that's okay.\nMaybe that restlessness is what makes us who we are.
\nIf you're reading this with your own idea rattling around in your head - some app concept, some tool you wish existed,\nsome problem you think you could solve - I want to tell you something.
\nBuild it.
\nNot because it will make you rich.\nStatistically, it won't.\nNot because it will become the next big thing.\nIt probably won't be that either.
\nBuild it because the person who finishes that project will not be the same person who started it.\nYou will learn things no tutorial can teach.\nYou will develop judgment that only comes from making real decisions with real consequences.\nYou will have stories, opinions, and experiences that set you apart.
\nThe outcome is almost beside the point.\nThe transformation is the product.
\nMaybe you'll end up with a successful SaaS.\nMaybe you'll end up with a failed project and a mass of hard-won knowledge.\nMaybe, like me, you'll end up somewhere you never expected - doing work you couldn't have imagined when you wrote that first line of code.
\nYou won't know until you build.
\nSo open your terminal.\nType git init.\nAnd start.
Let this be a year of building.
\nA ConcurrentDictionary keeps the cache thread-safe, but it does not stop 100 requests from missing at once and calling the API 100 times.\nWrap entries with a timestamp for expiration, then guard refreshes with double-checked locking on a SemaphoreSlim per key, so one caller fetches while the rest wait.\nProduction code should use HybridCache or FusionCache.
A couple of days ago, I was looking at a piece of code that's doing too much work.\nI'm sure you'll be able to draw a parallel to something in your own applications.\nMaybe it's a database call that should be faster, or an external API that's starting to bill you by the thousands.
\nMy first instinct is: "I'll just cache it".
\nIn .NET, that usually means reaching for IMemoryCache or plugging in a distributed cache like Redis.
But have you ever stopped to wonder what's actually happening inside those libraries?
\nWhy do we need all that complexity just to store a value in memory?
So I spent the afternoon trying to build a high-performance cache from scratch.
\nI don't recommend DIY-ing your own caching library for production use.\nBut I learn best by doing something myself.\nUnderstanding these patterns (concurrency, race conditions, and locking)\nis what separates a "coder" from an engineer.
\nI was working on a simple currency conversion handler.\nWe're calling a third-party API to get exchange rates.\nThe API returns the current exchange rate for a given currency code (like EUR, GBP, JPY) against USD.
\nThis is the initial implementation:
\npublic static class CurrencyConversion\n{\n public static async Task<IResult> Handle(\n\t\tstring currencyCode,\n\t\tdecimal amount,\n\t\tCurrencyApiClient currencyClient)\n\t{\n\t\t// Validate currency code format (3 uppercase letters)\n\t\tif (string.IsNullOrWhiteSpace(currencyCode) ||\n\t\t\tcurrencyCode.Length != 3 ||\n\t\t\t!currencyCode.All(char.IsLetter))\n\t\t{\n\t\t\treturn Results.BadRequest(\n\t\t\t\tnew { error = "Currency code must be a 3-letter uppercase code (e.g., EUR, GBP)" });\n\t\t}\n\n\t\t// Validate amount (must be positive)\n\t\tif (amount < 0)\n\t\t{\n\t\t\treturn Results.BadRequest(new { error = "Amount must be a positive number" });\n\t\t}\n\n\t\tvar rate = await currencyClient.GetExchangeRateAsync(currencyCode);\n\n\t\tif (rate == null)\n\t\t{\n\t\t\treturn Results.NotFound(\n\t\t\t\tnew { error = $"Exchange rate for {currencyCode} not found or API error occurred" });\n\t\t}\n\n\t\tvar convertedAmount = amount * rate.Value;\n\n\t\treturn Results.Ok(new ExchangeRateResponse(\n\t\t\tCurrency: currencyCode,\n\t\t\tBaseCurrency: "USD",\n\t\t\tRate: rate.Value,\n\t\t\tAmount: amount,\n\t\t\tConvertedAmount: convertedAmount\n ));\n }\n}\nThis works fine in your local dev environment.\nBut in production, if 100 people hit this at the same time, you're making 100 identical network calls.\nYour API provider will hate you (and you may even get rate limited), and your latency will spike.
\nNow let's build a cache to fix this without using any external libraries.\nRemember, we're doing this for learning purposes only.
\nConcurrentDictionaryYour first thought is probably to store the rates in a ConcurrentDictionary. It's thread-safe, so it feels like the right tool.
private static readonly ConcurrentDictionary<string, decimal> Cache = new();\n\n// In the Handler:\nif (Cache.TryGetValue(currencyCode, out var cachedRate))\n{\n\treturn cachedRate;\n}\n\nvar rate = await currencyClient.GetExchangeRateAsync(currencyCode);\n\nCache.TryAdd(currencyCode, rate.Value);\nThis definitely helps with performance under load.\nMultiple threads can read and write to the dictionary without crashing.\nBut ConcurrentDictionary protects the dictionary structure, not your logic.
If 100 users request "EUR" at the exact same time, TryGetValue will return false for all of them.\nThey will all proceed to call the API.\nThis is a classic race condition.\nYou've protected your memory, but you haven't protected the external API.
There's also another problem with this approach: the rates never expire.
\nCurrency rates don't stay the same forever.\nWe need a way to expire them.\nSince ConcurrentDictionary doesn't have a "Time to Live" (TTL), we have to wrap our data.
// Store both the rate and the time it was created\nprivate record CacheEntry(decimal Rate, DateTime CreatedAt);\n\n// Our cache now stores CacheEntry objects\nprivate static readonly ConcurrentDictionary<string, CacheEntry> Cache = new();\nprivate static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);\n\n// Check: Is it there? And is it still "fresh"?\nif (Cache.TryGetValue(currencyCode, out var entry) &&\n (DateTime.UtcNow - entry.CreatedAt) < CacheDuration)\n{\n\treturn entry.Rate;\n}\nNow we have expiration.\nBut we've actually created a new problem: The Thundering Herd (a.k.a Cache Stampede).
\nEvery 5 minutes, when the cache expires, all incoming traffic will see "stale" data and try to refresh it at once.
\nSo we need to fix that next.
\nTo fix the stampede, we need to ensure that only one person can fetch the update while everyone else waits.
\nHow do we do that in C#?
\nWe use a SemaphoreSlim and a pattern called Double-Checked Locking.\nWe check the cache once (the "fast path"), then we lock, and then we check again to see if someone else filled it while we were waiting for the lock.
// Basically a mutex but async-friendly\nprivate static readonly SemaphoreSlim Lock = new(1, 1);\n\npublic static async Task<decimal> GetRateAsync(string code, CurrencyApiClient client)\n{\n\t// Fast path: No locking needed\n\tif (Cache.TryGetValue(code, out var entry) && IsFresh(entry))\n\t{\n\t\treturn entry.Rate;\n\t}\n\n var acquired = await Lock.WaitAsync(TimeSpan.FromSeconds(10)); // Avoid deadlocks\n if (!acquired)\n {\n throw new Exception("Could not acquire lock to fetch exchange rate.");\n }\n\ttry\n\t{\n\t\t// Double-check: Did someone else finish the API call while we waited?\n\t\tif (Cache.TryGetValue(code, out entry) && IsFresh(entry))\n\t\t{\n\t\t\treturn entry.Rate;\n\t\t}\n\n\t\tvar rate = await client.GetExchangeRateAsync(code);\n\t\tvar newEntry = new CacheEntry(rate.Value, DateTime.UtcNow);\n\n\t\t// Atomically update the cache\n\t\t// This is safe because we're inside the lock\n\t\tCache.AddOrUpdate(code, newEntry, (_, _) => newEntry);\n\t\treturn rate.Value;\n\t}\n\tfinally\n\t{\n\t\t// Always release the lock\n\t\tLock.Release();\n\t}\n}\nThis is an improvement.\nBut something still feels off.
\nCan you spot the problem with this code?
\nOur lock behaves like a global lock.\nThis means that if one thread is fetching "EUR", all other threads (even those requesting "JPY") are blocked until the "EUR" fetch completes.\nThis problem is called lock contention.
\nLet's fix that next.
\nThe "pro" move here is Keyed Locking.\nWe create a lock for every specific currency.\nSince the number of currencies is finite, this isn't too memory-intensive.
\nWe need an additional ConcurrentDictionary to hold our semaphores, per currency code.
private static readonly ConcurrentDictionary<string, SemaphoreSlim> Locks = new();\n\n// In the Handler:\nvar semaphore = Locks.GetOrAdd(currencyCode, _ => new SemaphoreSlim(1, 1));\nif (!Cache.TryGetValue(currencyCode, out var cachedRate) &&\n\tDateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)\n{\n var acquired = await semaphore.WaitAsync(TimeSpan.FromSeconds(10));\n if (!acquired)\n {\n throw new Exception("Could not acquire lock to fetch exchange rate.");\n }\n\ttry\n\t{\n\t\t// Fetch and update logic...\n\t}\n\tfinally { semaphore.Release(); }\n}\nThe only thing that changes is how we acquire the lock.\nNow, if one thread is fetching "EUR", other threads requesting "JPY" can proceed without waiting.\nThis is the most scalable version of our cache.
\nBut... It only works in memory.\nSo it's not suitable for distributed systems or multiple server instances.\nThere are also a few more edge cases to consider, but you can explore those as an exercise.
\nHere's the final version of our caching logic:
\npublic static class CurrencyConversion\n{\n private record CacheEntry(decimal Rate, DateTime CreatedAt);\n private static readonly ConcurrentDictionary<string, CacheEntry> Cache = new();\n private static readonly TimeSpan CacheDuration = TimeSpan.FromMinutes(5);\n\n private static readonly ConcurrentDictionary<string, SemaphoreSlim> Locks = new();\n\n public static async Task<IResult> Handle(\n string currencyCode,\n decimal amount,\n CurrencyApiClient currencyClient)\n {\n // Validate currency code format (3 uppercase letters)\n if (string.IsNullOrWhiteSpace(currencyCode) ||\n currencyCode.Length != 3 ||\n !currencyCode.All(char.IsLetter))\n {\n return Results.BadRequest(\n new { error = "Currency code must be a 3-letter uppercase code (e.g., EUR, GBP)" });\n }\n\n // Validate amount (must be positive)\n if (amount < 0)\n {\n return Results.BadRequest(new { error = "Amount must be a positive number" });\n }\n\n decimal? rate;\n var semaphore = Locks.GetOrAdd(currencyCode, _ => new SemaphoreSlim(1, 1));\n if (!Cache.TryGetValue(currencyCode, out var cachedRate) &&\n DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)\n {\n var acquired = await semaphore.WaitAsync(TimeSpan.FromSeconds(10));\n if (!acquired)\n {\n throw new Exception("Could not acquire lock to fetch exchange rate.");\n }\n\n try\n {\n // Double-check locking pattern: check again inside the lock\n if (!Cache.TryGetValue(currencyCode, out cachedRate) &&\n DateTime.UtcNow - cachedRate?.CreatedAt < CacheDuration)\n {\n rate = await currencyClient.GetExchangeRateAsync(currencyCode);\n\n if (rate == null)\n {\n return Results.NotFound(\n new { error = $"Exchange rate for {currencyCode} not found or API error occurred" });\n }\n\n Cache.AddOrUpdate(currencyCode,\n _ => new CacheEntry(rate.Value, DateTime.UtcNow),\n (_, _) => new CacheEntry(rate.Value, DateTime.UtcNow));\n }\n else\n {\n rate = cachedRate!.Rate;\n }\n }\n finally\n {\n semaphore.Release();\n }\n }\n else\n {\n rate = cachedRate!.Rate;\n }\n\n var convertedAmount = amount * rate.Value;\n\n return Results.Ok(new ExchangeRateResponse(\n Currency: currencyCode,\n BaseCurrency: "USD",\n Rate: rate.Value,\n Amount: amount,\n ConvertedAmount: convertedAmount\n ));\n }\n}\nThe next step would be to extract the core caching logic into its own reusable class.\nThat way, you can use it in other parts of your application.
\nWhy go through all this trouble?
\nIt's easy to look at a simple ConcurrentDictionary and think you're done.\nBut as we've seen, the gap between "it works" and "it scales" is filled with edge cases that can bring a production system to its knees.
When you use a library, it handles these edge cases for you.\nBut building it yourself teaches you about the "three pillars" of high-performance code:
\nSometimes the most "boring" parts of our infrastructure, like a cache, are actually the most architecturally interesting.
\nThere's also that 1% of the time when you need a custom solution that no library can provide.\nSo it's worth knowing the fundamentals of how these things work.
\nModern libraries like HybridCache or\nFusionCache handle this for you,\nbut understanding these patterns ensures you know exactly why your application behaves the way it does under load.
\nAnd since this is the last issue of the year, I wish you a fantastic New Year! 🎉
\nServer-Sent Events stream data one way, from server to client, over a standard HTTP request with a text/event-stream content type.\nASP.NET Core 10 adds a native API: return Results.ServerSentEvents with an IAsyncEnumerable<T>, and the browser consumes it with EventSource, no client library required.\nSignalR is still the choice when you need two-way communication.
Real-time updates are no longer a "nice-to-have" feature.\nMost modern UI applications expect live data streams of some kind from the server.\nFor years, the go-to answer in the .NET ecosystem has been SignalR.\nWhile SignalR is incredibly powerful, it's nice to have other options for simpler use cases.
\nWith the release of ASP.NET Core 10, we finally have a native, high-level API for Server-Sent Events (SSE).\nIt bridges the gap between basic HTTP polling and full-duplex WebSockets via SignalR.
\nSignalR is a powerhouse that handles\nWebSockets, Long Polling, and\nSSE automatically, providing a full-duplex (two-way) communication channel.\nHowever, it comes with a footprint: a specific protocol (Hubs), a required client-side library, and a need for "sticky sessions" or a backplane (like Redis) for scaling.
\nSSE is different because:
\ntext/event-stream content type. No custom protocols.The beauty of the .NET 10 SSE API is its simplicity.\nYou can use the new Results.ServerSentEvents to return a stream of events from any IAsyncEnumerable<T>.\nBecause IAsyncEnumerable represents a stream of data that can arrive over time,\nthe server knows to keep the HTTP connection open rather than closing it after the first "chunk" of data.
Here's a minimal example of an SSE endpoint that streams order placements in real-time:
\napp.MapGet("orders/realtime", (\n\tChannelReader<OrderPlacement> channelReader,\n\tCancellationToken cancellationToken) =>\n{\n\t// 1. ReadAllAsync returns an IAsyncEnumerable\n\t// 2. Results.ServerSentEvents tells the browser: "Keep this connection open"\n\t// 3. New data is pushed to the client as soon as it enters the channel\n\treturn Results.ServerSentEvents(\n channelReader.ReadAllAsync(cancellationToken),\n eventType: "orders");\n});\nWhen a client hits this endpoint:
\nContent-Type: text/event-stream header.Channel, the IAsyncEnumerable yields that item,\nand .NET immediately flushes it down the open HTTP pipe to the browser.It's an incredibly efficient way to handle "push" notifications without the overhead of a stateful protocol.
\nI'm using a Channel here as a means to an end.\nIn a real application, you might have a background service\nthat listens to a message queue (like RabbitMQ or Azure Service Bus)\nor a database change feed, and pushes new events into the channel for connected clients to consume.
The simple endpoint we just built is great, but it has one weakness: it's missing resilience.
\nOne of the biggest challenges with real-time streams is connection drops.\nBy the time the browser automatically reconnects, several events might have already been sent and lost.\nTo solve this, SSE has a built-in mechanism: the Last-Event-ID header.\nWhen a browser reconnects, it sends this ID back to the server.
In .NET 10, we can use the SseItem<T>\ntype to wrap our data with metadata like IDs and retry intervals.
By combining a simple in-memory OrderEventBuffer with the Last-Event-ID provided by the browser, we can "replay" missed messages upon reconnection:
\napp.MapGet("orders/realtime/with-replays", (\n\tChannelReader<OrderPlacement> channelReader,\n\tOrderEventBuffer eventBuffer,\n\t[FromHeader(Name = "Last-Event-ID")] string? lastEventId,\n\tCancellationToken cancellationToken) =>\n{\n\tasync IAsyncEnumerable<SseItem<OrderPlacement>> StreamEvents()\n\t{\n\t\t// 1. Replay missed events from the buffer\n\t\tif (!string.IsNullOrWhiteSpace(lastEventId))\n\t\t{\n\t\t\tvar missedEvents = eventBuffer.GetEventsAfter(lastEventId);\n\t\t\tforeach (var missedEvent in missedEvents)\n\t\t\t{\n\t\t\t\tyield return missedEvent;\n\t\t\t}\n\t\t}\n\n\t\t// 2. Stream new events as they arrive in the Channel\n\t\tawait foreach (var order in channelReader.ReadAllAsync(cancellationToken))\n\t\t{\n\t\t\tvar sseItem = eventBuffer.Add(order); // Buffer assigns a unique ID\n\t\t\tyield return sseItem;\n\t\t}\n\t}\n\n\treturn TypedResults.ServerSentEvents(StreamEvents(), "orders");\n});\nServer-Sent Events is built on top of standard HTTP.\nBecause it is a standard GET request, your existing infrastructure "just works":
Authorization header.HttpContext.User to extract a User ID and filter the stream.\nYou only send a user the data that belongs to them.Here's an example of an SSE endpoint that streams only the orders for the authenticated user:
\napp.MapGet("orders/realtime", (\n\tChannelReader<OrderPlacement> channelReader,\n\tIUserContext userContext, // Injected context containing user metadata\n\tCancellationToken cancellationToken) =>\n{\n\t// The UserId is extracted from the JWT access token by the IUserContext\n\tvar currentUserId = userContext.UserId;\n\n\tasync IAsyncEnumerable<OrderPlacement> GetUserOrders()\n\t{\n\t\tawait foreach (var order in channelReader.ReadAllAsync(cancellationToken))\n\t\t{\n\t\t\t// We only yield data that belongs to the authenticated user\n\t\t\tif (order.CustomerId == currentUserId)\n\t\t\t{\n\t\t\t\tyield return order;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn Results.ServerSentEvents(GetUserOrders(), "orders");\n})\n.RequireAuthorization(); // Standard ASP.NET Core Authorization\nNote that when you write a message to a Channel it's broadcast to all connected clients.\nThis isn't ideal for per-user streams.\nYou'll probably want to use something more robust for production.
On the client side, you don't need to install a single npm package.\nThe browser's native EventSource API handles the heavy lifting, including the "reconnect and send Last-Event-ID" logic we discussed above.
const eventSource = new EventSource('/orders/realtime/with-replays');\n\n// Listen for the specific 'orders' event type we defined in C#\neventSource.addEventListener('orders', (event) => {\n const payload = JSON.parse(event.data);\n console.log(`New Order ${event.lastEventId}:`, payload.data);\n});\n\n// Do something when the connection opens\neventSource.onopen = () => {\n console.log('Connection opened');\n};\n\n// Handle generic messages (if any)\neventSource.onmessage = (event) => {\n console.log('Received message:', event);\n};\n\n// Handle errors and reconnections\neventSource.onerror = () => {\n if (eventSource.readyState === EventSource.CONNECTING) {\n console.log('Reconnecting...');\n }\n};\nSSE in .NET 10 is the perfect middle ground for simple, one-way updates like dashboards, notification bells, and progress bars.\nIt's lightweight, HTTP-native, and easy to secure using your existing middleware.
\nHowever, SignalR remains the robust, battle-tested choice for complex bi-directional communication or massive scale requiring a backplane.
\nThe goal isn't to replace SignalR, but to give you a simpler tool for simpler jobs.\nChoose the lightest tool that solves your problem.
\nThat's all for today. Hope this was helpful.
\n.slnx is Microsoft's XML-based solution format: a plain list of projects and folders that reads like a .csproj and drops the GUID blocks that cause merge conflicts.\nWith the .NET 9 SDK (9.0.200 or later), dotnet sln migrate generates a .slnx next to your existing .sln.\nDelete the old .sln afterwards.
Solution files have always been that one file nobody wants to touch during a merge conflict.\nI still remember the pain of resolving conflicts in large monorepo solutions with hundreds of projects.\nCan I just say this was not fun?
\nMicrosoft is (finally!) addressing that with .slnx: an XML-based, simpler solution format designed to be easier to read, edit, and merge.
Here is your practical guide to the future of .NET solutions.
\n.slnClassic .sln files are verbose: GUID-heavy project entries + configuration blocks that explode as your solution grows.\nIt's also a frequent source of merge conflicts.
To appreciate the new format, we must look at the old one.
\nHere's a typical .sln file from a moderately sized .NET solution:
Microsoft Visual Studio Solution File, Format Version 12.00\n# Visual Studio Version 17\nVisualStudioVersion = 17.7.34031.279\nMinimumVisualStudioVersion = 10.0.40219.1\nProject("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8FC526EA-218B-4615-8410-4E1850611F38}"\n\tProjectSection(SolutionItems) = preProject\n\t\t.editorconfig = .editorconfig\n\t\tDirectory.Build.props = Directory.Build.props\n\t\tDirectory.Packages.props = Directory.Packages.props\n\tEndProjectSection\nEndProject\nProject("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{64A28C1B-09AF-426E-8721-D002BE554B48}"\nEndProject\nProject("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SharedKernel", "src\\SharedKernel\\SharedKernel.csproj", "{166778A2-518F-47F0-BBC7-DB49C76A963C}"\nEndProject\nProject("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Domain", "src\\Domain\\Domain.csproj", "{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}"\nEndProject\nProject("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Application", "src\\Application\\Application.csproj", "{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}"\nEndProject\nProject("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Infrastructure", "src\\Infrastructure\\Infrastructure.csproj", "{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}"\nEndProject\nProject("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Web.Api", "src\\Web.Api\\Web.Api.csproj", "{86506D03-3746-41E7-A645-97D3633981DB}"\nEndProject\nProject("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{1EB88D85-BE1E-46DE-99A2-2F02363060AF}"\nEndProject\nProject("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ArchitectureTests", "tests\\ArchitectureTests\\ArchitectureTests.csproj", "{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}"\nEndProject\nProject("{E53339B2-1760-4266-BCC7-CA923CBCF16C}") = "docker-compose", "docker-compose.dcproj", "{34BB3069-D5D0-4046-ACAD-A2025ED7678F}"\nEndProject\nGlobal\n\tGlobalSection(SolutionConfigurationPlatforms) = preSolution\n\t\tDebug|Any CPU = Debug|Any CPU\n\t\tRelease|Any CPU = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(ProjectConfigurationPlatforms) = postSolution\n\t\t{166778A2-518F-47F0-BBC7-DB49C76A963C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{166778A2-518F-47F0-BBC7-DB49C76A963C}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{166778A2-518F-47F0-BBC7-DB49C76A963C}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{166778A2-518F-47F0-BBC7-DB49C76A963C}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{86506D03-3746-41E7-A645-97D3633981DB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{86506D03-3746-41E7-A645-97D3633981DB}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{86506D03-3746-41E7-A645-97D3633981DB}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{86506D03-3746-41E7-A645-97D3633981DB}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{34BB3069-D5D0-4046-ACAD-A2025ED7678F}.Release|Any CPU.Build.0 = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(SolutionProperties) = preSolution\n\t\tHideSolutionNode = FALSE\n\tEndGlobalSection\n\tGlobalSection(NestedProjects) = preSolution\n\t\t{166778A2-518F-47F0-BBC7-DB49C76A963C} = {64A28C1B-09AF-426E-8721-D002BE554B48}\n\t\t{6448ADE8-34BC-4F2F-A68C-5B2D6BF4FB0B} = {64A28C1B-09AF-426E-8721-D002BE554B48}\n\t\t{0F576D4A-156D-4626-A4D5-83DD0F6FAFE7} = {64A28C1B-09AF-426E-8721-D002BE554B48}\n\t\t{C699FD09-4D82-4C4B-8744-4FD3B0D60EFC} = {64A28C1B-09AF-426E-8721-D002BE554B48}\n\t\t{86506D03-3746-41E7-A645-97D3633981DB} = {64A28C1B-09AF-426E-8721-D002BE554B48}\n\t\t{8D8E2A8A-D3FE-4230-BEF7-C427D6BD87DA} = {1EB88D85-BE1E-46DE-99A2-2F02363060AF}\n\tEndGlobalSection\n\tGlobalSection(ExtensibilityGlobals) = postSolution\n\t\tSolutionGuid = {B948A3CC-9872-4612-ABD2-BB3D49671542}\n\tEndGlobalSection\nEndGlobal\nGood luck trying to make sense of that during a merge conflict!
\n.slnx looks likeA minimal .slnx is basically a list of projects in XML.
Here's the same solution as above, but in .slnx format.\nWe even have solution items, folders, and a docker-compose project.
<Solution>\n <Folder Name="/Solution Items/">\n <File Path=".editorconfig" />\n <File Path="Directory.Build.props" />\n <File Path="Directory.Packages.props" />\n </Folder>\n <Folder Name="/src/">\n <Project Path="src/Application/Application.csproj" />\n <Project Path="src/Domain/Domain.csproj" />\n <Project Path="src/Infrastructure/Infrastructure.csproj" />\n <Project Path="src/SharedKernel/SharedKernel.csproj" />\n <Project Path="src/Web.Api/Web.Api.csproj" />\n </Folder>\n <Folder Name="/tests/">\n <Project Path="tests/ArchitectureTests/ArchitectureTests.csproj" />\n </Folder>\n <Project Path="docker-compose.dcproj">\n <Build />\n </Project>\n</Solution>\n\nIt looks remarkably similar to a .csproj file.
The .slnx format is available in recent versions of Visual Studio 2022 (v17.13+) and the .NET 9 SDK. Here is how you can switch.
Option 1: The Command Line
\nIf you have the .NET 9 SDK installed (specifically 9.0.200 or later), you can migrate instantly via the CLI.
\nOpen your terminal in the solution folder.
\nRun the migration command:
\ndotnet sln migrate\nThis creates a new .slnx file alongside your old .sln.
At this point I would recommend deleting the old .sln file to avoid confusion.\nThere's no point in keeping both in the same repo.
Option 2: Visual Studio "Save As"
\nIf you prefer the GUI, you can do this directly inside Visual Studio 2022 (or 2026).
\nSelect the Solution in the Solution Explorer.
\nGo to File > Save Solution As....
![\"The](\"https://milanjovanovic.tech/blogs/mnw_172/visual_studio_save_as.png\")
\nChange the "Save as type" dropdown to Xml Solution File (*.slnx).
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_172/save_as_xml_solution_file.png\")
\n.csproj), which moved to simplified XML years ago.As of late 2025/early 2026, .slnx is technically a Preview feature.
Safe to use?\nYes, the format is stable.
\nTooling support?\nVisual Studio 2022, Visual Studio 2026 and Rider support it well.\nSo does the .NET CLI.\nSome older CI/CD pipelines or 3rd party tools might not recognize the extension yet.
\nMy recommendation: Try it on a side project or a branch first.\nIf your CI pipeline passes, you are ready to modernize.
\nI'm using this format in all my new projects and have migrated several existing ones without issues.
\nDbContext is not thread-safe, because it tracks changes and wraps a single database connection.\nRunning two queries on it at the same time throws "A second operation started on this context".\nInject IDbContextFactory<T> and create a fresh context inside each parallel task, so every query gets its own connection.
We have all built that endpoint.
\nYou know the one: the "Executive Dashboard" or the "User Summary" screen.\nIt's the endpoint that needs to fetch three or four completely unrelated sets of data to paint a complete picture for the user.\nIt needs the last 50 orders, the current system health logs, the user's profile settings, and maybe a notification count.
\nSo, you write the code the standard way:
\nvar orders = await GetRecentOrdersAsync(userId);\nvar logs = await GetSystemLogsAsync();\nvar stats = await GetUserStatsAsync(userId);\n\nreturn new DashboardDto(orders, logs, stats);\nThis works.\nIt's clean.\nIt's readable.\nBut there is a problem.
\nIf GetRecentOrdersAsync takes 300ms, GetSystemLogsAsync takes 400ms, and GetUserStatsAsync takes 300ms,\nyour users are staring at a loading spinner for 1 full second (300 + 400 + 300).
In a distributed system, latency kills user experience.\nSince these data sets are unrelated, we should be able to run them in parallel.\nIf we did, the total time would only be the duration of the slowest query (400ms).\nThat is a 60% performance improvement just by changing how we execute the code.
\nBut if you try the naive approach with Entity Framework Core, your application will crash.
\nThe most common mistake developers make when trying to optimize this is wrapping their existing repository calls in tasks and waiting for them all at once.
\nIt looks something like this:
\n// ❌ DO NOT DO THIS\npublic async Task<DashboardData> GetDashboardData(int userId)\n{\n // These methods all use the same injected _dbContext\n var ordersTask = _repository.GetOrdersAsync(userId);\n var logsTask = _repository.GetLogsAsync();\n var statsTask = _repository.GetStatsAsync(userId);\n\n await Task.WhenAll(ordersTask, logsTask, statsTask); // BOOM 💥\n\n return new DashboardData(ordersTask.Result, logsTask.Result, statsTask.Result);\n}\nIf you run this, you will immediately hit this dreaded exception:
\n\n\nA second operation started on this context before a previous operation completed.\nThis is usually caused by different threads using the same instance of DbContext, however instance members are not guaranteed to be thread safe.
\n
Why does this happen?
\nThe DbContext in EF Core is not thread-safe.\nIt is a stateful object designed to manage a single unit of work.\nIt maintains a "Change Tracker" to keep track of the entities you've loaded, and it wraps a single underlying database connection.
Database protocols (like the TCP stream for PostgreSQL or SQL Server) are generally synchronous at the connection level.\nYou cannot push two different SQL queries down the same wire at the exact same millisecond.\nWhen you use Task.WhenAll, multiple threads try to grab that single connection simultaneously,\nand EF Core steps in to throw the exception to prevent data corruption.
So, we have a dilemma: We want the speed of parallelism, but the DbContext forces us into sequential execution.
Since .NET 5, EF Core has provided a first-class solution for this exact scenario: IDbContextFactory<T>.
Instead of injecting a scoped instance of your context (which lives for the entire HTTP request),\nyou inject a factory that allows you to create lightweight, independent instances of DbContext on demand.
Note: While using the factory is the cleanest approach for Dependency Injection,\nyou can also manually instantiate the context (using var context = new AppDbContext(options)) if you have access to the DbContextOptions.
First, we need to register the factory in our Program.cs.
// This registers IDbContextFactory<AppDbContext> as a Singleton (by default)\n// It also registers AppDbContext as Scoped for ease of use elsewhere\nbuilder.Services.AddDbContextFactory<AppDbContext>(options =>\n{\n options.UseNpgsql(builder.Configuration.GetConnectionString("db"));\n});\nNow, let's refactor our slow dashboard endpoint.\nInstead of injecting AppDbContext, we inject IDbContextFactory<AppDbContext>.
Inside our method, we spin up a dedicated task for each query.\nInside each task, we create a brand new context, execute the query, and then immediately dispose of it.
\nusing Microsoft.EntityFrameworkCore;\n\npublic class DashboardService(IDbContextFactory<AppDbContext> contextFactory)\n{\n public async Task<DashboardDto> GetDashboardAsync(int userId)\n {\n // 1. Start the tasks (The queries start executing immediately upon invocation)\n var ordersTask = GetOrdersAsync(userId);\n var logsTask = GetSystemLogsAsync();\n var statsTask = GetUserStatsAsync(userId);\n\n // 2. Wait for all to complete\n await Task.WhenAll(ordersTask, logsTask, statsTask);\n\n // 3. Return results (using 'await Task.WhenAll' here unwraps the result cleanly)\n return new DashboardDto(\n await ordersTask,\n await logsTask,\n await statsTask\n );\n }\n\n private async Task<List<Order>> GetOrdersAsync(int userId)\n {\n // Create a fresh context for this specific operation\n await using var context = await contextFactory.CreateDbContextAsync();\n\n return await context.Orders\n .AsNoTracking()\n .Where(o => o.UserId == userId)\n .OrderByDescending(o => o.CreatedAt)\n .ThenByDescending(o => o.Amount)\n .Take(50)\n .ToListAsync();\n }\n\n private async Task<List<SystemLog>> GetSystemLogsAsync()\n {\n await using var context = await contextFactory.CreateDbContextAsync();\n\n return await context.SystemLogs\n .AsNoTracking()\n .OrderByDescending(l => l.Timestamp)\n .Take(50)\n .ToListAsync();\n }\n\n private async Task<UserStats?> GetUserStatsAsync(int userId)\n {\n await using var context = await contextFactory.CreateDbContextAsync();\n\n return await context.Users\n .Where(u => u.Id == userId)\n .Select(u => new UserStats { OrderCount = u.Orders.Count })\n .FirstOrDefaultAsync();\n }\n}\nKey Concepts
\nTo prove this works, I built a small .NET 10 app using Aspire and PostgreSQL..\nSince I'm running this locally, the absolute times are very low.\nIf I used a remote database, the times would be higher, but the speedup ratio would be similar.
\nSequential Execution: ~36ms
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_171/sequential_ef_queries_trace.png\")
\nThe waterfall is painfully obvious here.\nEach operation waits for the previous one to finish.
\nParallel Execution: ~13ms
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_171/parallel_ef_queries_trace.png\")
\nBy using the parallel approach, the timeline compresses.\nAll three database spans start at the same time and complete together.
\nIDbContextFactory bridges the gap between EF Core's unit-of-work design and the reality of modern, parallel requirements.\nIt allows you to break out of the "one request, one thread" box without sacrificing safety.
However, use this pattern sparingly:
\nNext time you are staring at a slow dashboard, don't reach for raw SQL immediately.\nCheck your awaits.\nIf they are lined up single-file, it might be time to introduce some parallelization.
\nShared code in Vertical Slice Architecture belongs in three tiers.\nTechnical infrastructure (logging, database contexts, the Result pattern) is shared freely, domain rules get pushed down into entities and value objects, and logic used by two related slices stays in a Shared folder inside that feature.\nA Common project couples unrelated features through the same helpers.
Vertical Slice Architecture (VSA) seems like a breath of fresh air when you first encounter it.\nYou stop jumping between seven layers to add a single field.\nYou delete the dozens of projects in your solution.\nYou feel liberated.
\nBut when you start implementing more complex features, the cracks begin to show.
\nYou build a CreateOrder slice.\nThen UpdateOrder.\nThen GetOrder.\nSuddenly, you notice the repetition.\nThe address validation logic is in three places.\nThe pricing algorithm is needed by both Cart and Checkout.
You feel the urge to create a Common project or SharedServices folder.\nThis is the most critical moment in your VSA adoption.
Choose wrong, and you'll reintroduce the coupling you were trying to escape.\nChoose right, and you maintain the independence that makes VSA worthwhile.
\nHere's how I approach shared code in Vertical Slice Architecture.
\nTo understand why this is hard, we need to look at what we left behind.
\nClean Architecture provides strict guardrails.\nIt tells you exactly where code lives: Entities go in Domain, interfaces go in Application, implementations go in Infrastructure.\nIt's safe.\nIt prevents mistakes, but it also prevents shortcuts when they're appropriate.
\nVertical Slice Architecture removes the guardrails.\nIt says, "Organize code by feature, not technical concern".\nThis gives you speed and flexibility, but it shifts the burden of discipline onto you.
\nSo what can you do about it?
\nThe path of least resistance is to create a project (or folder) named Shared, Common, or Utils.
This is almost always a mistake.
\nImagine a Common.Services project with an OrderCalculationService class.\nIt has a method for cart totals (used by Cart), another for historical revenue (used by Reporting),\nand a helper for invoice formatting (used by Invoices).\nThree unrelated concerns.\nThree different change frequencies.\nOne class coupling them all together.
A Common project inevitably becomes a junk drawer for anything you can't be bothered to name properly.\nIt creates a tangled web of dependencies where unrelated features are coupled together because they happen to use the same helper method.
You've reintroduced the very coupling you tried to escape.
\nWhen I hit a potential sharing situation, I ask three questions:
\n1. Is this infrastructural or domain?
\nInfrastructure (database contexts, logging, HTTP clients) almost always gets shared. Domain concepts need more scrutiny.
\n2. How stable is this concept?
\nIf it changes once a year, share it. If it changes with every feature request, keep it local.
\n3. Am I past the "Rule of Three"?
\nDuplicating the same code once is fine.\nHowever, creating three duplicates should raise an eyebrow.\nDon't abstract until you hit three.
\nWe solve this by refactoring our code.\nLet's look at some examples.
\nInstead of binary "Shared vs. Not Shared," think in three tiers.
\nPure plumbing that affects all slices equally: logging adapters, database connection factories, auth middleware,\nthe Result pattern, validation pipelines.
\nCentralize this in a Shared.Kernel or Infrastructure project.\nNote that this can also be a folder within your solution.\nIt rarely changes due to business requirements.
// ✅ Good Sharing: Technical Kernel\npublic readonly record struct Result\n{\n public bool IsSuccess { get; }\n public string Error { get; }\n\n private Result(bool isSuccess, string error)\n {\n IsSuccess = isSuccess;\n Error = error;\n }\n\n public static Result Success() => new(true, string.Empty);\n public static Result Failure(string error) => new(false, error);\n}\nThis is one of the best places to share logic.\nInstead of scattering business rules across slices, push them into entities and value objects.
\nHere's an example:
\n// ✅ Good Sharing: Entity with Business Logic\npublic class Order\n{\n public Guid Id { get; private set; }\n public OrderStatus Status { get; private set; }\n public List<OrderLine> Lines { get; private set; }\n\n public bool CanBeCancelled() => Status == OrderStatus.Pending;\n\n public Result Cancel()\n {\n if (!CanBeCancelled())\n {\n return Result.Failure("Only pending orders can be cancelled.");\n }\n\n Status = OrderStatus.Cancelled;\n return Result.Success();\n }\n}\nNow CancelOrder, GetOrder, and UpdateOrder all use the same business rules.\nThe logic lives in one place.
Logic shared between related slices, like CreateOrder and UpdateOrder, doesn't need to go global.\nCreate a Shared folder (there's an exception to every rule) within the feature:
📂 Features\n└──📂 Orders\n ├──📂 CreateOrder\n ├──📂 UpdateOrder\n ├──📂 GetOrder\n └──📂 Shared\n ├──📄 OrderValidator.cs\n └──📄 OrderPricingService.cs\nThis also has a hiddene benefit.\nIf you delete the Orders feature, the shared logic goes with it.\nNo zombie code left behind.
\nLet's explore some advanced scenarios most people overlook.
\nWhat about sharing code between unrelated features in Vertical Slice Architecture?
\nThe CreateOrder slice needs to check if a customer exists.\nGenerateInvoice needs to calculate tax.\nOrders and Customers both need to format notification messages.
This doesn't fit neatly into a feature's Shared folder.\nSo where does it go?
First, ask: do you actually need to share?
\nMost cross-feature "sharing" is just data access in disguise.
\nIf CreateOrder needs customer data, it queries the database directly.\nIt doesn't call into the Customers feature.\nEach slice owns its data access.\nThe Customer entity is shared (it lives in Domain), but there's no shared service between them.
When you genuinely need shared logic, ask what it is:
\nDomain/ServicesInfrastructure/Services// Domain/Services/TaxCalculator.cs\npublic class TaxCalculator\n{\n public decimal CalculateTax(Address address, decimal subtotal)\n {\n var rate = GetTaxRate(address.State, address.Country);\n return subtotal * rate;\n }\n}\nBoth CreateOrder and GenerateInvoice can use it without coupling to each other.
Before creating any cross-feature service, ask: could this logic live on a domain entity instead?\nMost "shared business logic" is actually data access, domain logic that belongs on an entity, or premature abstraction.
\nIf you need to trigger a side effect in another feature, I recommend using messaging and events.\nAlternatively, the feature you want to call into can explore a facade (public API) for that operation.
\nSometimes "shared" code isn't actually shared.\nIt just looks that way.
\n// Features/Orders/GetOrder\npublic record GetOrderResponse(Guid Id, decimal Total, string Status);\n\n// Features/Orders/CreateOrder\npublic record CreateOrderResponse(Guid Id, decimal Total, string Status);\nThey're identical.\nThe temptation to create a SharedOrderDto is overwhelming.\nResist it.
Next week, GetOrder needs a tracking URL.\nBut CreateOrder happens before shipping, so there's no URL yet.\nIf you'd shared the DTO, you'd now have a nullable property that's confusingly empty half the time.
Duplication is cheaper than the wrong abstraction.
\nHere's what a mature Vertical Slice Architecture project looks like:
\n📂 src\n└──📂 Features\n│ ├──📂 Orders\n│ │ ├──📂 CreateOrder\n│ │ ├──📂 UpdateOrder\n│ │ └──📂 Shared # Order-specific sharing\n│ ├──📂 Customers\n│ │ ├──📂 GetCustomer\n│ │ └──📂 Shared # Customer-specific sharing\n│ └──📂 Invoices\n│ └──📂 GenerateInvoice\n└──📂 Domain\n│ ├──📂 Entities\n│ ├──📂 ValueObjects\n│ └──📂 Services # Cross-feature domain logic\n└──📂 Infrastructure\n│ ├──📂 Persistence\n│ └──📂 Services\n└──📂 Shared\n └──📂 Behaviors\nAfter building several systems this way, here's what I've landed on:
\nFeatures own their request/response models. No exceptions.
\nPush business logic into the domain. Entities and value objects are the best place to share business rules.
\nKeep feature-family sharing local. If only Order slices need it, keep it in Features/Orders/Shared (feel free to find a better name than Shared).
Infrastructure is shared by default. Database contexts, HTTP clients, logging. These are technical concerns.
\nApply the Rule of Three. Don't extract until you have three real usages with identical, stable logic.
\nVertical Slice Architecture asks: "What feature does this belong to?"
\nThe shared code question is really asking: "What do I do when the answer is multiple features?"
\nAcknowledge that some concepts genuinely span features.\nGive them a home based on their nature (domain, infrastructure, or cross-cutting behavior).\nResist the urge to share everything just because you could.
\nThe goal isn't zero duplication.\nIt's code that's easy to change when requirements change.
\nAnd requirements always change.
\nThanks for reading.
\nAnd stay awesome!
\nCalling email and analytics APIs directly from your registration method makes the user wait on them, and a failure halfway through leaves partial state.\nDispatch a domain event instead, write it to an outbox table in the same transaction, and let a background worker publish it.\nWhen the follow-up step is mandatory, use a Saga with compensating transactions.
\nLet's be honest: We've all written this code.
\nIt's Monday morning, you have a deadline, and you need to implement a user registration feature.\nIt's simple enough: save the user, send a welcome email, and track the signup in your analytics dashboard.
\nYou write this:
\npublic class UserService(\n IUserRepository userRepository,\n IEmailService emailService,\n IAnalyticsService analyticsService)\n{\n public async Task RegisterUser(string email, string password)\n {\n var user = new User(email, password);\n await userRepository.SaveAsync(user);\n\n // 1. Directly coupled to email service (external API)\n await emailService.SendWelcomeEmail(user.Email);\n\n // 2. Directly coupled to analytics (this could be an external API)\n await analyticsService.TrackUserRegistration(user.Id);\n\n // What if we need to add more features?\n // This method will keep growing...\n }\n}\nIt looks clean. It's readable. It works on your machine.
\nBut this method is a ticking time bomb.
\nIt assumes the "Happy Path" is the only path.\nIt assumes the network is reliable, the email provider is up, and the analytics API is fast.\nIn production, none of these are guaranteed.
\nThinking further, I'm sure you can imagine similar code in your own projects.\nIt might not be this exact scenario, but the pattern is common: a single method that orchestrates multiple side effects in a linear fashion.
\nLet's break down why this code is dangerous and how we can refactor it into a robust, event-driven architecture.
\nThere are three major issues hiding in those ten lines of code.
\nWhen a user clicks "Register," they have to wait for:
\nIf your analytics provider is having a bad day and takes 3 seconds to respond, your user waits 3 seconds.\nYou are punishing your user for the slowness of a background system they don't even care about.
\nThis is the most critical risk. Imagine this scenario:
\nSaveAsync(user) succeeds. The user is in the DB.SendWelcomeEmail succeeds. The user gets an email.TrackUserRegistration throws a 503 Service Unavailable.What happens now?\nIf you wrap this in a transaction and rollback, you have deleted the user from the DB... but you already sent them a welcome email.\nThe user tries to log in, but they don't exist.\nNow what?
\nIf you don't rollback, you have a user in your system that is missing from your analytics.\nYou have data inconsistency.
\nYou might argue that because we are using interfaces (IEmailService), we are decoupled.\nThat is true for implementation details, but false for orchestration.
The UserService currently has two reasons to change:
The UserService should strictly be responsible for the state change (creating the user).\nIt should not be responsible for orchestrating the side effects of that change.
The first step to fixing this is to invert the control.\nInstead of the UserService commanding other services to do things, it should simply announce that something happened.
We can use Domain Events to achieve this.
\nHere is the refactored UserService:
public class UserService(\n IUserRepository userRepository,\n IDomainEventDispatcher dispatcher,\n IUnitOfWork unitOfWork)\n{\n public async Task RegisterUser(string email, string password)\n {\n // 1. Create the User Entity\n var user = new User(email, password);\n\n // 2. Capture the side effect as an event object\n var userRegisteredEvent = new UserRegisteredEvent(user.Id, user.Email);\n\n // 3. Add the entity to the repository\n await userRepository.AddAsync(user);\n\n // 4. Dispatch the event (Assuming in-process dispatching here for simplicity)\n // Note: Handlers for Email and Analytics are now completely separate classes.\n await dispatcher.Dispatch(userRegisteredEvent);\n\n await unitOfWork.SaveChangesAsync();\n }\n}\nThe UserService is now stable.\nAdding a "Loyalty Points" feature later doesn't require touching this method.\nYou just add a new handler for the UserRegisteredEvent.
However, we haven't solved the reliability problem yet.\nIf the process crashes immediately after Dispatch but before SaveChangesAsync completes, we might send an email for a user that failed to save.\nOr, if we save first and dispatch later, we might save the user but lose the event if the server crashes.
To fix this, we need Atomicity.\nAtomicity means that a set of operations either all succeed or all fail together.
\nWe need to guarantee that if the User is saved, the UserRegisteredEvent is also saved.
Enter the Outbox Pattern.
\nInstead of publishing the event immediately to a message bus, we save the event to an OutboxMessages table in the same database transaction as the user.
Here is the complete implementation logic:
\npublic async Task RegisterUser(string email, string password)\n{\n // 1. Create the Domain Event\n var user = new User(email, password);\n var domainEvent = new UserRegisteredEvent(user.Id, user.Email);\n\n // 2. Open a Transaction\n using var transaction = dbContext.Database.BeginTransaction();\n\n try\n {\n // 3. Save the User to the Users Table\n dbContext.Users.Add(user);\n\n // 4. Serialize the Event and Save to Outbox Table\n var outboxMessage = new OutboxMessage\n {\n Id = Guid.NewGuid(),\n Type = nameof(UserRegisteredEvent),\n Content = JsonSerializer.Serialize(domainEvent),\n OccurredOn = DateTime.UtcNow,\n ProcessedOn = null // Null means it hasn't been handled yet\n };\n\n dbContext.OutboxMessages.Add(outboxMessage);\n\n // 5. Commit BOTH changes atomically\n await dbContext.SaveChangesAsync();\n await transaction.CommitAsync();\n }\n catch\n {\n await transaction.RollbackAsync();\n throw;\n }\n}\nNow, a background worker (running in a separate process) polls the OutboxMessages table.\nIt picks up the message and publishes it to your message bus (RabbitMQ, Azure Service Bus, etc.).
If the email service is down, the background worker just retries later.\nWe have achieved At-Least-Once delivery.
\nThe Outbox pattern is perfect for side effects (fire-and-forget actions like emails).\nBut what if the subsequent action is mandatory?
\nScenario: When a user registers, we must create a crypto-wallet for them in the WalletService.\nIf the wallet creation fails (e.g., due to regulations), we cannot allow the user to exist in our system.
We can't just "retry later" if the WalletService says "Fraud Detected."\nWe need to undo the user creation.
This is a distributed transaction, and we handle it with the Saga Pattern.\nA Saga coordinates a series of steps.\nIf one fails, it executes Compensating Transactions to undo the previous work.
\nHere is how the failure scenario looks when using a Choreography-based Saga:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_169/saga_sequence_diagram.png\")
\nHere's the step-by-step breakdown of the flow:
\nUserCreatedUserCreated → Tries to create wallet\nWalletCreationFailedWalletCreationFailed → Deletes/Deactivates the UserThis ensures Eventual Consistency.\nThe system might be inconsistent for a few seconds (the user exists without a wallet),\nbut it will eventually settle into a valid state (the user is removed).
\nYou don't need Sagas for everything.\nOver-engineering is just as bad as tight coupling.\nUse this simple rule of thumb:
\nCoupling isn't just about code structure.\nIt's about understanding and managing failure boundaries.\nIf your Analytics Service goes down, it shouldn't prevent a user from registering.\nBuild your systems to survive the unhappy path.
\nHope this was helpful.
\nSee you next week.
\n.NET 10 introduced file-based apps: a single .cs file you run with dotnet run app.cs, with no project or solution file.\nDirectives that start with #: reference NuGet packages, target an SDK, and set project properties from inside that file.\nWhen a script outgrows one file, dotnet project convert turns it into a full project.
C# has always been a bit ceremony-heavy, and we all know it.\nEven the simplest "Hello World" program traditionally needed a solution file, a project file,\nand enough boilerplate to make you wonder if you should've just used a scripting language instead.
\nWell, Microsoft finally heard us.\nWith .NET 10, they've introduced file-based apps.\nAnd honestly, it's about time.
\nThe idea is simple: write your C# code in a single .cs file and run it directly. That's it.
No need to set up a whole project structure for that quick utility script you need to parse some CSV files or test an API endpoint.
\nYou get to keep everything that makes C# great: the type safety, the performance, the rich standard library.\nBut now you can use it for those throwaway scripts where setting up a full project would've been overkill.\nAnd yes, you can still reference NuGet packages, reference other C# projects, target specific SDKs,\nand configure project properties, all from within that single file using special directives that start with #:.
The feature builds on top-level statements (remember those from C# 9?) and takes them to their logical conclusion.\nIf we're already letting people skip the class and Main method ceremony, why not let them skip the project ceremony too?
Let's say you want to quickly check what day of the week a specific date falls on.\nCreate a file called date-checker.cs:
var targetDate = new DateTime(2025, 12, 31);\nConsole.WriteLine($"New Year's 2025 falls on a {targetDate.DayOfWeek}");\nConsole.WriteLine($"That's {(targetDate - DateTime.Today).Days} days from now");\nRun it with:
\ndotnet run date-checker.cs\nThe first time you run this, the CLI does some behind-the-scenes magic.\nIt creates a virtual project, compiles your code, and caches everything.\nSubsequent runs are nearly instant because it's smart enough to know when nothing has changed.
\nHere's where things get interesting.\nSay you need to quickly process some JSON data and generate a report.
\nLet's do something practical with System.Text.Json and CsvHelper:
#:package CsvHelper@33.1.0\nusing System.Text.Json;\nusing CsvHelper;\nusing System.Globalization;\n\nvar json = await File.ReadAllTextAsync("sales_data.json");\nvar sales = JsonSerializer.Deserialize<List<SaleRecord>>(json);\n\nvar topProducts = sales\n .GroupBy(s => s.Product)\n .Select(g => new {\n Product = g.Key,\n TotalRevenue = g.Sum(s => s.Amount),\n UnitsSold = g.Count()\n })\n .OrderByDescending(p => p.TotalRevenue)\n .Take(10);\n\nusing var writer = new StreamWriter("top_products.csv");\nusing var csv = new CsvWriter(writer, CultureInfo.InvariantCulture);\ncsv.WriteRecords(topProducts);\n\nConsole.WriteLine("Report generated! Check top_products.csv");\n\nrecord SaleRecord(string Product, decimal Amount, DateTime Date);\nNotice how we're mixing package references, async operations, LINQ, and record types, all in a single file that reads like a cohesive script.\nThis is the kind of thing you'd typically reach for Python for, but now you can stay in C# land.
\nYou can actually create an Aspire AppHost in a single file, which is pretty wild when you think about it:
\n#:sdk Aspire.AppHost.Sdk@13.0.0\n#:package Aspire.Hosting.AppHost@13.0.0\n\nvar builder = DistributedApplication.CreateBuilder(args);\n\nvar cache = builder.AddRedis("cache")\n .WithDataVolume();\n\nvar postgres = builder.AddPostgres("postgres")\n .WithDataVolume()\n .AddDatabase("tododb");\n\nvar todoApi = builder.AddProject<Projects.TodoApi>("api")\n .WithReference(cache)\n .WithReference(postgres);\n\nbuilder.AddNpmApp("frontend", "../TodoApp")\n .WithReference(todoApi)\n .WithReference("api")\n .WithHttpEndpoint(env: "PORT")\n .WithExternalHttpEndpoints();\n\nbuilder.Build().Run();\nWith the #:sdk Aspire.AppHost.Sdk@13.0.0 directive, your single file becomes a full orchestrator for a distributed application.\nYou're defining infrastructure, wiring up dependencies, and setting up a complete development environment, all without creating a project file.\nIt's particularly useful when you're prototyping architectures or need to quickly spin up a test environment.
Eventually, some scripts outgrow their single-file roots.\nMaybe you need to split things into multiple files, or maybe you want proper IDE support for debugging.\nThe transition is painless:
\ndotnet project convert MyUtility.cs\nThis generates a proper project structure while preserving all your package references and SDK choices.\nYour code moves to Program.cs, and you get a .csproj that reflects all those #: directives you were using.
Right now, it's strictly single-file.\nIf you need multiple files, you'll have to wait for .NET 11 or convert to a full project.\nOf course, you can still reference other projects or packages, but the main script has to be in one file.
\nThe caching mechanism can occasionally get confused if you're rapidly iterating on package versions.\nAnd while the IDE support is getting better, it's not quite at the same level as full projects yet, especially for IntelliSense with dynamically referenced packages.
\nBut for what it's designed to do (make C# approachable for scripting scenarios), it works remarkably well.\nYou can use it for build scripts, data migration one-offs, quick API tests, or even teaching C# without overwhelming beginners with project structure.
\nFile-based apps feel like C# finally acknowledging that not every piece of code needs to be an enterprise application.\nSometimes you just need to parse a log file, sometimes you want to quickly test an algorithm,\nand sometimes you're teaching someone programming and don't want to explain what a solution file is on day one.
\nThe feature doesn't revolutionize C# development, but it fills a gap that's been annoying developers for years.\nIf you've been keeping a folder of scripts for quick tasks because C# felt too heavy, maybe it's time to give your favorite language another shot.
\nAfter all, the best language for a quick script is the one you already know, and now C# makes that argument a lot more compelling.
\nThe Idempotent Consumer pattern records each processed message ID in a database table and checks it before handling a message.\nThe side effects and that record commit in the same transaction, so a redelivered duplicate short-circuits and produces no duplicate side effects.\nBrokers can deduplicate on the producer side, but only the consumer can defend against redeliveries.
\nDistributed systems are unreliable by nature.
\nI always recommend reading about the Fallacies of Distributed Computing to understand the common pitfalls.
\nOne of the key challenges is ensuring that messages are processed exactly once.\nTheoretically, that's impossible to guarantee in most systems.\nI won't dive into the CAP theorem or the\nTwo Generals Problem here, but suffice to say:
\nIf you design your system assuming every message will be processed exactly once, you're setting yourself up for subtle data corruption.
\nBut we can design our system to apply side effects exactly once using the Idempotent Consumer pattern.
\nLet's unpack what can go wrong, how brokers help with idempotency, and how you can build an idempotent consumer in .NET.
\nLet's say your service publishes an event when a new note is created:
\nawait publisher.PublishAsync(new NoteCreated(note.Id, note.Title, note.Content));\nWe don't have to worry about the specific implementation of publisher or the message broker here.\nIt could be RabbitMQ, SQS, Azure Service Bus, etc.
Now imagine:
\nNoteCreated eventsFrom the producer's perspective, it "fixed" a timeout.\nBut from the consumer's perspective, it received two events for the same note creation.
\n![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_167/distributed_messaging_with_error.png\")
\nAnd that's just one failure path.\nYou can also get duplicates from:
\nSo even if you do everything "right" on the publisher, the consumer still has to be defensive.
\nMany message brokers already support idempotent publishing via message deduplication if you include a unique message ID.\nAzure Service Bus, for instance, can detect duplicates and ignore re-publishes for the same message ID within a configured window.\nAmazon SQS and other brokers also offer similar guarantees.
\nYou don't need to reinvent this logic in your application.\nThe key is to assign each message a stable identifier that uniquely represents the logical event you're sending.
\nFor example, when publishing a NoteCreated event:
\nvar message = new NoteCreated(note.Id, note.Title, note.Content)\n{\n MessageId = Guid.NewGuid() // or you can use note.Id\n};\n\nawait publisher.PublishAsync(message);\n\nIf the network drops after you send the message, your app might retry.\nBut when the broker sees the same MessageId, it knows this is a duplicate and safely discards it.\nYou get deduplication without any custom tracking tables or extra state in your service.
This broker-level idempotency solves a large class of producer-side issues: network retries, transient failures, and duplicated publishes.
\nWhat it doesn't handle are consumer retries, which happen when messages are redelivered or your service crashes mid-processing.
\nThat's where the idempotent consumer pattern comes in.
\nHere's an example of an idempotent consumer for a NoteCreated event:.
internal sealed class NoteCreatedConsumer(\n TagsDbContext dbContext,\n HybridCache hybridCache,\n ILogger<Program> logger) : IConsumer<NoteCreated>\n{\n public async Task ConsumeAsync(ConsumeContext<NoteCreated> context)\n {\n // 1. Check if we've already processed this message for this consumer\n if (await dbContext.MessageConsumers.AnyAsync(c =>\n c.MessageId == context.MessageId &&\n c.ConsumerName == nameof(NoteCreatedConsumer)))\n {\n return;\n }\n\n var request = new AnalyzeNoteRequest(\n context.Message.NoteId,\n context.Message.Title,\n context.Message.Content);\n\n try\n {\n using var transaction = await dbContext.Database.BeginTransactionAsync();\n\n // 2. Deterministic processing: derive tags from note content\n var tags = AnalyzeContentForTags(request.Title, request.Content);\n\n // 3. Persist tags\n var tagEntities = tags.Select(ProjectToTagEntity(request.NoteId)).ToList();\n dbContext.Tags.AddRange(tagEntities);\n\n // 4. Record that this message was processed\n dbContext.MessageConsumers.Add(new MessageConsumer\n {\n MessageId = context.MessageId,\n ConsumerName = nameof(NoteCreatedConsumer),\n ConsumedAtUtc = DateTime.UtcNow\n });\n\n await dbContext.SaveChangesAsync();\n await transaction.CommitAsync();\n\n // 5. Update cache\n await CacheNoteTags(request, tags);\n }\n catch (Exception ex)\n {\n logger.LogError(ex, "Error analyzing note {NoteId}", request.NoteId);\n throw;\n }\n }\n}\nThis is a typical idempotent consumer with a few important details.
\n1. The Idempotency Key
\nif (await dbContext.MessageConsumers.AnyAsync(c =>\n c.MessageId == context.MessageId &&\n c.ConsumerName == nameof(NoteCreatedConsumer)))\n{\n return;\n}\nYou use:
\nMessageId from the transport (context.MessageId)ConsumerName (so multiple consumers can safely process the same message)If a duplicate message arrives, you short-circuit and do nothing.
\nWhat's also important here is having a unique constraint on (MessageId, ConsumerName) in the MessageConsumers table to prevent\nrace conditions.\nSo even if you have concurrent processing of the same message, only one will succeed in inserting the record.
2. Atomic Side Effects + Idempotency Record
\nThe processing and storing the message consumer record happen in the same transaction:
\nusing var transaction = await dbContext.Database.BeginTransactionAsync();\n\n// write tags\ndbContext.Tags.AddRange(tagEntities);\n\n// write message-consumer record\ndbContext.MessageConsumers.Add(new MessageConsumer { ... });\n\nawait dbContext.SaveChangesAsync();\nawait transaction.CommitAsync();\nWhy this matters:
\nMessageConsumers, so the message can be retriedMessageConsumer row are committed togetherThis is the core of idempotency:
\n\n\nDo this work exactly once per message ID, even under retries.
\n
3. Handling At-Least-Once Delivery
\nMost realistic setups are at-least-once:
\nWith this pattern, the second run hits the MessageConsumers table and returns early.
No duplicate side effects.
\nThis works, except for one caveat...
\nWhat happens when your handler calls something outside the database?\nAn email API, a payment gateway, or a background job queue?
\nThese are all common side effects that need to be idempotent too.
\nThose calls sit outside your transaction boundary.\nYour database might commit successfully, but if the network hiccups before the external service responds, you can't tell if the action happened or not.\nOn retry, your consumer might send another email or charge the credit card twice.
\nYou've now crossed into the messy territory of non-deterministic handlers: operations that can't be repeated safely.
\nThere are two main strategies to deal with this.
\n1. Use an Idempotency Key in the External Call
\nIf the external service supports it, pass a stable identifier, like the message's MessageId with every request.\nMany APIs, including payment processors and email platforms, let you specify an idempotency key header.\nThe service ensures that identical requests with the same key only execute once.
For example:
\nawait emailService.SendAsync(new SendEmailRequest\n{\n To = user.Email,\n Subject = "Welcome!",\n Body = "Thanks for signing up.",\n IdempotencyKey = context.MessageId\n});\n\nEven if the request is retried, the provider will recognize the key and skip the duplicate.\nThis is the simplest and most reliable approach, if your external dependency supports it.
\n2. Store the Intent Locally
\nIf the external service doesn't support idempotency keys, you can simulate it.\nStore a record of the intended action in your database before calling the external system.\nFor example, create a PendingEmails table that records which messages should be sent, keyed by message ID or user ID.
A background process can later read these pending records and perform the action once.\nThis makes the process deterministic, but at the cost of more complexity, extra tables, and background workers.\nIt's often overengineering unless the side effect is critical or irreversible, like payments or account provisioning.
\nThe trade-off comes down to confidence.\nIf repeating the action has real consequences, introduce idempotency explicitly.\nIf not, retrying the operation might be acceptable.
\nNot every consumer needs the overhead of idempotency checks.\nIf your operation is already naturally idempotent, you can often skip the extra table and transaction logic.
\nUpdating a projection, setting a status flag, or refreshing a cache are all examples of deterministic actions that can safely run multiple times.\nFor instance, "set user's status to Active" or "rebuild the read model" are operations that overwrite state rather than append to it.
\nSome handlers also use precondition checks to avoid duplication.\nIf the handler updates an entity, it can first check whether that entity is already in the desired state and return early.\nThat simple guard clause can be enough.
\nDon't blindly apply the Idempotent Consumer pattern everywhere.\nApply it where it protects you from real harm, where duplicate processing causes financial or data inconsistencies.
\nFor everything else, simpler is better.
\nDistributed systems are unpredictable.\nRetries, duplicates, and partial failures are part of normal operation.\nYou can't avoid them, but you can design your system so they don't impact you as much.
\nUse your broker's built-in message deduplication to prevent duplicates from the producer side.\nFor the consumer side, apply the Idempotent Consumer pattern to ensure side effects happen once, even under retries.\nKeep the record of processed messages and the actual side effect in the same transaction.
\nNot every message handler needs this.\nIf your consumer is naturally idempotent or can short-circuit with a simple precondition, skip the extra complexity.\nBut for anything that modifies persistent state or calls external systems, idempotency isn't optional, it's the only way to keep your system consistent.
\nBuild your consumers to tolerate retries.\nAnd your distributed system will be that much more reliable.\nThe interesting part is that once you understand this principle, you start seeing it everywhere in real-world systems.
\nIf you want to dive deeper into messaging patterns and learn how this is implemented in a production-grade system,\ncheck out my Modular Monolith Architecture course.\nWe'll build a full-featured application with distributed messaging, CQRS, and DDD patterns from scratch.
\nHope this was helpful.
\n.NET 10 adds first-class LeftJoin and RightJoin methods to LINQ, and EF Core translates them to LEFT JOIN and RIGHT JOIN in SQL.\nBefore that, a left join meant combining GroupJoin, DefaultIfEmpty, and SelectMany.\nEF Core generates the same SQL either way, so the win is fewer moving parts and clearer intent.
If you've ever worked with databases, you know about LEFT JOIN (and conversely RIGHT JOIN).\nIt's one of those things we use often, if not all the time.\nBut in Entity Framework Core, doing a left join has always been... well, a bit of a pain.
I like joins that read like what they do.\nUnfortunately, until now, LINQ didn't have a straightforward way to express left/right joins.\nYou had to jump through hoops with GroupJoin and DefaultIfEmpty, which made the code harder to read and maintain.
But .NET 10 finally fixes this with the brand new LeftJoin and RightJoin methods.
A LEFT JOIN returns all rows from the left side and the matching rows from the right side.\nIf there's no match, the right side is null.\nWhy we use it: to keep "owners" even when they have no related rows (e.g., show all products even if some don't have a review).
\n![\"Animated](\"https://milanjovanovic.tech/blogs/mnw_166/left_join.gif\")
\n GroupJoin + DefaultIfEmpty)Before .NET 10, a left join in LINQ needed a group join (GroupJoin), then DefaultIfEmpty to keep left rows with no match.\nIt worked, but the intent was buried in noise.
There are two ways you could write it: query syntax and method syntax.
\nvar query =\n from product in dbContext.Products\n join review in dbContext.Reviews on product.Id equals review.ProductId into reviewGroup\n from subReview in reviewGroup.DefaultIfEmpty()\n orderby product.Id, subReview.Id\n select new\n {\n ProductId = product.Id,\n product.Name,\n product.Price,\n ReviewId = (int?)subReview.Id ?? 0,\n Rating = (int?)subReview.Rating ?? 0,\n Comment = subReview.Comment ?? "N/A"\n };\nHere's the SQL generated by EF Core for the above query:
\nSELECT\n p."Id" AS "ProductId",\n p."Name",\n p."Price",\n COALESCE(r."Id", 0) AS "ReviewId",\n COALESCE(r."Rating", 0) AS "Rating",\n COALESCE(r."Comment", 'N/A') AS "Comment"\nFROM "Products" AS p\nLEFT JOIN "Reviews" AS r ON p."Id" = r."ProductId"\nORDER BY p."Id", COALESCE(r."Id", 0)\nvar query = dbContext.Products\n .GroupJoin(\n dbContext.Reviews,\n product => product.Id,\n review => review.ProductId,\n (product, reviewList) => new { product, subgroup = reviewList })\n .SelectMany(\n joinedSet => joinedSet.subgroup.DefaultIfEmpty(),\n (joinedSet, review) => new\n {\n ProductId = joinedSet.product.Id,\n joinedSet.product.Name,\n joinedSet.product.Price,\n ReviewId = (int?)review!.Id ?? 0,\n Rating = (int?)review!.Rating ?? 0,\n Comment = review!.Comment ?? "N/A"\n })\n .OrderBy(result => result.ProductId)\n .ThenBy(result => result.ReviewId);\nWhy this works: GroupJoin matches rows, DefaultIfEmpty inserts a single default (null) when no matches exist, so the left row still appears.\nWe then flatten with SelectMany.
I think we can all agree that this is way too verbose for something as common as a left join.
\nLeftJoinNow we can write what we mean.\nLeftJoin is first-class LINQ and EF Core translates it to a LEFT JOIN in SQL.
var query = dbContext.Products\n .LeftJoin(\n dbContext.Reviews,\n product => product.Id,\n review => review.ProductId,\n (product, review) => new\n {\n ProductId = product.Id,\n product.Name,\n product.Price,\n ReviewId = (int?)review.Id ?? 0,\n Rating = (int?)review.Rating ?? 0,\n Comment = review.Comment ?? "N/A"\n })\n .OrderBy(x => x.ProductId)\n .ThenBy(x => x.ReviewId)\nThe generated SQL is identical to the previous example.
\nWhy this is better:
\nLeftJoin, you know what to expect.GroupJoin, no DefaultIfEmpty, no SelectMany).RightJoinRightJoin keeps all rows from the right side and only matching rows from the left.\nEF Core translates it to RIGHT JOIN.\nIt's handy when the "must keep" side is the second sequence.
Conceptually:
\nvar query = dbContext.Reviews\n .RightJoin(\n dbContext.Products,\n review => review.ProductId,\n product => product.Id,\n (review, product) => new\n {\n ProductId = product.Id,\n product.Name,\n product.Price,\n ReviewId = (int?)review.Id ?? 0,\n Rating = (int?)review.Rating ?? 0,\n Comment = review.Comment ?? "N/A"\n });\nWhy use RightJoin: when your reporting starts from Reviews (keep all), and bring in matching Products if they exist.
Here's the generated SQL:
\nSELECT\n p."Id" AS "ProductId",\n p."Name",\n p."Price",\n COALESCE(r."Id", 0) AS "ReviewId",\n COALESCE(r."Rating", 0) AS "Rating",\n COALESCE(r."Comment", 'N/A') AS "Comment"\nFROM "Reviews" AS r\nRIGHT JOIN "Products" AS p ON r."ProductId" = p."Id"\nThink about how often you need left joins.\nShowing all users with optional profile settings.\nAll products with optional reviews.\nAll orders with optional shipping info.\nIt's everywhere!
\nBefore, developers would sometimes skip the proper left join and do two separate queries instead.\nOr worse, they'd use an inner join and miss data.\nNow there's no excuse - it's just as easy as any other LINQ method.
\nA few quick tips when writing LINQ queries:
\nreview.Comment ?? "N/A"That's it.\nWith LeftJoin and RightJoin, the code finally matches the mental model.
See you next Saturday.
\nA report that takes five minutes to generate should not block the user on a long HTTP request.\nAccept the request, save it as a job record, and return immediately.\nA background worker builds the file, uploads it to S3 or Azure Blob, and notifies the user with a download link.
\nAbout six or seven years ago, I went through an interview for a mid-level .NET role.
\nOne of the questions has stayed with me ever since:
\n\n\nA user clicks a button on the UI to generate an Excel or PDF report.\nThe report generation takes around five minutes (time can be arbitrary).\nThe user has to wait for it to finish.\nHow would you optimize this flow?
\n
At the time, I focused on what I knew best: performance.\nI started thinking about how to make the report generation faster.\nMaybe I could optimize the SQL queries, reduce data transformations, or cache parts of the result.\nIf I could get the process down from five minutes to one, that felt like a big win.
\nBut even if I made it five times faster, the user still had to wait.\nIf the browser crashed, they lost everything.\nIf the network dropped, the process stopped.\nIf they closed the tab, all progress was gone.
\nIt wasn't really a performance issue at all, it was a design issue.
\nLooking back, I realize I was stuck in the mindset of "make the code faster".\nNot that there's anything wrong with that, performance optimization is a valuable skill.\nWhat I didn't see immediately was the bigger problem.\nThe app was doing all this work synchronously, holding the user hostage until it finished.\nI did eventually figure it out, with a few nudges from the interviewer.
\n![\"Synchronous](\"https://milanjovanovic.tech/blogs/mnw_165/sync_reporting_flow.png\")
\nThe better question wasn't "How can I make this faster?"
\nIt was "Why is the user waiting in the first place?"
\nIf something takes minutes (or hours, days) to complete, it shouldn't block the user.\nIt should happen in the background, out of the main request flow, while the user moves on with their work.
\nStill, don't forget to optimize the code itself.\nDatabase queries, data processing, and file generation all matter.\nMaybe there's a missing index, an inefficient loop, or a better library for creating Excel files.\nBut those optimizations are just part of the solution, not the whole picture.
\nToday, I'd still start with the same UI button.\nThe user clicks "Generate Report," but instead of waiting, the backend accepts the request,\nsaves it somewhere (maybe as a job record in a database), and returns right away.\nThis is the essence of building asynchronous APIs.\nThe job is then picked up by a background worker.
\nThe worker can be a hosted service,\na Quartz job,\nor even an AWS Lambda Function triggered by a queue message.\nIt handles the heavy lifting: pulling the data, building the file, and uploading it to storage like S3 or Azure Blob.
\nOnce the report is ready, the worker updates the job status to "completed" and notifies the user.\nThat could be an email with a download link or a real-time SignalR message that shows up in the app.\nThe link points to the stored report, served securely from the backend.
\n![\"Asynchronous](\"https://milanjovanovic.tech/blogs/mnw_165/async_reporting_flow.png\")
\nNow, the user isn't waiting on a long-running HTTP request.\nThe server isn't holding open connections for minutes.\nIf something fails, it can be retried automatically.\nYou also have the option to track progress or cancel the job if needed.\nAnd if a hundred users request reports at once, the system can scale without locking up.
\nThe experience feels faster, even if the actual report generation time hasn't changed.\nBecause in the end, users don't care about performance metrics, they care about responsiveness.
\nA few years later, I started using this exact question when interviewing other developers.\nNot to trick anyone, but because it reveals how people think.
\nSome candidates go straight to optimizing code and queries, just like I did back then.\nThis is a good sign that they know their way around performance tuning.\nI can proceed with further technical questions around algorithms, data structures, or database optimization.
\nOthers pause for a moment and start thinking about user experience, background processing, and fault tolerance.\nThat's when the real conversation begins: queues, retries, notifications, secure file sharing, etc.\nThere are so many ways you can spin off this one scenario into a broader system design discussion.
\nThere's no single right answer.\nBut there's a big difference between someone who focuses only on code and someone who can design a scalable system.
\nWhen I first heard this question, I thought about making the code faster.\nNow I think about making the experience better.
\nOptimizing a query or loop can help, but it doesn't fix waiting, failures, or scalability.\nIf many users start the same report at once, a synchronous design breaks down fast.\nAn asynchronous flow keeps the system responsive and resilient, no matter the load.
\nThat shift from optimizing functions to designing scalable systems is the difference between a good developer and a great one.
\nIf you want to go deeper into building systems that scale, my Clean Architecture course walks you through exactly that.\nYou'll learn how to structure applications, separate concerns, and design systems that grow without breaking.
\nHope this was helpful.
\nSee you next week.
\nSet up a new .NET project in six steps: an .editorconfig for code style, Directory.Build.props for shared build settings, and Directory.Packages.props for central package management.\nThen add static analysis with SonarAnalyzer, Docker Compose or .NET Aspire for local orchestration, and a GitHub Actions build.\nThe whole setup happens before you write any business logic.
Starting a new .NET project is always exciting.\nBut it's also easy to skip the groundwork that makes a project scalable and maintainable.
\nBefore you write your first line of business logic, there are a few key setup steps that make your life (and your teammates) much easier later on.
\nHere's how I usually set up a new .NET project in six simple steps.
\nThe first thing I add is an .editorconfig file.
This file ensures everyone on your team uses the same formatting and naming conventions, reducing inconsistent indents or random naming rules.
\nYou can create one directly in Visual Studio:
\n![\"Visual](\"https://milanjovanovic.tech/blogs/mnw_164/add_editorconfig.png\")
\nThe default configuration is a great start.\nBut you can customize it further to fit your team's preferences.
\nPlace it at the solution root so all projects follow the same rules.\nYou can still override specific settings in subfolders if needed by placing an .editorconfig file there.
Here are two sample .editorconfig files you can use:
Next, I add a Directory.Build.props file to the solution root.\nThis file lets you define build settings that apply to every project in the solution.
Here's an example:
\n<Project>\n <PropertyGroup>\n <TargetFramework>net10.0</TargetFramework>\n <ImplicitUsings>enable</ImplicitUsings>\n <Nullable>enable</Nullable>\n <TreatWarningsAsErrors>true</TreatWarningsAsErrors>\n </PropertyGroup>\n</Project>\nThis keeps your .csproj files clean and consistent, since there's no need to repeat these properties in every project.
If you later want to enable static analyzers or tweak build options, you can do it once here.
\nWhat's cool about this is your .csproj files become basically empty, with only NuGet package references most of the time.
As your solution grows, managing NuGet package versions across multiple projects gets painful.
\nThat's where central package management helps.
\nCreate a file named Directory.Packages.props at the root:
<Project>\n <PropertyGroup>\n <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>\n </PropertyGroup>\n\n <ItemGroup>\n <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />\n <PackageVersion Include="SonarAnalyzer.CSharp" Version="10.15.0.120848" />\n </ItemGroup>\n</Project>\nNow, when you reference a NuGet package in your project, you don't specify the version.\nYou can only use the package name like this:
\n<PackageReference Include="Microsoft.AspNetCore.OpenApi" />\nAll versioning is handled centrally.\nThis makes dependency upgrades trivial and avoids version drift between projects.
\nYou can still override versions in individual projects if needed.
\nStatic code analysis helps catch potential bugs and maintain code quality.\n.NET has a set of built-in analyzers, but I like to add SonarAnalyzer.CSharp for more comprehensive checks.
\nLet's install SonarAnalyzer.CSharp to catch potential code issues early:
\nInstall-Package SonarAnalyzer.CSharp\nAdd it as a global package reference inside your Directory.Build.props:
<ItemGroup>\n <PackageReference Include="SonarAnalyzer.CSharp" />\n</ItemGroup>\nCombine this with:
\n<Project>\n <PropertyGroup>\n <TreatWarningsAsErrors>true</TreatWarningsAsErrors>\n <AnalysisLevel>latest</AnalysisLevel>\n <AnalysisMode>All</AnalysisMode>\n <CodeAnalysisTreatWarningsAsErrors>true</CodeAnalysisTreatWarningsAsErrors>\n <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>\n </PropertyGroup>\n</Project>\n…and your build will fail on serious code quality issues.\nThis can be a great safety net.
\nBut it can also be noisy at first.\nIf some rules don't fit your context, you can adjust or suppress them in .editorconfig by setting the rule severity to none.
For a consistent local environment across your team, you'll want container orchestration.
\nYou have two main options:
\nOption 1: Docker Compose
\nAdd Docker Compose support in Visual Studio.\nIt will scaffold a docker-compose.yml file where you can define services like:
services:\n webapi:\n build: .\n postgres:\n image: postgres:18\n environment:\n POSTGRES_PASSWORD: password\nThis lets every developer spin up the same stack locally with one command.
\nOption 2: .NET Aspire
\n.NET Aspire takes orchestration a step further.\nIt provides service discovery,\ntelemetry, and streamlined configuration, all integrated with your .NET projects.\nIt's become a personal favorite of mine.
\nYou can add a .NET project and a Postgres resource with a few lines of code:
\nvar postgres = builder.AddPostgres("demo-db");\n\nbuilder.AddProject<WebApi>("webapi")\n .WithReference(postgres)\n .WaitFor(postgres);\n\nbuilder.Build().Run();\nAspire still uses Docker under the hood but provides a richer developer experience.
\nWhether you pick Docker Compose or Aspire, the goal is the same: a repeatable, reliable local setup that works the same on every machine.
\nFinally, I set up a simple GitHub Actions workflow to validate each commit.
\nExample .github/workflows/build.yml:
name: Build\n\non:\n push:\n # Filter to only run on main branch\n branches: [main]\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-dotnet@v5\n with:\n dotnet-version: 10.0.x\n - run: dotnet restore\n - run: dotnet build --no-restore --configuration Release\n - run: dotnet test --no-build --configuration Release\nThis ensures your project always builds and passes tests, and it catches issues before they reach production.\nIf the CI build fails, you know something's wrong right away.
\nWhen it comes to testing, I highly recommend exploring:
\nThis will give you confidence that your code works as expected in an (as close as possible) production-like environment.
\nThat's a wrap.\nYour new .NET project is now set up with:
\nThese small setup steps save countless hours down the road and keep your codebase clean, predictable, and ready to scale.
\nOnce your project setup is solid, the next step is designing scalable boundaries.\nIn my Modular Monolith Architecture course, I show how to grow a .NET application without turning it into a tangled mess,\nthrough clear module boundaries, messaging, and domain isolation.
\nIf you're looking for a practical walkthrough of these steps, check out this video.
\nThanks for reading.
\nAnd stay awesome!
\nYou can run ASP.NET Core Minimal APIs on AWS Lambda by installing Amazon.Lambda.AspNetCoreServer.Hosting and adding one line to Program.cs.\nThe same code still runs on Kestrel locally.\nIn my tests a cold start took just over 2 seconds, while warm requests came back in about 150 ms.
Have you ever wondered if you could host a tiny .NET API without running servers 24/7?\nYou can!
\nAWS Lambda lets you run code on-demand, and with the Amazon.Lambda.AspNetCoreServer.Hosting library,\nyou can plug an ASP.NET Core Minimal APIs straight into AWS Lambda.
\nIn this article we'll set up a minimal API, deploy it, and discuss how it performs.
\nDon't worry if you're new to serverless, I'll keep everything simple enough to follow along.
\nLet's start with the basics. You need just three things to turn your Minimal API into a Lambda function.
\nFirst, create your API:
\ndotnet new webapi -n MyLambdaApi\ncd MyLambdaApi\nSecond, add Amazon's hosting package:
\nInstall-Package Amazon.Lambda.AspNetCoreServer.Hosting\nThird, add one line to your Program.cs:
var builder = WebApplication.CreateBuilder(args);\n\n// This line does all the Lambda magic\nbuilder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);\n\nvar app = builder.Build();\n\napp.MapGet("/", () => "Hello from Lambda!");\n\napp.Run();\nThat's it.\nYour API now runs both locally (for testing) and in Lambda (for production).\nWhen you run locally, it uses Kestrel like normal.\nWhen you deploy the app to AWS, Lambda takes over.
\nYou'll need the Lambda tools installed:
\ndotnet tool install -g Amazon.Lambda.Tools\nThen deploy with one command:
\ndotnet lambda deploy-function\nThe tool asks you a few questions (like the function name, which IAM role to use).\nPick the defaults if you're just testing.\nIn a minute or two, your API is live with a URL like: https://[abc123xyz].lambda-url.[region-name].on.aws/.
From the AWS Management Console, you can find your function with its URL and all the other details.
\n![\"AWS](\"https://milanjovanovic.tech/blogs/mnw_163/aws_console_lambda_function.png\")
\nHere's where things become interesting (and problematic).\nLambda functions "go to sleep" when nobody uses them.\nWaking them up takes time, this is the famous "cold start" problem.
\nI ran some simple tests with a basic Minimal API:
\nAs you can see, the first request is slow due to the cold start.\nSubsequent requests are much faster, around 150 ms.\nAfter 10 minutes of inactivity, the function goes cold again, and the next request takes over 2 seconds.\nThere's an optimization feature called SnapStart that can help reduce cold start times,\nbut it has its own tradeoffs and isn't always suitable for every application.
\nAnother thing to note is that I'm in Europe, and my Lambda function is in the US East (N. Virginia) region.\nThis adds network latency, so your results may vary based on your location and the region you choose.
\nEven when warm, the latency is higher than a typical server-hosted API.\nThis may be acceptable for low-traffic or non-critical endpoints, but it's something to consider.
\nLet's move beyond a "Hello World" example to something more realistic.
\nTo see how a simple API performs in the real world, I built a tiny CRUD app that creates a record, fetches it, updates it and then deletes it.\nFirst I ran each operation once to see the raw latency.\nThen I used a load-testing tool with 100 virtual users (VUs) to measure average latency under a bit more stress.
\n// POST /products - Create new product\napp.MapPost("/products", async (CreateProductRequest request, NpgsqlDataSource dataSource) =>\n{\n const string sql =\n """\n INSERT INTO Products (Name, Description, Price, CreatedAt)\n VALUES (@Name, @Description, @Price, @CreatedAt)\n RETURNING Id, Name, Description, Price, CreatedAt\n """;\n\n await using var connection = await dataSource.OpenConnectionAsync();\n var product = await connection.QueryFirstAsync<Product>(sql, new\n {\n request.Name,\n request.Description,\n request.Price,\n CreatedAt = DateTime.UtcNow\n });\n\n return Results.Created(\n $"/products/{product.Id}",\n new ProductResponse(\n product.Id,\n product.Name,\n product.Description,\n product.Price,\n product.CreatedAt));\n});\n// Other endpoints omitted for brevity:\n// - GET /products/{id} - Get product by ID\n// - PUT /products/{id} - Update product\n// - DELETE /products/{id} - Delete product\nThe application uses .NET 8, Npgsql and Dapper\nto interact with a PostgreSQL database running on Amazon RDS.\nYou can find the source code for this example (and the previous one) in this repository.
\nHere are the results:
\nSingle-call latency
\n| Operation | Latency (ms) | Notes |\n| ---------- | ------------ | ------------------------------- |\n| Create | 537 | Cold start plus object creation |\n| Read | 134 | Simple GET of the new record |\n| Update | 140 | Changing one property |\n| Delete | 167 | Removing the record |\nThe create call took half a second because it included a cold start and initialization overhead.\nOnce the function was warmed up, the other operations completed in under two hundred milliseconds.
\nLoad test with 100 virtual users
\nDuring the load test, I simulated 100 clients hitting the API at once.\nAWS automatically scaled the Lambda function to handle the traffic, and average latencies dropped because the functions were already warm.\nHere are the averages:
\nThese numbers show that once your function is up and running, Lambda can respond quite quickly even when many users are making requests.\nOf course, actual times will vary depending on what your API does and how it stores data.
\nRemember that each of these operations involves network calls to the database, which adds latency.\nOverall, I don't find these numbers bad for a serverless setup.
\nHosting minimal APIs in AWS Lambda is surprisingly straightforward.\nWith one library and a single method call, your ASP.NET Core code can run "without servers".\nYou pay only for the compute you use.\nAlso, the AWS Lambda free tier includes one million free requests per month, which is great for testing and light usage.
\nHowever, there are tradeoffs.\nBecause of cold starts and the overhead of starting the .NET runtime, latency isn't as low as hosting on a dedicated server.\nIf your API is mission-critical or requires sub-100 ms responses at all times, you may need to look at provisioned concurrency, containers, or a traditional host.
\nLambda shines for small, event-driven or intermittent workloads that don't justify a full-time server.\nBut it's less suitable for latency-sensitive or heavy, long-running applications.\nFor occasional or low-traffic API endpoints, though, Lambda offers a cost-effective and simple option.
\nThat's all for today.
\nSee you next week.
\nEF Core calls PostgreSQL functions and stored procedures without dropping down to ADO.NET.\nUse dbContext.Database.SqlQuery<T> with an interpolated string for functions, aliasing columns to match your DTO, and ExecuteSqlAsync with CALL for procedures.\nThe interpolation is parameterized, so it is not a SQL injection risk.
You're building a .NET application with EF Core.\nMost of your queries work fine with LINQ, but now you're hitting scenarios where you need something more.
\nMaybe you have a complex report that joins five tables with aggregations and window functions.\nYour LINQ query generates SQL that's slower than you'd like, and you know you could write better SQL by hand.
\nOr maybe you need to update inventory with proper locking to prevent race conditions.\nYou could manage transactions and explicit locks in C#, but it feels like you're fighting the framework.
\nHere's what usually happens: you search for "EF Core stored procedures" and find conflicting advice.\nSome articles say avoid raw SQL at all costs.\nOthers suggest abandoning EF entirely and writing ADO.NET.\nNeither feels right.
\nActually, EF Core works great with database functions and procedures.\nYou get the database's power for what it does best, and EF's convenience for everything else.\nLet me show you how this actually works.
\nI'll use PostgreSQL for examples, but the same principles apply to SQL Server and other relational databases.
\nLet's be honest: most of the time, LINQ is fine.\nEF Core translates your C# into decent SQL, and you get type safety and refactoring support.
\nBut there are times when raw SQL makes more sense:
\nYou need performance you can't get from LINQ.\nComplex aggregations with multiple joins, window functions, or reporting queries often run faster when written directly in SQL.\nYou can test and tune the query in your database tool before bringing it into your code.
\nYou're using database-specific features.\nPostgreSQL has powerful capabilities like full-text search, JSON operators,\nand common table expressions (CTEs) that don't always have clean LINQ equivalents.\nSometimes the straightest path is just writing the SQL.
\nYou have existing database logic.\nIf your database already has stored procedures and functions (maybe from a legacy system),\ncalling them directly beats rewriting everything in C#.
\nYou need atomic operations with proper locking.\nA stored procedure that coordinates multiple updates with FOR UPDATE locks (here's a good use case)\nis simpler and safer than trying to manage that from application code.
You want to reduce round trips.\nOne function call that aggregates data from five tables is more efficient than five separate LINQ queries.
\nNow let's see how to actually do this.
\nHere's a straightforward function that tells you how many tickets are left:
\nCREATE OR REPLACE FUNCTION ticketing.tickets_left(p_ticket_type_id uuid)\nRETURNS numeric\nLANGUAGE sql\nAS $$\n SELECT tt.available_quantity\n FROM ticketing.ticket_types tt\n WHERE tt.id = p_ticket_type_id\n$$;\nNothing fancy, just a query wrapped in a function.
\nCalling it from EF Core is straightforward:
\napp.MapGet("ticket-types/{ticketTypeId}/available-quantity",\nasync (Guid ticketTypeId, EventManagementContext dbContext) =>\n{\n var result = await dbContext.Database.SqlQuery<int>(\n $"""\n SELECT ticketing.tickets_left({ticketTypeId}) AS "Value"\n """)\n .FirstAsync();\n\n return Results.Ok(result);\n});\nNotice the AS "Value" alias.\nWhen EF Core maps to a primitive type, it expects a property named Value.\nThe quotes preserve the exact casing (PostgreSQL lowercases unquoted identifiers by default).
The interpolated string syntax ($"{ticketTypeId}") might look dangerous, but EF Core converts this into a parameterized query automatically.\nYou're not building SQL strings, you're using C# interpolation as a convenient syntax for parameters.
Functions can return entire result sets, which is where they really shine:
\nCREATE OR REPLACE FUNCTION ticketing.customer_order_summary(p_customer_id uuid)\nRETURNS TABLE (\n order_id uuid,\n created_at_utc timestamptz,\n total_price numeric,\n currency text,\n item_count numeric\n)\nLANGUAGE sql\nAS $$\nSELECT\n o.id,\n o.created_at_utc,\n o.total_price,\n o.currency,\n COALESCE(SUM(oi.quantity), 0) AS item_count\nFROM ticketing.orders o\nLEFT JOIN ticketing.order_items oi ON oi.order_id = o.id\nWHERE o.customer_id = p_customer_id\nGROUP BY o.id, o.created_at_utc, o.total_price, o.currency\nORDER BY o.created_at_utc DESC\n$$;\nThis function joins orders with their items, aggregates quantities, and returns multiple rows.\nYou could write this in LINQ, but the SQL is clearer and you can test it directly in your database tool.
\nTo use it from C#, create a DTO that matches the function's output:
\npublic class OrderSummaryDto\n{\n public Guid OrderId { get; set; }\n public DateTime CreatedAtUtc { get; set; }\n public decimal TotalPrice { get; set; }\n public string Currency { get; set; }\n public int ItemCount { get; set; }\n}\nThen query the function like any other table:
\napp.MapGet("customers/{customerId}/order-summary",\nasync (Guid customerId, EventManagementContext dbContext) =>\n{\n var orders = await dbContext.Database\n .SqlQuery<OrderSummaryDto>(\n $"""\n SELECT\n order_id AS OrderId,\n created_at_utc AS CreatedAtUtc,\n total_price AS TotalPrice,\n currency AS Currency,\n item_count AS ItemCount\n FROM ticketing.customer_order_summary({customerId})\n """)\n .ToListAsync();\n\n return Results.Ok(orders);\n});\nThe key is mapping column names to your DTO properties using aliases.\nEF Core handles the rest automatically.
\nThis is a simple case without joins, but you can use this pattern in more complex queries too.\nHowever, you will have to project into DTOs manually since EF Core can't translate joins in raw SQL into entity graphs.\nUsually, you'll return a flat structure from functions anyway, and then map to richer models in C# if needed.
\nPostgreSQL distinguishes between functions and procedures in important ways:
\nFunctions are designed to return values.\nThey can return scalar values, tables, or even complex JSON objects.\nYou call them with SELECT and can use them in queries like any other expression.\nFunctions run within a transaction and can be used in WHERE clauses, joins, and other query contexts.
Procedures are designed for side effects.\nThey don't return values directly but can modify data and have OUT parameters.\nYou call them with CALL and they're ideal for complex operations that need to manage transactions explicitly or perform multiple related updates.
Think of it this way: use functions when you need data, use procedures when you need to change something.
\nThis distinction matters because it affects how you design your database logic and how you call these routines from C#.
\nLet's see an example of a procedure.
\nHere's where procedures really prove their worth.\nLet's say you need to adjust ticket inventory, but you want to prevent race conditions and validate the operation:
\nCREATE OR REPLACE PROCEDURE ticketing.adjust_available_quantity(\n p_ticket_type_id uuid,\n p_delta numeric,\n p_reason text DEFAULT 'manual-adjust'\n)\nLANGUAGE plpgsql\nAS $$\nDECLARE\n v_qty numeric;\n v_avail numeric;\n v_new_avail numeric;\nBEGIN\n SELECT quantity, available_quantity\n INTO v_qty, v_avail\n FROM ticketing.ticket_types\n WHERE id = p_ticket_type_id\n FOR UPDATE;\n\n IF NOT FOUND THEN\n RAISE EXCEPTION 'ticket_type % not found', p_ticket_type_id;\n END IF;\n\n v_new_avail := v_avail + p_delta;\n\n IF v_new_avail < 0 THEN\n RAISE EXCEPTION 'Cannot reduce below zero';\n END IF;\n\n IF v_new_avail > v_qty THEN\n RAISE EXCEPTION 'Cannot exceed quantity';\n END IF;\n\n UPDATE ticketing.ticket_types\n SET available_quantity = v_new_avail\n WHERE id = p_ticket_type_id;\nEND;\n$$;\nThis procedure does several important things:
\nFOR UPDATE so no other transaction can modify it until we're doneYou could do all this in C# with manual transaction management and explicit locking, but it's more complex and error-prone.\nLet the database handle what it's good at.
\nHere's how you call it from EF Core:
\napp.MapPut("ticket-types/{ticketTypeId}/available-quantity", async (\n Guid ticketTypeId,\n int quantity,\n EventManagementContext dbContext) =>\n{\n try\n {\n await dbContext.Database.ExecuteSqlAsync(\n $"""\n CALL ticketing.adjust_available_quantity({ticketTypeId},{quantity})\n """);\n\n return Results.Ok(result);\n }\n catch (Exception e)\n {\n return Results.BadRequest(e.Message);\n }\n});\nThe procedure doesn't return a value, but if it raises an exception (with RAISE EXCEPTION), PostgreSQL will propagate that to your C# code.\nYou can catch it and return a proper error response.
You might be looking at those interpolated strings and thinking "wait, isn't this SQL injection waiting to happen?"
\nIt's not.
\nWhen you write:
\n$"SELECT * FROM users WHERE id = {userId}"\nEF Core doesn't concatenate strings.\nIt converts this into:
\nSELECT * FROM users WHERE id = @p0\nThe actual value is sent as a parameter, completely separate from the SQL text.\nThis works for all the examples in this article.
\nThe interpolation syntax is just a convenient way to write parameterized queries.
\nThe reason why is we're not actually passing in a string to the SqlQuery method,\nbut a FormattableString.\nThis is a special type that captures the format and arguments separately, allowing EF Core to handle parameters.
Everything in this article works with SQL Server,\nMySQL,\nSQLite, and other databases EF Core supports.\nThe differences are mostly syntax.
\nDatabase views are like functions without parameters.\nThey're saved queries you can reference by name.
\nYou can query them using SqlQuery<T> just like functions:
var results = await dbContext.Database\n .SqlQuery<ActiveCustomerDto>(\n $"SELECT * FROM ticketing.active_customers")\n .ToListAsync();\nOr you can map them to entity types in your DbContext for full LINQ support.
Views are great for frequently-used queries that don't need parameters.\nFunctions give you the flexibility of parameterization.
\nWe've covered how to use PostgreSQL functions and procedures with EF Core, from simple scalar functions to complex procedures with validation and locking.
\nYou learned when to use functions (when you need data back) versus procedures (when you need to modify data).\nYou saw how EF Core's SqlQuery<T> and ExecuteSqlAsync give you type safety while letting you write the SQL you need.\nAnd you learned when raw SQL makes sense: complex aggregations, database-specific features, atomic operations with locking, and reducing round trips.
EF Core doesn't force you to choose between LINQ and raw SQL.\nYou can use both.
\nUse functions when you need to return data, procedures when you need to modify data with complex logic,\nand raw SQL queries when LINQ doesn't capture your requirements efficiently.\nThe combination of EF Core's convenience and the database's power gives you the flexibility to choose the right tool for each scenario.
\nThat's all for today. Hope this was helpful.
\nRole-Based Access Control assigns users to roles, and roles carry permissions like users:read or orders:create.\nIn ASP.NET Core you check the permission, not the role name: a custom AuthorizationHandler looks for a matching permission claim and calls context.Succeed.\nRoles can then change without touching code.
Authentication tells you who the user is.\nAuthorization tells you what they can do.
\nMost .NET developers start with simple role-based checks: "Is this user an Admin?"\nBut as your application grows, you quickly realize that roles alone aren't enough.\nYou need granular permissions that can be combined and assigned flexibly.
\nThat's where Role-Based Access Control (RBAC) shines.\nInstead of hardcoding role checks everywhere, you define specific permissions and let roles carry those permissions.\nA user might be a Manager role, but what matters is whether they have the users:delete permission.
Let me show you how to build a flexible, permission-based authorization system in ASP.NET Core.
\nRBAC has three key components that work together:
\nUsers → assigned to → Roles → which contain → Permissions
\nHere's how it flows:
\n![\"Role-based](\"https://milanjovanovic.tech/blogs/mnw_161/rbac.png\")
\nThe beauty is in the flexibility.\nYou can assign multiple roles to a user, and roles can be modified without touching user assignments.\nNeed to give all Managers the ability to export reports?\nJust add the reports:export permission to the Manager role.
This is much more maintainable than checking if someone is specifically an Admin or Super Manager in your code.
It also adds an extra extension point: you can implement custom permissions for some users without creating new roles.
\nASP.NET Core's authorization system is built around policies and requirements.\nLet's create a custom handler that checks permissions stored in the user's claims:
\npublic class PermissionAuthorizationRequirement(params string[] allowedPermissions)\n : AuthorizationHandler<PermissionAuthorizationRequirement>, IAuthorizationRequirement\n{\n public string[] AllowedPermissions { get; } = allowedPermissions;\n\n protected override Task HandleRequirementAsync(\n AuthorizationHandlerContext context,\n PermissionAuthorizationRequirement requirement)\n {\n foreach (var permission in requirement.AllowedPermissions)\n {\n bool found = context.User.FindFirst(c =>\n c.Type == CustomClaimTypes.Permission &&\n c.Value == permission) is not null;\n\n if (found)\n {\n context.Succeed(requirement);\n break;\n }\n }\n return Task.CompletedTask;\n }\n}\nHere's what's happening under the hood:
\nThe class combines both the requirement (what permissions are needed) and the handler (how to check them).\nThis keeps related logic together and reduces boilerplate.
\nThe handler looks through the user's claims for any claim with type Permission that matches one of the required permissions.\nIt's an OR operation - the user only needs one of the specified permissions to proceed.
If a matching permission is found, we call context.Succeed(requirement) and break out early.\nNo need to check the remaining permissions.
Alternatively, you could implement an AND operation if your use case requires all permissions to be present.
\nYou'll need to define your custom claim type:
\npublic static class CustomClaimTypes\n{\n public const string Permission = "permission";\n}\nAnd then you'll use this when issuing JWT tokens or setting up user claims.
\nvar permissions = await (\n from role in dbContext.Roles\n join permission in dbContext.RolePermissions on role.Id equals permission.RoleId\n where roles.Contains(role.Name)\n select permission.Name)\n .Distinct()\n .ToArrayAsync();\n\nList<Claim> claims =\n[\n new(JwtRegisteredClaimNames.Sub, user.Id),\n new(JwtRegisteredClaimNames.Email, user.Email!),\n ..roles.Select(r => new Claim(ClaimTypes.Role, r)),\n ..permissions.Select(p => new Claim(CustomClaimTypes.Permission, p))\n];\n\nvar tokenDescriptor = new SecurityTokenDescriptor\n{\n Subject = new ClaimsIdentity(claims),\n Expires = DateTime.UtcNow.AddMinutes(configuration.GetValue<int>("Jwt:ExpirationInMinutes")),\n SigningCredentials = credentials,\n Issuer = configuration["Jwt:Issuer"],\n Audience = configuration["Jwt:Audience"]\n};\n\nvar tokenHandler = new JsonWebTokenHandler();\n\nstring accessToken = tokenHandler.CreateToken(tokenDescriptor);\nRaw authorization policies work, but they're verbose. Let's create extension methods that make the developer experience much cleaner:
\npublic static class PermissionExtensions\n{\n public static void RequirePermission(\n this AuthorizationPolicyBuilder builder,\n params string[] allowedPermissions)\n {\n builder.AddRequirements(new PermissionAuthorizationRequirement(allowedPermissions));\n }\n}\nNow you can use this with Minimal APIs:
\npublic static class Permissions\n{\n public const string UsersRead = "users:read";\n public const string UsersUpdate = "users:update";\n public const string UsersDelete = "users:delete";\n}\n\napp.MapGet("me", (ApplicationDbContext dbContext) =>\n{\n var user = await dbContext.Users\n .AsNoTracking()\n .Where(u => u.Id == int.Parse(User.FindFirstValue(JwtRegisteredClaimNames.Sub)!))\n .Select(u => new UserDto\n {\n u.Id,\n u.Email,\n u.FirstName,\n u.LastName\n })\n .SingleOrDefaultAsync();\n\n return Results.Ok(user);\n})\n.RequireAuthorization(policy => policy.RequirePermission(Permissions.UsersRead));\nFor MVC Controllers, create an attribute:
\n[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]\npublic class RequirePermissionAttribute(params string[] permissions) : AuthorizeAttribute\n{\n public RequirePermissionAttribute(params string[] permissions)\n : base(policy: string.Join(",", permissions))\n {\n }\n}\nThen register the policy in your DI container:
\nbuilder.Services.AddAuthorizationBuilder()\n .AddPolicy("users:read", policy => policy.RequirePermission(Permissions.UsersRead))\n .AddPolicy("users:update", policy => policy.RequirePermission(Permissions.UsersUpdate));\nUsage becomes clean:
\n[RequirePermission(Permissions.UsersUpdate)]\npublic async Task<IActionResult> UpdateUser(int id, UpdateUserRequest request)\n{\n // Your logic here\n}\nThe basic implementation works great, but we could improve it further.\nHere are two key extension points:
\nInstead of magic strings, use enums for compile-time safety:
\npublic enum Permission\n{\n UsersRead,\n UsersUpdate,\n UsersDelete,\n OrdersCreate,\n ReportsExport\n}\nYou'll have to convert these to strings when issuing claims and checking permissions.\nAnd also convert from a string to an enum, when reading from claims and validating the permissions.
\nRather than storing all permissions in JWT tokens (which can get large), fetch them server-side using IClaimsTransformation:
public class PermissionClaimsTransformation(IPermissionService permissionService)\n : IClaimsTransformation\n{\n public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)\n {\n if (principal.Identity?.IsAuthenticated != true)\n {\n return principal;\n }\n\n var userId = principal.FindFirst(ClaimTypes.NameIdentifier)?.Value;\n if (userId == null)\n {\n return principal;\n }\n\n // Fetch permissions from database, then cache\n // IMPORTANT: Cache these results to avoid DB hits on every request\n var permissions = await permissionService.GetUserPermissionsAsync(userId);\n\n var claimsIdentity = (ClaimsIdentity)principal.Identity;\n foreach (var permission in permissions)\n {\n claimsIdentity.AddClaim(new Claim(CustomClaimTypes.Permission, permission));\n }\n\n return principal;\n }\n}\nRegister it in your DI container:
\nbuilder.Services.AddScoped<IClaimsTransformation, PermissionClaimsTransformation>();\nThis approach keeps your JWTs lightweight while still providing fast authorization checks through claims.
\nYou can learn more about claims transformation in my previous article.
\nRBAC transforms authorization from a maintenance headache into a flexible, scalable system.
\nStart with permissions: Define what actions users can perform, not what roles they have.
\nCustom authorization handlers give you complete control over how permissions are validated.
\nExtension methods make the developer experience clean and consistent across your API.
\nFor production systems, consider type-safe enums and server-side permission resolution to keep your tokens lean and your code maintainable.
\nThe result? Authorization logic that's easy to understand, test, and modify as your application evolves.
\nDistributed locking lets one application instance hold a critical section while the others wait, which in-process primitives like lock and SemaphoreSlim cannot do once you scale out.\nIn .NET you can build it on PostgreSQL advisory locks with pg_try_advisory_lock, or use the DistributedLock library with a Postgres, Redis, or SQL Server backend.
When you build applications that run across multiple servers or processes, you eventually run into the problem of concurrent access.\nMultiple workers try to update the same resource at the same time, and you end up with race conditions, duplicated work, or corrupted data.
\n.NET provides excellent concurrency control primitives for single-process scenarios,\nlike lock, SemaphoreSlim, and Mutex.\nBut when your application is scaled out across multiple instances, these primitives don't work anymore.
That's where distributed locking comes in.
\nDistributed locking provides a solution by ensuring only one node (application instance) can access a critical section at a time,\npreventing race conditions and maintaining data consistency across your distributed system.
\nIn a single-process app, you can just use lock or the new Lock class in .NET 10.\nBut once you scale out, that's not enough, because each process has its own memory space.
A few common cases where distributed locks are valuable:
\nThe key value: consistency and safety across distributed environments.\nWithout this, you risk duplicate operations, corrupted state, or unnecessary load.
\nNow you know why distributed locking is important.
\nLet's look at some implementation options.
\nLet's start simple.\nPostgreSQL has a feature called advisory locks that's perfect for distributed locking.\nUnlike table locks, these don't interfere with your data - they're purely for coordination.
\nHere's an example:
\npublic class NightlyReportService(NpgsqlDataSource dataSource)\n{\n public async Task ProcessNightlyReport()\n {\n await using var connection = dataSource.OpenConnection();\n\n var key = HashKey("nightly-report");\n\n var acquired = await connection.ExecuteScalarAsync<bool>(\n "SELECT pg_try_advisory_lock(@key)",\n new { key });\n\n if (!acquired)\n {\n throw new ConflictException("Another instance is already processing the nightly report");\n }\n\n try\n {\n await DoWork();\n }\n finally\n {\n await connection.ExecuteAsync(\n "SELECT pg_advisory_unlock(@key)",\n new { key });\n }\n }\n\n private static long HashKey(string key) =>\n BitConverter.ToInt64(SHA256.HashData(Encoding.UTF8.GetBytes(key)), 0);\n\n private static Task DoWork() => Task.Delay(5000); // Your actual work here\n}\nHere's what's happening under the hood.
\nFirst, we convert our lock name into a number.\nPostgreSQL advisory locks need numeric keys, so we hash nightly-report into a 64-bit integer.\nEvery node (application instance) must generate the same number for the same string, or this won't work.
Next, pg_try_advisory_lock() attempts to grab an exclusive lock on that number.\nIt returns true if successful, false if another connection already holds it.\nThis call doesn't block - it tells you immediately whether you got the lock.
If we get the lock, we do our work.\nIf not, we return a conflict response and let the other instance handle it.
\nThe finally block ensures we always release the lock, even if something goes wrong.\nPostgreSQL also automatically releases advisory locks when connections close, which is a nice safety net.
SQL Server has a similar feature with sp_getapplock.
\nWhile the DIY approach works, production applications need more sophisticated features.\nThe DistributedLock library handles the edge cases and\nprovides multiple backend options (Postgres, Redis, SqlServer, etc.).\nYou know I'm a fan of not reinventing the wheel, so this is a great choice.
\nInstall the package:
\nInstall-Package DistributedLock\nI'll use the approach with IDistributedLockProvider which works nicely with DI.\nYou can acquire a lock without having to know anything about the underlying infrastructure.\nAll you have to do is register a lock provider implementation in your DI container.
For example, using Postgres:
\n// Register the distributed lock provider\nbuilder.Services.AddSingleton<IDistributedLockProvider>(\n (_) =>\n {\n return new PostgresDistributedSynchronizationProvider(\n builder.Configuration.GetConnectionString("distributed-locking")!);\n });\nOr if you want to use Redis with the Redlock algorithm:
\n// Requires StackExchange.Redis\nbuilder.Services.AddSingleton<IConnectionMultiplexer>(\n (_) =>\n {\n return ConnectionMultiplexer.Connect(\n builder.Configuration.GetConnectionString("redis")!);\n });\n\n// Register the distributed lock provider\nbuilder.Services.AddSingleton<IDistributedLockProvider>(\n (sp) =>\n {\n var connectionMultiplexer = sp.GetRequiredService<IConnectionMultiplexer>();\n\n return new RedisDistributedSynchronizationProvider(connectionMultiplexer.GetDatabase());\n });\nThe usage is straightforward:
\n// You can also pass in a timeout, where the provider will keep retrying to acquire the lock\n// until the timeout is reached.\nIDistributedSynchronizationHandle? distributedLock = distributedLockProvider\n .TryAcquireLock("nightly-report");\n\n// If we didn't get the lock, the object will be null\nif (distributedLock is null)\n{\n return Results.Conflict();\n}\n\n// It's important to wrap the lock in a using statement to ensure it's released properly\nusing (distributedLock)\n{\n await DoWork();\n}\nThe library handles all the tricky parts: timeouts, retries, and ensuring locks are released even in failure scenarios.
\nIt also supports many backends (SQL Server, Azure, ZooKeeper, etc.), making it a solid choice for production workloads.
\nDistributed locking isn't something you need every day.\nBut when you do, it saves you from subtle, painful bugs that only appear under load or in production.
\nStart simple: if you're already using Postgres, advisory locks are a powerful tool.\nI now run that exact pattern in production, and the full implementation (blocking acquire, key hashing, the fail-open decision) is in distributed locking with Postgres advisory locks.
\nFor a cleaner developer experience, reach for the DistributedLock library.
\nChoose the backend that fits your infrastructure (Postgres, Redis, SQL Server, etc.).
\nThe right lock at the right time ensures your system stays consistent, reliable, and resilient, even across multiple processes and servers.
\nVertical Slice Architecture organizes .NET code by business feature instead of technical layer.\nEach slice holds everything one feature needs: the request, handler, validation, and endpoint in a single folder.\nYou change one folder to change a feature, instead of editing files spread across Controllers, Services, and Repositories.
Let's say you need to add an "export user data" feature to your .NET application.\nUsers click a button, your system generates their data export, uploads it to cloud storage, and emails them a secure download link.
\nIn your current layered architecture with a technical folder structure, you'll probably touch six different folders:\nControllers, Services, Models, DTOs, Repositories, and Validators.\nYou'll scroll up and down your solution explorer, lose your train of thought,\nand wonder why adding one feature requires editing files scattered across your entire codebase.
If this sounds familiar, you're not alone.\nMost .NET developers start with the "standard" layered architecture, organizing code by technical concerns rather than business features.
\nBut there's a better way: Vertical Slice Architecture.
\nInstead of organizing your code by technical layers (Controllers, Services, Repositories),\nVertical Slice Architecture organizes it by business features.\nEach feature becomes a self-contained "slice" that includes everything needed for that specific functionality.
Think of it this way: traditional layered architecture is like organizing a library by book size or color,\nwhile vertical slices are like organizing by subject.\nWhen you want to learn about history, you don't want to hunt through the entire library, you want all the history books in one place.
\n![\"Vertical](\"https://milanjovanovic.tech/blogs/mnw_159/vertical_slice_architecture.png\")
\nLet's look at a practical example.
\nLet's look at our data export example.\nHere's how a typical .NET project would structure this feature:
\nTraditional Layered Structure:
\n📁 Controllers/\n└── UsersController.cs (export endpoint)\n📁 Services/\n├── IDataExportService.cs\n├── DataExportService.cs\n├── ICloudStorageService.cs\n├── CloudStorageService.cs\n├── IEmailService.cs\n└── EmailService.cs\n📁 Models/\n├── ExportDataRequest.cs\n└── ExportDataResponse.cs\n📁 Repositories/\n├── IUserRepository.cs\n└── UserRepository.cs\nNow here's the same functionality organized as vertical slices:
\nVertical Slice Structure:
\n📁 Features/\n└──📁 Users/\n └──📁 ExportData/\n ├── ExportUserData.cs\n └── ExportUserDataEndpoint.cs\n 📁 Create/\n └── CreateUser.cs\n 📁 GetById/\n └── GetUserById.cs\nThe ExportData folder contains everything related to exporting user data: the request, response, business logic, and API endpoint.
Notice I'm still injecting ICloudStorageClient and IEmailSender rather than putting that logic directly in the handler.\nThese are genuine cross-cutting concerns that multiple features will use.\nThe key is distinguishing between 'shared because it should be' vs 'shared because this pattern told me to'.
I organize by domain first (Users), then by feature (ExportData).\nSome teams prefer Features/ExportUserData directly, but I find the domain grouping helps when you have many features.\nRelated features stay visually grouped.
Here's what our data export feature slice looks like using a request, handler, and minimal APIs:
\nFeatures/Users/ExportData/ExportUserData.cs
\npublic static class ExportUserData\n{\n public record Request(Guid UserId) : IRequest<Response>;\n\n public record Response(string DownloadUrl, DateTime ExpiresAt);\n\n public class Handler(\n AppDbContext dbContext,\n ICloudStorageClient storageClient,\n IEmailSender emailSender)\n : IRequestHandler<Request, Response>\n {\n public async Task<Response> Handle(Request request, CancellationToken ct = default)\n {\n // Get user data\n var user = await dbContext.Users\n .Include(u => u.Orders)\n .Include(u => u.Preferences)\n .FirstOrDefaultAsync(u => u.Id == request.UserId, ct);\n\n if (user == null)\n {\n throw new NotFoundException($"User {request.UserId} not found");\n }\n\n // Generate export data\n var exportData = new\n {\n user.Email,\n user.Name,\n user.CreatedAt,\n Orders = user.Orders.Select(o => new { o.Id, o.Total, o.Date }),\n Preferences = user.Preferences\n };\n\n // Upload to cloud storage\n var fileName = $"user-data-{user.Id}-{DateTime.UtcNow:yyyyMMdd}.json";\n var expiresAtUtc = DateTime.UtcNow.AddDays(7);\n\n var downloadUrl = await storageClient.UploadAsJsonAsync(\n fileName,\n exportData,\n expiresAtUtc,\n ct);\n\n // Send email notification\n await emailSender.SendDataExportEmailAsync(user.Email, downloadUrl, ct);\n\n return new Response(downloadUrl, expiresAtUtc);\n }\n }\n\n // Simple validation using FluentValidation\n public sealed class Validator : AbstractValidator<Request>\n {\n public Validator()\n {\n RuleFor(r => r.UserId).NotEmpty();\n }\n }\n}\nEverything related to exporting user data is in one place: the database query, validation, business logic, cloud storage integration, and email notification.
\nThe minimal API endpoint is straightforward:
\npublic static class ExportUserDataEndpoint\n{\n public static void Map(IEndpointRouteBuilder app)\n {\n app.MapPost("/users/{userId}/export", async (\n Guid userId,\n IRequestHandler<ExportUserData.Request, ExportUserData.Response> handler) =>\n {\n var response = await handler.Handle(new ExportUserData.Request(userId));\n return Results.Ok(response);\n });\n }\n}\nWe could even define the endpoint inside the ExportUserData.cs file if we wanted to keep everything together.\nThis is more a matter of preference and team conventions.\nEither approach works well, from my experience.
You might have noticed something: I put everything in a single file.\nThis is a design choice with trade-offs.
\nSingle File Approach (ExportUserData.cs):
\npublic static class ExportUserData\n{\n public record Request(Guid UserId) : IRequest<Response>;\n public record Response(string DownloadUrl, DateTime ExpiresAt);\n public class Handler : IRequestHandler<Request, Response> { /* ... */ }\n public class Validator : AbstractValidator<Request> { /* ... */ }\n}\nMultiple Files Approach:
\n📁 ExportData/\n├── ExportUserDataCommand.cs\n├── ExportUserDataResponse.cs\n├── ExportUserDataHandler.cs\n├── ExportUserDataValidator.cs\n└── ExportUserDataEndpoint.cs\nSingle file is great when: the feature is straightforward, you want maximum locality, and the file doesn't exceed a few hundred lines of code.
\nLines of code isn't a strict rule, but if a file grows beyond 300-400 lines, consider splitting it up for readability.\nAgain, this is a matter of team preference and not a hard rule I go by.\nIt's important to trust your instincts and what feels right for your team.
\nMultiple files work better when: you have complex validation logic, multiple response types,\nor when the handler grows large enough that you want to focus on one concern at a time.
\nYou can even mix both approaches within the same project.
\nBoth approaches keep related code together.\nAnd this is what matters most in Vertical Slice Architecture.
\nThe benefits of vertical slices become obvious once you try it.\nYour brain doesn't have to remember which files are related to which features.\nEverything lives together.
\nNeed to modify the data export feature?\nEverything's in the ExportData folder.\nNo hunting across Controllers, Services, and Repositories layers.\nEach slice can evolve independently, so simple CRUD operations stay simple while complex features like data export can use sophisticated approaches.
You don't need to rewrite your entire application overnight.\nStart with new features using vertical slices.\nAs you touch existing code, gradually move related pieces into feature folders.
\nGood architecture is about making your codebase easier to understand and modify.\nWhen all the code for a feature lives together, you spend less mental energy navigating your solution and more time solving actual problems.
\nHere are a few resources if you want to learn more:
\n\nAll of these concepts tie together to help you build maintainable, scalable .NET applications.
\nAmazon S3 Vectors is a new S3 bucket type built for storing and querying vector embeddings, at 90% lower cost than alternatives according to the AWS announcement.\nIn .NET, you generate embeddings with Semantic Kernel and Amazon Bedrock, then store and query them with the S3 Vectors SDK.\nIt was still in preview when I wrote this.
\nI implemented full-text search on my static website using Lunr.js.\nIt works great for exact matches or phrases, but it doesn't understand meaning.\nSomeone searches for "modular monolith" and finds posts that contain these phrases.\nBut when they search for "database performance issues," they might miss my articles about query optimization and index tuning, even though that's exactly what they need.
\nAmazon S3 is now also a vector database,\nand it's 90% cheaper (according to the announcement) than the alternatives.
\nFor those of us running static sites or simple web apps, it means we can finally add semantic search without the operational overhead of\nrunning a vector database like Pinecone, Weaviate, or Qdrant.
\nInstead, we can just use S3 buckets that understand vectors.
\nI'm adding it alongside my existing full-text search implementation, and the whole thing took an afternoon to build.
\nThe entire semantic search flow is straightforward:
\n![\"Semantic](\"https://milanjovanovic.tech/blogs/mnw_158/semantic_search_flow.png\")
\nYou have to start with some data.\nIn my case, this data comes from the articles I've written over the years.
\nThen we need an embedding model.\nAmazon Bedrock offers many to choose from.\nYou use an embedding model to convert text into vectors.\nVectors are numerical representations of your data that capture semantic meaning.
\nFinally, we store these vectors in an S3 Vector Bucket, a new type of S3 bucket designed specifically for vector storage and search.\nWhen someone searches, we convert their query into a vector and find the closest matches in the bucket.
\nIf you want to understand the fundamentals, I wrote an article explaining what vector search is.
\nMicrosoft's Semantic Kernel makes working with Bedrock surprisingly clean.
\nWe'll need to install a few NuGet packages:
\n# Semantic kernel packages\nInstall-Package Microsoft.SemanticKernel\nInstall-Package Microsoft.SemanticKernel.Connectors.Amazon\n\n# AWS SDK for Bedrock\nInstall-Package AWSSDK.BedrockRuntime\nWe have to configure the embedding generator in our application.\nHere we can specify which model to use for generating embeddings.\nI'll use the Amazon Titan embedding model (amazon.titan-embed-text-v2:0) which produces 1024-dimensional vectors.
builder.Services.AddBedrockEmbeddingGenerator("amazon.titan-embed-text-v2:0");\n\nbuilder.Services.AddTransient(sp =>\n{\n return new Kernel(sp);\n});\nAnd then we can use the IEmbeddingGenerator abstraction to generate embeddings:
var kernel = app.Services.GetRequiredService<Kernel>();\n\nvar embeddingGenerator = kernel.Services\n .GetRequiredService<IEmbeddingGenerator<string, Embedding<float>>>();\n\nvar articleContent = await blogService.GetBlogContentAsync(articleUrl);\n\nEmbedding<float> embedding = await embeddingGenerator.GenerateAsync(articleContent);\n\nembeddings.Add((articleUrl, embedding.Vector.ToArray()));\nThe number of dimensions varies depending on the embedding model you choose.\nYou can find more information about that in the documentation for your specific model.
\nS3 Vectors uses an entirely new bucket type, not a feature you enable on existing buckets.\nThey're a fundamentally different storage system optimized for vector operations.\nCreating one feels familiar if you've used S3 before:
\n![\"Creating](\"https://milanjovanovic.tech/blogs/mnw_158/s3_vectors_bucket.png\")
\nPick a unique name for your vector bucket:
\n![\"Creating](\"https://milanjovanovic.tech/blogs/mnw_158/s3_vectors_bucket_create.png\")
\nAnd finally, you can create a vector index for your bucket.\nYou get to choose the number of dimensions in each vector.\nThis is dictated by the embedding model you use.\nAll vectors within a vector index should use the same embedding model.\nOtherwise, you won't get the correct results when searching.\nYou also have to choose the distance metric (e.g., cosine similarity, Euclidean distance) for your vector index.\nI went with cosine similarity, which is a common choice for text embeddings.\nThe additional settings let you configure non-filterable metadata.\nBy default, all metadata is filterable.
\n![\"Creating](\"https://milanjovanovic.tech/blogs/mnw_158/s3_vectors_index_create.png\")
\nThe UI is not polished at all, and you can't do much else.\nI expect this will improve over time, but for now, everything else is done via the SDK or CLI.\nThere are certain limitations to be aware of, you can check out the docs here.
\nNow that we have our vector index, we can start storing vector embeddings with metadata.\nMetadata is interesting because it enables filtered searches.\nWant to search only recent posts? Posts in a specific category?\nThe metadata makes it possible.
\nHere's how you can store vectors:
\npublic async Task IndexBlogPost(BlogPost post)\n{\n List<float> embedding = await GenerateEmbedding(post.Content);\n\n await s3VectorsClient.PutVectorsAsync(new PutVectorsRequest\n {\n VectorBucketName = "mjtech-articles-semantic-search",\n IndexName = "mjtech-article-content",\n Vectors = new List<Vector>\n {\n new PutInputVector\n {\n Key = post.Slug,\n Data = new VectorData\n {\n Float32 = embedding\n },\n Metadata = new Document(new Dictionary<string, Document>\n {\n ["title"] = post.Title,\n ["date"] = post.PublishedDate.ToString("yyyy-MM-dd"),\n ["category"] = post.Category,\n ["url"] = $"/posts/{post.Slug}"\n })\n }\n }\n });\n}\nBut if you're indexing your entire blog archive, doing it one post at a time is costly.\nYou can batch together multiple posts and index them in a single API call.\nThe SDK makes it easy to do this by accepting a list of vectors.
\nWhen someone searches your site, you convert their query into a vector and find the closest matches.
\nHere's how you can implement semantic search:
\npublic async Task<List<SearchResult>> SemanticSearch(\n string query,\n int topK = 10)\n{\n // Convert search query to vector (use same model as vectors!)\n List<float> queryEmbedding = await GenerateEmbedding(query);\n\n var request = new QueryVectorsRequest\n {\n VectorBucketName = "mjtech-articles-semantic-search",\n IndexName = "mjtech-article-content",\n QueryVector = new VectorData\n {\n Float32 = queryEmbedding\n },\n TopK = topK,\n ReturnMetadata = true,\n ReturnDistance = true\n };\n\n QueryVectorsResponse response = await s3VectorsClient.QueryVectorsAsync(request);\n\n return response.Vectors.Select(v => new SearchResult\n {\n Distance = v.Distance,\n Title = v.Metadata.AsDictionary()["title"].ToString(),\n Url = v.Metadata.AsDictionary()["url"].ToString(),\n Category = v.Metadata.AsDictionary()["category"].ToString()\n }).ToList();\n}\nI omitted metadata filtering here, but you can explore the documentation\nfor more details.
\nWould I migrate from an existing vector database?\nProbably not if everything's working.\nThe operational overhead would have to justify the switch.
\nBut if you're adding semantic search for the first time, or your vector database bills are getting uncomfortable, S3 Vectors is a viable choice.\nThe setup takes an afternoon, the ongoing maintenance is zero, and your users get search that actually understands what they're looking for.
\nDon't forget that S3 Vectors is still in preview, so we can expect some changes before general availability.
\nHere's what I'm planning to do next:
\nThat's all for today.
\nSee you next week.
\nThe Aspire Dashboard ships as a standalone container image, mcr.microsoft.com/dotnet/aspire-dashboard, so you can drop it into Docker Compose without adopting Aspire orchestration.\nServices export telemetry to it over OTLP on port 18889, and the UI runs on 18888.\nStorage is in memory only, so it is meant for local development and debugging.
You've built a distributed .NET application.\nMultiple services, databases, message queues.\nNow something's slow, and you need to figure out why.
\nThe Aspire Dashboard runs perfectly as a standalone container,\ngiving you distributed tracing,\nstructured logs,\nand real-time metrics without the full orchestration framework.
\nWhile Aspire's orchestration is incredibly powerful for managing distributed applications,\nsometimes you just need the observability piece.\nMaybe you're already using Docker Compose or Kubernetes.\nMaybe you're debugging an existing system.\nThe standalone dashboard gives you valuable telemetry visualization with minimal setup.
\nLet's get it running in under 5 minutes.
\nMost teams already have their deployment story figured out.\nDocker Compose, Kubernetes, or some platform-specific orchestration.\nYou don't want to rewrite everything just to get observability.
\nThe standalone Aspire Dashboard hits a sweet spot for development:
\nOne caveat: it's in-memory only.\nPerfect for development and debugging, not for production.\nFor production, you'll want something like Jaeger,\nPrometheus, or a commercial APM solution.
\nBut for understanding what your code is doing right now?\nIt's exactly what you need.
\nDrop this into your docker-compose.yml:
aspire-dashboard:\n container_name: aspire-dashboard\n image: mcr.microsoft.com/dotnet/aspire-dashboard:13.0\n ports:\n - 18888:18888\nThat's it. The dashboard is running.\nNavigate to http://localhost:18888 and... you'll need a token.
![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_157/aspire_dashboard_login.png\")
\nCheck the container logs for the login link.\nThe dashboard generates a unique authentication token on startup:
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_157/aspire_dashboard_login_link.png\")
\nClick that link, and you're in.\nEmpty for now, but not for long.
\nYour services need to know where to send their telemetry.\nAdd these environment variables to your API containers:
\nusers.api:\n image: ${DOCKER_REGISTRY-}usersapi\n build:\n context: .\n dockerfile: Users.Api/Dockerfile\n ports:\n - 5100:5100\n - 5101:5101\n environment:\n - OTEL_EXPORTER_OTLP_ENDPOINT=http://aspire-dashboard:18889\n - OTEL_EXPORTER_OTLP_PROTOCOL=grpc\n depends_on:\n - users.database\nNotice port 18889?\nThat's the OTLP ingestion endpoint.\nThe dashboard listens on 18888 for the UI, 18889 for telemetry data.
Install the necessary OpenTelemetry packages:
\n<PackageReference Include="Npgsql.OpenTelemetry" Version="9.0.3" />\n<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />\n<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />\n<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />\n<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />\nThen configure OpenTelemetry in your Program.cs:
builder.Services.AddOpenTelemetry()\n .ConfigureResource(resource => resource.AddService(builder.Environment.ApplicationName))\n .WithTracing(tracing => tracing\n .AddHttpClientInstrumentation()\n .AddAspNetCoreInstrumentation()\n .AddNpgsql())\n .WithMetrics(metrics => metrics\n .AddHttpClientInstrumentation()\n .AddAspNetCoreInstrumentation());\n\nbuilder.Logging.AddOpenTelemetry(options =>\n{\n options.IncludeScopes = true;\n options.IncludeFormattedMessage = true;\n});\n\nbuilder.Services.AddOpenTelemetry().UseOtlpExporter();\nThis configuration:
\nThe UseOtlpExporter() method automatically picks up the OTEL_EXPORTER_OTLP_ENDPOINT environment variable you configured earlier.
Start your application and make a few requests.\nThe dashboard immediately lights up with data.
\nEvery log entry includes full context: trace IDs, request paths, user identities.\nClick any log to see the complete structured data.
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_157/structured_logs.png\")
\nSee the complete request flow across all your services.\nWhich database query is slow? Which HTTP call is failing?\nThe trace view shows you exactly where time is spent.
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_157/distributed_traces.png\")
\nYou can click into a trace to see the individual spans and any metadata associated with them.
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_157/distributed_trace_details.png\")
\nResponse times, error rates, throughput, all updating live.\nPerfect for load testing or understanding traffic patterns.
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_157/metrics.png\")
\nThe standalone Aspire Dashboard is perfect for local development and debugging.\nSpin up your stack, make requests, and instantly see what's happening across all your services.\nFind bottlenecks in the trace view, correlate logs with requests, watch metrics update in real-time.
\nRemember: this is for development only since data is in-memory and disappears on restart.\nThat last part might be fixed soon, according to the Aspire roadmap.\nFor production, you'll want proper solutions like Jaeger for tracing, Prometheus for metrics, or a commercial APM like Application Insights.
\nBut for that immediate "what is my code actually doing?" question during development?\nYou've got professional observability in under 5 minutes.
\nJust add the container, configure OpenTelemetry, and start debugging like a pro.
\nThat's all for today.
\nSee you next Saturday.
\nAbstractions in .NET pay off when they isolate genuine volatility, like payment providers, external APIs, and third-party SDKs.\nThey turn into technical debt when they wrap stable mechanics such as EF Core's LINQ or HttpClient configuration.\nThe test: if removing the layer makes the code simpler, it was costing more than it earned.
As developers, we love abstractions.\nRepositories, services, mappers, wrappers.\nThey make our code look "clean," they promise testability, and they give us the sense that we're building something flexible.
\nEvery abstraction is a loan.\nYou pay interest the moment you write it.
\nSome abstractions earn their keep by isolating real volatility and protecting your system from change.\nOthers quietly pile up complexity, slow down onboarding, and hide performance problems behind layers of indirection.
\nLet's explore when abstractions pay dividends and when they become technical debt.
\nThe best abstractions isolate true volatility, the parts of your system that you genuinely expect to change.
\nYour core business logic shouldn't depend directly on Stripe's SDK.\nIf you ever switch to Adyen or Braintree, you don't want that decision rippling through every corner of your codebase.\nHere, an abstraction makes perfect sense:
\npublic interface IPaymentProcessor\n{\n Task ProcessAsync(Order order, CancellationToken ct);\n}\n\npublic class StripePaymentProcessor : IPaymentProcessor\n{\n public async Task ProcessAsync(Order order, CancellationToken ct)\n {\n // Stripe-specific implementation\n // Handle webhooks, error codes, etc.\n }\n}\n\npublic class AdyenPaymentProcessor : IPaymentProcessor\n{\n public async Task ProcessAsync(Order order, CancellationToken ct)\n {\n // Adyen-specific implementation\n // Different API, same business outcome\n }\n}\nNow your business logic can stay focused on the domain:
\npublic class CheckoutService(IPaymentProcessor processor)\n{\n public Task CheckoutAsync(Order order, CancellationToken cancellationToken) =>\n processor.ProcessAsync(order, cancellationToken);\n}\nThis abstraction isolates a genuinely unstable dependency (the payment provider) while keeping checkout logic independent.\nWhen Stripe changes their API or you switch providers, only one class needs to change.
\nThat's a good abstraction.\nIt buys you optionality where you actually need it.
\nProblems arise when we abstract things that aren't actually volatile.\nWe end up wrapping stable libraries or creating layers that don't add real value.\nThe "clean" layer you added today becomes tomorrow's maintenance burden.
\nMost teams start with something reasonable:
\npublic interface IUserRepository\n{\n Task<IEnumerable<User>> GetAllAsync();\n}\nBut as requirements evolve, so does the interface:
\npublic interface IUserRepository\n{\n Task<IEnumerable<User>> GetAllAsync();\n Task<User?> GetByEmailAsync(string email);\n Task<IEnumerable<User>> GetActiveUsersAsync();\n Task<IEnumerable<User>> GetUsersByRoleAsync(string role);\n Task<IEnumerable<User>> SearchAsync(string keyword, int page, int pageSize);\n Task<IEnumerable<User>> GetUsersWithRecentActivityAsync(DateTime since);\n // ...and it keeps growing\n}\nSuddenly, the repository is leaking query logic into its interface.\nEvery new way of fetching users means another method, and your "abstraction" becomes a grab bag of every possible query.
\nMeanwhile, Entity Framework already gives you all of this through LINQ: strongly typed queries that map directly to SQL.\nInstead of leveraging that power, you've introduced an indirection layer that hides query performance characteristics and often performs worse.\nThe repository pattern made sense when ORMs were immature.\nToday, it's often just ceremony.
\nI've been guilty of this myself.\nBut part of maturing as a developer is recognizing when patterns become anti-patterns.\nRepositories make sense when they encapsulate complex query logic or provide a unified API over multiple data sources.\nBut you should strive to keep them focused on domain logic.\nAs soon as they explode into a myriad of methods for every possible query, it's a sign that the abstraction has failed.
\nNot all service wrappers are problematic. Context matters.
\n✅ Good Example: External API Integration
\nWhen integrating with external APIs, a wrapper provides genuine value by centralizing concerns:
\npublic interface IGitHubClient\n{\n Task<UserDto?> GetUserAsync(string username);\n Task<IReadOnlyList<RepoDto>> GetRepositoriesAsync(string username);\n}\n\npublic class GitHubClient(HttpClient httpClient) : IGitHubClient\n{\n public Task<UserDto?> GetUserAsync(string username) =>\n httpClient.GetFromJsonAsync<UserDto>($"/users/{username}");\n\n public Task<IReadOnlyList<RepoDto>> GetRepositoriesAsync(string username) =>\n httpClient.GetFromJsonAsync<IReadOnlyList<RepoDto>>($"/users/{username}/repos");\n}\nThis wrapper isolates GitHub's API details.\nWhen authentication changes or endpoints evolve, you update one place.\nYour business logic never needs to know about HTTP headers, base URLs, or JSON serialization.
\n❌ Bad Example: Pass-Through Services
\nThe trouble starts when we wrap our own stable services without adding business value:
\npublic class UserService(IUserRepository userRepository)\n{\n // Just forwarding calls with no added value\n public Task<User?> GetByIdAsync(Guid id) => userRepository.GetByIdAsync(id);\n public Task<IEnumerable<User>> GetAllAsync() => userRepository.GetAllAsync();\n public Task SaveAsync(User user) => userRepository.SaveAsync(user);\n}\nThis UserService is pure indirection.\nAll it does is forward calls to the IUserRepository.\nIt doesn't enforce business rules, add validation, implement caching, or provide any real functionality.\nIt's a layer that exists only because "services are good architecture."
As these anemic wrappers multiply, your codebase becomes a maze.\nDevelopers waste time navigating layers instead of focusing on where business logic actually lives.
\nHere's how to think about when abstractions are worth the investment:
\nHttpClient configuration, JSON serializationAbstract policies because they give you flexibility.\nDon't abstract mechanics, they're already stable APIs that rarely change in breaking ways.
\nIf you only have one implementation, resist the interface urge.\nA single implementation doesn't justify abstraction, it's premature generalization that adds complexity without benefit.
\nConsider this evolution:
\n// Step 1: Start concrete\npublic class EmailNotifier\n{\n public async Task SendAsync(string to, string subject, string body)\n {\n // SMTP implementation\n }\n}\n\n// Step 2: Need SMS? Now abstract\npublic interface INotifier\n{\n Task SendAsync(string to, string subject, string body);\n}\n\npublic class EmailNotifier : INotifier { /* ... */ }\npublic class SmsNotifier : INotifier { /* ... */ }\nThe abstraction emerges naturally when you actually need it.\nThe interface reveals itself through real requirements, not imaginary ones.
\nInside your application, prefer concrete types.\nUse Entity Framework directly, configure HttpClient as typed clients, work with domain entities.\nOnly introduce abstractions where your system meets the outside world: external APIs, third-party SDKs, infrastructure services.
That's where change is most likely, and where abstractions earn their keep.
\nRegularly review your abstractions with this question: If I removed this abstraction, would the code become simpler or more complex?
\nIf removing an interface or service layer would make the code clearer and more direct,\nthat abstraction is probably costing more than it's worth.\nDon't be afraid to delete unnecessary layers.\nSimpler code is often better code.
\nWhen you identify problematic abstractions, here's how to safely remove them:
\nFor example, replacing a repository with direct EF Core usage:
\n// Before: Hidden behind repository\nvar users = await _userRepo.GetActiveUsersWithRecentOrders();\n\n// After: Direct, optimized query\nvar users = await _context.Users\n .Where(u => u.IsActive)\n .Where(u => u.Orders.Any(o => o.CreatedAt > DateTime.Now.AddDays(-30)))\n .Include(u => u.Orders.Take(5))\n .ToListAsync();\nThe concrete version is more explicit about what data it fetches and how, making performance characteristics visible and optimization possible.\nIf you need the same query in multiple places, you could move it into an extension method to make it shareable.
\nAbstractions are powerful tools for managing complexity and change, but they're not free.\nEach one adds indirection, cognitive overhead, and maintenance burden.
\nThe cleanest architecture isn't the one with the most layers.\nIt's the one where each layer has a clear, justified purpose.
\nBefore adding your next abstraction, ask yourself:
\nRemember: abstractions are loans that accrue interest over time.\nMake sure you're borrowing for the right reasons, not just out of habit.
\nThe goal is to use abstractions intentionally, where they solve real problems and protect against genuine volatility.\nBuild abstractions that earn their keep.\nDelete the ones that don't.
\nThanks for reading.
\nAnd stay awesome!
\nGitHub Models gives you OpenAI, Microsoft, and Meta models behind one API, and .NET Aspire 9.4 added an integration for it.\nYou declare the model in the AppHost with AddGitHubModel, reference it from your project, and call AddAzureChatCompletionsClient and AddChatClient in the consuming service.\nAspire wires the API key and connection by resource name.
I wanted to see what the simplest practical AI app I could build was, and this is what I came up with.
\nEvery week, I publish blog posts covering different topics - architecture patterns, cloud services, programming techniques, business insights.\nSometimes I write about DevOps, other times about security.\nAfter years of writing, I realized I had no systematic way to categorize my content.\nSure, I could manually tag each post, but where's the fun in that?
\nSo I built a simple AI-powered blog analyzer.\nIt fetches any blog post, extracts the content, and uses AI to automatically categorize it.\nThe entire thing took less than an hour to build thanks to .NET Aspire 9.4 and it's new GitHub Models integration.
\nWhat surprised me wasn't just how easy it was to build, but how the integration completely removes the typical AI service complexity.\nNo juggling API keys in configuration files, no manual HTTP client setup, no wrestling with different SDK patterns for different AI providers.\nYou declare an AI model in your AppHost just like you would a database, and Aspire handles the rest.
\nHere's what I learned building this simple app, and how you can use the same patterns to add AI to your applications.
\nGitHub Models is a service that provides access to AI models from OpenAI, Microsoft, Meta, and others through a single API.\nYou get free tier access for prototyping (with rate limits), an interactive playground for testing prompts, and pay-per-use billing when you're ready for production.
\nThe models range from cost-effective options like GPT-4o-mini to more advanced models.\nEach model has different strengths - some excel at reasoning, others at code generation or creative writing.
\nWhen you combine GitHub Models with .NET Aspire's orchestration, you get:
\nThe GitHub Models integration splits into two parts: configuring models in your AppHost and consuming them in your services.
In your AppHost project, you define AI models as resources alongside your other services:
\nvar builder = DistributedApplication.CreateBuilder(args);\n\nvar blogService = builder.AddExternalService("dotnet-blog", "https://www.milanjovanovic.tech/blog");\nvar aiModel = builder.AddGitHubModel("ai-model", "openai/gpt-4o-mini");\n\nbuilder.AddProject<Projects.GitHub_Models_Demo>("github-models-demo")\n .WithReference(blogService)\n .WithReference(aiModel);\nNotice how the AI model sits alongside the external blog service.\nBoth are resources that your main application depends on.\nAspire handles the connection details - you just declare what you need.
\nMake sure to install the Aspire.Hosting.GitHub.Models NuGet package to enable this integration.
\nTo call the GitHub Models inference API you need a personal access token with the models:read permission.\nWhen you call AddGitHubModel, Aspire automatically creates a parameter named {resourceName}-gh-apikey (for example, ai-model-gh-apikey)
You can populate the parameter through user secrets for local development:
\n{\n "Parameters": {\n "ai-model-gh-apikey": "github_pat_YOUR_PERSONAL_ACCESS_TOKEN"\n }\n}\nIf you don't provide this value from configuration, Aspire will prompt you to enter it when you run the application.\nYou'll have an option to store the access token securely in user secrets.
\nIn your consuming service, add the Azure AI client (which works with GitHub Models):
\nbuilder\n .AddAzureChatCompletionsClient("ai-model")\n .AddChatClient();\nThat's it.\nNo manual HTTP client configuration, no hardcoded endpoints.\nThe ai-model name matches what you defined in the AppHost, and Aspire wires everything together.
You'll need to install the Aspire.Azure.AI.Inference NuGet package to enable this integration.\nIt also exposes an integration with MEAI using the AddChatClient method.\nThis simplifies the process of interacting with LLMs in your applications.
Now let's build something useful.\nWe'll create a service that fetches blog posts and uses AI to categorize them.
\nFirst, we need to extract readable content from blog posts:
\npublic async Task<string> GetBlogContentAsync(string slug)\n{\n var response = await httpClient.GetAsync(slug);\n response.EnsureSuccessStatusCode();\n var htmlContent = await response.Content.ReadAsStringAsync();\n\n return ExtractArticleContent(htmlContent);\n}\nThe ExtractArticleContent method (not shown) uses HtmlAgilityPack to pull out the main article text,\nstripping away navigation, ads, and other page elements.
Here's where it gets interesting.\nWe'll use the AI model to analyze the content and assign a category:
\npublic async Task<string> SummarizeBlogAsync(string blogContent)\n{\n var prompt =\n @"""\n You are a blog content assistant. Summarize the following blog post\n as one of the following categories: Technology, Business, Programming,\n Architecture, DevOps, Cloud, Security, General.\n Only those eight values are allowed. Be as concise as possible.\n I want a 1-word response with one of these options: Technology, Business,\n Programming, Architecture, DevOps, Cloud, Security, General.\n\n The blog content is: {blogContent}\n """;\n\n var response = await chatClient.GetResponseAsync(prompt);\n\n if (!response.Messages.Any())\n {\n return "General";\n }\n\n var category = response.Messages.First().Text switch\n {\n var s when s.Contains("Technology", StringComparison.OrdinalIgnoreCase) => "Technology",\n var s when s.Contains("Business", StringComparison.OrdinalIgnoreCase) => "Business",\n var s when s.Contains("Programming", StringComparison.OrdinalIgnoreCase) => "Programming",\n var s when s.Contains("Architecture", StringComparison.OrdinalIgnoreCase) => "Architecture",\n var s when s.Contains("DevOps", StringComparison.OrdinalIgnoreCase) => "DevOps",\n var s when s.Contains("Cloud", StringComparison.OrdinalIgnoreCase) => "Cloud",\n var s when s.Contains("Security", StringComparison.OrdinalIgnoreCase) => "Security",\n var s when s.Contains("General", StringComparison.OrdinalIgnoreCase) => "General",\n _ => "General"\n };\n\n return category;\n}\nA few things make this work reliably:
\nFinally, we wrap everything in a simple API endpoint:
\napp.MapPost("/summarize-blog", async (\n string slug,\n BlogService blogService,\n BlogSummarizer blogSummarizer) =>\n{\n var content = await blogService.GetBlogContentAsync(slug);\n var category = await blogSummarizer.SummarizeBlogAsync(content);\n\n return Results.Ok(new\n {\n slug,\n category,\n content = $"{content.Substring(0, 50)}..."\n });\n});\nCall this endpoint with a blog post URL slug, and you get back the category and a preview of the content.\nThe dependency injection handles service resolution, and Aspire manages the AI model connection behind the scenes.
\nHere's an example response:
\n{\n "slug": "screaming-architecture", // https://www.milanjovanovic.tech/blog/screaming-architecture\n "category": "Architecture",\n "content": "If you were to glance at the folder structure of y..."\n}\nHere's the distributed trace in Aspire showing the request and response flow.\nYou can see the request to the blog service and the AI model.
\n![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_155/distributed_trace.png\")
\nThe GitHub Models integration with .NET Aspire removes much of the complexity from adding AI to your applications.\nYou get:
\nWhether you're adding AI to an existing system or building something new, this integration provides the foundation you need.\nStart with simple categorization or summarization, then expand as you learn what works for your use case.
\nThanks for reading.
\nAnd stay awesome!
\nThe five mistakes I see most often are inconsistent naming and structure, bumping the version instead of evolving the contract, no pagination or filtering, vague error responses, and security left for phase 2.\nEvery one of them is harder to fix once clients depend on the API.
\nBad APIs create friction for developers, increase maintenance costs, and make change risky.\nGood API design doesn't mean following every "best practice" blindly.\nIt means choosing the right trade-offs for your context and sticking to them.
\nHere are 5 common mistakes I see repeatedly, why they cause problems, and how to avoid them with pragmatic, battle-tested solutions.
\nNaming is the first thing consumers see.\nInconsistency here leads to constant documentation lookups, broken expectations, and more bugs.
\nLook, we've all been there.\nYou successfully call /users and /products, so naturally you try /orders.\nBut nope, this API uses /order-list for some reason.\nNow you're back to the docs, breaking your flow, wondering why anyone would do this.\nMultiply this friction by dozens of endpoints, and you've built an API that makes developers want to flip tables.
I get it, deep URL hierarchies like /users/{id}/habits/{habitId}/entries/{entryId}/comments/{commentId} feel satisfying.\nThey mirror your beautiful domain model!\nBut here's the thing: you've just hardcoded your entire data structure into your URLs.\nWhen business requirements change (and they will), you can't reorganize without breaking clients.
Plus, what happens when someone only has a comment ID?\nThey need to somehow figure out the user, habit, and entry IDs just to fetch one comment.\nThat's ridiculous.
\nKeep it simple with plural nouns: /users, /habits, /entries.\nNo more guessing if it's user or users.
Only nest when something truly belongs to something else.\nUser settings belong to and die with the user, so /users/{id}/settings makes sense.\nComments can exist independently, so /users/{id}/posts/{postId}/comments can be simplified.
Instead, flatten with filters:
\n# Instead of deep nesting\nGET /users/{userId}/habits/{habitId}/entries\n\n# Use filters for flexibility\nGET /entries?userId={userId}&habitId={habitId}\nGET /entries?habitId={habitId} # Now you can get entries without knowing the user\nAnd please, for the love of all that is holy, wrap your arrays:
\n{\n "data": [\n {\n "id": "e_8YH",\n "habitId": "code-review",\n "at": "2025-08-08T09:17:34Z",\n "value": 5,\n "unit": "reviews",\n "tags": ["team"]\n },\n {\n "id": "e_8Z2",\n "habitId": "deep-work",\n "at": "2025-08-07T07:00:00Z",\n "value": 2,\n "unit": "pomodoros",\n "note": "EF filters optimized"\n }\n ],\n "total": 42,\n "hasMore": true,\n "nextCursor": "cursor_01J9KaBcd"\n}\nI know it feels like pointless boilerplate now, but trust me, when you need to add pagination info six months from now,\nyou'll thank yourself for not having to break every client that expects a raw array.
\nYeah, the REST purists will complain that filters aren't "RESTful enough."\nLet them.\nYour API will be flexible, maintainable, and actually pleasant to use.\nI'll take that over conceptual purity any day.
\nEveryone defaults to versioning (/v1/users) thinking they're being smart about future changes.\nSpoiler: they're not. They're creating a maintenance nightmare.
Here's what actually happens when you have v1, v2, and v3 running:
\nBut the worst part?\nVersioning makes you lazy.\nInstead of thinking "how can I evolve this without breaking clients?" you just think "eh, I'll bump the version."\nNow your clients have to rewrite their entire integration because you wanted to rename a field.
\nWatch this disaster unfold:
\nv1: GET /users returns {id, name, email}\nv2: GET /users returns {id, fullName, emailAddress} // "looks cleaner!"\nv3: GET /users returns {id, firstName, lastName, email} // "we need split names!"\nCongrats, you're now maintaining three different response formats for the same damn data.\nThat v1 client?\nThey'll never get new features unless they rewrite everything.\nFound a critical bug? Hope you enjoy patching it three times!
\nHere's the radical idea: don't version at all.\nI'm serious.
\nAdd fields, don't replace them:
\n// What you ship first\n{ "id": 1, "name": "John Doe" }\n\n// What you ship later (keeping the old field)\n{\n "id": 1,\n "name": "John Doe", // Still there! Mark it deprecated in docs\n "firstName": "John",\n "lastName": "Doe"\n}\nNeed optional features?\nUse query parameters:
\nGET /users/{id}?include=habits,entries\nGET /users/{id}?format=detailed\nIf you absolutely must make a breaking change (and really think about this), create a new resource:
\n# Old faithful, unchanged\nGET /users/{id}\n\n# New hotness\nGET /userProfiles/{id}\nWhen breaking changes are truly unavoidable, at least be a decent human about it.\nGive people 6-12 months notice.\nRun both versions in parallel.\nWrite a migration guide that doesn't suck.\nAnd for crying out loud, monitor who's still using the old stuff so you can reach out before pulling the plug.
\nYes, this means you need to actually think about your API design upfront.\nYou can't just YOLO field names and fix them later.\nBut that constraint will make you design better APIs, and future-you will buy present-you a beer.
\nIf you want to learn more about this, I recommend reading API Change Management.
\nThat GET /entries endpoint works great with your 10 test records.\nThen you launch, get actual users, and suddenly you're returning 100,000 entries in a single response.\nYour API times out, your mobile users on crappy connections hate you, and your cloud bill makes you cry.
"We'll add pagination later," you said.\nWell, now it's later, and adding pagination means breaking every client that expects an array.\nNice job.
\nWithout filtering, your clients are downloading thousands of records to find the five they actually need.\nIt's like making someone download all of Wikipedia to read one article.\nYour servers are melting, serializing data nobody wants.\nYour users are burning through their data plans.\nEveryone loses.
\nFiltering is for when you know exactly what you want:
\nGET /entries?habitId=123&date=2025-08-01&status=completed\nSearching is for when you kinda know what you want:
\nGET /entries/search?q=morning+run+park\nDon't try to be clever and combine them.\nFiltering uses your database indexes efficiently.\nSearching needs full-text magic.\nMix them and you'll end up with something that does neither well.
\nFor pagination, you've got two choices, and they both kinda suck in different ways.
\nOffset/limit is what everyone starts with:
\nGET /entries?offset=100&limit=50\n # or you can call them skip and take\n # or you can call them page and pageSize\n # use whatever you like best\nIt's dead simple and lets users jump to page 5, but here's the fun part: add or delete an item while someone's paginating, and they'll either skip entries or see duplicates.\nPlus, asking for offset=10000 makes your database cry as it counts through all those rows.
\nCursor-based pagination is the "proper" solution:
\nGET /entries?limit=50&cursor=eyJpZCI6MTIzfQ==\nRock solid, no skipped items, consistent performance.\nBut you can't jump to arbitrary pages and cursors can become invalid if underlying data changes significantly.
\nYeah, implementing all this is a pain.\nYou need cursor encoding, parameter validation, query optimization.\nBut trying to add it after launch?\nWouldn't recommend.\nJust build it right the first time.
\n{"error": "An error occurred"} — if you return this, I hate you.
Seriously, when your API spits out these useless errors, here's what happens: I try random stuff hoping something works.\nI add defensive code everywhere because I don't trust you.\nI flood your support channel asking what's wrong.\nThen I complain about your API on social media (any publicity is good publicity, eh?).
\nA good error tells me three things: what broke, why it broke, and how to fix it.\nIs that so hard?
\nStop inventing your own janky error format.\nUse Problem Details (RFC 9457) like a civilized developer:
\n{\n "type": "https://api.example.com/errors/validation-failed",\n "title": "Validation Failed",\n "status": 400,\n "detail": "The request body contains invalid fields",\n "instance": "/habits/123",\n "errors": [\n {\n "field": "name",\n "reason": "Must be between 1 and 100 characters",\n "value": ""\n },\n {\n "field": "frequency",\n "reason": "Must be one of: daily, weekly, monthly",\n "value": "sometimes"\n }\n ]\n}\nSee how that actually helps me fix the problem? Revolutionary, I know.
\nAnd please use the right status codes. It's not that hard:
\n400 Bad Request: You sent garbage401 Unauthorized: Who are you?403 Forbidden: I know who you are, but no404 Not Found: That thing doesn't exist409 Conflict: That conflicts with something422 Unprocessable Entity: I understand what you want, but it's wrong429 Too Many Requests: Slow down, cowboy500 Internal Server Error: We screwed up503 Service Unavailable: We're drowning, try again laterNow, don't go leaking your entire stack trace in production like an amateur.\nGive friendly errors to users, detailed errors in dev/staging, and log the gory details server-side where you can actually use them.
\n"We'll add auth in phase 2" — famous last words before your API becomes a data buffet for hackers.\nAsk the Tea app how that worked out for them.
\nHere's what happens when you try to bolt on security later: Every client breaks when you add authentication.\nThat data you've been leaking? It's probably been scraped already.\nYour compliance audit? Failed.\nThat one security incident? Your users will bring it up for years.
\nAuthentication (who are you?) and Authorization (what can you do?) are different things.\nI've seen so many APIs that check if you're logged in but never check if you should actually access that data.\nDon't be that person.
\nRate limiting isn't just about stopping abuse, it's about fairness.\nStart simple: 1000 requests per hour per API key.\nWhen they hit the limit, return 429 with headers showing when they can try again.\nThen get fancy: different limits for different endpoints, higher limits for paying customers,\nlower limits for that one client who keeps doing weird stuff.
HTTPS everywhere.\nYes, even for your internal "no one will ever find this" API.\nIt's 2025, not 2005.\nLet's Encrypt is free.\nYou have no excuse.
\nLook, security makes things slower and more complex.\nAuth checks on every request, encryption overhead, state management for rate limiting, it all adds up.\nBut you know what's worse?\nExplaining to your users why their data is being sold on the dark web.\nBuild security in from the start, or prepare for a world of pain.
\nGood API design isn't about perfection, it's about making intentional, informed decisions.\nEvery choice is a tradeoff.\nConsistency might limit flexibility.\nSecurity will impact performance.\nStability means slower innovation.
\nHere's what actually matters: know your tradeoffs and own them.\nDocument why you made these choices (future you will thank you).\nStay consistent even when it's tempting not to.\nDesign for evolution, not some imaginary perfect future.\nAnd listen to your users, but don't turn your API into a frankenstein monster trying to please everyone.
\nYour API is a promise to other developers.\nEvery time you break that promise (with a breaking change, an inconsistent pattern, or a useless error message) you lose their trust.\nAnd trust me, developers hold grudges.
\nBuild the API you'd want to use.\nYour developers will thank you, your support team will thank you, and honestly, you'll thank yourself six months from now when you have to maintain this thing.
\nWant to dive deeper? Check out my Pragmatic REST APIs course where I cover all of this (and more).
\nP.S. Any sharp language here is just me being snarky for emphasis.\nI'm critiquing patterns, not people.\nDon't take the strong wording too seriously.
\nEnforce data boundaries in the database, not only in code.\nGive each module its own PostgreSQL schema and login role, grant that role privileges on its schema alone, and point one EF Core DbContext per module at it with the module's connection string.\nCross-module reads go through a view or an API.
Modular monoliths promise the productivity of a monolith and the clear boundaries of microservices.\nThey work because each module is self-contained: its domain model, behavior and data live behind a boundary.\nBut one of the hardest places to maintain those boundaries is in the database.
\nNothing stops a developer from running a rogue JOIN across tables or bypassing a public API.
In previous articles, I described four levels of data isolation (table, schema, database and alternative persistence)\nand argued that modules should expose explicit APIs to access their data.
\nThis article goes deeper on the database side.\nYou'll learn how to carve out logical and physical boundaries using PostgreSQL schemas and roles and EF Core,\nwhy those choices matter, and how to handle cross-cutting queries without breaking encapsulation.
\nIn a modular monolith each module owns its data.\nIf Module A reaches into Module B's tables, you lose this constraint and your modules become tightly coupled.\nInstead, B exposes a public API and hides its persistence logic from consumers.
\nBeyond clean code, enforcing boundaries at the database level protects you against mistakes\nand makes it easier to extract a module into its own service later.
\nDatabase schemas act like folders: they let you organise objects and share a database among many users,\nbut a user can access any schema only if they have privileges.\nThis means we can deliberately lock each module to its own schema.
\nThe strategy
\nDbContext per module, setting a default schema and connection string per module.These practices give us enforceable boundaries while keeping the operational overhead low.
\nPostgreSQL lets you create multiple schemas within a single database.\nA module can define its own schema and a role that owns it.\nThe role only has usage and table-level privileges on that schema.\nFor example, for an orders module:
\n-- create a user for the module and its schema\nCREATE ROLE orders_role LOGIN PASSWORD 'orders_secret';\nCREATE SCHEMA orders AUTHORIZATION orders_role;\nGRANT USAGE ON SCHEMA orders TO orders_role;\nGRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA orders TO orders_role;\nALTER ROLE orders_role SET search_path = orders;\nThe ALTER ROLE command sets the role's default search path so unqualified names resolve to the module's schema.\nIf you don't want to rely on the search path, always qualify table names (orders.table_name).
Row-level security (RLS) allows you to filter rows based on a policy expression.\nYou enable RLS on a table and define a policy referencing current_user or columns:
RLS is powerful for multi-tenant scenarios or sensitive data, but it adds complexity.\nStart with schemas and roles and add RLS only when necessary.
\nI assume readers are comfortable with EF Core, so we'll skip the basics and focus on what matters for modular monoliths:
\nmodelBuilder.HasDefaultSchema("orders") in OnModelCreating\nto map entities to the correct schema.\nSetting a default schema also affects sequences and migrations.MigrationsHistoryTable("__EFMigrationsHistory", "orders")\nso that EF's migration metadata stays within the module's schema.These settings ensure EF Core queries and migrations respect the boundaries established by the database.
\nSuppose we have two modules (Orders and Shipping) and we want to enforce boundaries between them.\nHere's what we need to do:
\nCreate schemas and roles.\nUse SQL to create orders and shipping schemas and their corresponding roles (orders_role, shipping_role).\nGrant each role privileges only on its schema.
-- Orders schema and role\nCREATE ROLE orders_role LOGIN PASSWORD 'orders_secret';\nCREATE SCHEMA orders AUTHORIZATION orders_role;\nGRANT USAGE ON SCHEMA orders TO orders_role;\nGRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA orders TO orders_role;\nALTER ROLE orders_role SET search_path = orders;\n\n -- Shipping schema and role\n CREATE ROLE shipping_role LOGIN PASSWORD 'shipping_secret';\n CREATE SCHEMA shipping AUTHORIZATION shipping_role;\n GRANT USAGE ON SCHEMA shipping TO shipping_role;\n GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA shipping TO shipping_role;\n ALTER ROLE shipping_role SET search_path = shipping;\nAdd connection strings. In configuration, define separate connection strings per module:
\n{\n "ConnectionStrings": {\n "Orders": "Host=localhost;Database=appdb;Username=orders_role;Password=orders_secret",\n "Shipping": "Host=localhost;Database=appdb;Username=shipping_role;Password=shipping_secret"\n }\n}\nDefine DbContexts. Each module defines its own context and sets the default schema. For the Orders module:
\npublic class OrdersDbContext : DbContext\n{\n public DbSet<Order> Orders { get; set; } = default!;\n public DbSet<OrderLine> OrderLines { get; set; } = default!;\n\n public OrdersDbContext(DbContextOptions<OrdersDbContext> options) : base(options) { }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n // set default schema for all entities in this context\n modelBuilder.HasDefaultSchema("orders");\n // optional: configure tables explicitly\n modelBuilder.Entity<Order>().ToTable("orders");\n modelBuilder.Entity<OrderLine>().ToTable("order_lines");\n base.OnModelCreating(modelBuilder);\n }\n}\nRegister each context with its connection string and specify the migrations history table:
\nbuilder.Services.AddDbContext<OrdersDbContext>(options =>\n options.UseNpgsql(builder.Configuration.GetConnectionString("Orders"),\n o => o.MigrationsHistoryTable("__EFMigrationsHistory", "orders")));\n\nbuilder.Services.AddDbContext<ShippingDbContext>(options =>\n options.UseNpgsql(builder.Configuration.GetConnectionString("Shipping"),\n o => o.MigrationsHistoryTable("__EFMigrationsHistory", "shipping")));\nMaintain migrations separately.\nBecause each module has its own context and schema, you maintain migrations separately.\nWhen generating a migration, specify the context:
\ndotnet ef migrations add InitialOrders --context OrdersDbContext --output-dir Data/Migrations/Orders\nRepeat this for the Shipping context.\nEF Core will generate migration classes that create tables within the specified schema (because of HasDefaultSchema).\nRemember to apply the migrations in the correct order when deploying. You can automate this by having a migration runner iterate through the contexts.
With schemas, roles and multiple contexts in place, the data boundary becomes enforceable at the database level:
\nDbContext knows only about the orders schema and uses credentials that have no privileges on the Shipping schema.orders.orders directly because its role lacks the necessary privileges.Even in a modular system you occasionally need a screen that spans multiple modules,\nsuch as an Order History page that shows order and shipping data.\nResist the temptation to JOIN across schemas.\nTwo approaches can help:
Dedicated read model.\nOne module owns a view model and subscribes to events from others.\nThis pattern works well when modules might be extracted later.
\nDatabase views with privileges.\nSince our modules share a database, we can create a read-only view in the public schema that joins the relevant tables.\nWe grant SELECT on the view to a special role or module.\nThis view acts like a controlled public API.\nConsumers query the view but cannot access the underlying tables directly.\nThe trade-off is similar to calling a synchronous API: if you later split the database, the view will have to be replaced with a service call.
For example:
\nCREATE VIEW public.order_summary AS\nSELECT o.id, o.total, s.status\nFROM orders.orders o\nJOIN shipping.shipments s ON s.order_id = o.id;\n\n-- grant read access to a reporting role\nGRANT SELECT ON public.order_summary TO reporting_role;\nThis approach lets you build dashboards or admin screens without breaking boundaries.
\nBy giving each module its own schema, role and DbContext, and by controlling cross-module access via views or APIs,\nyou ensure that boundaries in your modular monolith are enforceable rather than aspirational.\nThis discipline makes it easier to evolve your system and paves the way for a future microservice extraction.
\nIf you found this article valuable, check out my previous posts on modular monoliths:
\nIf you want a structured, hands-on approach to building modular systems, from defining boundaries to extracting services,\ncheck out my Modular Monolith Architecture course.\nJoin more than 2,100+ students who have mastered modular monoliths with it.\nThe course walks through these patterns in depth and shows how to apply them in a real codebase.
\nThanks for reading.
\nAnd stay awesome!
\nNamed query filters are a feature EF 10 introduced: you attach multiple global query filters to one entity by passing a name to HasQueryFilter.\nYou can then disable individual filters by name with IgnoreQueryFilters instead of turning them all off at once.\nThat makes combinations like soft deletion plus multi-tenancy much safer.
Entity Framework Core's global query filters have long been a convenient way to apply common conditions to all queries on an entity.\nThey're especially handy in scenarios like soft deletion\nand multi-tenancy,\nwhere you want the same WHERE clause added automatically to every query.
Previous versions of EF Core, however, suffered from one big limitation: each entity type could only have one filter defined.\nIf you needed to combine multiple conditions (for example, soft-delete and tenant isolation)\nyou either had to write explicit && expressions or manually disable and reapply filters in specific queries.
With EF 10, that changes.\nThe new named query filters feature lets you attach multiple filters to a single entity and reference them by name.\nYou can then disable individual filters as needed, rather than turning off all filters at once.
\nLet's explore this new capability, why it matters, and some practical ways to use it.
\nIf you've used EF Core for a while, you may already be familiar with\nglobal query filters.\nA query filter is a condition that EF automatically applies to all queries for a particular entity type.\nUnder the hood, EF adds a WHERE clause whenever that entity is queried. Typical uses include:
For example, a soft-delete filter might be configured like this:
\nmodelBuilder.Entity<Order>()\n .HasQueryFilter(order => !order.IsDeleted);\nWith the filter in place, every query on Orders automatically excludes soft-deleted records.\nTo include deleted data (say, for an admin report), you can call IgnoreQueryFilters() on the query.\nThe downside is that all filters on that entity are disabled,\nwhich opens the door to accidentally leaking data you don't intend to show.
Until now, EF permitted only one query filter per entity.\nIf you called HasQueryFilter twice on the same entity, the second call overwrote the first.\nTo combine filters you had to write a single expression with &&:
modelBuilder.Entity<Order>()\n .HasQueryFilter(order => !order.IsDeleted && order.TenantId == tenantId);\nThis works but makes it impossible to selectively disable one condition.\nIgnoreQueryFilters() disables both, forcing you to manually re-apply whichever filter you still need.\nEF 10 introduces a better alternative: named query filters.
To attach multiple filters to an entity, call HasQueryFilter with a name for each filter:
modelBuilder.Entity<Order>()\n .HasQueryFilter("SoftDeletionFilter", order => !order.IsDeleted)\n .HasQueryFilter("TenantFilter", order => order.TenantId == tenantId);\nUnder the hood, EF creates separate filters identified by the names you provide.\nYou can now turn off just the soft-delete filter while keeping the tenant filter in place:
\n// Returns all orders (including soft‑deleted) for the current tenant\nvar allOrders = await context.Orders.IgnoreQueryFilters(["SoftDeletionFilter"]).ToListAsync();\nIf you omit the parameter array, IgnoreQueryFilters() disables all filters for the entity.
Named filters use string keys.\nHard-coding those names throughout your codebase makes it easy to introduce typos and brittle magic strings.\nTo avoid this, define constants or enums for your filter names and reuse them wherever needed.\nFor example:
\npublic static class OrderFilters\n{\n public const string SoftDelete = nameof(SoftDelete);\n public const string Tenant = nameof(Tenant);\n}\n\nmodelBuilder.Entity<Order>()\n .HasQueryFilter(OrderFilters.SoftDelete, order => !order.IsDeleted)\n .HasQueryFilter(OrderFilters.Tenant, order => order.TenantId == tenantId);\n\n// Later in your query\nvar allOrders = await context.Orders.IgnoreQueryFilters([OrderFilters.SoftDelete]).ToListAsync();\nHaving the filter names defined in a single place reduces duplication and improves maintainability.\nAnother best practice is to wrap the ignore call in an extension method or repository\nso that consumers don't directly interact with filter names at all. For example:
\npublic static IQueryable<Order> IncludeSoftDeleted(this IQueryable<Order> query)\n => query.IgnoreQueryFilters([OrderFilters.SoftDelete]);\nThis makes your intent explicit and centralizes the filter logic in one place.
\nThe introduction of named query filters in EF 10 removes one of the longstanding limitations\nof EF's global query filters feature.\nYou can now:
\nIgnoreQueryFilters(["FilterName"])Named query filters can become a powerful tool to keep your queries clean and your domain logic encapsulated.
\nWhether you're building SaaS applications that isolate tenant data or\nensuring that deleted records stay hidden until you explicitly need them,\nEF 10's named query filters offer the flexibility you've been waiting for.
\nGive them a try in the preview and start thinking about how they can simplify your codebase.
\nThat's all for today.
\nSee you next week.
\nYou can generate PDF reports in .NET for free by rendering an HTML template with Handlebars.NET and printing it with PuppeteerSharp, which drives headless Chromium.\nYou keep full CSS control over the layout.\nThe cost is a bundled browser: about 12 seconds on a cold start, around 580ms once it is warm.
\nSooner or later, every .NET developer needs to generate PDF reports.\nAnd generating polished PDF reports in .NET doesn't have to be painful.\nLet me explain how.
\nMy go-to method?
\nHTML to PDF conversion.\nIt's:
\nBut many popular libraries require a commercial license.\nThis post walks you through a completely free approach using:
\nThis gives you full control over layout, styling, and content.\nIt's perfect for invoices, dashboards, and exports.
\nWe'll start from scratch and build up to a complex, dynamic invoice report with full styling, images, and even headers and footers.
\nPros:
\nCons:
\nWe'll start by installing the NuGet packages we need for Handlebars and PuppeteerSharp:
\nInstall-Package Handlebars.Net\nInstall-Package PuppeteerSharp\nNext, we'll create our first template.\nIt's a simple HTML document with some Handlebars placeholders.\nYou'll notice them with the {{variable}} syntax.\nThese placeholders will be replaced with actual data when rendering the template.
<!-- Templates/InvoiceTemplate.html -->\n<!-- The file extension doesn't really matter. -->\n<html lang="en">\n <head>\n <style>\n body {\n font-family: Arial;\n }\n </style>\n </head>\n <body>\n <h1>Invoice #{{Number}}</h1>\n\n <p>Date: {{formatDate IssuedDate}}</p>\n\n <h2>From:</h2>\n <p>{{SellerAddress.CompanyName}}</p>\n <p>{{SellerAddress.Email}}</p>\n\n <h2>To:</h2>\n <p>{{CustomerAddress.CompanyName}}</p>\n <p>{{CustomerAddress.Email}}</p>\n\n <h2>Items:</h2>\n <table>\n <tr>\n <th>Name</th>\n <th>Price</th>\n </tr>\n {{#each LineItems}}\n <tr>\n <td>{{Name}}</td>\n <td>{{formatCurrency Price}}</td>\n </tr>\n {{/each}}\n </table>\n\n <p><strong>Total: {{formatCurrency Total}}</strong></p>\n </body>\n</html>\nThe function calls, like {{formatDate IssuedDate}}, are custom helpers we can define in Handlebars.\nYou register them like this:
Handlebars.RegisterHelper("formatDate", (context, arguments) =>\n{\n if (arguments[0] is DateOnly date)\n {\n return date.ToString("dd/MM/yyyy");\n }\n return arguments[0]?.ToString() ?? "";\n});\nThis allows us to format dates, currencies, or any other data type as needed.\nYou register these helpers before compiling the template, once per application start is enough.
\nHow do we render this template and convert it to PDF?\nWe'll use Handlebars.NET to compile the template with data, then PuppeteerSharp to render it to PDF.
\nFirst, we read the template file and compile it with Handlebars:
var template = File.ReadAllText("Templates/InvoiceTemplate.html");\nvar data = new {\n customer = "Milan Jovanović",\n items = new[] {\n new { description = "Software License", price = 99 },\n new { description = "Support Plan", price = 49 }\n }\n};\n\nvar compiledTemplate = Handlebars.Compile(template);\n\nstring html = compiledTemplate(data);\nThis gives us the final HTML with all placeholders replaced by actual data.
\nNote: You don't necessarily need to use Handlebars.\nYou can use any templating engine that suits your needs,\nlike Razor or Scriban.
\nNext, we need to convert this HTML to PDF using PuppeteerSharp.\nWe'll launch a headless browser, set the content to our HTML, and then generate the PDF.\nHere's how we do it:
\n// Ensure PuppeteerSharp has the browser binaries\nvar browserFetcher = new BrowserFetcher();\nawait browserFetcher.DownloadAsync(BrowserFetcher.DefaultChromiumRevision);\n\n// Launch the browser and create a new page\nusing var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });\nusing var page = await browser.NewPageAsync();\n\n// Set the content of the page to our compiled HTML\nawait page.SetContentAsync(html);\n\n// Optional: wait for fonts to load if using custom fonts\nawait page.EvaluateExpressionHandleAsync("document.fonts.ready");\n\nbyte[] pdf = await page.PdfDataAsync(new PdfOptions {\n Format = PaperFormat.A4,\n PrintBackground = true,\n MarginOptions = new MarginOptions\n {\n Top = "50px",\n Right = "20px",\n Bottom = "50px",\n Left = "20px"\n }\n});\nThis gives us a byte array containing the PDF data.\nYou can then save it to a file or return it from an API endpoint.
\nHere's a simple example of returning it from a Minimal API endpoint:
\nreturn Results.File(pdf, "application/pdf", "invoice.pdf");\nHere's what the document looks like when rendered:
\n![\"Simple](\"https://milanjovanovic.tech/blogs/mnw_151/simple_template.png\")
\n What are some improvements we can make to this basic setup?
\nFor example, you can add images to your template using the <img> tag.\nA simple approach is to use a base64-encoded image directly in the HTML.\nNote that we're passing the image data using the LogoBase64 variable.
<img\n src="data:image/png;base64,{{LogoBase64}}"\n alt="Logo"\n style="height:50px; max-width:200px; object-fit:contain;"\n/>\nWe can also render dynamic headers and footers using PuppeteerSharp's built-in support.\nYou can define these in the PdfOptions object when generating the PDF.\nHere's an example:
var pdfOptions = new PdfOptions\n{\n HeaderTemplate =\n @"""\n <div style='font-size: 14px; text-align: center; padding: 10px;'>\n <span style='margin-right: 20px;'><span class='title'></span></span>\n <span><span class='date'></span></span>\n </div>\n """,\n FooterTemplate =\n @"""\n <div style='font-size: 14px; text-align: center; padding: 10px;'>\n <span style='margin-right: 20px;'>Generated on <span class='date'></span></span>\n <span>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span>\n </div>\n """,\n DisplayHeaderFooter = true\n};\nPuppeteerSharp uses CSS classes like title, date, pageNumber, and totalPages to inject dynamic values.\nThis could be different for some other libraries, so check the documentation.
Lastly, I want to mention that you can use CSS for advanced styling.\nThis can be inline in the HTML or in a separate CSS file.\nYou can also reference external stylesheets if needed, using the <link> tag.
Here's a complete example of a more complex template with images, headers, and footers:
\n<html lang="en">\n <head>\n <meta charset="UTF-8" />\n <meta name="viewport" content="width=device-width, initial-scale=1.0" />\n <title>Invoice #{{Number}}</title>\n <style>\n /* Omitted for brevity */\n </style>\n </head>\n <body>\n <div class="invoice-container">\n <!-- Header with Logo -->\n <div\n style="display: flex; justify-content: space-between; align-items: flex-start;"\n >\n <div>\n <h1 class="invoice-title">Invoice #{{Number}}</h1>\n <div class="invoice-dates">\n <p><strong>Issued:</strong> {{formatDate IssuedDate}}</p>\n <p><strong>Due:</strong> {{formatDate DueDate}}</p>\n </div>\n </div>\n <div>\n {{#if LogoBase64}}\n <img\n src="data:image/png;base64,{{LogoBase64}}"\n alt="Logo"\n style="height:50px; max-width:200px; object-fit:contain;"\n />\n {{/if}}\n </div>\n </div>\n <hr\n style="margin: 20px 0; border: none; border-top: 1px solid #e9ecef;"\n />\n\n <!-- Addresses - Side by Side -->\n <div class="addresses">\n <!-- Seller Address -->\n <div class="address-box">\n <h3 class="address-title">From:</h3>\n <div class="address-content">\n <p class="company-name">{{SellerAddress.CompanyName}}</p>\n <p>{{SellerAddress.Street}}</p>\n <p>{{SellerAddress.City}}, {{SellerAddress.State}}</p>\n <p class="email">{{SellerAddress.Email}}</p>\n </div>\n </div>\n\n <!-- Customer Address -->\n <div class="address-box">\n <h3 class="address-title">Bill To:</h3>\n <div class="address-content">\n <p class="company-name">{{CustomerAddress.CompanyName}}</p>\n <p>{{CustomerAddress.Street}}</p>\n <p>{{CustomerAddress.City}}, {{CustomerAddress.State}}</p>\n <p class="email">{{CustomerAddress.Email}}</p>\n </div>\n </div>\n </div>\n\n <!-- Items Table -->\n <div class="items-section">\n <h2 class="items-title">Items</h2>\n <table class="items-table">\n <thead>\n <tr>\n <th>#</th>\n <th>Description</th>\n <th>Price</th>\n <th>Qty</th>\n <th>Total</th>\n </tr>\n </thead>\n <tbody>\n {{#each LineItems}}\n <tr>\n <td>{{@index}}</td>\n <td>{{Name}}</td>\n <td>{{formatCurrency Price}}</td>\n <td>{{formatNumber Quantity}}</td>\n <td>{{formatCurrency (multiply Price Quantity)}}</td>\n </tr>\n {{/each}}\n </tbody>\n </table>\n </div>\n\n <!-- Totals -->\n <div class="totals">\n <div class="totals-container">\n <div class="totals-row subtotal">\n <span>Subtotal:</span>\n <span>{{formatCurrency Subtotal}}</span>\n </div>\n <div class="totals-row">\n <span>Tax:</span>\n <span>{{formatCurrency 0}}</span>\n </div>\n <div class="totals-row total">\n <span>Total:</span>\n <span>{{formatCurrency Total}}</span>\n </div>\n </div>\n </div>\n </div>\n </body>\n</html>\nAnd the rendered PDF looks like this:
\n![\"Complex](\"https://milanjovanovic.tech/blogs/mnw_151/complex_template.png\")
\n Here's a small tip: PuppeteerSharp requires the Chromium browser binaries to be downloaded at runtime.\nYou can do this by calling BrowserFetcher.DownloadAsync() before launching the browser.\nThis ensures the required browser version is available when you run your application.
A simple way to do this is to add it to your application startup code or a background service:
\npublic class BrowserSetupService : BackgroundService\n{\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n var browserFetcher = new BrowserFetcher();\n await browserFetcher.DownloadAsync();\n }\n}\nThen register this service in your Program.cs:
builder.Services.AddHostedService<BrowserSetupService>();\nLet's talk about performance.\nHow fast is this approach and can you use it at scale?
\nThe first thing to consider is the use a headless browser like Chromium.\nThis can be slower than native PDF libraries, especially for large documents or high concurrency.\nIt also adds overhead at runtime since the browser binaries need to be downloaded and launched.
\nYou should definitely consider moving this out of your main application.\nYou can use a background service or a separate microservice to handle PDF generation.\nEvent a cloud function can be a good fit if you need to scale.
\nBut as with anything performance-related, it depends on your specific use case.\nSo measure and profile your application to see if this approach meets your needs.
\nHere are some benchmarks I ran on a sample invoice template.\nIt's nothing scientific, but it gives you an idea of the performance.\nI didn't test this with concurrent requests, but rather just the time it takes to generate a single PDF.
\nCold Start: ~12s spent downloading + launching Chromium
\nWarm Run: ~580ms
\nHTML + PuppeteerSharp is one of the most pragmatic approaches for PDF reporting in .NET.
\nIt lets you:
\nAnd all of this without relying on commercial libraries.
\nI've also written about PDF generation in the past,\nwith libraries like QuestPdf or IronPdf.\nYou can take a look at those if you want to compare approaches.
\nThe cold start can be expensive, but once warmed up, rendering is fast and reliable.\nYou get total layout control, CSS styling, and even dynamic headers and footers with page numbers and timestamps.
\nIf you're building internal dashboards, invoice generators, or export endpoints, this approach delivers excellent value.
\nIf you need pixel-perfect PDF reports in .NET and want full design control,\ncombining Handlebars.NET with PuppeteerSharp is a powerful approach.
\nYou'll trade some performance and setup cost for flexibility, but for most internal tools, dashboards, or customer-facing reports, it's worth it.
\nASP.NET Core gives you three options for global error handling: custom middleware with a try-catch, the same middleware writing through IProblemDetailsService, and IExceptionHandler.\nFor new projects I reach for IExceptionHandler with AddProblemDetails, because each handler covers one exception type and the framework tries them in registration order.
Let's talk about something we all deal with but often put off until the last minute - error handling in our ASP.NET Core apps.
\nWhen something breaks in production, the last thing you want is a cryptic 500 error with zero context.\nProper error handling isn't just about logging exceptions.\nIt's about making sure your app fails gracefully and gives useful info to the caller (and you).
\nIn this article, I'll walk through the main options for global error handling in ASP.NET Core.
\nWe'll look at how I used to do it, what ASP.NET Core 9 offers now, and where each approach makes sense.
\nThe classic way to catch unhandled exceptions is with custom middleware.\nThis is where most of us start, and honestly, it still works great for most scenarios.
\ninternal sealed class GlobalExceptionHandlerMiddleware(\n RequestDelegate next,\n ILogger<GlobalExceptionHandlerMiddleware> logger)\n{\n public async Task InvokeAsync(HttpContext context)\n {\n try\n {\n await next(context);\n }\n catch (Exception ex)\n {\n logger.LogError(ex, "Unhandled exception occurred");\n\n // Make sure to set the status code before writing to the response body\n context.Response.StatusCode = ex switch\n {\n ApplicationException => StatusCodes.Status400BadRequest,\n _ => StatusCodes.Status500InternalServerError\n };\n\n await context.Response.WriteAsJsonAsync(\n new ProblemDetails\n {\n Type = ex.GetType().Name,\n Title = "An error occured",\n Detail = ex.Message\n });\n }\n }\n}\nDon't forget to add the middleware to the request pipeline:
\napp.UseMiddleware<GlobalExceptionHandlerMiddleware>();\nThis approach is solid and works everywhere in your pipeline.\nThe beauty is its simplicity: wrap everything in a try-catch, log the error, and return a consistent response.
\nBut once you start adding specific rules for different exception types (e.g. ValidationException, NotFoundException), this becomes a mess.\nYou end up with long if / else chains or more abstractions to handle each exception type.
Plus, you're manually crafting JSON responses, which means you're probably not following\nRFC 9457 (Problem Details) standards.
\nMicrosoft recognized this pain point and gave us IProblemDetailsService to standardize error responses.\nInstead of manually serializing our own error objects, we can use the built-in Problem Details format.
internal sealed class GlobalExceptionHandlerMiddleware(\n RequestDelegate next,\n IProblemDetailsService problemDetailsService,\n ILogger<GlobalExceptionHandlerMiddleware> logger)\n{\n public async Task InvokeAsync(HttpContext context)\n {\n try\n {\n await next(context);\n }\n catch (Exception ex)\n {\n logger.LogError(ex, "Unhandled exception occurred");\n\n // Make sure to set the status code before writing to the response body\n context.Response.StatusCode = ex switch\n {\n ApplicationException => StatusCodes.Status400BadRequest,\n _ => StatusCodes.Status500InternalServerError\n };\n\n await problemDetailsService.TryWriteAsync(new ProblemDetailsContext\n {\n HttpContext = context,\n Exception = ex,\n ProblemDetails = new ProblemDetails\n {\n Type = ex.GetType().Name,\n Title = "An error occured",\n Detail = ex.Message\n }\n });\n }\n }\n}\nThis is much cleaner.\nWe're now using a standard format that API consumers expect, and we're not manually fiddling with JSON serialization.\nBut we're still stuck with that growing switch statement problem.\nYou can learn more about using Problem Details in .NET here.
\nASP.NET Core 8 introduced IExceptionHandler, and it's a game-changer.\nInstead of one massive middleware handling everything, we can create focused handlers for specific exception types.
Here's how it works:
\ninternal sealed class GlobalExceptionHandler(\n IProblemDetailsService problemDetailsService,\n ILogger<GlobalExceptionHandler> logger) : IExceptionHandler\n{\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n logger.LogError(exception, "Unhandled exception occurred");\n\n httpContext.Response.StatusCode = exception switch\n {\n ApplicationException => StatusCodes.Status400BadRequest,\n _ => StatusCodes.Status500InternalServerError\n };\n\n return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext\n {\n HttpContext = httpContext,\n Exception = exception,\n ProblemDetails = new ProblemDetails\n {\n Type = exception.GetType().Name,\n Title = "An error occured",\n Detail = exception.Message\n }\n });\n }\n}\nThe key here is the return value.\nIf your handler can deal with the exception, return true.\nIf not, return false and let the next handler try.
Don't forget to register it with DI and the request pipeline:
\nbuilder.Services.AddExceptionHandler<GlobalExceptionHandler>();\nbuilder.Services.AddProblemDetails();\n\n// And in your pipeline\napp.UseExceptionHandler();\nThis approach is so much cleaner.\nEach handler has one job, and the code is easy to test and maintain.
\nYou can chain multiple exception handlers together, and they'll run in the order you register them.\nASP.NET Core will use the first one that returns true from TryHandleAsync.
Example: One for validation errors, one global fallback.
\nbuilder.Services.AddExceptionHandler<ValidationExceptionHandler>();\nbuilder.Services.AddExceptionHandler<GlobalExceptionHandler>();\nLet's say you're using FluentValidation (and you should be).\nHere's a complete setup:
\ninternal sealed class ValidationExceptionHandler(\n IProblemDetailsService problemDetailsService,\n ILogger<ValidationExceptionHandler> logger) : IExceptionHandler\n{\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n if (exception is not ValidationException validationException)\n {\n return false;\n }\n\n logger.LogError(exception, "Unhandled exception occurred");\n\n httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;\n var context = new ProblemDetailsContext\n {\n HttpContext = httpContext,\n Exception = exception,\n ProblemDetails = new ProblemDetails\n {\n Detail = "One or more validation errors occurred",\n Status = StatusCodes.Status400BadRequest\n }\n };\n\n var errors = validationException.Errors\n .GroupBy(e => e.PropertyName)\n .ToDictionary(\n g => g.Key.ToLowerInvariant(),\n g => g.Select(e => e.ErrorMessage).ToArray()\n );\n context.ProblemDetails.Extensions.Add("errors", errors);\n\n return await problemDetailsService.TryWriteAsync(context);\n }\n}\nAnd in your app, just throw like this:
\n// In your controller or service - IValidator<CreateUserRequest>\npublic async Task<IActionResult> CreateUser(CreateUserRequest request)\n{\n await _validator.ValidateAndThrowAsync(request);\n\n // Your business logic here\n}\nThe execution order is important.\nThe framework will try each handler in the order you registered them.\nSo put your most specific handlers first, and your catch-all handler last.
\nWe've come a long way from the days of manually crafting error responses in middleware.\nThe evolution looks like this:
\nFor new projects, I'd go straight to IExceptionHandler.\nIt's cleaner, more maintainable, and gives you the flexibility to handle different exception types exactly how you want.
The key takeaway?\nDon't let error handling be an afterthought.\nSet it up early, make it consistent, and your users (and your future self) will thank you when things inevitably go wrong.
\nThanks for reading.
\nAnd stay awesome!
\nAspire's Docker publisher, a preview package in mid 2025, turns the services you declare in C# into a docker-compose.yml and a matching .env file.\nYou call AddDockerComposeEnvironment in the AppHost, then run aspire publish to generate the artifacts.\nDeploying them to a VPS is still your job.
.NET Aspire is one of the most exciting additions to the .NET ecosystem in years.
\nIt brings a fresh, modern approach to building cloud-native apps, with a focus on developer productivity,\ngreat defaults, and tight integration across your entire stack.
\nOne of the most asked-for features is the ability to publish your app to Docker Compose.\nThis is now available in the latest preview, and I'm excited to share how it works.
\nIn this post, I'll walk you through how I used Aspire's Docker publisher to spin up a demo app that includes an API, a Postgres database, and a Redis cache.\nEverything runs using Docker Compose, and Aspire generates the whole thing from C# code.
\nI'll show you how to set it up, explain what it's doing behind the scenes,\nand give you a glimpse into how easy it is to take that setup and run it on a VPS or cloud server.
\nThe app is intentionally simple, just enough to demonstrate how Aspire wires things together.
\nIn a traditional setup, you'd manually connect these services, manage configuration files, handle environment variables,\nand write a docker-compose.yml from scratch.
With Aspire, you declare everything in C# inside the AppHost project.\nHere's a quick look at the setup:
\nvar builder = DistributedApplication.CreateBuilder(args);\n\n// Enables Docker publisher\nbuilder.AddDockerComposeEnvironment("aspire-docker-demo");\n\nvar postgres = builder.AddPostgres("database")\n .WithDataVolume();\n\nvar database = postgres.AddDatabase("demo-db");\n\nvar redis = builder.AddRedis("cache");\n\nvar webApi = builder.AddProject<Projects.Web_Api>("web-api")\n .WithReference(database).WaitFor(postgres)\n .WithReference(redis).WaitFor(redis);\n\nbuilder.Build().Run();\nThis gives you a development environment where Aspire runs Postgres and Redis in containers, and connects your API to them.
\nThe AddDockerComposeEnvironment method enables the Docker publisher.\nIt's available in the Aspire.Hosting.Docker NuGet package, which is currently in preview.
Install-Package Aspire.Hosting.Docker -Version 9.3.1-preview.1.25305.6\nTo publish your app to Docker Compose, install the Aspire CLI:
\ndotnet tool install --global aspire.cli --prerelease\nThen you can run the publish command:
aspire publish -o docker-compose-artifacts\nThis command will scan your solution for the Aspire project and generate a Docker Compose file and an .env file\nbased on the services you've defined.
![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_149/aspire_publish.png\")
\nLet's examine what Aspire created for us:
\nservices:\n database:\n image: 'docker.io/library/postgres:17.4'\n environment:\n POSTGRES_HOST_AUTH_METHOD: 'scram-sha-256'\n POSTGRES_INITDB_ARGS: '--auth-host=scram-sha-256 --auth-local=scram-sha-256'\n POSTGRES_USER: 'postgres'\n POSTGRES_PASSWORD: '${DATABASE_PASSWORD}'\n ports:\n - '8000:5432'\n volumes:\n - type: 'volume'\n target: '/var/lib/postgresql/data'\n source: 'aspire.apphost-1f0ed76b33-database-data'\n read_only: false\n networks:\n - 'aspire'\n redis:\n image: 'docker.io/library/redis:7.4'\n command:\n - '-c'\n - 'redis-server --requirepass $$REDIS_PASSWORD'\n entrypoint:\n - '/bin/sh'\n environment:\n REDIS_PASSWORD: '${REDIS_PASSWORD}'\n ports:\n - '8001:6379'\n networks:\n - 'aspire'\n web-api:\n image: '${WEB_API_IMAGE}'\n environment:\n OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: 'true'\n OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: 'true'\n OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: 'in_memory'\n ASPNETCORE_FORWARDEDHEADERS_ENABLED: 'true'\n HTTP_PORTS: '8002'\n ConnectionStrings__demo-db: 'Host=database;Port=5432;Username=postgres;Password=${DATABASE_PASSWORD};Database=demo-db'\n ConnectionStrings__redis: 'redis:6379,password=${REDIS_PASSWORD}'\n ports:\n - '8003:8002'\n - '8005:8004'\n depends_on:\n database:\n condition: 'service_started'\n redis:\n condition: 'service_started'\n networks:\n - 'aspire'\nnetworks:\n aspire:\n driver: 'bridge'\nvolumes:\n aspire.apphost-1f0ed76b33-database-data:\n driver: 'local'\nThis docker-compose file is generated from the C# code we wrote earlier.\nIt defines the services, their images, environment variables, ports, and dependencies.
The .env file contains some of the configuration we need:
# Parameter database-password\nDATABASE_PASSWORD=<YOUR_STRONG_PASSWORD>\n\n# Container image name for web-api\n# Change this to the imaage name in the container registry\nWEB_API_IMAGE=web-api:latest\n\n# Parameter redis-password\nREDIS_PASSWORD=<YOUR_STRONG_PASSWORD>\nIt contains the passwords for the database and Redis, as well as the image name for the API.\nYou'll need to replace the placeholders with actual values.\nFor the API image, you can build and tag the image yourself, or use a pre-built one from a registry.
\nAspire doesn't deploy the app for you, but it gives you everything you need.
\nOnce the Compose file is ready, deployment to a VPS is straightforward:
\nscp or git).docker compose up -d inside the artifact directory.Make sure Docker and Docker Compose are installed on the server.
\nYou can expose ports with a reverse proxy like Nginx or Caddy, and secure it with HTTPS using Let's Encrypt.
\nI'll cover this in more detail in a future post.
\n.NET Aspire with Docker Compose provides a smooth developer experience and a simple way to deploy full-stack apps.
\nYou define everything in C#, test it locally, and publish it with one command.\nNo need to write Compose files or manage infrastructure manually.\nThis opens up new possibilities for deploying and managing cloud-native apps.\nYou're not locked into a specific cloud provider, and you can easily move between environments.
\nCan I just say how much I love this?\nI'm really excited about the future of cloud-native development with .NET and Aspire.
\nIf you liked this article and want to learn how I structure larger apps, check out Modular Monolith Architecture.\nIt walks you through building clean, scalable .NET applications with strong internal boundaries and maintainability in mind.
\nThanks for reading and stay awesome!
\nTestcontainers runs real Postgres and Redis containers for your integration tests instead of mocks or in-memory fakes.\nKeep them reliable by starting and stopping containers from IAsyncLifetime on your WebApplicationFactory, passing connection strings through UseSetting because the ports are dynamic, and pinning image tags like postgres:17.
Integration tests with Testcontainers are powerful, but they can quickly become a maintenance nightmare if you don't follow the right patterns.
\nI've seen teams struggle with flaky tests, slow test suites, and configuration headaches that could have been avoided with better practices from the start.
\nToday, I'll show you the patterns that make Testcontainers tests reliable, fast, and easy to maintain.
\nTraditional integration tests often rely on shared test databases or in-memory alternatives that don't match production behavior.\nYou either deal with test pollution between runs or sacrifice realism for speed.
\nTestcontainers solves this by spinning up real Docker containers for your dependencies.\nYour tests run against actual PostgreSQL, Redis, or any other service you use in production.\nWhen tests complete, containers are destroyed, giving you a clean slate every time.
\nThe magic happens through Docker's API.\nTestcontainers manages the entire lifecycle: pulling images, starting containers, waiting for readiness, and cleanup.\nYour test code just needs to know how to connect.
\nFirst, make sure you have the necessary packages:
\nInstall-Package Microsoft.AspNetCore.Mvc.Testing\nInstall-Package Testcontainers.PostgreSql\nInstall-Package Testcontainers.Redis\nIf you want to learn more about the basic setup, check out my article on\nintegrating testing with Testcontainers.
\nHere's how to set up your containers with proper configuration:
\nPostgreSqlContainer _postgresContainer = new PostgreSqlBuilder()\n .WithImage("postgres:17")\n .WithDatabase("devhabit")\n .WithUsername("postgres")\n .WithPassword("postgres")\n .Build();\n\nRedisContainer _redisContainer = new RedisBuilder()\n .WithImage("redis:latest")\n .Build();\nTo start and stop containers cleanly across your test suite, implement IAsyncLifetime in your WebApplicationFactory:
public sealed class IntegrationTestWebAppFactory : WebApplicationFactory<Program>, IAsyncLifetime\n{\n public async Task InitializeAsync()\n {\n await _postgresContainer.StartAsync();\n await _redisContainer.StartAsync();\n // Start other dependencies here\n }\n\n public async Task DisposeAsync()\n {\n await _postgresContainer.StopAsync();\n await _redisContainer.StopAsync();\n }\n}\nThis ensures containers are ready before tests run and cleaned up afterward.\nThis means no leftover Docker state or race conditions.
\nA tip: pin your image versions (like postgres:17) to avoid surprises from upstream changes
I learned this the hard way when a minor version update caused my tests to fail unexpectedly.
\nThe biggest mistake I see is hardcoding connection strings.\nTestcontainers assigns dynamic ports.\nDon't hardcode anything.
\nInstead, inject values via WebApplicationFactory.ConfigureWebHost:
protected override void ConfigureWebHost(IWebHostBuilder builder)\n{\n builder.UseSetting("ConnectionStrings:Database", _postgresContainer.GetConnectionString());\n builder.UseSetting("ConnectionStrings:Redis", _redisContainer.GetConnectionString());\n}\nThe key is to use the UseSetting method to pass connection strings dynamically.\nIt also avoids any race conditions or conflicts with other tests that might run in parallel.
This ensures your tests always connect to the right ports, regardless of what Docker assigns.
\nThere's no need to remove services from the service collection or manually configure them (contrary to what you might find online).\nJust set the connection strings, and your application will use them automatically.
\nWhat's a test fixture?\nA fixture is a shared context for your tests, allowing you to set up expensive resources like databases or message brokers once and reuse them across multiple tests.
\nThis is where most teams get tripped up.\nThe choice between class and collection fixtures affects both test performance and isolation.
\nClass Fixture - One container per test class:
\nUse class fixtures when tests modify global state or when debugging test interactions becomes difficult.
\npublic class AddItemToCartTests : IClassFixture<DevHabitWebAppFactory>\n{\n private readonly DevHabitWebAppFactory _factory;\n\n public AddItemToCartTests(DevHabitWebAppFactory factory)\n {\n _factory = factory;\n }\n\n [Fact]\n public async Task Should_ReturnFailure_WhenNotEnoughQuantity() { ... }\n}\nCollection Fixture - One container shared across multiple test classes:
\nUse collection fixtures when your tests don't modify shared state or when you can reliably clean up between tests.
\n[CollectionDefinition(nameof(IntegrationTestCollection))]\npublic sealed class IntegrationTestCollection : ICollectionFixture<DevHabitWebAppFactory>\n{\n}\nThen apply it to your test classes:
\n[Collection(nameof(IntegrationTestCollection))]\npublic class AddItemToCartTests : IntegrationTestFixture\n{\n public AddItemToCartTests(DevHabitWebAppFactory factory) : base(factory) { }\n\n [Fact]\n public async Task Should_ReturnFailure_WhenNotEnoughQuantity()\n {\n Guid customerId = await Sender.CreateCustomerAsync(Guid.NewGuid());\n var command = new AddItemToCartCommand(customerId, ticketTypeId, Quantity + 1);\n\n Result result = await Sender.Send(command);\n\n result.Error.Should().Be(TicketTypeErrors.NotEnoughQuantity(Quantity));\n }\n}\nWhen to use which:
\nWith collection fixtures, you have to take care of cleaning up any state that might persist between tests.\nThis could include resetting databases, clearing caches, or removing test data.\nIf you don't do this, you risk tests affecting each other, leading to flaky results.
\nYour fixture can expose helpers to simplify test writing:
\npublic async Task<HttpClient> CreateAuthenticatedClientAsync() { ... }\n\nprotected async Task CleanupDatabaseAsync() { ... }\nThese methods can handle authentication setup and database cleanup, so you don't have to repeat boilerplate code in every test.\nThis lets your test code focus on assertions, not setup.
\nWith the infrastructure properly configured, your actual tests should focus on business logic:
\n[Fact]\npublic async Task Should_ReturnFailure_WhenNotEnoughQuantity()\n{\n //Arrange\n Guid customerId = await Sender.CreateCustomerAsync(Guid.NewGuid());\n var eventId = Guid.NewGuid();\n var ticketTypeId = Guid.NewGuid();\n\n await Sender.CreateEventWithTicketTypeAsync(eventId, ticketTypeId, Quantity);\n\n var command = new AddItemToCartCommand(customerId, ticketTypeId, Quantity + 1);\n\n //Act\n Result result = await Sender.Send(command);\n\n //Assert\n result.Error.Should().Be(TicketTypeErrors.NotEnoughQuantity(Quantity));\n}\nNotice how the tests focus on business rules rather than infrastructure concerns.\nThe container complexity is hidden behind well-designed base classes and helper methods.\nYou're not mocking Postgres or Redis, you're testing real behavior.
\nTestcontainers transforms integration testing by giving you the confidence that comes from testing against real dependencies.\nNo more wondering if your in-memory database behavior matches production, or dealing with shared test environments that break when someone else runs their tests.
\nStart simple: pick one integration test that currently uses mocks or in-memory databases, and convert it to use Testcontainers.\nYou'll immediately notice the difference in confidence when that test passes.\nThen gradually expand to cover your critical business flows.
\nIf you want to learn how to structure your applications for testability from day one,\nmy Pragmatic Clean Architecture course covers integration testing with Testcontainers alongside domain modeling,\nAPI design, and the architectural decisions that make applications maintainable over time.
\nThat's all for today.
\nSee you next week.
\nTo monitor a .NET application with OpenTelemetry and Grafana, install the OpenTelemetry hosting and instrumentation packages, call AddOpenTelemetry() in Program.cs, and point the OTLP exporter at your Grafana Cloud stack with three settings: endpoint, protocol, and an authorization header.\nTraces and logs then show up in Grafana, with automatic correlation between them.
Your .NET application is running in production, but you're flying blind.
\nWhen something breaks, you're stuck digging through logs, guessing at performance bottlenecks,\nand trying to piece together what actually happened across your distributed system.
\nThat ends today.
\nGrafana is a complete observability platform that unifies metrics, logs, and traces in one place.
\nWith Grafana, you get:
\nGrafana Cloud makes this even easier.\nNo infrastructure to manage, automatic scaling, and built-in integrations with OpenTelemetry.\nThere's a generous free tier that allows you to get started without any upfront costs.
\nWhen you combine Grafana with OpenTelemetry, you get vendor-neutral observability that actually delivers insights instead of just pretty charts.
\nFirst, install the core OpenTelemetry packages:
\nInstall-Package OpenTelemetry.Extensions.Hosting\nInstall-Package OpenTelemetry.Exporter.OpenTelemetryProtocol\nInstall-Package OpenTelemetry.Instrumentation.AspNetCore\nInstall-Package OpenTelemetry.Instrumentation.Http\nYou can also add instrumentation for other libraries as needed:
\nInstall-Package OpenTelemetry.Instrumentation.EntityFrameworkCore\nInstall-Package OpenTelemetry.Instrumentation.StackExchangeRedis\nInstall-Package Npgsql.OpenTelemetry\nConfigure OpenTelemetry in your Program.cs:
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services\n .AddOpenTelemetry()\n .ConfigureResource(resource => resource.AddService(serviceName))\n .WithTracing(tracing =>\n {\n tracing\n .AddAspNetCoreInstrumentation()\n .AddHttpClientInstrumentation()\n .AddEntityFrameworkCoreInstrumentation()\n .AddRedisInstrumentation()\n .AddNpgsql();\n\n tracing.AddOtlpExporter();\n });\n\nbuilder.Logging.AddOpenTelemetry(logging =>\n{\n logging.IncludeScopes = true;\n logging.IncludeFormattedMessage = true;\n\n logging.AddOtlpExporter();\n});\n\nvar app = builder.Build();\n\n// Your app configuration...\n\napp.Run();\nThis configuration:
\nGet your Grafana Cloud credentials:
\nLog into Grafana Cloud
\nGo to My Account → Stack Details
\n![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_setup.png\")
\nhttps://otlp-gateway-prod-eu-west-2.grafana.net/otlp)![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_setup_endpoint.png\")
\n![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_setup_token.png\")
\nYou should also see the environment variables you can use to configure OpenTelemetry:
\n![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_setup_env_vars.png\")
\nConfigure the OTLP exporter in your appsettings.json:
{\n "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp",\n "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",\n "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Basic <your-base64-encoded-token>"\n}\nYou can also set these as environment variables in your hosting environment.
\nStart your application and generate some traffic.\nNow head to your Grafana Cloud instance.
\nTraces
\nIf everything is set up correctly, you should see traces from your application in the Traces section.
\nHere's an example of a trace view in Grafana Cloud.\nIt's a POST users/register request that contains multiple spans:
![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_trace_1.png\")
\nHere's another example of a trace that includes messages sent to a message broker (like RabbitMQ or Kafka).
\n![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_trace_2.png\")
\nLogs
\nYou can also view logs in Grafana Cloud.
\nHere's an example of a log view that shows multiple log entries for our application.
\n![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_logs_1.png\")
\nYou can drill down into individual log entries, filter by severity, and search for specific terms.
\n![\"Grafana](\"https://milanjovanovic.tech/blogs/mnw_147/grafana_logs_2.png\")
\nOpenTelemetry automatically correlates your logs with traces.\nIn the trace detail view, click Logs to see all log entries that occurred during that request.
\nYour logs will include trace and span IDs.
\nYou now have full observability for your .NET application.
\nWhen something goes wrong in production, you won't be guessing anymore.\nYou'll see exactly which requests were slow, what errors occurred, and how they propagated through your system.
\nGrafana gives you the dashboards and alerting to catch problems before users do.\nOpenTelemetry gives you the detailed traces to understand exactly what happened.
\nThis setup scales from a single service to hundreds of microservices without changing your instrumentation code.\nAnd when your apps outgrow a single machine, the collector setup evolves too; I wrote about that next step in the agent + gateway collector pattern.
\nReady to take your observability further?
\nThis article showed you the basics, but modern applications need advanced patterns like distributed tracing across event-driven architectures,\ncustom instrumentation strategies, and observability-driven development practices.
\nI cover all of this in-depth in my Modular Monolith Architecture course,\nwhere you'll learn how to implement OpenTelemetry across complex, event-driven systems that actually scale in production.
\nThat's all for today.
\nSee you next Saturday.
\n.NET 10 (starting with Preview 4) lets you run a single C# file directly with dotnet run app.cs, no project file or Main method required.\nFile-level directives like #:package pull in NuGet packages, and dotnet project convert turns the script into a full project when it outgrows a single file.
.NET 10 just got a whole lot more lightweight.
\nYou can now run a C# file directly with:
\ndotnet run app.cs\nThat's it.\nNo .csproj.\nNo Program.cs.\nNo solution files.\nJust a single C# file.
This new feature, introduced in .NET 10 Preview 4,\nis a big step toward making C# more script-friendly, especially for quick utilities, dev tooling, and CLI-based workflows.
\nFor years, C# has been perceived as heavyweight for small scripts.\nCompare that to Python, Bash, or even JavaScript, where you can just write a file and run it.
\nThat barrier is now gone.
\nYou can now:
\n.cs filesAnd it runs on any OS with the .NET SDK installed.
\nHere's a simple script that prints today's date:
\nConsole.WriteLine($"Today is {DateTime.Now:dddd, MMM dd yyyy}");\nRun it:
\ndotnet run app.cs\nOutput:
\nToday is Saturday, Jun 14 2025\nThat's it.\nNo boilerplate, no boring Main() method.\nJust top-level programs and C# code.
Let's say you want to make an HTTP request using Flurl.Http.
You can do this inline:
\n#:package Flurl.Http@4.0.2\n\nusing Flurl.Http;\n\nvar response = await "https://api.github.com"\n .WithHeader("Accept", "application/vnd.github.v3+json")\n .WithHeader("User-Agent", "dotnet-script")\n .GetAsync();\n\nConsole.WriteLine($"Status code: {response.StatusCode}");\n\nConsole.WriteLine(await response.GetJsonAsync<object>());\nTo run it:
\ndotnet run fetch.cs\nBehind the scenes, the compiler downloads and restores NuGet dependencies automatically.
\nHere's a script I recently used to seed some test data into my Postgres database.
\n#:package Dapper@2.1.66\n#:package Npgsql@9.0.3\n\nusing Dapper;\nusing Npgsql;\n\nconst string connectionString = "Host=localhost;Port=5432;Username=postgres;Password=postgres";\n\nusing var connection = new NpgsqlConnection(connectionString);\nawait connection.OpenAsync();\n\nusing var transaction = connection.BeginTransaction();\n\nConsole.WriteLine("Creating tables...");\n\nawait connection.ExecuteAsync(@"\n CREATE TABLE IF NOT EXISTS users (\n id SERIAL PRIMARY KEY,\n name TEXT NOT NULL\n );\n");\n\nConsole.WriteLine("Inserting users...");\n\nfor (int i = 1; i <= 10_000; i++)\n{\n await connection.ExecuteAsync(\n "INSERT INTO users (name) VALUES (@Name);",\n new { Name = $"User {i}" });\n\n if (i % 1000 == 0)\n {\n Console.WriteLine($"Inserted {i} users...");\n }\n}\n\ntransaction.Commit();\n\nConsole.WriteLine("Done!");\nWhy did I write this as a script?\nI didn't want to clutter my app with throwaway seed logic.\nI just needed a quick way to populate my database with test data.\nThis script does exactly that, and I can run it with:
\ndotnet run seed.cs\nThe real power comes from file-level directives.\nThese let you configure your app without leaving the .cs file:
\nPackage References
\n#:package Dapper@2.1.66\n#:package Npgsql@9.0.3\nSDK Selection
\n#:sdk Microsoft.NET.Sdk.Web\nThis tells .NET to treat your file as a web application, enabling ASP.NET Core features:
\n#:sdk Microsoft.NET.Sdk.Web\n#:package Microsoft.AspNetCore.OpenApi@9.*\n\nvar builder = WebApplication.CreateBuilder();\n\nbuilder.Services.AddOpenApi();\n\nvar app = builder.Build();\n\napp.MapOpenApi();\n\napp.MapGet("/", () => "Hello from a file-based API!");\napp.MapGet("/users/{id}", (int id) => new { Id = id, Name = $"User {id}" });\n\napp.Run();\nYou now have a running web API.\nNo project file.\nNo Startup.cs.\nJust C# that does what you want.
MSBuild Properties
\nYou can also set MSBuild properties directly in the file:
\n#:property LangVersion preview\n#:property Nullable enable\nThe brilliant part? When your file-based app gets complex enough to need project structure, converting is seamless:
\ndotnet project convert api.cs\nThis creates:
\n.csproj file with all your directives converted to MSBuild propertiesapi.cs (or Program.cs if you prefer)Given our API example above, the generated .csproj looks like:
<Project Sdk="Microsoft.NET.Sdk.Web">\n <PropertyGroup>\n <TargetFramework>net10.0</TargetFramework>\n <ImplicitUsings>enable</ImplicitUsings>\n <Nullable>enable</Nullable>\n </PropertyGroup>\n\n <ItemGroup>\n <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />\n </ItemGroup>\n</Project>\nYour file-based app evolves naturally into a project-based app.\nNo need to rewrite or restructure everything.\nThis makes it easy to start small and grow as needed, without losing the simplicity of the initial script.
\nThe bottom line is this: C# just became significantly more approachable.\nThe barrier to entry dropped from "learn project files and MSBuild" to "write C# and run it."
\nFor experienced developers, this is a productivity boost for scripting and prototyping.\nFor newcomers, this removes the biggest stumbling block to getting started with C#.
\nThe best part?\nMicrosoft didn't create a separate scripting language or runtime.\nThey made regular C# easier to use.\nYour file-based apps are real .NET applications that can grow into full projects when needed.
\nThe ceremony is dead. Long live practical C#.
\nNo, filtering in a subquery before a JOIN does not make your SQL faster on a modern database.\nI tested both versions on PostgreSQL with 10,000 users and 5 million orders, and they produced identical execution plans, each running in about 685ms.\nThe cost-based optimizer rewrites both queries into the same plan, regardless of how you write them.
\nI came across a Medium article with 700+ claps promoting this "SQL performance trick":
\n"Filter Early, JOIN Later"
\n![\"SQL](\"https://milanjovanovic.tech/blogs/mnw_145/sql_performance_tip.png\")
\n The claim goes like this: instead of joining tables first and then filtering, you should filter in a subquery first, then join.
\nThe supposed benefit?
\n\n\nThe database filtered the smaller table first, then did the JOIN — saving time and memory.
\n
Here is the thing - this advice is completely wrong for modern databases.
\nLet me show you why with actual data.
\nThe article shows two queries. Here is the "bad" version:
\nSELECT *\nFROM users u\nJOIN orders o ON u.id = o.user_id\nWHERE o.total > 500;\nAnd the "optimized" version:
\nSELECT *\nFROM (\n SELECT * FROM orders WHERE total > 500\n) o\nJOIN users u ON u.id = o.user_id;\nThe claim is that the second query is faster because it "filters first, then joins."
\nSounds logical, right?\nWrong.
\nI tested both queries on a PostgreSQL database with:
\nLet me run EXPLAIN ANALYZE on both queries to see what actually happens.
\nHere are the execution plans for both queries:
\n"Bad" Query Execution Plan:
\nHash Join (cost=280.00..96321.92 rows=2480444 width=27) (actual time=1.014..641.202 rows=2499245 loops=1)\n Hash Cond: (o.user_id = u.id)\n -> Seq Scan on orders o (cost=0.00..89528.00 rows=2480444 width=14) (actual time=0.006..368.857 rows=2499245 loops=1)\n Filter: (total > '500'::numeric)\n Rows Removed by Filter: 2500755\n -> Hash (cost=155.00..155.00 rows=10000 width=13) (actual time=0.998..0.999 rows=10000 loops=1)\n Buckets: 16384 Batches: 1 Memory Usage: 577kB\n -> Seq Scan on users u (cost=0.00..155.00 rows=10000 width=13) (actual time=0.002..0.341 rows=10000 loops=1)\nPlanning Time: 0.121 ms\nExecution Time: 685.818 ms\n"Optimized" Query Execution Plan:
\nHash Join (cost=280.00..96321.92 rows=2480444 width=27) (actual time=1.019..640.613 rows=2499245 loops=1)\n Hash Cond: (orders.user_id = u.id)\n -> Seq Scan on orders (cost=0.00..89528.00 rows=2480444 width=14) (actual time=0.005..368.260 rows=2499245 loops=1)\n Filter: (total > '500'::numeric)\n Rows Removed by Filter: 2500755\n -> Hash (cost=155.00..155.00 rows=10000 width=13) (actual time=1.004..1.005 rows=10000 loops=1)\n Buckets: 16384 Batches: 1 Memory Usage: 577kB\n -> Seq Scan on users u (cost=0.00..155.00 rows=10000 width=13) (actual time=0.003..0.348 rows=10000 loops=1)\nPlanning Time: 0.118 ms\nExecution Time: 685.275 ms\nThe execution plans are identical.
\nBoth queries took ~685ms.\nThe "optimization" did absolutely nothing.
\nHere's the simplified execution plan, where I removed some details:
\nHash Join\n Hash Cond: (o.user_id = u.id)\n -> Seq Scan on orders o\n Filter: (total > '500'::numeric)\n Rows Removed by Filter\n -> Hash\n -> Seq Scan on users u\nThe core operations are:
\norders table with filter appliedusers tableusersuser_idModern databases use cost-based optimizers.\nHere is what happens when you run a query:
\nThe optimizer looks at your query and says:\n"I don't care how you wrote this. I will figure out the best way to execute it."
\nBoth of our queries get rewritten to the same optimal plan:
\nThe optimizer already does the "optimization" automatically.
\nYour manual subquery does not make it faster - it just makes your SQL harder to read.
\nThe query optimizer has statistics about your tables:
\nIt uses these stats to estimate the cost of different execution strategies:
\nThen it picks the cheapest plan.\nYour well-intentioned manual "optimization" gets ignored because the optimizer knows better.
\nThe "Filter Early, JOIN Later" advice is a relic from ancient database systems that did not have sophisticated optimizers.
\nModern databases like PostgreSQL, MySQL, and SQL Server already do predicate pushdown and join reordering automatically.\nYour manual "optimizations" are pointless and make code harder to maintain.
\nWrite clear, readable SQL.\nLet the optimizer do its job.
\nThe real lesson?\nStop believing every performance tip you read online.\nUse EXPLAIN ANALYZE to understand what your database is actually doing.
Tuned properly, Nginx edges out YARP on raw throughput: about 46k versus 36k requests per second at 200 virtual users in my tests.\nAgainst Nginx's default configuration, YARP handled almost 3.6x more requests.\nYARP still wins on .NET integration, so pick based on whether throughput or developer experience matters more to your team.
\nWhen you're building .NET applications, choosing the right reverse proxy can make a huge difference.\nTwo popular options keep coming up: Microsoft's YARP (Yet Another Reverse Proxy)\nand the tried-and-true Nginx.
\nHere's the thing - everyone talks about which one is "better," but rarely do you see actual numbers.\nSo I decided to put both through the same tests and see what happens.
\nI'll test both proxies using the exact same API, same hardware, and same load testing approach.\nNo bias, just data.
\nI kept the test API super simple on purpose.\nThis way, we're measuring proxy performance, not how fast the backend can process complex requests:
\nvar builder = WebApplication.CreateBuilder(args);\nvar app = builder.Build();\n\napp.MapGet("/hello", () =>\n{\n return Results.Ok("Hello world!");\n});\n\napp.Run();\nThis basic endpoint means we're testing the proxy itself, not waiting for complex business logic to run.
\nYARP is pretty nice to work with if you're already in the .NET world. The setup is straightforward:
\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services\n .AddReverseProxy()\n .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));\n\nvar app = builder.Build();\napp.MapReverseProxy();\napp.Run();\nIt's equally simple to configure load balancing\nor authentication.
\nThe routing setup is clean and uses a **catch-all pattern to forward everything:
{\n "ReverseProxy": {\n "Routes": {\n "default": {\n "ClusterId": "hello",\n "Match": { "Path": "{**catch-all}" }\n }\n },\n "Clusters": {\n "hello": {\n "Destinations": {\n "destination1": {\n "Address": "http://hello.api:8080"\n }\n }\n }\n }\n }\n}\nFor Nginx, I went with Docker to keep things simple.\nThe configuration does the same job as YARP:
\nnginx.proxy:\n image: nginx:alpine\n ports:\n - '3001:80'\n volumes:\n - ./nginx-proxy.conf:/etc/nginx/nginx.conf:ro\n depends_on:\n - hello.api\nThe Nginx config does exactly what YARP does - just with different syntax:
\nevents {}\n\nhttp {\n upstream backend {\n server hello.api:8080;\n }\n\n server {\n listen 80;\n location / {\n proxy_pass http://backend;\n }\n }\n}\nHere's the complete docker-compose.yml that ties everything together:
services:\n hello.api:\n image: ${DOCKER_REGISTRY-}helloapi\n build:\n context: .\n dockerfile: Hello.Api/Dockerfile\n\n yarp.proxy:\n image: ${DOCKER_REGISTRY-}yarpproxy\n build:\n context: .\n dockerfile: Yarp.Proxy/Dockerfile\n ports:\n - 3000:8080\n depends_on:\n - hello.api\n\n nginx.proxy:\n image: nginx:alpine\n ports:\n - '3001:80'\n volumes:\n - ./nginx-proxy.conf:/etc/nginx/nginx.conf:ro\n depends_on:\n - hello.api\nI used k6 to hit both proxies with the same load patterns.\nI repeated the test with different numbers of virtual users (VUs) to see how each proxy handles increasing traffic.\nThis keeps things fair - same test, same conditions:
\nYARP Test Script:
\nimport http from 'k6/http';\nimport { check } from 'k6';\n\nexport let options = {\n scenarios: {\n yarp: {\n executor: 'per-vu-iterations',\n vus: 200, // 10, 50, 100, 200\n iterations: 1000,\n exec: 'testYarp',\n startTime: '0s'\n }\n }\n};\n\nexport function testYarp() {\n let res = http.get('http://localhost:3000/hello');\n check(res, {\n 'YARP: status 200': (r) => r.status === 200\n });\n}\nNginx Test Script:
\nimport http from 'k6/http';\nimport { check } from 'k6';\n\nexport let options = {\n scenarios: {\n nginx: {\n executor: 'per-vu-iterations',\n vus: 200, // 10, 50, 100, 200\n iterations: 1000,\n exec: 'testNginx',\n startTime: '0s'\n }\n }\n};\n\nexport function testNginx() {\n let res = http.get('http://localhost:3001/hello');\n check(res, {\n 'NGINX: status 200': (r) => r.status === 200\n });\n}\nHere's where things get interesting.\nThe numbers show a clear pattern:
\n| VUs | YARP RPS | NGINX RPS | YARP p90 Latency (ms) | NGINX p90 Latency (ms) | YARP p95 Latency (ms) | NGINX p95 Latency (ms) |\n|------|----------|-----------|-----------------------|------------------------|-----------------------|------------------------|\n| 10 | 12692 | 9756 | 1.04 | 1.10 | 1.06 | 1.52 |\n| 50 | 27080 | 10614 | 2.70 | 5.23 | 3.18 | 5.68 |\n| 100 | 32432 | 10324 | 4.66 | 10.61 | 5.43 | 10.96 |\n| 200 | 36662 | 10169 | 7.77 | 21.23 | 8.81 | 21.92 |\nRequest per second (RPS) is how many requests each proxy handled per second.
\n![\"YARP](\"https://milanjovanovic.tech/blogs/mnw_144/rps_comparison.png\")
\np90 latency is the time it took for 90% of requests to complete.
\n![\"YARP](\"https://milanjovanovic.tech/blogs/mnw_144/p90_comparison.png\")
\np95 latency is the time it took for 95% of requests to complete.
\n![\"YARP](\"https://milanjovanovic.tech/blogs/mnw_144/p95_comparison.png\")
\nYARP really shines here.\nIt handles way more requests - almost 3.6x more at 200 users.\nWhat's cool is how it scales up as you add more load.\nNginx stays pretty much flat around 10k requests per second, but YARP keeps climbing from 12k all the way to 36k.
\nThe latency story is even more impressive for YARP.\nAt 200 users, YARP keeps response times under 8ms while Nginx hits 21ms.\nThat's a big difference when you're trying to keep your app fast.
\nLooking at these results, we're missing something important: this comparison isn't fair to Nginx.
\nThe default Nginx configuration I used is fine for basic setups, but it's not optimized for high-throughput scenarios.\nNginx uses conservative defaults that work everywhere but don't push performance limits.
\nSo let me fix the Nginx configuration and re-run the tests.
\nHere's the updated Nginx config with some tweaks to improve performance:
\nworker_processes auto;\n\nevents {\n worker_connections 65536;\n multi_accept on;\n use epoll;\n}\n\nhttp {\n sendfile on;\n tcp_nopush on;\n tcp_nodelay on;\n keepalive_timeout 30;\n keepalive_requests 1000;\n types_hash_max_size 4096;\n\n upstream backend {\n server hello.api:8080;\n keepalive 512;\n }\n\n server {\n listen 80;\n\n location / {\n proxy_pass http://backend;\n proxy_http_version 1.1;\n proxy_set_header Connection "";\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n }\n}\nHere are the results after re-running the tests:
\n| VUs | YARP RPS | NGINX RPS | YARP p90 Latency (ms) | NGINX p90 Latency (ms) | YARP p95 Latency (ms) | NGINX p95 Latency (ms) |\n|------|----------|-----------|-----------------------|------------------------|-----------------------|------------------------|\n| 10 | 12692 | 17572 | 1.04 | 0.58 | 1.06 | 0.74 |\n| 50 | 27080 | 36687 | 2.70 | 1.81 | 3.18 | 2.09 |\n| 100 | 32432 | 43289 | 4.66 | 3.18 | 5.43 | 3.88 |\n| 200 | 36662 | 46850 | 7.77 | 6.34 | 8.81 | 7.72 |\n![\"YARP](\"https://milanjovanovic.tech/blogs/mnw_144/rps_comparison_tuned.png\")
\n![\"YARP](\"https://milanjovanovic.tech/blogs/mnw_144/p90_comparison_tuned.png\")
\n![\"YARP](\"https://milanjovanovic.tech/blogs/mnw_144/p95_comparison_tuned.png\")
\nNow this is more interesting.\nNginx actually edges out YARP in raw throughput - hitting 46k requests per second vs YARP's 36k at 200 users.\nBoth proxies scale well as load increases, but Nginx shows why it's been the go-to choice for high-traffic sites.
\nThe latency story is pretty close.\nAt lower loads, Nginx actually has better response times.\nAt 200 users, both proxies keep response times reasonable - YARP at 7.77ms and Nginx at 6.34ms for p90 latency.\nThe difference isn't huge either way.
\nConfiguration matters more than you think.\nThe initial results showed YARP crushing Nginx, but that was with Nginx's conservative defaults.\nOnce properly tuned, Nginx shows why it's been powering the internet for years.
\nNginx wins on raw performance.\nWith proper configuration, Nginx handles more requests and keeps latency slightly lower.\nThat extra throughput matters when you're dealing with serious traffic.
\nYARP offers better integration.\nEven though Nginx edges out performance, YARP feels natural in .NET projects.\nSame configuration style, same patterns, same tooling.\nSometimes that developer experience is worth more than a few extra requests per second.
\nAlways tune your tools.\nThis whole exercise shows why benchmarks with default configs can be misleading.\nIf you're choosing between these two, make sure you're comparing optimized configurations, not defaults.
\nThe choice isn't as clear-cut as I initially thought.\nNginx wins on pure performance, but YARP wins on .NET integration.\nPick based on what matters more for your specific situation.
\nDomain events let one part of your system publish an event and other parts subscribe to it, instead of calling email or analytics services directly.\nYou can build an in-process dispatcher in .NET with two small interfaces, DI registration, and a strongly typed handler wrapper, no third-party libraries required.
\nDomain events are a powerful way to decouple parts of your system.\nInstead of tightly coupling your logic, you can publish events and have other parts of your code subscribe to those events.\nThis pattern is especially valuable in Domain-Driven Design (DDD)\nwhere business logic should remain focused and cohesive.
\nIn this article, we'll walk through how to implement a lightweight, custom domain event dispatcher in .NET.\nThe core dispatching logic should not depend on third-party libraries.
\nWe'll cover:
\nLet's get started.
\nBefore diving into implementation, let's understand the problem domain events solve.\nConsider this tightly coupled code:
\npublic class UserService\n{\n public async Task RegisterUser(string email, string password)\n {\n var user = new User(email, password);\n await _userRepository.SaveAsync(user);\n\n // Directly coupled to email service\n await _emailService.SendWelcomeEmail(user.Email);\n\n // Directly coupled to analytics\n await _analyticsService.TrackUserRegistration(user.Id);\n\n // What if we need to add more features?\n // This method will keep growing...\n }\n}\nWith domain events, we can decouple this:
\npublic class UserService\n{\n public async Task RegisterUser(string email, string password)\n {\n var user = new User(email, password);\n await _userRepository.SaveAsync(user);\n\n // Publish event - let other parts of the system react\n await _domainEventsDispatcher.DispatchAsync(\n [new UserRegisteredDomainEvent(user.Id, user.Email)]);\n }\n}\nNow the UserService focuses solely on user registration, while other concerns are handled through event handlers.
Let's start by defining two simple interfaces that form the foundation of our event system:
\n// Marker interface for all domain events.\npublic interface IDomainEvent\n{\n // We could add common properties here like:\n // DateTime OccurredAt { get; }\n // Guid EventId { get; }\n}\n\n// Generic interface for handling domain events.\npublic interface IDomainEventHandler<in T> where T : IDomainEvent\n{\n Task Handle(T domainEvent, CancellationToken cancellationToken = default);\n}\nThis design gives us type safety through generic constraints while keeping publishers and handlers completely decoupled.\nYou can add new events or handlers without touching existing code, and everything remains easily testable in isolation.
\nLet's add some sample handlers that demonstrate how different parts of your system can react to the same event:
\n// Handles sending welcome emails when users register\ninternal sealed class SendWelcomeEmailHandler(IEmailService emailService)\n : IDomainEventHandler<UserRegisteredDomainEvent>\n{\n public async Task Handle(\n UserRegisteredDomainEvent domainEvent,\n CancellationToken cancellationToken = default)\n {\n // Send welcome email\n var welcomeEmail = new WelcomeEmail(domainEvent.Email, domainEvent.UserId);\n\n await emailService.SendAsync(welcomeEmail, cancellationToken);\n }\n}\n\n// Handles analytics tracking for new user registrations\ninternal sealed class TrackUserRegistrationHandler(IAnalyticsService analyticsService)\n : IDomainEventHandler<UserRegisteredDomainEvent>\n{\n public async Task Handle(\n UserRegisteredDomainEvent domainEvent,\n CancellationToken cancellationToken = default)\n {\n // Track registration in analytics\n await analyticsService.TrackEvent(\n "user_registered",\n new\n {\n user_id = domainEvent.UserId,\n registration_date = domainEvent.RegisteredAt\n },\n cancellationToken);\n }\n}\nTo make this work, we need to register our handlers with the DI container.
\nHere's how to do it manually:
\n// In your Program.cs or Startup.cs\nservices.AddScoped<IDomainEventHandler<UserRegisteredDomainEvent>, SendWelcomeEmailHandler>();\nservices.AddScoped<IDomainEventHandler<UserRegisteredDomainEvent>, TrackUserRegistrationHandler>();\nOr you can automate this registration using assembly scanning with Scrutor:
\nservices.Scan(scan => scan.FromAssembliesOf(typeof(DependencyInjection))\n .AddClasses(classes => classes.AssignableTo(typeof(IDomainEventHandler<>)), publicOnly: false)\n .AsImplementedInterfaces()\n .WithScopedLifetime());\nThe important thing is that multiple handlers can react to the same event.
\nNow we need something to orchestrate calling the handlers.\nThe dispatcher will take the domain events and call the appropriate handlers for each event.
\npublic interface IDomainEventsDispatcher\n{\n Task DispatchAsync(\n IEnumerable<IDomainEvent> domainEvents,\n CancellationToken cancellationToken = default);\n}\n\ninternal sealed class DomainEventsDispatcher(IServiceProvider serviceProvider)\n : IDomainEventsDispatcher\n{\n private static readonly ConcurrentDictionary<Type, Type> HandlerTypeDictionary = new();\n private static readonly ConcurrentDictionary<Type, Type> WrapperTypeDictionary = new();\n\n public async Task DispatchAsync(\n IEnumerable<IDomainEvent> domainEvents,\n CancellationToken cancellationToken = default)\n {\n foreach (IDomainEvent domainEvent in domainEvents)\n {\n using IServiceScope scope = serviceProvider.CreateScope();\n\n Type domainEventType = domainEvent.GetType();\n\n Type handlerType = HandlerTypeDictionary.GetOrAdd(\n domainEventType,\n et => typeof(IDomainEventHandler<>).MakeGenericType(et));\n\n IEnumerable<object?> handlers = scope.ServiceProvider.GetServices(handlerType);\n\n foreach (object? handler in handlers)\n {\n if (handler is null) continue;\n\n var handlerWrapper = HandlerWrapper.Create(handler, domainEventType);\n\n await handlerWrapper.Handle(domainEvent, cancellationToken);\n }\n }\n }\n\n // Abstract base class for strongly-typed handler wrappers\n private abstract class HandlerWrapper\n {\n public abstract Task Handle(IDomainEvent domainEvent, CancellationToken cancellationToken);\n\n public static HandlerWrapper Create(object handler, Type domainEventType)\n {\n Type wrapperType = WrapperTypeDictionary.GetOrAdd(\n domainEventType,\n et => typeof(HandlerWrapper<>).MakeGenericType(et));\n\n return (HandlerWrapper)Activator.CreateInstance(wrapperType, handler)!;\n }\n }\n\n // Generic wrapper that provides strong typing for handler invocation\n private sealed class HandlerWrapper<T>(object handler) : HandlerWrapper where T : IDomainEvent\n {\n private readonly IDomainEventHandler<T> _handler = (IDomainEventHandler<T>)handler;\n\n public override async Task Handle(\n IDomainEvent domainEvent,\n CancellationToken cancellationToken)\n {\n await _handler.Handle((T)domainEvent, cancellationToken);\n }\n }\n}\nThe dispatcher uses a wrapper to eliminate reflection during handler execution while maintaining type safety.\nWhen we encounter a UserRegisteredDomainEvent, we create a HandlerWrapper<UserRegisteredDomainEvent>\nthat holds a strongly-typed reference to IDomainEventHandler<UserRegisteredDomainEvent>.\nThe wrapper casts the generic IDomainEvent to the specific event type at runtime, but the actual handler invocation uses compile-time types.
This gives us the performance benefits of avoiding reflection in the hot path (handler execution) while only using reflection once during wrapper creation.\nThe trade-off is additional complexity, but the performance gain is significant if you're dispatching many events.
\nDon't forget to register the dispatcher with DI:
\nservices.AddTransient<IDomainEventsDispatcher, DomainEventsDispatcher>();\nHere's how to use the domain events dispatcher in your application:
\npublic class UserController(\n IUserService userService,\n IDomainEventsDispatcher domainEventsDispatcher) : ControllerBase\n{\n [HttpPost("register")]\n public async Task<IActionResult> Register([FromBody] RegisterUserRequest request)\n {\n try\n {\n // Create the user\n var user = await userService.CreateUserAsync(request.Email, request.Password);\n\n // Publish the domain event\n var userRegisteredEvent = new UserRegisteredDomainEvent(user.Id, user.Email);\n\n await domainEventsDispatcher.DispatchAsync([userRegisteredEvent]);\n\n return Ok(new { UserId = user.Id, Message = "User registered successfully" });\n }\n catch (Exception ex)\n {\n return BadRequest(new { Error = ex.Message });\n }\n }\n}\nYou could also integrate domain events directly into your domain entities.
\nThis implementation runs entirely in-process, which has important implications.\nAll handlers execute synchronously within the same request context, but each gets its own DI scope.\nThis means:
\nImmediate feedback:\nIf any handler fails, the exception bubbles up to the caller immediately.\nNo silent failures or eventual consistency surprises.
\nCaller control:\nThe code that dispatches events decides how to handle failures — rollback transactions, retry operations, or continue despite errors.\nThe dispatcher doesn't make these decisions for you.
\nReliability concerns:\nIf the process crashes after some handlers succeed but before others complete, there's no automatic recovery.\nEvents aren't persisted or retried.
\nFor critical side effects that can't be lost, consider the Outbox pattern.\nInstead of dispatching events immediately, store them alongside your business data in the same transaction.\nA background service can later retry failed events, ensuring nothing gets lost.\nThis decouples reliability from performance — your main operation completes quickly while events are processed reliably in the background.
\nDomain events are a powerful pattern for decoupling business logic, and you don't need a heavyweight framework to use them effectively.\nThe implementation we've built here provides a solid foundation that you can extend as your needs grow.
\nThe beauty of rolling your own solution is that you understand every piece, making debugging and customization straightforward.\nThis pattern fits excellently in Domain-Driven Design and\nClean Architecture systems where decoupling business logic is crucial.
\nFor systems requiring bulletproof reliability or cross-service communication, invest in proper message infrastructure.\nBut for many applications, this simple approach hits the sweet spot between coupling and complexity.
\nThe key insight is understanding your trade-offs upfront rather than discovering them in production.\nStart simple, measure what matters, and evolve based on real requirements.
\nYou don't need MediatR to implement CQRS in .NET.\nA few simple abstractions cover what most projects use it for: ICommand, IQuery, their handler interfaces, and decorators for cross-cutting concerns.\nIn this article, I'll show you how to build that lightweight setup with plain interfaces and DI.
MediatR is going commercial.
\nJimmy Bogard recently announced\nthat MediatR will adopt a commercial license model for companies above a certain size.
\nFor many teams, this is a trigger to re-evaluate their usage and possibly look for alternatives.
\nAnd it's not a bad time to do so.\nMediatR became almost synonymous with CQRS in .NET, despite the fact that CQRS and MediatR are not the same thing.\nMost projects use it as a thin dispatching layer for commands and queries — a use case that can be covered with a few straightforward abstractions.
\nBy removing MediatR, you gain:
\nIn this article, I'll walk you through building a minimal CQRS setup with just a few interfaces and support for decorators.\nNo hidden DI magic.\nJust clean, predictable code.
\nWe'll cover:
\nICommand, IQuery, and handler contractsLet's get started.
\nLet's start by defining the basic contracts for commands and queries.
\n// ICommand.cs\npublic interface ICommand;\npublic interface ICommand<TResponse>;\n\n// IQuery.cs\npublic interface IQuery<TResponse>;\nThese interfaces exist purely as markers.\nThey allow us to structure application logic around intention — write operations go through ICommand, read operations through IQuery.
The handler interfaces follow the same model:
\n// ICommandHandler.cs\npublic interface ICommandHandler<in TCommand>\n where TCommand : ICommand\n{\n Task<Result> Handle(TCommand command, CancellationToken cancellationToken);\n}\n\npublic interface ICommandHandler<in TCommand, TResponse>\n where TCommand : ICommand<TResponse>\n{\n Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken);\n}\n// IQueryHandler.cs\npublic interface IQueryHandler<in TQuery, TResponse>\n where TQuery : IQuery<TResponse>\n{\n Task<Result<TResponse>> Handle(TQuery query, CancellationToken cancellationToken);\n}\nThese are nearly identical to MediatR's IRequest and IRequestHandler APIs, making migration trivial if you're moving off of MediatR.
You'll notice we're using a Result wrapper for all return types.\nThis is optional, but it promotes explicit success/failure handling and encourages consistency across the application boundary.\nYou can learn more about it in my previous article.
These interfaces form a lightweight CQRS infrastructure, focused purely on intent and separation of concerns.\nNo mediator, no runtime indirection — just clear contracts for handling reads and writes.
\nTo see these abstractions in action, let's implement a command that marks a todo item as completed.
\n// CompleteTodoCommand.cs\npublic sealed record CompleteTodoCommand(Guid TodoItemId) : ICommand;\n\n// CompleteTodoCommandHandler.cs\ninternal sealed class CompleteTodoCommandHandler(\n IApplicationDbContext context,\n IDateTimeProvider dateTimeProvider,\n IUserContext userContext)\n : ICommandHandler<CompleteTodoCommand>\n{\n public async Task<Result> Handle(CompleteTodoCommand command, CancellationToken cancellationToken)\n {\n TodoItem? todoItem = await context.TodoItems\n .SingleOrDefaultAsync(\n t => t.Id == command.TodoItemId && t.UserId == userContext.UserId,\n cancellationToken);\n\n if (todoItem is null)\n {\n return Result.Failure(TodoItemErrors.NotFound(command.TodoItemId));\n }\n\n if (todoItem.IsCompleted)\n {\n return Result.Failure(TodoItemErrors.AlreadyCompleted(command.TodoItemId));\n }\n\n todoItem.IsCompleted = true;\n todoItem.CompletedAt = dateTimeProvider.UtcNow;\n\n todoItem.Raise(new TodoItemCompletedDomainEvent(todoItem.Id));\n\n await context.SaveChangesAsync(cancellationToken);\n\n return Result.Success();\n }\n}\nA few important things to note:
\nISender, no hidden dispatching. The handler is invoked directly via our custom abstractions.This makes intent explicit, avoids magic, and keeps the dependencies minimal.
\nWe'll look at how to add decorators next, so we can introduce things like logging, validation, or transactions without modifying the handler itself.
\nTo support cross-cutting concerns like logging, validation, and transactions, we apply the decorator pattern around our handlers.\nTechnically, this is closer to the proxy pattern, since we're injecting behavior before/after delegating to the real handler.\nBut in the context of cross-cutting concerns, most people refer to this as a decorator — which is fine for our purposes.
\nLet's look at two examples: one for logging, one for validation.
\nusing Serilog.Context;\n\ninternal sealed class LoggingCommandHandler<TCommand, TResponse>(\n ICommandHandler<TCommand, TResponse> innerHandler,\n ILogger<CommandHandler<TCommand, TResponse>> logger)\n : ICommandHandler<TCommand, TResponse>\n where TCommand : ICommand<TResponse>\n{\n public async Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken)\n {\n string commandName = typeof(TCommand).Name;\n\n logger.LogInformation("Processing command {Command}", commandName);\n\n Result<TResponse> result = await innerHandler.Handle(command, cancellationToken);\n\n if (result.IsSuccess)\n {\n logger.LogInformation("Completed command {Command}", commandName);\n }\n else\n {\n using (LogContext.PushProperty("Error", result.Error, true))\n {\n logger.LogError("Completed command {Command} with error", commandName);\n }\n }\n\n return result;\n }\n}\nThis class wraps any ICommandHandler<TCommand, TResponse>, injecting the decorated handler as innerHandler.\nIt adds structured logging around the command execution without touching the core business logic.
Now a validation example with FluentValidation:
\nusing FluentValidation;\nusing FluentValidation.Results;\n\ninternal sealed class ValidationCommandHandler<TCommand, TResponse>(\n ICommandHandler<TCommand, TResponse> innerHandler,\n IEnumerable<IValidator<TCommand>> validators)\n : ICommandHandler<TCommand, TResponse>\n where TCommand : ICommand<TResponse>\n{\n public async Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken)\n {\n // Validate the command using all registered validators\n ValidationFailure[] validationFailures = await ValidateAsync(command, validators);\n\n if (validationFailures.Length == 0)\n {\n return await innerHandler.Handle(command, cancellationToken);\n }\n\n // If validation fails, return a failure result with the errors\n return Result.Failure<TResponse>(CreateValidationError(validationFailures));\n }\n\n private static async Task<ValidationFailure[]> ValidateAsync<TCommand>(\n TCommand command,\n IEnumerable<IValidator<TCommand>> validators)\n {\n if (!validators.Any())\n {\n return [];\n }\n\n var context = new ValidationContext<TCommand>(command);\n\n ValidationResult[] validationResults = await Task.WhenAll(\n validators.Select(validator => validator.ValidateAsync(context)));\n\n ValidationFailure[] validationFailures = validationResults\n .Where(validationResult => !validationResult.IsValid)\n .SelectMany(validationResult => validationResult.Errors)\n .ToArray();\n\n return validationFailures;\n }\n\n private static ValidationError CreateValidationError(ValidationFailure[] validationFailures) =>\n new(validationFailures.Select(f => Error.Problem(f.ErrorCode, f.ErrorMessage)).ToArray());\n}\nEach decorator handles a single concern and can be layered transparently around the core handler.
\nImportant: Since we're working with generic interfaces (ICommandHandler<,>, IQueryHandler<,>),\neach decorator must explicitly target the same generic contract.\nThat means you'll need separate decorator classes for each handler abstraction you're using (e.g. command with result, command without result, query with result).
In the next section, we'll wire this up using Scrutor.\nIt's a simple assembly scanning library that helps us register and decorate handlers cleanly.\nYes, it uses reflection, but only during startup — and it's fully transparent and predictable.
\nWith our handlers and decorators in place, we can register everything using Scrutor.
\nservices.Scan(scan => scan.FromAssembliesOf(typeof(DependencyInjection))\n .AddClasses(classes => classes.AssignableTo(typeof(IQueryHandler<,>)), publicOnly: false)\n .AsImplementedInterfaces()\n .WithScopedLifetime()\n .AddClasses(classes => classes.AssignableTo(typeof(ICommandHandler<>)), publicOnly: false)\n .AsImplementedInterfaces()\n .WithScopedLifetime()\n .AddClasses(classes => classes.AssignableTo(typeof(ICommandHandler<,>)), publicOnly: false)\n .AsImplementedInterfaces()\n .WithScopedLifetime());\nThis scans the application assembly and registers all command and query handlers (including internal types) as their respective interfaces.
\nNext, we apply decorators for validation and logging:
\nservices.Decorate(typeof(ICommandHandler<,>), typeof(ValidationDecorator.CommandHandler<,>));\nservices.Decorate(typeof(ICommandHandler<>), typeof(ValidationDecorator.CommandBaseHandler<>));\n\nservices.Decorate(typeof(IQueryHandler<,>), typeof(LoggingDecorator.QueryHandler<,>));\nservices.Decorate(typeof(ICommandHandler<,>), typeof(LoggingDecorator.CommandHandler<,>));\nservices.Decorate(typeof(ICommandHandler<>), typeof(LoggingDecorator.CommandBaseHandler<>));\nEach Decorate call wraps the previous registration.\nOrder matters, but it might not be intuitive at first glance.
The last decorator applied will be the outermost one at runtime.\nSo in this example:
\nWhich means the logging decorator runs first, followed by validation, and then the core handler.
\nThis order allows logging to capture the full command lifecycle, including any early exits from validation failures.
\nWith this setup, you now have a fully functional and extensible CQRS pipeline:
\nOnce everything is wired up, using a command handler from a Minimal API endpoint is straightforward:
\ninternal sealed class Complete : IEndpoint\n{\n public void MapEndpoint(IEndpointRouteBuilder app)\n {\n app.MapPut("todos/{id:guid}/complete", async (\n Guid id,\n ICommandHandler<CompleteTodoCommand> handler,\n CancellationToken cancellationToken) =>\n {\n var command = new CompleteTodoCommand(id);\n\n Result result = await handler.Handle(command, cancellationToken);\n\n return result.Match(Results.NoContent, CustomResults.Problem);\n })\n .WithTags(Tags.Todos)\n .RequireAuthorization();\n }\n}\nWe're injecting the appropriate ICommandHandler<CompleteTodoCommand> directly into the endpoint.\nNo need for ISender, no mediator layer, no runtime lookup.
This keeps the endpoint clean and focused on its primary responsibility: handling HTTP requests.
\nEverything is resolved explicitly by the container.\nThis makes the code easier to test, reason about, and trace while maintaining all the benefits of CQRS and separation of concerns.
\nCQRS doesn't require a complex framework.
\nWith a few small interfaces, some decorator classes, and a clean DI setup, you can build a simple and flexible pipeline for handling commands and queries.\nIt's easy to understand, easy to test, and easy to extend.
\nIf you want to see this pattern applied in a complete solution,\nmy free Clean Architecture template includes everything covered in this article (fully wired up).
\nUse it as a reference or as a starting point for your next project.
\nAn anemic domain model keeps entities as data holders and pushes every rule into a service class.\nYou fix it by moving one rule at a time into the aggregate: a static Create factory that fails fast on broken invariants, and internal state that consumers cannot mutate.\nThe application layer is left with orchestration.
If you've ever worked with a legacy C# codebase, you know the pain of an anemic domain model.\nYou have probably opened an OrderService (all similarities to production code are merely a coincidence) and thought "this file does everything."\nPricing logic, discount rules, stock checks, database writes — all jam-packed into one class.\nIt works — until it doesn't.\nNew features turn into regression roulette, and test coverage plummets because the domain is buried under infrastructure.
This is the classic symptom of an anemic domain model, where entities are nothing but data holders, and all logic lives elsewhere.\nIt makes the system harder to reason about, and every change becomes a guessing game.\nBut what if we could push behavior back into the domain, one rule at a time?
\nIn this article, we'll:
\nEverything fits in a 6-minute read, but the pattern scales to any legacy system.
\nBelow is an (unfortunately common) OrderService.\nBesides calculating totals it also:
// OrderService.cs\npublic void PlaceOrder(Guid customerId, IEnumerable<OrderItemDto> items)\n{\n var customer = _db.Customers.Find(customerId);\n if (customer is null)\n {\n throw new ArgumentException("Customer not found");\n }\n\n var order = new Order { CustomerId = customerId };\n\n foreach (var dto in items)\n {\n var inventory = _inventoryService.GetStock(dto.ProductId);\n if (inventory < dto.Quantity)\n {\n throw new InvalidOperationException("Item out of stock");\n }\n\n var price = _pricingService.GetPrice(dto.ProductId);\n var lineTotal = price * dto.Quantity;\n if (customer.IsVip)\n {\n lineTotal *= 0.95m; // 5% discount for VIPs\n }\n\n order.Items.Add(new OrderItem\n {\n ProductId = dto.ProductId,\n Quantity = dto.Quantity,\n UnitPrice = price,\n LineTotal = lineTotal\n });\n }\n\n order.Total = order.Items.Sum(i => i.LineTotal);\n\n if (customer.CreditUsed + order.Total > customer.CreditLimit)\n {\n throw new InvalidOperationException("Credit limit exceeded");\n }\n\n _db.Orders.Add(order);\n _db.SaveChanges();\n}\nOrderService must know about pricing, inventory, and EF Core just to place an order.Goal: Embed these rules inside the domain so the application layer only deals with orchestration.
\nOrder aggregate.The goal here isn't to chase purity or academic DDD.\nIt's to incrementally improve cohesion and make room for the domain to express itself.
\nAt every step, we ask: Is this behavior something the domain should own?\nIf yes, we pull it inward.
\nThe first move is to make the aggregate responsible for building itself.\nA static Create method gives us a single entry point where all invariants can fail fast.
While pushing stock validation into Order improves testability,\nit does couple the order flow with inventory availability.\nIn some domains, you'd instead model this as a domain event and validate asynchronously.
// Order.cs (Factory Method)\npublic static Order Create(\n Customer customer,\n IEnumerable<(Guid productId, int quantity)> lines,\n IPricingService pricingService,\n IInventoryService inventoryService)\n{\n var order = new Order(customer.Id);\n\n foreach (var (productId, quantity) in lines)\n {\n if (inventoryService.GetStock(productId) < quantity)\n {\n throw new InvalidOperationException("Item out of stock");\n }\n\n var unitPrice = pricingService.GetPrice(productId);\n order.AddItem(productId, quantity, unitPrice, customer.IsVip);\n }\n\n order.EnsureCreditWithinLimit(customer);\n\n return order;\n}\nWhy?\nCreation now fails fast if any invariant is broken.\nThe service no longer micromanages stock or discounts.
\nNotice how we're now following the "Tell, Don't Ask" principle.\nRather than the service checking conditions and then manipulating the Order,\nwe're telling the Order to create itself with the necessary validations built in.\nThis is a fundamental shift toward encapsulation.
\n💡 On Injecting Services into Domain Methods
\nPassing services like IPricingService or IInventoryService into a domain method such as Order.Create might seem unconventional at first glance.\nBut it's a deliberate design choice: it keeps the orchestration inside the domain model, where the business logic naturally belongs,\ninstead of bloating the application service with procedural workflows.
This approach maintains the entity's autonomy while still aligning with dependency injection principles — dependencies are passed explicitly, not resolved from within.\nIt's a powerful technique, but one that should be used selectively — only when the operation clearly fits within the domain's responsibility\nand benefits from direct access to external services.
\n// Order.cs (excerpt)\nprivate readonly List<OrderItem> _items = new();\npublic IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly(); // C# 12 -> [.._items]\n\nprivate void AddItem(Guid productId, int quantity, decimal unitPrice, bool isVip)\n{\n if (quantity <= 0)\n {\n throw new ArgumentException("Quantity must be positive");\n }\n\n var finalPrice = isVip ? unitPrice * 0.95m : unitPrice;\n _items.Add(new OrderItem(productId, quantity, finalPrice));\n\n RecalculateTotal();\n}\n\nprivate void EnsureCreditWithinLimit(Customer customer)\n{\n if (customer.CreditUsed + Total > customer.CreditLimit)\n {\n throw new InvalidOperationException("Credit limit exceeded");\n }\n}\nWhy bother?
\n_items directly, ensuring invariants hold.public void PlaceOrder(Guid customerId, IEnumerable<OrderLineDto> lines)\n{\n var customer = _db.Customers.Find(customerId);\n if (customer is null)\n {\n throw new ArgumentException("Customer not found");\n }\n var input = lines.Select(l => (l.ProductId, l.Quantity));\n\n var order = Order.Create(customer, input, _pricingService, _inventoryService);\n\n _db.Orders.Add(order);\n _db.SaveChanges();\n}\nThe PlaceOrder method drops from 44 lines to 14, with zero business logic.
Before the refactor
\nAfter the refactor
\nOrder aggregate.The real value in refactoring anemic models isn't technical — it's strategic.
\nBy moving business logic closer to the data, you:
\nBut you don't need a big rewrite.\nStart with one rule.\nRefactor it.\nThen the next.
\nThat's how legacy systems evolve into maintainable architectures.
\nIf you enjoyed this breakdown and want a hands-on, real-world guide to untangling messy services,\ncheck out my course Pragmatic Domain-Driven Design.\nIt's packed with before-and-after examples like this one.
\nIn .NET, an event-driven system with RabbitMQ has three parts: a producer that publishes to an exchange, a queue that stores the messages, and a consumer that reads from that queue.\nThe official RabbitMQ.Client package handles all three.\nCompeting consumers split the work, and a fanout exchange gives every consumer a copy.
Event-driven architecture (EDA) can make applications more flexible and reliable.\nInstead of one part of the system calling another directly, we let events flow through a message broker.\nIn this quick guide, I'll show you how to set up a simple event-driven system in .NET using RabbitMQ.
\nWe'll build a small example with a producer that sends events and a consumer that receives them.\nFor testing, I'll run RabbitMQ in a Docker container (with the Management UI enabled so we can see what's happening).\nWe'll use the official RabbitMQ.Client NuGet package in a .NET console app.
\nNote: If you don't have RabbitMQ installed, you can run it quickly with Docker. For example:
\ndocker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4-management\nThis starts a RabbitMQ broker on localhost (AMQP port 5672) and a management website at http://localhost:15672.
Before coding, let's cover the basic components in RabbitMQ:
\nIn RabbitMQ, you can have multiple producers and multiple consumers.\nProducers never send directly to a queue by name; instead, they send to an exchange.\nThe exchange decides which queues (if any) should get each message based on routing rules.
\nFor now, we'll use a simple setup where the exchange will deliver all messages to one queue.
\nLet's start with the producer.\nIn our .NET console app, we'll use RabbitMQ.Client to connect to the RabbitMQ broker and send a message.
\nFor instance, an OrderPlaced event could trigger downstream services - inventory, email notifications, etc. -\nwithout the ordering system needing to call them directly.
var factory = new ConnectionFactory() { HostName = "localhost" };\nusing var connection = await factory.CreateConnectionAsync();\nusing var channel = await connection.CreateChannelAsync();\n\n// Ensure the queue exists (create it if not already there)\nawait channel.QueueDeclareAsync(\n queue: "orders",\n durable: true, // save to disk so the queue isn't lost on broker restart\n exclusive: false, // can be used by other connections\n autoDelete: false, // don't delete when the last consumer disconnects\n arguments: null);\n\n// Create a message\nvar orderPlaced = new OrderPlaced\n{\n OrderId = Guid.NewGuid(),\n Total = 99.99,\n CreatedAt = DateTime.UtcNow\n};\nvar message = JsonSerializer.Serialize(orderPlaced);\nvar body = Encoding.UTF8.GetBytes(message);\n\n// Publish the message\nawait channel.BasicPublishAsync(\n exchange: string.Empty, // default exchange\n routingKey: "orders",\n mandatory: true, // fail if the message can't be routed\n basicProperties: new BasicProperties { Persistent = true }, // message will be saved to disk\n body: body);\n\nConsole.WriteLine($"Sent: {message}");\nThis code connects to RabbitMQ on localhost, declares a queue named orders (creates it if it doesn't exist already),\nand publishes an OrderPlaced message to that queue.\nWe use an empty string for the exchange parameter, which tells RabbitMQ to use the default exchange.\nThe default exchange routes the message directly to the orders queue.
What's happening here:
\nNow let's look at the consumer side.
\nNext, let's set up a consumer to receive messages from the queue.\nThe consumer will also connect to RabbitMQ and subscribe to the same queue.
\nTo test this out, start the consumer application first (it will wait for messages), then run the producer application to send an event.
\nvar factory = new ConnectionFactory() { HostName = "localhost" };\nusing var connection = await factory.CreateConnectionAsync();\nusing var channel = await connection.CreateChannelAsync();\n\n// Declare (or check) the queue to consume from\nawait channel.QueueDeclareAsync(\n queue: "orders",\n durable: true, // must match the producer's queue settings\n exclusive: false, // can be used by other connections\n autoDelete: false, // don't delete when the last consumer disconnects\n arguments: null);\n\n// Define a consumer and start listening\nvar consumer = new AsyncEventingBasicConsumer(channel);\nconsumer.ReceivedAsync += async (sender, eventArgs) =>\n{\n byte[] body = eventArgs.Body.ToArray();\n string message = Encoding.UTF8.GetString(body);\n var orderPlaced = JsonSerializer.Deserialize<OrderPlaced>(message);\n\n Console.WriteLine($"Received: OrderPlaced - {orderPlaced.OrderId}");\n\n // Acknowledge the message\n await ((AsyncEventingBasicConsumer)sender)\n .Channel.BasicAckAsync(eventArgs.DeliveryTag, multiple: false);\n};\nawait channel.BasicConsumeAsync("orders", autoAck: false, consumer);\n\nConsole.WriteLine("Waiting for messages...");\nThe consumer code declares the same orders queue and sets up an event handler for incoming messages.\nWe call BasicConsumeAsync to start listening on the queue.\nRabbitMQ will push any new messages to our consumer's event handler.\nWhenever a message arrives, the consumer.ReceivedAsync event fires, and we print out the message.
What's important here:
\nautoAck: false ensures we only acknowledge messages we actually processBasicNack to requeue or route to a dead-letter queueSo far we've had one consumer. But what if we run multiple consumers on the same queue?
\nWhat if you have multiple consumers for the same queue?\nRabbitMQ allows competing consumers on a queue.
\nIf two or more consumers listen on the same queue, each message from that queue will be delivered to only one of them:
\nIn other words, consumers compete for messages on that queue.\nThis pattern helps spread the workload, but note that each individual message is still processed by a single consumer.
\nCompeting consumers share the work by dividing messages, but sometimes you want every service to get the event.\nThat's where a fanout exchange comes in.
\nIn RabbitMQ, a fanout exchange is used for broadcasting events to multiple consumers.\nInstead of all consumers sharing one queue, each consumer has its own queue.\nWhen the producer sends a message to a fanout exchange, the exchange copies and routes the message to all bound queues.\nThis way, every consumer receives a copy via its own queue.
\nTo set this up in code, we declare a fanout exchange and bind queues to it.
\nProducer:
\n// Producer setup for fanout\nawait channel.ExchangeDeclareAsync(\n exchange: "orders",\n durable: true, // durable exchange\n autoDelete: false, // don't delete when the last consumer disconnects\n type: ExchangeType.Fanout);\n\n// Publish a message to the fanout exchange (routingKey is ignored for fanout)\nvar orderPlaced = new OrderPlaced\n{\n OrderId = Guid.NewGuid(),\n Total = 99.99,\n CreatedAt = DateTime.UtcNow\n};\nvar message = JsonSerializer.Serialize(orderPlaced);\nvar body = Encoding.UTF8.GetBytes(message);\n\nawait channel.BasicPublishAsync(\n exchange: "orders",\n routingKey: string.Empty,\n mandatory: true,\n basicProperties: new BasicProperties { Persistent = true },\n body: body);\nConsumer:
\n// Consumer setup for fanout\nawait channel.ExchangeDeclareAsync(\n exchange: "orders",\n durable: true,\n autoDelete: false,\n type: ExchangeType.Fanout);\n\n// Create a queue for this consumer and bind it\nawait channel.QueueDeclareAsync(\n queue: "orders-consumer-1",\n durable: true,\n exclusive: false,\n autoDelete: false,\n arguments: null);\n\nawait channel.QueueBindAsync("orders-consumer-1", "orders", routingKey: string.Empty);\n\n// Then consume messages from queueName as usual...\nIn the producer, we call ExchangeDeclareAsync to make sure an orders exchange exists (of type fanout).\nWe then BasicPublishAsync to that exchange.\nFor a fanout exchange, the routingKey can be an empty string because it's ignored (fanout sends to all queues regardless of any routing key).\nOn the consumer side, we declare the same exchange and then create a new orders-consumer-1 queue.\nWe bind that queue to the orders exchange.\nNow any message sent to the exchange will be delivered to this queue, and we can consume it.
If you run multiple consumer programs (each with its own queue bound to orders exchange),\neach one will get every message (unlike the competing consumers scenario).\nYou can also peek into RabbitMQ's Management UI to see the exchange and queues in action.
![\"RabbitMQ](\"https://milanjovanovic.tech/blogs/mnw_140/rabbitmq_ui.png\")
\nYou can expand this basic setup with more advanced RabbitMQ features.\nFor example, you might use a direct exchange or topic exchange to route events to specific services,\nset up acknowledgment and retry policies for robustness,\nor implement dead-letter queues for error handling.\nThe core idea throughout is the same: decouple senders and receivers with a message broker, making your system more flexible and resilient.
\nIf you want to explore event-driven architecture further, including patterns like the ones we touched on (and beyond),\ncheck out my Modular Monolith Architecture course.\nIt covers these concepts in depth with practical examples, so you can apply EDA in real-world projects.
\nGood luck out there, and see you next week.
\nAn overgrown bounded context shows up as one class doing billing, notifications, reporting, and user management at once.\nYou split it by grouping the code into logical subdomains, extracting a low risk one first, and replacing direct calls with domain events.\nData isolation comes later, one schema at a time.
\nWhen you're building a modular monolith, it's easy to let bounded contexts grow too large over time.\nWhat started as a clean domain boundary slowly turns into a dumping ground for unrelated logic.\nBefore you know it, you have a massive context responsible for users, payments, notifications, and reporting - all tangled together.
\nThis article is about tackling that mess.\nWe'll walk through how to identify an overgrown bounded context, and refactor it step-by-step into smaller, well-defined contexts.\nYou'll see practical techniques in action, with real .NET code and without theoretical fluff.
\nYou know you have a problem when:
\nHere's a classic example.
\nWe start with a BillingContext that now handles everything from notifications to reporting:
public class BillingService\n{\n public void ChargeCustomer(int customerId, decimal amount) { ... }\n public void SendInvoice(int invoiceId) { ... }\n public void NotifyCustomer(int customerId, string message) { ... }\n public void GenerateMonthlyReport() { ... }\n public void DeactivateUserAccount(int userId) { ... }\n}\nThis service has no clear boundaries.\nIt mixes Billing, Notifications, Reporting, and User Management into a single, bloated class.\nChanging one feature could easily break another.
\nWe start by breaking this apart logically.\nThink like a product owner.
\nJust ask: "What domains are we really working with?"
\nGroup the methods:
\nChargeCustomer, SendInvoiceNotifyCustomerGenerateMonthlyReportDeactivateUserAccountCode within a bounded context should model a coherent domain.\nWhen multiple domains are jammed into the same context, your architecture becomes misleading.
\nYou can validate these groupings by checking:
\nIf yes, it's a sign you're dealing with distinct contexts.
\nDon't try to do it all at once.\nStart with something low-risk.
\nLet's begin by extracting Notifications.
\nWhy Notifications?\nBecause it's a pure side-effect.\nIt doesn't impact business state, so it's easier to decouple safely.
\nCreate a new module and move the logic there:
\n// New module: Notifications\npublic class NotificationService\n{\n public void Send(int customerId, string message) { ... }\n}\nThen simplify the original BillingService:
public class BillingService\n{\n private readonly NotificationService _notificationService;\n\n public BillingService(NotificationService notificationService)\n {\n _notificationService = notificationService;\n }\n\n public void ChargeCustomer(int customerId, decimal amount)\n {\n // Charge logic...\n _notificationService.Send(customerId, $"You were charged ${amount}");\n }\n}\nThis works. But now Billing depends on Notifications.\nThat's a coupling we want to avoid long-term.
\nWhy?\nBecause a failure in Notifications could block a billing operation.\nIt also means Billing can't evolve independently.
\nLet's decouple with domain events:
\npublic class CustomerChargedEvent\n{\n public int CustomerId { get; init; }\n public decimal Amount { get; init; }\n}\n\n// Module: Billing\npublic class BillingService\n{\n private readonly IDomainEventDispatcher _dispatcher;\n\n public BillingService(IDomainEventDispatcher dispatcher)\n {\n _dispatcher = dispatcher;\n }\n\n public void ChargeCustomer(int customerId, decimal amount)\n {\n // Charge logic...\n _dispatcher.Dispatch(new CustomerChargedEvent\n {\n CustomerId = customerId,\n Amount = amount\n });\n }\n}\n\n// Module: Notifications\npublic class CustomerChargedEventnHandler : IDomainEventHandler<CustomerChargedEvent>\n{\n public Task Handle(CustomerChargedEvent @event)\n {\n // Send notification\n }\n}\nNow Billing doesn't even know about Notifications.\nThat's real modularity.\nYou can replace, remove, or enhance the Notifications module without touching Billing.
\nMost monoliths start with a single database.\nThat's fine.\nBut real modularity comes when each module controls its own schema.
\nWhy?\nBecause the database structure reflects ownership.\nIf everything touches the same tables, it's hard to enforce boundaries.
\nYou don't have to do it all at once.\nStart with:
\nDbContext per module// Module: Billing\npublic class BillingDbContext : DbContext\n{\n public DbSet<Invoice> Invoices { get; set; }\n}\n\n// Module: Notifications\npublic class NotificationsDbContext : DbContext\n{\n public DbSet<NotificationLog> Logs { get; set; }\n}\nThis separation enables independent schema evolution.\nIt also makes testing faster and safer.
\nWhen migrating, use a transitional phase where both contexts read from the same underlying data.\nOnly switch write paths when confidence is high.
\nApply the same playbook.\nTarget a clean split per subdomain.
\nNext up: Reporting and User Management.
\nBefore:
\nbillingService.GenerateMonthlyReport();\nbillingService.DeactivateUserAccount(userId);\nAfter:
\nreportingService.GenerateMonthlyReport();\nuserService.DeactivateUser(userId);\nOr via events:
\n_dispatcher.Dispatch(new MonthEndedEvent());\n_dispatcher.Dispatch(new UserInactiveEvent(userId));\nThe goal here isn't just technical cleanliness - it's clarity.\nAnyone looking at your solution should know what each module is responsible for.
\nAnd remember: boundaries should be enforced by code, not just by folder structure.\nDifferent projects, separate EF models, and explicit interfaces help enforce the split.\nArchitecture tests can also help ensure that modules don't break their boundaries.
\nOnce you've finished the refactor, you'll have:
\nThis is more than structure, it's design that supports change.\nYou get loose coupling, testability, and clearer mental models.
\nYou don't need microservices to get modularity.\nYou need to treat your monolith like a set of cooperating, isolated parts.
\nStart with one module.\nShip the change.\nRepeat.
\nWant to go deeper into modular monolith design?\nMy full video course, Modular Monolith Architecture,\nwalks you through building a real-world system from scratch - with clear boundaries, isolated modules, and practical patterns that scale.\nJoin 1,800+ students and start building better systems today.
\nThat's all for today.
\nSee you next Saturday.
\nMicroservices are services modeled around a business domain and deployed independently of each other.\nEach service owns its own data behind a well-defined interface and talks to the others over the network.\nThey buy you options, like scaling one service on its own, and you pay for them with network failures, operational overhead, and eventual consistency.
\nI've been revisiting Sam Newman's excellent book "Monolith to Microservices" recently,\nand it's reminded me just how transformative this architectural approach can be when applied correctly.
\nAs someone who's implemented microservices in various organizations, I wanted to share some valuable insights I've gained through both study and practical experience.
\nWhat exactly are microservices, and why might they be the right architectural choice for your organization?
\nLet's dive into the core concepts and benefits of microservices architecture.
\nMicroservices are independently deployable services modeled around a business domain.\nBusiness domain is key here, but more on that later.\nThey communicate with each other via networks and offer many options for solving complex architectural problems.
\nThink of microservices as small, focused teams rather than a large department.\nEach team has a specific responsibility, operates somewhat independently, and communicates clearly with other teams when needed.\nInstead of one massive codebase that handles everything, you have multiple smaller codebases, each focusing on a specific business capability.
\n![\"Microservices](\"https://milanjovanovic.tech/blogs/mnw_138/microservices_architecture.png\")
\nAs Sam Newman defines them in "Monolith to Microservices":
\n\n\nMicroservices are independently deployable services modeled around a business domain.\nThey communicate with each other via networks, and as an architecture choice offer many options for solving the problems you may face.
\n
Microservices give you a strategy to design a modular system and decompose it into bounded contexts.\nHowever, the problem I often see is that developers use microservices to enforce code boundaries.\nThis is a mistake.\nWe'll fix that in a moment.
\nLet's explore some of the key characteristics that define microservices:
\nYou can make changes to a microservice and deploy it to production without having to deploy anything else.\nThis isn't just a theoretical ability - it's a discipline you practice for most of your releases.
\nThe value here is significant: smaller deployments carry less risk, enable faster release cycles, and allow teams to test their changes in isolation.
\nWhen a critical bug appears in one service, you can fix and deploy just that service rather than orchestrating a full system release.\nThis is especially valuable in large systems where coordinating releases can be a logistical nightmare.
\nMicroservices are organized around business capabilities rather than technical layers.\nInstead of having separate frontend, backend, and database teams (and the coordination that requires),\nyou might have teams dedicated to "Event Management," "Customer Accounts," or "Attendance."
\nThis alignment makes it easier to implement business functionality changes since all the related code - from UI to data storage - is grouped together.\nWhen a business requirement changes, you can often change just one service rather than coordinating changes across multiple layers.
\n![\"Event](\"https://milanjovanovic.tech/blogs/mnw_138/event_storming.png\")
\nMicroservices encapsulate data storage and retrieval, exposing data only via well-defined interfaces.\nDatabases are hidden inside the service boundary rather than shared between services.
\nThis stands in stark contrast to traditional approaches where multiple applications share a common database, often leading to tight coupling and risky schema changes.
\nWhen a service owns its data exclusively, it can:
\nIt's not uncommon for multiple services to share the same database, but you're giving up some of the benefits of microservices by doing so.\nIn practice, one database per service is the most common approach.
\nServices communicate with each other via networks, making microservices a form of distributed system.\nThis network-based communication could use REST APIs, message queues, gRPC, GraphQL, or other protocols depending on the specific needs.
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_138/network_communication.png\")
\nThis explicit communication over networks allows services to be deployed independently and even run on different infrastructure.\nBut it also means dealing with network latency, potential failures, and serialization concerns.
\nTeams building microservices need to carefully design their inter-service communication patterns\nto balance performance, reliability, and flexibility.
\nThe term "microservices" has an interesting origin story.\nIn 2011, a software consultant named James Lewis became interested in what he called "micro-apps" - small services optimized to be easily replaceable.
\nThe distinguishing feature was how small in scope these services were.\nSome could be written or rewritten in just a few days.\nAs discussions evolved, the term "microservices" was adopted since these weren't self-contained applications but rather services working together.
\nIt's worth noting that while "micro" is in the name, the size of a microservice isn't its defining characteristic.\nRather, it's about having services with well-defined boundaries that can be developed, deployed, and scaled independently.
\nWhat are the benefits of adopting a microservices architecture?
\nWhy should you consider it for your organization?
\nLet's explore some of the key advantages:
\nMicroservices give you options.\nThey provide flexibility in how you can scale, evolve, and maintain your system over time.
\nThis ability to evolve incrementally is particularly valuable in rapidly changing business environments where time-to-market is critical.
\nWith microservices, you can mix and match technology stacks.\nEach service can use the programming language, database, or framework best suited for its specific requirements.\nThis practice is known as polyglot programming and polyglot persistence.
\nFor example, a recommendation engine might use Python with specialized machine learning libraries.\nOn the other hand, a transaction processing service might use .NET for its strong typing and performance characteristics.
\nA reporting service might use a columnar database optimized for analytics,\nwhile a user profile service could use a document database that better fits its data model.
\n![\"Event](\"https://milanjovanovic.tech/blogs/mnw_138/polyglot_persistence.png\")
\nThis flexibility allows teams to choose the right tool for each job rather than compromising on a one-size-fits-all approach.
\nMultiple teams can work on different services simultaneously without stepping on each other's toes.\nThis parallelization can significantly accelerate development velocity in larger organizations.
\nEach team can maintain its own release schedule, make technology decisions, and optimize for their specific service's needs without coordinating with every other team.\nI've seen firsthand how this autonomy can reduce dependencies between teams, minimizing bottlenecks and wait times.
\nOrganizations commonly structure their teams around services or groups of related services.\nYou might know this concept as Conway's Law:
\n\n\nOrganizations, who design systems, are constrained to produce designs which are copies of the communication structures of these organizations.
\n
You can scale just the services that need it, rather than scaling the entire system.\nThis provides more efficient resource utilization and can reduce operational costs.
\nFor example, if your product catalog needs to handle high traffic during a sale, you can scale just the catalog service without scaling your payment processing service.
\nThis granular scaling becomes especially valuable as systems grow and different components have different performance characteristics.\nSome services might be CPU-intensive while others are memory-intensive, and with microservices, you can optimize the infrastructure for each service's specific needs.
\nThis approach can lead to significant cost savings compared to scaling a monolith,\nwhere all components must scale together regardless of their individual requirements.
\nMicroservices can help align your technical architecture with your organizational structure.\nTeams can own specific services that correspond to their business domain expertise, promoting clearer ownership and accountability.
\n![\"UML](\"https://milanjovanovic.tech/blogs/mnw_138/evently_domain.png\")
\nThis alignment reduces handoffs and coordination costs between teams, as each team has clear boundaries of responsibility.\nIt supports Conway's Law in a positive way.\nInstead of having your communication structure accidentally create your architecture, you deliberately design both your teams and your services around business capabilities.
\nThis approach can lead to more stable team structures and software boundaries over time, as business domains tend to evolve more slowly than technical implementations.
\nWhile microservices offer numerous benefits, they're not without challenges:
\nNetwork communication introduces latency, reliability challenges, and makes debugging more difficult.\nServices must handle network failures gracefully, implement retries with backoff strategies,\nand deal with the reality that a request might succeed but the response might get lost.
\nDistributed tracing becomes essential to understand how requests flow through the system.
\n![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_138/distributed_trace.png\")
\nYou'll need to develop strategies for handling partial system failures.\nConcepts like circuit breakers and bulkheads become part of your everyday vocabulary.
\nManaging many services requires robust deployment pipelines, monitoring, and debugging tools.\nYou'll need to invest in automation for deployment, health checking, scaling,\nand perhaps service discovery.\nEach service needs monitoring, logging, and alerting.
\nThis overhead can be substantial.\nOrganizations successfully running microservices typically have a strong DevOps culture and tooling to manage this complexity.
\nMaintaining consistency across service boundaries becomes more challenging without the safety of database transactions.
\nImplementing business processes that span multiple services often requires eventual consistency models and compensation mechanisms to handle failures.\nYou'll need to design your services with idempotency in mind and may need to implement patterns like the\nSaga pattern to manage distributed transactions.
\nThese approaches add complexity but can actually lead to more resilient systems when implemented correctly.
\nOrchestrating workflows that span multiple services requires careful design.\nSimple processes in a monolith can become complex choreographies in a microservice architecture.
\nYou'll need to decide whether to use orchestration (where a central service directs the process)\nor choreography (where services react to events without central coordination).\nThese patterns have different trade-offs in terms of coupling, resilience, and observability.
\nDesigning these cross-service workflows often reveals subdomain boundaries you might have missed in initial modeling.
\nFrom my experience, the most important thing to remember is that microservices ultimately buy you options.\nThey provide flexibility but come with costs.
\nAre these costs worth the options you want to exercise?
\nFor organizations with a large engineering team working on a complex system that needs to evolve quickly, microservices may be worth the overhead.\nFor smaller teams or systems with more stable requirements, a well-designed monolith might be more appropriate.\nForget about resume-driven development for a moment.\nIt's about what solves your specific problems with acceptable trade-offs.
\nIn my work, I've found that the most successful microservice adoptions start small, often by breaking off just one or two services from a monolith.\nThen, gradually expanding as the organization builds the necessary skills and infrastructure.\nThis evolutionary approach reduces risk and allows teams to learn as they go.
\nI always like to reflect on these questions:
\nIf you want to dive deeper into building microservices - but starting from a monolith, check out Modular Monolith Architecture.\nThere's an entire chapter dedicated to developing microservices, including advanced techniques such as API gateways, using message queues, and system integration testing.
\nThanks for reading.
\nAnd stay awesome!
\nVector search is changing how we find information.\nUnlike old search methods that look for exact words, vector search finds content based on meaning.\nThis makes search results more helpful and human-like.
\nWhen you search for "quick healthy breakfast ideas," vector search can find articles about "nutritious morning meals" even if they don't use your exact words.\nThis happens because vector search understands what you mean, not just what you type.
\nIn this week's newsletter, we'll break down how vector search works and why it's important.
\nAt the heart of vector search are vector embeddings.\nThese are lists of numbers that represent data.\nBut how do we get from words or images to numbers?
\nHere's how it works:
\n![\"Vector](\"https://milanjovanovic.tech/blogs/mnw_137/vector_space.png\")
\nThink of each number in the vector as describing one aspect of the data.\nWith hundreds or thousands of these numbers, vectors can capture complex meanings and relationships.
\nFor example, in vector form, the words "lion" and "bobcat" would have similar number patterns because they refer to similar animals.\nMeanwhile, "cat" would have a different pattern, though still somewhat similar since it's also a feline.
\nWhen you search using vector search:
\nTo find similar vectors, the system measures how close they are to each other.\nThink of each vector as a point in space - the closer two points are, the more similar their meanings.
\n![\"Vector](\"https://milanjovanovic.tech/blogs/mnw_137/vector_search.png\")
\nTo make vector search work well with lots of data, we need special storage systems called vector databases.\nThese databases are built to store and quickly search through millions or billions of vectors.
\nVector databases do more than just store vectors - they organize them in smart ways that make searching faster.\nThey use special methods called "Approximate Nearest Neighbor" (ANN) algorithms that can find similar vectors without checking every single one in the database.
\n![\"Vector](\"https://milanjovanovic.tech/blogs/mnw_137/vector_databases_landscape.png\")
\n These databases also store the original content along with its vector, so when you get search results,\nyou see the actual text, images, or other data you were looking for.\nPopular vector databases include Weaviate, Pinecone, and Qdrant.\nBut you can also turn PostgreSQL into a vector database using the pgvector extension.
\nThe combination of vector embeddings and vector databases makes search extremely fast, even with millions of items to search through.\nThis speed makes vector search practical for real-world applications where users expect instant results.
\nTraditional keyword search works like this:
\nThis approach has problems:
\nAn improvement to keyword search is full-text search, which looks at the whole text of documents.\nHowever, this still has some shortcomings that vector search solves.
\nVector search fixes these issues by focusing on meaning rather than exact words.\nIt can:
\nThis is why vector search powers many modern AI applications.\nIt helps chatbots find relevant information and makes recommendation systems more accurate.
\nVector search represents a major step forward in how computers understand and retrieve information.\nBy converting data into number patterns that capture meaning, vector search can find connections that keyword search would miss.
\nThis technology is behind many of the smart search features we now take for granted -\nfrom finding similar products in online stores to helping AI assistants answer our questions.\nAs AI continues to advance, vector search will play an increasingly important role in helping us navigate the growing sea of digital information.
\nWhile not perfect, vector search bridges the gap between how computers store data and how humans think about meaning -\nmaking our digital tools more helpful and intuitive to use.
\nIn a future newsletter, we'll dive into the practical side of vector search.\nYou'll learn how to implement your own vector search system using popular tools and libraries, with step-by-step code examples and best practices.
\nThat's all for today.
\nSee you next week.
\nMediatR, AutoMapper, and MassTransit all announced moves to commercial licensing in 2025.\nThe announcements kept the existing open source versions available, with MassTransit v8 security patches planned through 2026.\nYour options are to buy a license, stay on the current version, switch to alternatives like Mapster or Rebus, or write the functionality yourself.
\nBig changes are happening in the .NET ecosystem.\nThree powerhouse libraries - MediatR, AutoMapper, and MassTransit - are moving to commercial licenses.\nNot so long ago, Fluent Assertions also announced its plans to move to a commercial license.
\nAs someone who's built countless systems with these tools over the past decade, I have thoughts.\nAnd some strong opinions.
\nIf you're a .NET developer, you likely use at least one of these:
\nAutoMapper (794.7M downloads) transforms objects from one type to another.\nIt removes mountains of tedious mapping code that nobody enjoys writing.\nOne line replaces twenty.\nI personally despise AutoMapper and mapping libraries in general, but I can't deny their popularity.
\nMediatR (286.6M downloads) implements the mediator pattern.\nIt decouples requests from the objects handling them, promoting separation of concerns.\nThere's also the pipeline behavior feature, which allows you to add cross-cutting concerns.\nI'm a huge fan and use it regularly in my projects.
\nMassTransit (130.0M downloads) makes distributed messaging simple.\nIt wraps message brokers like RabbitMQ and Azure Service Bus with an elegant API.\nBuilding event-driven systems becomes approachable.\nThis is another tool I love and often recommend.
\nThese libraries aren't just popular - they're transformative.\nThey've shaped how we build .NET applications.
\nBoth announcements tell a similar story.
\n![\"AutoMapper](\"https://milanjovanovic.tech/blogs/mnw_136/mediatr_automapepr_announcement.png\")
\n Jimmy Bogard (AutoMapper, MediatR) writes:
\n\n\nYou can see exactly where my contributions cratered and flat-lined. And that's just commits—issues, PRs, discussions, all my time dried up.
\n
His OSS work was previously sponsored by his former employer.\nWhen he went independent, that support vanished.\nHis focus shifted to his consulting business.
\n![\"Announcing](\"https://milanjovanovic.tech/blogs/mnw_136/masstransit_announcement.png\")
\n Similarly, MassTransit has grown from "a single assembly that supported MSMQ" in 2007 to over thirty NuGet packages.\nIts success created demands that are impossible to meet through volunteer work alone:
\nBoth maintainers face the same dilemma: how do you support widely used libraries when nobody pays you to do it?
\nHere's what's happening:
\nAutoMapper and MediatR: Jimmy hasn't shared specific timing or pricing yet.\nHe states, "Short term, nothing will change."
\nMassTransit: Moving from v8 (open source) to v9 (commercial) with this timeline:
\nMassTransit's pricing targets:
\nNone of this is set in stone.\nThe pricing aspect should be final by the time the commercial version is released.
\nBoth maintainers waited over a decade before making this move.\nThey've contributed immense value to our community for free.
\nTheir announcements show careful consideration.\nThey're not abandoning users:
\nI honestly hope none of the above changes in the future.\nThe work they do is valuable.
\nWriting these libraries from scratch would cost your team far more than their license fees.
\nIf your project uses these libraries, you have choices:
\nPurchase the commercial license
\nThis supports continued development and gets you new features and official support.
Stay on the current open source version
\nMassTransit v8 and current MediatR/AutoMapper will remain available.\nSecurity patches will continue through 2026 for MassTransit.\nFor MassTransit specifically, I'd consider staying on v8 for the long term if possible.
Switch to alternatives
\nFor AutoMapper: consider Mapster or manual mapping (my recommendation).
For MediatR: explore FastEndpoints or build a simple mediator yourself.
\nFor MassTransit: look at raw client libraries like RabbitMQ.Client and\nAzure.Messaging.ServiceBus,\nand another option to consider is Rebus.
\nWrite equivalent functionality yourself
\nMediatR isn't too complex to build on your own.\nI recommend giving it a try as an excellent coding exercise - it's probably the simplest way to move away from MediatR.
For AutoMapper, many teams have deep integrations with business logic in custom mappers.\nThis makes extracting and replacing it difficult.\nExpect significant tech debt if you don't address this.
\nMassTransit, on the other hand, does so many things (and does them well) that migrating away would be challenging.\nSaga support or the request-response messaging\nfeatures are hard to replicate.\nThe only real alternative is diving into raw client libraries for your chosen message transport.
\nEach option involves tradeoffs. The right choice depends on your project needs and budget.
\nThese changes have made me reflect on something important: we should never lose sight of fundamentals.
\nWe've been pampered and spoiled by these awesome libraries.\nIt's easy to lose sight of the actual problems they're solving and how they work under the hood.\nPeople know how to use MediatR, but they don't understand the mechanisms behind it.
\nThe same goes for MassTransit.\nIt abstracts away so many complexities of working with message brokers that it's possible to use it without knowing how RabbitMQ or Azure Service Bus actually works.
\nRemember this: using a library that abstracts something away doesn't excuse you from understanding the patterns and tools you're using.\nThe fundamentals are still there and always have been.\nThis might be the perfect opportunity to deepen your knowledge of what's happening beneath these abstractions.
\nOpen source isn't free. Someone pays - either with time or money.
\nI'm honestly tired of seeing developers complain about these changes.\nWho are they to demand software for free?\nThe entitlement is astounding.\nThese maintainers have provided immense value for over a decade without asking for anything in return.
\nWe've enjoyed years of exceptional tooling without directly funding it.\nNow we face a reckoning.
\nAs businesses reap massive productivity gains from these libraries, it's reasonable to ask: shouldn't some of that value flow back to the creators?
\nI hope these projects thrive under their new models.\nThey've earned support after years of thankless work.
\nBoth my Pragmatic Clean Architecture and\nModular Monolith Architecture courses currently use MediatR and MassTransit extensively.\nI plan to keep them on MediatR v12 and MassTransit v8 in the short term.\nHowever, I'll also be updating them to show migration paths away from these libraries.
\nWhat's your take?\nWill you stick with the open versions, pay for licenses, or explore alternatives?
\nThanks for reading.
\nAnd stay awesome!
\n.NET Aspire skips the centralized service registry and does service discovery through configuration.\nYou declare the relationship in the App Host with WithReference, and Aspire injects the endpoints for each service name.\nYour HttpClient then targets http://weather-api and resolves to the right address in every environment.
Unless you've been living under a rock, you know that .NET Aspire\nis changing (for the better) how we build distributed applications in .NET.\nA simple way to think about Aspire: it makes all the difficult things in software development easy.
\n.NET Aspire is a cloud-native application stack that simplifies the development and deployment of distributed applications.\nOne of the key challenges when building multi-service applications is building reliable communication between services.
\nIn this week's newsletter, I want to focus on one aspect of .NET Aspire - service discovery.\nService discovery lets our services figure out how to locate other services they want to integrate with.\n.NET Aspire tackles this challenge with a simple, configuration-based approach that reduces complexity and boilerplate code.
\nService discovery\nis the process by which services in a distributed application locate and communicate with each other.\nAs applications scale and evolve, keeping track of service endpoints becomes increasingly challenging.\nServices might run on different ports during development or be deployed to different environments in production,\nmaking hard-coded service URLs impractical.
\nTraditional approaches to service discovery often introduce complexity:
\nWhile many service discovery implementations rely on centralized registries,\n.NET Aspire takes a different approach by leveraging application configuration to connect services.\nThis design choice simplifies the development experience while maintaining flexibility for various deployment scenarios.\nAspire automatically takes care of wiring up the correct service URLs and injecting them into your application settings.
\n![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_135/aspire_service_discovery.png\")
\nTo understand how .NET Aspire handles service discovery, let's look at a practical example of an application with multiple services:
\nvar builder = DistributedApplication.CreateBuilder(args);\n\n// Add services to the app\nvar apiService = builder.AddProject<Projects.WeatherApi>("weather-api");\nvar webFrontend = builder.AddProject<Projects.WebFrontend>("web-frontend")\n .WithReference(apiService);\n \nbuilder.Build().Run();\nIn this App Host definition, we're creating two services: a weather API and a web frontend.\nThe .WithReference() method establishes a connection between these services, which enables service discovery.\nThis simple declaration tells .NET Aspire\nthat the web frontend depends on the weather API and needs to communicate with it.\nNote that the web-frontend has to be a server-side application (like Blazor Server)\nfor Aspire to be able to inject the service URL.
With this configuration in place, the web frontend can now reach the API using the service name weather-api\nwithout additional service discovery code:
// Configures the default Aspire services, including service discovery\nbuilder.AddServiceDefaults();\n\n// In Program.cs of the web-frontend project\nbuilder.Services.AddHttpClient("weather-api", (_, client) => {\n // The service name "weather-api" automatically resolves to the correct address\n client.BaseAddress = new Uri("http://weather-api");\n});\nThis works because .NET Aspire manages the mapping between service names and their actual endpoints.\nWhen the application runs, service discovery ensures that requests to http://weather-api are routed to the appropriate destination.
The previous example contains a bit of "magic" that might not be immediately clear.\nThe AddServiceDefaults() method configures the default services for the application, including service discovery.
If we were to configure everything manually, it would look something like this:
\nbuilder.Services.AddServiceDiscovery();\n\nbuilder.Services.AddHttpClient("weather-api", (_, client) => {\n client.BaseAddress = new Uri("http://weather-api");\n})\n.AddServiceDiscovery();\nThe first AddServiceDiscovery() method registers the necessary services to enable service discovery in the application.\nThe second AddServiceDiscovery() method on the HTTP client configures it to use service discovery for resolving the base address.\nThis means that when the HTTP client makes requests to http://weather-api,\nit will automatically resolve the correct endpoint based on the service discovery configuration.
We can also configure service discovery globally for all HTTP clients in the application:
\nbuilder.Services.ConfigureHttpClientDefaults(static http =>\n{\n // Turn on service discovery by default\n http.AddServiceDiscovery();\n});\nThis configuration ensures that all HTTP clients in the application will use service discovery by default,\neliminating the need to configure it for each client individually.
\nWhat Aspire does at runtime for all of this to work is inject a set of configuration values.\nThe configuration value names are derived from the service names we defined in the App Host, plus the respective scheme (http or https).\nHere's an example of what the weather-api configuration might look like:
{\n "Services": {\n "weather-api": {\n "http": [\n "localhost:8080"\n ]\n }\n }\n}\nWe can also configure service discovery to work with HTTPS by adding the https scheme to the service name:
// Specify the https scheme explicitly in the service name\nbuilder.Services.AddHttpClient("weather-api", (_, client) => {\n client.BaseAddress = new Uri("https://weather-api");\n});\n\n// Alternatively, we can use the https+http scheme and let Aspire handle the conversion\nbuilder.Services.AddHttpClient("weather-api-2", (_, client) => {\n client.BaseAddress = new Uri("https+http://weather-api");\n});\nA significant advantage of Aspire's service discovery is its consistent behavior across environments:
\nYour code remains unchanged across these scenarios because the service name abstraction shields you from the underlying networking details.
\nNote that you don't have to use .NET Aspire to benefit from service discovery.\nIt's available as a standalone library (Microsoft.Extensions.ServiceDiscovery) and you can use it in any .NET application.
A powerful application of .NET Aspire's service discovery capabilities is in API gateway scenarios using\nYARP (Yet Another Reverse Proxy).\nLet's explore how to implement this pattern:
\n// In the App Host\nvar apiService = builder.AddProject<Projects.WeatherApi>("weather-api");\nvar userService = builder.AddProject<Projects.UserApi>("user-api");\nvar proxyService = builder.AddProject<Projects.ApiGateway>("api-gateway")\n .WithReference(apiService)\n .WithReference(userService);\nWe'll need to add the YARP NuGet package to the API gateway project:
\nInstall-Package Yarp.ReverseProxy # Adds the YARP package\nInstall-Package Microsoft.Extensions.ServiceDiscovery.Yarp # Adds the YARP service discovery package\nIn the gateway project, we can configure YARP to use service discovery:
\n// In Program.cs of the api-gateway project\nvar builder = WebApplication.CreateBuilder(args);\n\n// Cofigures the service discovery services\nbuilder.Services.AddServiceDiscovery();\n\n// Add YARP services\nbuilder.Services.AddReverseProxy()\n .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))\n // Configures a destination resolver that can use service discovery\n .AddServiceDiscoveryDestinationResolver();\n\nvar app = builder.Build();\n\n// Configure the HTTP request pipeline\napp.MapReverseProxy();\n\napp.Run();\nThe YARP configuration in appsettings.json leverages the service names for endpoint resolution:
{\n "ReverseProxy": {\n "Routes": {\n "weather-route": {\n "ClusterId": "weather-cluster",\n "Match": {\n "Path": "/weather/{**catch-all}"\n },\n "Transforms": [\n { "PathRemovePrefix": "/weather" }\n ]\n },\n "user-route": {\n "ClusterId": "user-cluster",\n "Match": {\n "Path": "/users/{**catch-all}"\n },\n "Transforms": [\n { "PathRemovePrefix": "/users" }\n ]\n }\n },\n "Clusters": {\n "weather-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "http://weather-api"\n }\n }\n },\n "user-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "http://user-api"\n }\n }\n }\n }\n }\n}\nThis configuration creates an API gateway that:
\n/weather/* to the weather API service/users/* to the user API serviceweather-api and user-api) that service discovery resolves at runtimeThe beauty of this approach is that the gateway doesn't need to know the actual endpoints of the backend services.\nIt simply uses the service names, and .NET Aspire handles providing the configuration at runtime.\nThis makes the gateway configuration more portable and easier to maintain as the application evolves.
\n.NET Aspire transforms service discovery from a complex infrastructure challenge into a straightforward configuration concern.\nBy using a configuration-based approach rather than a centralized registry,\nit simplifies the development experience while maintaining the flexibility needed for various deployment scenarios.
\nThe key advantages of Aspire's service discovery include:
\nAs the .NET Aspire stack continues to evolve, its approach to service discovery represents\none of the ways it's making cloud-native development more accessible to .NET developers.\nBy reducing the complexity of service-to-service communication,\nAspire enables teams to focus on building features rather than wrestling with infrastructure concerns.
\nIf you want to explore more robust service discovery solutions for large-scale distributed systems,\ncheck out my previous article on implementing service discovery with Consul.\nIt provides a complementary approach for scenarios that might require a more traditional service registry.
\nFor those who found the YARP integration particularly interesting, my Modular Monolith Architecture\ncourse dives deeper into building scalable applications with YARP as an API gateway.\nYou'll learn how to leverage these patterns to create maintainable,\nevolvable systems regardless of whether you're using microservices or a monolith.
\nThat's all for today.
\nSee you next Saturday.
\nYou validate options with FluentValidation by implementing IValidateOptions<T> that resolves the matching validator from a scoped service provider and maps failures to ValidateOptionsResult.Fail.\nChain ValidateOnStart() when configuring the options, so a bad appsettings.json stops the application from starting instead of failing later at runtime.
If you've worked with the Options Pattern in ASP.NET Core,\nyou're likely familiar with the built-in validation using Data Annotations.\nWhile functional, Data Annotations can be limiting for complex validation scenarios.
\nThe Options Pattern lets you use classes to obtain strongly typed configuration objects at runtime.
\nThe problem? You can't be certain that the configuration is valid until you try to use it.
\nSo why not validate it at application startup?
\nIn this article, we'll explore how to integrate the more powerful FluentValidation\nlibrary with ASP.NET Core's Options Pattern,\nto build a robust validation solution that executes at application startup.
\nData Annotations work well for simple validations, but FluentValidation offers several advantages:
\nBefore diving deep into validation, it's important to understand the lifecycle of options in ASP.NET Core:
\nIOptions<T>, IOptionsSnapshot<T>, or IOptionsMonitor<T>The ValidateOnStart() method forces validation to occur during application startup rather than when options are first resolved.
Without validation, configuration issues can manifest in several ways:
\nBy validating at startup, you create a fast feedback loop that prevents these issues.
\nFirst, let's add the FluentValidation package to our project:
\nInstall-Package FluentValidation # base package\nInstall-Package FluentValidation.DependencyInjectionExtensions # for DI integration\nFor our example, we'll use a GitHubSettings class that requires validation:
public class GitHubSettings\n{\n public const string ConfigurationSection = "GitHubSettings";\n\n public string BaseUrl { get;init; }\n public string AccessToken { get; init; }\n public string RepositoryName { get; init; }\n}\nNext, we'll create a validator for our settings class:
\npublic class GitHubSettingsValidator : AbstractValidator<GitHubSettings>\n{\n public GitHubSettingsValidator()\n {\n RuleFor(x => x.BaseUrl).NotEmpty();\n\n RuleFor(x => x.BaseUrl)\n .Must(baseUrl => Uri.TryCreate(BaseUrl, UriKind.Absolute, out _))\n .When(x => !string.IsNullOrWhiteSpace(x.baseUrl))\n .WithMessage($"{nameof(GitHubSettings.BaseUrl)} must be a valid URL");\n\n RuleFor(x => x.AccessToken)\n .NotEmpty();\n\n RuleFor(x => x.RepositoryName)\n .NotEmpty();\n }\n}\nTo integrate FluentValidation with the Options Pattern, we need to create a custom IValidateOptions<T> implementation:
using FluentValidation;\nusing Microsoft.Extensions.Options;\n\npublic class FluentValidateOptions<TOptions>\n : IValidateOptions<TOptions>\n where TOptions : class\n{\n private readonly IServiceProvider _serviceProvider;\n private readonly string? _name;\n\n public FluentValidateOptions(IServiceProvider serviceProvider, string? name)\n {\n _serviceProvider = serviceProvider;\n _name = name;\n }\n\n public ValidateOptionsResult Validate(string? name, TOptions options)\n {\n if (_name is not null && _name != name)\n {\n return ValidateOptionsResult.Skip;\n }\n\n ArgumentNullException.ThrowIfNull(options);\n\n using var scope = _serviceProvider.CreateScope();\n\n var validator = scope.ServiceProvider.GetRequiredService<IValidator<TOptions>>();\n\n var result = validator.Validate(options);\n if (result.IsValid)\n {\n return ValidateOptionsResult.Success;\n }\n\n var type = options.GetType().Name;\n var errors = new List<string>();\n\n foreach (var failure in result.Errors)\n {\n errors.Add($"Validation failed for {type}.{failure.PropertyName} " +\n $"with the error: {failure.ErrorMessage}");\n }\n\n return ValidateOptionsResult.Fail(errors);\n }\n}\nA few important notes about this implementation:
\n_name propertyWhen adding our custom FluentValidation integration, it's helpful to understand how it connects to ASP.NET Core's options system:
\nIValidateOptions<T> interface is the hook that ASP.NET Core provides for options validationFluentValidateOptions<T> class implements this interface to bridge to FluentValidationValidateOnStart() is called, ASP.NET Core resolves all IValidateOptions<T> implementations and runs themOptionsValidationException is thrown, preventing the application from startingNow, let's create a few extension methods to make our validation easier to use:
\npublic static class OptionsBuilderExtensions\n{\n public static OptionsBuilder<TOptions> ValidateFluentValidation<TOptions>(\n this OptionsBuilder<TOptions> builder)\n where TOptions : class\n {\n builder.Services.AddSingleton<IValidateOptions<TOptions>>(\n serviceProvider => new FluentValidateOptions<TOptions>(\n serviceProvider,\n builder.Name));\n\n return builder;\n }\n}\nThis extension method allows us to call .ValidateFluentValidation() when configuring options, similar to the built-in .ValidateDataAnnotations() method.
For even more convenience, we can create another extension method to simplify the entire configuration process:
\npublic static class ServiceCollectionExtensions\n{\n public static IServiceCollection AddOptionsWithFluentValidation<TOptions>(\n this IServiceCollection services,\n string configurationSection)\n where TOptions : class\n {\n services.AddOptions<TOptions>()\n .BindConfiguration(configurationSection)\n .ValidateFluentValidation() // Configure FluentValidation validation\n .ValidateOnStart(); // Validate options on application start\n\n return services;\n }\n}\nThere are a few ways to use our FluentValidation integration:
\n// Register the validator\nbuilder.Services.AddScoped<IValidator<GitHubSettings>, GitHubSettingsValidator>();\n\n// Configure options with validation\nbuilder.Services.AddOptions<GitHubSettings>()\n .BindConfiguration(GitHubSettings.ConfigurationSection)\n .ValidateFluentValidation() // Configure FluentValidation validation\n .ValidateOnStart();\n// Register the validator\nbuilder.Services.AddScoped<IValidator<GitHubSettings>, GitHubSettingsValidator>();\n\n// Use the convenience extension\nbuilder.Services.AddOptionsWithFluentValidation<GitHubSettings>(GitHubSettings.ConfigurationSection);\nIf you have many validators and want to register them all at once, you can use FluentValidation's assembly scanning:
\n// Register all validators from assembly\nbuilder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);\n\n// Use the convenience extension\nbuilder.Services.AddOptionsWithFluentValidation<GitHubSettings>(GitHubSettings.ConfigurationSection);\nWith .ValidateOnStart(), the application will throw an exception during startup if any validation rules fail.\nFor example, if your appsettings.json is missing the required AccessToken, you'll see something like:
Microsoft.Extensions.Options.OptionsValidationException:\n Validation failed for GitHubSettings.AccessToken with the error: 'Access Token' must not be empty.\nThis prevents your application from even starting with invalid configuration, ensuring issues are caught as early as possible.
\nASP.NET Core's configuration system supports multiple sources.\nWhen using the Options Pattern with FluentValidation, remember that validation works regardless of the source:
\nThis is particularly useful for containerized applications where configuration comes from environment variables or mounted secrets.
\nOne benefit of using FluentValidation is that validators are easy to test:
\n// Uses helper methods from FluentValidation.TestHelper\n[Fact]\npublic void GitHubSettings_WithMissingAccessToken_ShouldHaveValidationError()\n{\n // Arrange\n var validator = new GitHubSettingsValidator();\n var settings = new GitHubSettings { RepositoryName = "test-repo" };\n\n // Act\n TestValidationResult<GitHubSettings>? result = await validator.TestValidate(settings);\n\n // Assert\n result.ShouldHaveValidationErrorFor(x => x.BaseUrl);\n result.ShouldHaveValidationErrorFor(x => x.AccessToken);\n}\nBy combining FluentValidation with the Options Pattern and ValidateOnStart(),\nwe create a powerful validation system that ensures our application has correct configuration at startup.
This approach:
\nThis pattern is particularly valuable in microservice architectures or containerized applications\nwhere configuration errors should be detected immediately rather than at runtime.
\nRemember to register your validators appropriately and use .ValidateOnStart() to ensure validation happens during application startup.
That's all for today.
\nSee you next Saturday.
\nDeploying a .NET 9 app to Azure with GitHub Actions takes two jobs.\nThe first restores, builds, tests, and publishes the app, then uploads the output as an artifact.\nThe second downloads that artifact and pushes it to Azure App Service with azure/webapps-deploy, authenticating with a publish profile stored as a GitHub secret.
I remember the days of deploying .NET applications by hand: publishing locally, copying files to servers, running scripts,\nand crossing my fingers that nothing would break.\nIt was stressful, time-consuming, and honestly, a bit scary.
\nBut those days are over.
\nAfter implementing CI/CD pipelines for dozens of projects,\nI've seen firsthand how automation transforms the deployment process from a dreaded chore into a reliable, even boring, part of development.
\nAnd boring deployments are good deployments.
\nIn this article, I'll walk you through setting up a robust CI/CD pipeline for .NET 9 applications using\nGitHub Actions and Azure App Service.\nI'll cover:
\nWhether you're tired of manual deployments or looking to improve your existing automation,\nthis guide will help you build a robust CI/CD pipeline that you can easily extend to fit your needs.
\nCI/CD stands for Continuous Integration and Continuous Delivery/Deployment.
\nIn simple terms:
\nThe main benefits I've seen:
\nHere's the workflow I use to deploy a simple time service API to Azure App Service:
\n# Name of the workflow as it appears in GitHub Actions UI\nname: Time Service CI\n\n# Define when this workflow will run\non:\n workflow_dispatch: # Allow manual triggering from GitHub UI\n push:\n branches:\n - main # Run automatically when code is pushed to main branch\n\n# Environment variables used throughout the workflow\nenv:\n AZURE_WEBAPP_NAME: time-service\n AZURE_WEBAPP_PACKAGE_PATH: './Time.Api/publish'\n DOTNET_VERSION: '9.x'\n SOLUTION_PATH: 'Time.Api.sln'\n API_PROJECT_PATH: 'Time.Api'\n PUBLISH_DIR: './publish'\n\n# Define the separate jobs that make up this workflow\njobs:\n # First job: build and test the application\n build-and-test:\n name: Build and Test\n runs-on: ubuntu-latest # Use Ubuntu runner for this job\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Setup .NET\n uses: actions/setup-dotnet@v4\n with:\n dotnet-version: ${{ env.DOTNET_VERSION }}\n\n - name: Restore\n run: dotnet restore ${{ env.SOLUTION_PATH }}\n\n - name: Build\n run: dotnet build ${{ env.SOLUTION_PATH }}\n --configuration Release\n --no-restore\n\n - name: Test\n run: dotnet test ${{ env.SOLUTION_PATH }}\n --configuration Release\n --no-restore\n --no-build\n --verbosity normal\n\n\n - name: Publish\n run: dotnet publish ${{ env.API_PROJECT_PATH }}\n --configuration Release\n --no-restore\n --no-build\n --property:PublishDir=${{ env.PUBLISH_DIR }}\n\n # Store the published output as an artifact for later jobs\n - name: Publish Artifacts\n uses: actions/upload-artifact@v4\n with:\n name: webapp # Name of the artifact\n path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}\n\n # Second job: deploy the application to Azure\n deploy:\n name: Deploy to Azure\n runs-on: ubuntu-latest\n needs: [build-and-test] # This job depends on the build-and-test job\n\n steps:\n # Retrieve the artifacts from the build job\n - name: Download artifact from build job\n uses: actions/download-artifact@v4\n with:\n name: webapp\n path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}\n\n # Deploy to Azure App Service using publish profile credentials\n - name: Deploy\n uses: azure/webapps-deploy@v2\n with:\n app-name: ${{ env.AZURE_WEBAPP_NAME }}\n # Authentication credentials stored as a secret\n publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}\n package: '${{ env.AZURE_WEBAPP_PACKAGE_PATH }}'\nThis workflow does two main things: it builds and tests the code and then deploys it to Azure.
\nThe first job checks out our repository, sets up .NET 9, and runs through a standard build process:\nrestore packages, build the solution, run tests, and publish the application.\nThe detailed comments in the YAML explain each step.\nOnce everything passes, it packages the application as an artifact for the next job.
\nThe second job takes that artifact and deploys it to Azure App Service using a publish profile.\nI store the publish profile as a GitHub secret for security.\nThe needs: [build-and-test] line ensures deployment only happens if all tests pass, which protects our production environment from broken code.
![\"An](\"https://milanjovanovic.tech/blogs/mnw_133/ci_cd_pipeline.png\")
\n While the basic workflow gets your application deployed, most real-world projects need more sophisticated pipelines.\nAs your project grows, so should your CI/CD process.\nExtensions to your pipeline could help catch issues earlier, ensure quality standards, and provide better visibility into your development process.
\nHere are some valuable additions to consider:
\nDatabase schema changes can be tricky to coordinate with code deployments.\nThere are several approaches to handling this:
\nUsing EF Core Migration Bundles:
\n- name: Create migration bundle\n run: dotnet ef migrations bundle --project ${{ env.DATA_PROJECT }} --output ${{ env.MIGRATIONS_BUNDLE }}\n\n- name: Apply migrations\n run: ${{ env.MIGRATIONS_BUNDLE }}\nMigration bundles (introduced in EF Core 6.0) package your migrations into a standalone executable,\nmaking them easier to run in deployment pipelines.
\nAdding Manual Review for Migrations:
\ndeploy-database:\n name: Deploy Database Changes\n environment: production\n runs-on: ubuntu-latest\n needs: [build-and-test]\nThis approach adds an environment with protection rules, requiring a DBA to review and approve migration scripts before they run.\nThis is safer for production databases with valuable data.
\nPros:
\nCons:
\nTo minimize risks, I test migrations in a staging environment first and always back up production databases before deployment.
\nI like knowing how much of my code is covered by tests.\nHere's an example of how to generate and publish code coverage reports to Codecov:
\n- name: Generate coverage report\n run: dotnet test ${{ env.SOLUTION_PATH }} /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura\n\n- name: Publish coverage report\n uses: codecov/codecov-action@v5\n with:\n files: ./**/coverage.cobertura.xml\n fail_ci_if_error: true\n token: ${{ secrets.CODECOV_TOKEN }}\nAdding minimum coverage requirements prevents drops in test coverage and encourages the team to maintain quality standards.\nYou can also configure it to fail builds when coverage falls below a threshold.
\nFor larger projects, deploying to multiple environments with approval gates provides better control:
\ndeploy-staging:\n name: Deploy to Staging\n environment: staging\n runs-on: ubuntu-latest\n needs: [build-and-test]\n steps:\n # Deployment steps...\n\ndeploy-production:\n name: Deploy to Production\n environment: production\n runs-on: ubuntu-latest\n needs: [deploy-staging]\n steps:\n # Deployment steps...\nAdding protection rules to your production environment creates checkpoints where team members can verify changes before they reach users.
\nHere's an example of some GitHub Environment protection rules:
\nThese guardrails are especially important for critical environments where downtime can be costly.
\nA good CI/CD pipeline evolves with your project.\nStart simple, focus on automating the most painful manual tasks first, then gradually add more features as needed.
\nThe initial setup takes time, but the long-term benefits are huge.\nMy team now deploys multiple times per day instead of once every few weeks, with fewer bugs reaching production.
\nIf you want to learn more about building robust APIs that complement your CI/CD process, check out my Pragmatic REST APIs course.\nIt covers designing, implementing, and deploying production-ready APIs with best practices that work perfectly with the deployment pipeline we've discussed here.
\nWhat's your CI/CD setup like?\nI'd love to hear how you've customized your workflows for .NET applications.
\nThat's all for today.
\nSee you next week.
\nTo add user context to request tracing in ASP.NET Core, write a middleware that reads the user ID from the authenticated user's claims, tags the current Activity, and opens a logging scope containing the ID.\nEvery log entry and trace in the request then carries the user ID.\nRegister the middleware after authentication and authorization so the user identity is available.
When building web applications, knowing what's happening behind the scenes is crucial.\nIn ASP.NET Core, we can make our lives easier by adding user context to our request tracing.\nThis helps us track issues, understand user behavior, and improve our applications.
\nLet me show you how to enhance your request tracing by adding user context in ASP.NET Core applications.
\nWhen something goes wrong in your application, having the user's ID in your logs makes it much easier to figure out what happened.\nInstead of searching through thousands of log entries, you can filter by user ID and see only the relevant logs.
\nAdding user context also helps with:
\nThe core of our solution is a middleware component that extracts the user ID from the current user's claims and adds it to the current activity and logging scope.
\nA logging scope in ASP.NET Core lets you attach additional data to all log messages created within that scope.\nStructured logging frameworks like Serilog\nand the built-in logger support this feature.\nFor example, if you add a user ID to a logging scope, every log message within that scope will include that user ID,\neven if the log message itself doesn't mention the user.\nThis makes it easy to correlate logs for a specific user across different parts of your application.
\nThe Activity class is part of the .NET diagnostics infrastructure.\nIt represents a unit of work or operation and is designed for distributed tracing across service boundaries.\nWhen you add a tag to Activity.Current, that information becomes part of the trace and can be used to filter and analyze requests in your monitoring systems.
Here's the code:
\nusing System.Diagnostics;\nusing System.Security.Claims;\n\nnamespace MyApp.Middleware;\n\npublic sealed class UserContextEnrichmentMiddleware(\n RequestDelegate next,\n ILogger<UserContextEnrichmentMiddleware> logger)\n{\n public async Task InvokeAsync(HttpContext context)\n {\n string? userId = context.User?.FindFirstValue(ClaimTypes.NameIdentifier);\n if (userId is not null)\n {\n Activity.Current?.SetTag("user.id", userId);\n\n var data = new Dictionary<string, object>\n {\n ["UserId"] = userId\n };\n\n using (logger.BeginScope(data))\n {\n await next(context);\n }\n }\n else\n {\n await next(context);\n }\n }\n}\nLet's break down what this middleware does:
\ncontext.User?.FindFirstValue(ClaimTypes.NameIdentifier)Activity.Current?.SetTag("user.id", userId)ILogger.BeginScope with the user ID, which means all log entries within this scope will include the user IDIf you're using OpenTelemetry to export logs,\nyou have to configure the provider to include the log scopes on the generated log records.
\nHere's how:
\nbuilder.Logging.AddOpenTelemetry(options =>\n{\n options.IncludeScopes = true;\n options.IncludeFormattedMessage = true;\n});\nTo use this middleware in your ASP.NET Core application, add it to your pipeline in the Program.cs file:
app.UseAuthentication();\napp.UseAuthorization();\n\n// Add the user context enrichment middleware after authentication\napp.UseMiddleware<UserContextEnrichmentMiddleware>();\n\napp.MapControllers();\n\napp.Run();\nMake sure to place it after the authentication and authorization middleware so that the user identity is available.
\nWhen adding user IDs to your logs and traces, you need to be careful about Personally Identifiable Information (PII).\nHere are some important points to consider:
\nIf you need to comply with data protection regulations, consider implementing log retention policies and the ability to purge user data from logs when needed.
\nUser IDs are just the beginning.\nWe can add more context to make our logs and traces even more useful:
\nFeature flags help us roll out new features gradually or enable them for specific users.\nAdding feature flag information to our context gives us valuable insights:
\n// Inside the middleware\nif (featureFlagService.IsEnabled("NewFeature", userId))\n{\n Activity.Current?.SetTag("features.newfeature", "enabled");\n // Add to logging scope as well\n}\nIf your application serves multiple tenants, adding tenant IDs is extremely helpful:
\nstring? tenantId = context.User?.FindFirstValue("TenantId");\nif (tenantId is not null)\n{\n Activity.Current?.SetTag("tenant.id", tenantId);\n // Add to logging scope\n}\nAdding user context to your request tracing in ASP.NET Core is a simple but powerful technique.\nBy implementing the middleware we've explored, you'll see several important benefits:
\nUnderstanding logging scopes and the Activity class helps you get the most out of this technique.\nLogging scopes ensure your log entries contain consistent contextual information,\nwhile activities enable distributed tracing across service boundaries.\nRemember to be careful with PII and make sure your logging practices comply with relevant regulations.
Thanks for reading.
\nAnd stay awesome!
\nDapr (Distributed Application Runtime) is a CNCF runtime that runs as a sidecar next to your service and exposes building blocks for state, pub/sub, service invocation, secrets, and more.\nYour code calls Dapr over HTTP or gRPC, and the backing provider is swapped in a YAML component file instead of in code.
\nBuilding distributed systems has never been more important—or more challenging.\nAs .NET developers, we're constantly juggling service discovery,\nstate management,\nmessaging,\nresilience patterns,\nand various infrastructure SDKs.\nOur business logic gets buried under mountains of plumbing code, and we become tightly coupled to specific technologies.
\nWhat if there was a better way?
\nEnter Dapr (Distributed Application Runtime), an open-source project that handles the complex infrastructure challenges so you can focus on what matters most:\nyour application's business logic.
\nIn this article, we'll explore how Dapr transforms microservice development for .NET developers by:
\nWhether you're building your first microservice or evolving a complex system, Dapr offers a simpler path forward.\nLet's explore how it works.
\nDapr is a portable, event-driven runtime that simplifies building microservices.\nAs a graduated project within the Cloud Native Computing Foundation (CNCF), Dapr has proven its value in production environments.
\nAt its core, Dapr provides standardized building blocks that abstract away the complexity of common microservice patterns.\nRather than wrestling with infrastructure-specific code, you can focus on your business logic while Dapr handles the rest.
\nBefore Dapr, building a microservice architecture in .NET might require direct integration with multiple infrastructure components:
\n// Pre-Dapr approach - direct infrastructure dependencies\nbuilder.Services.AddStackExchangeRedisCache(options => { options.Configuration = "redis:6379"; });\n\nbuilder.Services.AddSingleton<IMessageBroker>(provider => new KafkaMessageBroker("kafka:9092"));\n\nbuilder.Services.AddSingleton<ISecretManager>(provider =>\n new AzureKeyVaultClient(new Uri("https://myvault.vault.azure.net")));\nThis approach tightly couples your application to specific technologies.
\nWith Dapr, you gain flexibility through standardized APIs:
\n// Dapr approach - simple, consistent APIs\nbuilder.Services.AddDaprClient();\n\n// Later in code:\n// State management (could be Redis, Cosmos DB, etc.)\nawait daprClient.SaveStateAsync("statestore", "customer-123", customerData);\n\n// Pub/sub (could be Kafka, RabbitMQ, etc.)\nawait daprClient.PublishEventAsync("pubsub", "orders", orderData);\n\n// Secrets (could be Azure Key Vault, HashiCorp Vault, etc.)\nvar secret = await daprClient.GetSecretAsync("secretstore", "api-keys");\nThe underlying providers can be swapped without code changes - just by updating Dapr component configuration files.
\nDapr uses the sidecar architectural pattern,\nwhere it runs as a separate process alongside your application:
\n![\"Dapr](\"https://milanjovanovic.tech/blogs/mnw_131/dapr_sidecar.png\")
\n Your application communicates with the Dapr sidecar through HTTP or gRPC, and Dapr handles communication with infrastructure services.\nThis separation brings several benefits:
\nDapr offers several building blocks that solve common microservice challenges.\nEach provides a standardized API that abstracts away infrastructure complexity:
\nHere's an overview of Dapr's building blocks and the most popular services they interact with:
\n![\"Dapr](\"https://milanjovanovic.tech/blogs/mnw_131/dapr_components.png\")
\n Let's explore the most commonly used building blocks in depth.
\nThe service invocation\nbuilding block enables reliable service-to-service communication with automatic mTLS encryption, retries, and observability.
\nThis solves several challenging microservice problems:
\n![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_131/dapr_service_invocation.png\")
\n Here's a simple example of invoking a service using Dapr's .NET SDK:
\n// Client application making a request\nusing Dapr.Client;\n\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.Services.AddDaprClient();\n\nvar app = builder.Build();\n\napp.MapGet("/checkout/{itemId}", async (int itemId, DaprClient daprClient) =>\n{\n // Create order data\n var orderData = new OrderData(itemId, DateTime.UtcNow);\n\n // Invoke the order-processing service\n var result = await daprClient.InvokeMethodAsync<OrderData, string>(\n "order-processor",\n "process-order",\n orderData);\n\n return Results.Ok(new { Message = $"Order {itemId} processed: {result}" });\n});\n\nawait app.RunAsync();\n\npublic record OrderData(int ItemId, DateTime OrderedAt);\nAnd the corresponding service handling the request:
\nvar builder = WebApplication.CreateBuilder(args);\nvar app = builder.Build();\n\napp.MapPost("/process-order", (OrderData order) =>\n{\n Console.WriteLine($"Processing order {order.ItemId} placed at {order.OrderedAt}");\n return $"Order {order.ItemId} confirmation: #{Guid.NewGuid().ToString()[..8]}";\n});\n\nawait app.RunAsync();\n\npublic record OrderData(int ItemId, DateTime OrderedAt);\nWhat's happening here:
\ncheckout service calls InvokeMethodAsync using the DaprClient to send a request to the order serviceThis process provides automatic service discovery, encryption, retries, and distributed tracing without any additional code.
\nThe publish and subscribe\nbuilding block provides asynchronous messaging between services with at-least-once delivery guarantees.\nThis pattern is essential for building resilient, loosely-coupled microservices that can:
\n![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_131/dapr_publish_subscribe.png\")
\n Pub/Sub in Dapr follows this flow:
\nDapr uses component configuration files to define the pub/sub message broker. Here's a typical Redis pub/sub component:
\napiVersion: dapr.io/v1alpha1\nkind: Component\nmetadata:\n name: order-events\nspec:\n type: pubsub.redis\n version: v1\n metadata:\n - name: redisHost\n value: localhost:6379\n - name: redisPassword\n value: ''\nThe key parts of this configuration are:
\nmetadata.name: The component name (order-events) that your application will reference when publishing/subscribingspec.type: The type of component (pubsub.redis in this case)spec.metadata: Configuration specific to the component typeThis file should be placed in a components directory where Dapr can discover it.\nWhen running locally, this is typically ./components/ relative to your application.
What if you want to switch from Redis to RabbitMQ?\nYou'd replace the spec.type with pubsub.rabbitmq and update the metadata section accordingly.\nThis change doesn't require any code modifications in your application.\nIsn't this flexibility amazing?
Here's how to publish events using Dapr:
\n// Publisher service\nusing Dapr.Client;\n\nvar builder = WebApplication.CreateBuilder(args);\nbuilder.Services.AddDaprClient();\n\nvar app = builder.Build();\n\napp.MapPost("/create-order", async (OrderRequest request, DaprClient daprClient) =>\n{\n var orderEvent = new OrderCreatedEvent(\n request.OrderId,\n request.CustomerId,\n request.Items,\n DateTime.UtcNow\n );\n\n // Publish event to "orders" topic\n await daprClient.PublishEventAsync("order-events", "orders", orderEvent);\n\n return Results.Accepted();\n});\n\nawait app.RunAsync();\n\npublic record OrderRequest(Guid OrderId, string CustomerId, List<string> Items);\npublic record OrderCreatedEvent(Guid OrderId, string CustomerId, List<string> Items, DateTime CreatedAt);\nAnd here's how a subscriber would handle these events:
\n// Subscriber service\nusing Dapr;\nusing Microsoft.AspNetCore.OutputCaching;\n\nvar builder = WebApplication.CreateBuilder(args);\n\n// Add Dapr event handling\nbuilder.Services.AddDapr();\nbuilder.Services.AddControllers();\n\nvar app = builder.Build();\n\n// Required for Dapr pub/sub\napp.UseCloudEvents();\napp.MapSubscribeHandler();\n\n// Subscribe to "orders" topic\napp.MapPost("/events/orders", [Topic("order-events", "orders")] async (OrderCreatedEvent orderEvent) =>\n{\n Console.WriteLine($"Processing order {orderEvent.OrderId} for customer {orderEvent.CustomerId}");\n await ProcessOrderAsync(orderEvent);\n return Results.Ok();\n});\n\nawait app.RunAsync();\n\nasync Task ProcessOrderAsync(OrderCreatedEvent orderEvent)\n{\n // Process the order\n await Task.Delay(100); // Simulate work\n}\n\npublic record OrderCreatedEvent(Guid OrderId, string CustomerId, List<string> Items, DateTime CreatedAt);\nThe key components:
\n[Topic] attributesNote that the name defined in the component file (order-events in our example) must match the first parameter used in\nPublishEventAsync("order-events", ...) and [Topic("order-events", ...)].\nIf these names don't match exactly, messages won't flow correctly between services.
Dapr works seamlessly with .NET Aspire,\nMicrosoft's new cloud-ready stack for building distributed applications.\nWhile Aspire focuses on .NET-specific application orchestration, Dapr provides language-agnostic building blocks.
\nHere's how to integrate Dapr with a .NET Aspire application:
\nusing CommunityToolkit.Aspire.Hosting.Dapr;\n\n// Program.cs in the Aspire AppHost project\nvar builder = DistributedApplication.CreateBuilder(args);\n\n// Add Aspire service and configure Dapr\nvar orderService = builder.AddProject<Projects.OrderService>("orderservice")\n .WithDaprSidecar(new DaprSidecarOptions\n {\n AppId = "order-api",\n Config = "./dapr/config.yaml",\n ResourcesPaths = ["./dapr/components"]\n });\n\n// Add another service that can communicate with the order service via Dapr\nvar checkoutService = builder.AddProject<Projects.CheckoutService>("checkoutservice")\n .WithDaprSidecar(new DaprSidecarOptions\n {\n AppId = "checkout-api",\n Config = "./dapr/config.yaml",\n ResourcesPaths = ["./dapr/components"]\n })\n // Reference the order service by its Dapr app ID\n .WithReference(orderService);\n\nbuilder.Build().Run();\nNote that I'm using the CommunityToolkit.Aspire.Hosting.Dapr package, which is the official Dapr integration for .NET Aspire.\nThe Aspire.Hosting.Dapr library is now deprecated.
Here's an example of how a message flow might look in the Aspire dashboard:
\n![\"A](\"https://milanjovanovic.tech/blogs/mnw_131/dapr_aspire_distributed_trace.png\")
\nIf you're looking for a structured way to learn Dapr, I highly recommend checking out Dapr University.\nYou can run the hands-on lessons completely for free.
\nAs someone who started with limited Dapr experience, I found the "Dapr 101" course particularly valuable.\nIt provides hands-on exercises for State Management, Service Invocation, and Pub/Sub—exactly what you need to get started quickly.
\n![\"Dapr](\"https://milanjovanovic.tech/blogs/mnw_131/dapr_university.png\")
\nDapr simplifies microservice development for .NET developers by providing standardized building blocks that handle infrastructure complexity.\nWith its sidecar pattern, Dapr lets you focus on business logic while it manages cross-cutting concerns.\nAs you build distributed applications, consider how Dapr can help you:
\nReady to dive deeper?\nCheck out Dapr University for comprehensive courses and hands-on learning.
\nThat's all for today. Hope this was helpful.
\nMediatR notifications are not asynchronous in the background-processing sense.\nBoth built-in publishers, ForeachAwaitPublisher and TaskWhenAllPublisher, block the publishing thread until every handler finishes.\nA custom INotificationPublisher backed by a bounded channel returns immediately, but queued notifications are lost if the process crashes.
I've been meaning to write this article for a while now.\nThis problem has been bugging me, and I finally found the time to address it.
\nWhat problem is that?
\nWell, it's about MediatR's notification publishing mechanism.
\nMediatR supports simple in-process publish/subscribe capabilities.\nThis lets you broadcast notifications to multiple handlers without coupling them directly to the publisher.
\nWhile MediatR's notification system appears asynchronous at first glance, it's not.
\nBy asynchronous, I mean that the publishing thread should not wait for all handlers to complete.\nInstead, it should return immediately after queuing the notification for processing.
\nIn this article, we'll understand MediatR's notification publishing mechanics.\nWe'll use distributed tracing to examine its execution model, and explore alternatives for true asynchronous processing.
\nMediatR provides two built-in implementations of its INotificationPublisher interface.\nThey each have distinct characteristics but share one crucial trait: they block the publishing thread until the handlers complete.
Here's the INotificationPublisher interface:
public interface INotificationPublisher\n{\n Task Publish(\n IEnumerable<NotificationHandlerExecutor> handlerExecutors,\n INotification notification,\n CancellationToken cancellationToken);\n}\nThis interface provides the contract for executing notification handlers, but the execution strategy is left to the implementing classes.
\nBy default, MediatR uses the ForeachAwaitPublisher:
public class ForeachAwaitPublisher : INotificationPublisher\n{\n public async Task Publish(\n IEnumerable<NotificationHandlerExecutor> handlerExecutors,\n INotification notification,\n CancellationToken cancellationToken)\n {\n foreach (var handler in handlerExecutors)\n {\n await handler.HandlerCallback(notification, cancellationToken).ConfigureAwait(false);\n }\n }\n}\nThis implementation processes handlers sequentially, ensuring a predictable order of execution.
\nThe alternative TaskWhenAllPublisher offers concurrent execution:
public class TaskWhenAllPublisher : INotificationPublisher\n{\n public Task Publish(\n IEnumerable<NotificationHandlerExecutor> handlerExecutors,\n INotification notification,\n CancellationToken cancellationToken)\n {\n var tasks = handlerExecutors\n .Select(handler => handler.HandlerCallback(notification, cancellationToken))\n .ToArray();\n\n return Task.WhenAll(tasks);\n }\n}\nWhile this publisher executes handlers concurrently, it's crucial to understand that "concurrent" doesn't mean "background processing".\nThe publishing thread still waits for all handlers to complete before continuing.
\nTo demonstrate the blocking nature of both publishers, let's set up a simple example with OpenTelemetry tracing:
\nvar builder = WebApplication.CreateBuilder(args);\n\n// This will register all handlers in the same assembly as the Program class\n// We're also configuring the notifcation publisher\nbuilder.Services.AddMediatR(cfg =>\n{\n cfg.RegisterServicesFromAssemblyContaining<Program>();\n\n cfg.NotificationPublisherType = typeof(ForeachAwaitPublisher);\n // or we could say 👇\n // cfg.NotificationPublisherType = typeof(TaskWhenAllPublisher);\n});\n\nbuilder.Services\n .AddOpenTelemetry()\n .ConfigureResource(r => r.AddService(DiagnosticConfig.Source.Name))\n .WithTracing(tracing =>\n tracing\n .AddAspNetCoreInstrumentation()\n .AddSource(DiagnosticConfig.Source.Name))\n .UseOtlpExporter();\n\nvar app = builder.Build();\n\n// Dummy endpoint to trigger the notification\napp.MapPost("orders", async (IMediator mediator) =>\n{\n using var activity = DiagnosticConfig.Source.StartActivity("CreateOrder");\n\n var orderId = Guid.NewGuid();\n // Just publish the notification, we don't care about doing "real" work here\n await mediator.Publish(new OrderCreatedNotification\n {\n OrderId = orderId,\n ParentId = activity?.Id // Propagating the parent activity ID\n });\n\n return Results.Ok(orderId);\n});\n\napp.Run();\n\n// The simple notification class\npublic class OrderCreatedNotification : INotification\n{\n public Guid OrderId { get; set; }\n public string? ParentId { get; set; }\n}\n\n// A slow handler to simulate blocking behavior\npublic class SlowOrderCreatedHandler(ILogger<SlowOrderCreatedHandler> logger)\n : INotificationHandler<OrderCreatedNotification>\n{\n public async Task Handle(OrderCreatedNotification notification, CancellationToken token)\n {\n using var activity = DiagnosticConfig.Source.StartActivity(\n "SlowOrderCreatedHandler.Handle",\n ActivityKind.Internal,\n notification.ParentId);\n\n await Task.Delay(2000, token); // Simulate work\n\n logger.LogInformation(\n "Slow handler completed for order {OrderId}",\n notification.OrderId);\n }\n}\n\n// Defines the OpenTelemetry ActivitySource\ninternal static class DiagnosticConfig\n{\n internal static readonly ActivitySource Source = new("Order.Service");\n}\nWhen we examine the resulting traces, we'll see that the handler execution spans are contained within the HTTP request span,\nindicating that the request thread is blocked until all handlers complete.
\nNow, let's see how these publishers behave in practice.\nI'll add a few more handlers to the mix to make the example more interesting.
\nYou can see the sequential execution of handlers in the trace visualization.\nThe request span encompasses all handler execution, demonstrating the blocking nature of the ForeachAwaitPublisher.
![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_130/foreachawait_publisher.png\")
\nSimilarly, the TaskWhenAllPublisher shows concurrent handler execution within the request span.\nWe do get a slight improvement in handler execution time, but the request thread still waits for all handlers to complete before returning.
![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_130/taskwhenall_publisher.png\")
\nHow can we make MediatR's notification publishing truly asynchronous?
\nWe'll implement a custom INotificationPublisher that leverages System.Threading.Channels for true asynchronous processing.\nThis implementation will queue notifications for background processing, allowing the publishing thread to return immediately.
Here's the ChannelPublisher:
// The publisher just queues the notification for processing\npublic class ChannelPublisher(NotificationsQueue queue) : INotificationPublisher\n{\n public async Task Publish(\n IEnumerable<NotificationHandlerExecutor> handlerExecutors,\n INotification notification,\n CancellationToken cancellationToken)\n {\n // Write the message to the channel, and return immediately\n await queue.Writer.WriteAsync(\n new NotificationEntry(handlerExecutors.ToArray(), notification),\n cancellationToken);\n }\n}\n\n// It's the Channel that handles the actual message passing\n// We can control the capacity and backpressure handling here\npublic class NotificationsQueue(int capacity = 100)\n{\n private readonly Channel<NotificationEntry> _queue =\n Channel.CreateBounded<NotificationEntry>(new BoundedChannelOptions(capacity)\n {\n FullMode = BoundedChannelFullMode.Wait // Backpressure handling\n });\n\n public ChannelReader<NotificationEntry> Reader => _queue.Reader;\n public ChannelWriter<NotificationEntry> Writer => _queue.Writer;\n}\n\n// A simple data structure to hold the notification and handlers\npublic record NotificationEntry(NotificationHandlerExecutor[] Handlers, INotification Notification);\n\n// Program.cs\nbuilder.Services.AddSingleton<NotificationsQueue>();\nBut this is just part of the solution.\nWe need a background service to process the queued notifications:
\n// We'll use the NotificationsQueue to read and process notifications\npublic class ChannelPublisherWorker(NotificationsQueue queue) : BackgroundService\n{\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n // Read notifications from the queue and process them\n await foreach (NotificationEntry entry in queue.Reader.ReadAllAsync(stoppingToken))\n {\n // Parallel.ForEachAsync for style points\n await Parallel.ForEachAsync(entry.Handlers, stoppingToken, async (executor, token) =>\n {\n // We're finally executing the handler\n await executor.HandlerCallback(entry.Notification, token);\n });\n }\n }\n}\n\n// Program.cs\nbuilser.Services.AddHostedService<ChannelPublisherWorker>();\nThis implementation offers several advantages:
\nTo use this publisher, register it with MediatR by setting the NotificationPublisherType to be ChannelPublisher:
services.AddMediatR(cfg =>\n{\n cfg.NotificationPublisherType = typeof(ChannelPublisher);\n});\nLet's see how this implementation performs in practice.
\nWhen we examine the traces with our ChannelPublisher, we'll see a significant difference:
![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_130/channel_publisher.png\")
\nThis visualization clearly demonstrates the non-blocking nature of our implementation.
\nBut is it worth it?
\nHere's what you should consider first before adopting this approach:
\nChannelPublisher introduces additional complexity compared to the built-in publishersBefore you know it, you might find yourself reinventing the wheel with a custom message queueing system.
\nInstead, consider using a real message broker like RabbitMQ.\nCombine it with a library like MassTransit or NServiceBus for a robust, scalable, and reliable messaging solution.
\nMediatR's notification system is great for simple in-process pub/sub scenarios.\nHowever, the built-in publishers can become a bottleneck in high-throughput applications due to their blocking nature.
\nThe ChannelPublisher implementation we explored offers true asynchronous processing.\nHowever, it also comes with extra complexity around message handling and delivery guarantees.\nManaging message persistence, error handling, retries, and idempotency quickly becomes challenging.
If your application requires these features,\nyou'll be better off adopting a mature solution like RabbitMQ\nor Amazon SQS.
\nThat's all for today. Hope this was helpful.
\nCursor pagination filters on the last row you saw instead of using OFFSET, which forces the database to scan and discard every row before the page you asked for.\nPerformance stays flat no matter how deep you page.\nIn my PostgreSQL tests on a million rows, the same page dropped from 704 ms to 41 ms.
Pagination is crucial for efficiently handling large datasets.\nWhile offset pagination is widely used and gets the job done, cursor-based pagination offers some interesting advantages for certain scenarios.
\nIt's particularly valuable for real-time feeds, infinite scroll interfaces, and APIs where performance at scale matters -\nlike social media timelines, activity logs, or event streams where users frequently page through large datasets.
\nLet's explore both approaches using a simple UserNotes table and see how they perform with a million records.
We'll look at the implementation details, compare query performance, and discuss where each approach makes the most sense.
\nI've included real execution plans from PostgreSQL to demonstrate the significant performance differences between these approaches.
\nI created a simple table to demonstrate pagination techniques.\nThe table is seeded with 1,000,000 records for testing purposes, which should be enough to show the performance difference between offset and cursor pagination.
We'll use the following SQL schema for the examples:
\nCREATE TABLE user_notes (\n id uuid NOT NULL,\n user_id uuid NOT NULL,\n note character varying(500),\n date date NOT NULL,\n CONSTRAINT pk_user_notes PRIMARY KEY (id)\n);\nAnd here's the C# class representing the UserNote entity:
public class UserNote\n{\n public Guid Id { get; set; }\n public Guid UserId { get; set; }\n public string? Note { get; set; }\n public DateOnly Date { get; set; }\n}\nI will use PostgreSQL as the database, but the concepts also apply to other databases.
\nOffset pagination uses Skip and Take operations.\nWe skip a certain number of rows and take a fixed number of rows.\nThese usually translate to OFFSET and LIMIT in SQL queries.
Here's an example of offset pagination in ASP.NET Core:
\napp.MapGet("/offset", async (\n AppDbContext dbContext,\n int page = 1,\n int pageSize = 10,\n CancellationToken cancellationToken = default) =>\n{\n if (page < 1) return Results.BadRequest("Page must be greater than 0");\n if (pageSize < 1) return Results.BadRequest("Page size must be greater than 0");\n if (pageSize > 100) return Results.BadRequest("Page size must be less than or equal to 100");\n\n var query = dbContext.UserNotes\n .OrderByDescending(x => x.Date)\n .ThenByDescending(x => x.Id);\n\n // Offset pagination typically counts the total number of items\n var totalCount = await query.CountAsync(cancellationToken);\n var totalPages = (int)Math.Ceiling(totalCount / (double)pageSize);\n\n // Skip and take the required number of items\n var items = await query\n .Skip((page - 1) * pageSize)\n .Take(pageSize)\n .ToListAsync(cancellationToken);\n\n return Results.Ok(new\n {\n Items = items,\n Page = page,\n PageSize = pageSize,\n TotalCount = totalCount,\n TotalPages = totalPages,\n HasNextPage = page < totalPages,\n HasPreviousPage = page > 1\n });\n});\nNote that I'm sorting the results by Date and Id in descending order.\nThis ensures consistent results when paginating.
Here's the generated SQL for offset pagination:
\n-- This query is sent first\nSELECT count(*)::int FROM user_notes AS u;\n\n-- Followed by the actual data query\nSELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nORDER BY u.date DESC, u.id DESC\nLIMIT @pageSize OFFSET @offset;\nCursor pagination uses a reference point (cursor) to fetch the next set of results.\nThis reference point is typically a unique identifier or a combination of fields that define the sort order.
\nI'll use the Date and Id fields to create a cursor for our UserNotes table.\nThe cursor is a composite of these two fields, allowing us to paginate efficiently.
Here's an example of cursor pagination in ASP.NET Core:
\napp.MapGet("/cursor", async (\n AppDbContext dbContext,\n DateOnly? date = null,\n Guid? lastId = null,\n int limit = 10,\n CancellationToken cancellationToken = default) =>\n{\n if (limit < 1) return Results.BadRequest("Limit must be greater than 0");\n if (limit > 100) return Results.BadRequest("Limit must be less than or equal to 100");\n\n var query = dbContext.UserNotes.AsQueryable();\n\n if (date != null && lastId != null)\n {\n // Use the cursor to fetch the next set of results\n // If we were sorting in ASC order, we'd use > instead of <\n query = query.Where(x => x.Date < date || (x.Date == date && x.Id <= lastId));\n }\n\n // Fetch the items and determine if there are more\n var items = await query\n .OrderByDescending(x => x.Date)\n .ThenByDescending(x => x.Id)\n .Take(limit + 1)\n .ToListAsync(cancellationToken);\n\n // Extract the cursor and ID for the next page\n bool hasMore = items.Count > limit;\n DateOnly? nextDate = hasMore ? items[^1].Date : null;\n Guid? nextLastId = hasMore ? items[^1].Id : null;\n\n // Remove the extra item before returning results\n if (hasMore)\n {\n items.RemoveAt(items.Count - 1);\n }\n\n return Results.Ok(new\n {\n Items = items,\n NextDate = nextDate,\n NextLastId = nextLastId,\n HasMore = hasMore\n });\n});\nThe sort order is the same as in the offset pagination example.\nHowever, the sort order is critical for consistent results with cursor pagination.\nBecause the Date isn't a unique value in our table, we use the Id field to handle ties.\nThis ensures that we don't miss or duplicate items when paginating.
Here's the generated SQL for cursor pagination:
\nSELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nWHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)\nORDER BY u.date DESC, u.id DESC\nLIMIT @limit;\nNote that there's no OFFSET in the query.\nWe're directly seeking the rows based on the cursor, which is more efficient than offset pagination.
The COUNT query is omitted in cursor pagination because we're not counting the total number of items.\nThis can be a limitation if you need to display the total number of pages upfront.\nHowever, the performance benefits of cursor pagination often outweigh this limitation.
I wanted to compare the execution plans for offset and cursor pagination.\nI used the EXPLAIN ANALYZE command in PostgreSQL to see the query plans.
Here's the offset pagination query:
\nSELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nORDER BY u.date DESC, u.id DESC\nLIMIT 1000 OFFSET 900000;\nI'm intentionally skipping 900,000 rows to exaggerate the performance impact.\nAfter that, we fetch the next 1,000 rows.
Here's the query plan for offset pagination:
\nEXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nORDER BY u.date DESC, u.id DESC\nLIMIT 1000 OFFSET 900000;\n\n---\nLimit (cost=165541.59..165541.71 rows=1 width=52) (actual time=695.026..701.406 rows=1000 loops=1)\n -> Gather Merge (cost=68312.50..165541.59 rows=833334 width=52) (actual time=342.475..684.567 rows=901000 loops=1)\n Workers Planned: 2\n Workers Launched: 2\n -> Sort (cost=67312.48..68354.15 rows=416667 width=52) (actual time=327.846..450.295 rows=300841 loops=3)\n Sort Key: date DESC, id DESC\n Sort Method: external merge Disk: 20440kB\n Worker 0: Sort Method: external merge Disk: 18832kB\n Worker 1: Sort Method: external merge Disk: 18912kB\n -> Parallel Seq Scan on user_notes u (cost=0.00..14174.67 rows=416667 width=52) (actual time=1.035..22.876 rows=333333 loops=3)\nPlanning Time: 0.050 ms\nJIT:\n Functions: 8\n Options: Inlining false, Optimization false, Expressions true, Deforming true\n Timing: Generation 0.243 ms (Deform 0.111 ms), Inlining 0.000 ms, Optimization 0.270 ms, Emission 4.085 ms, Total 4.598 ms\nExecution Time: 704.217 ms\nThe total execution time is 704.217 ms for offset pagination.
Here's the query returning the same set of rows using cursor pagination.\nI had to hardcode the @date and @lastId values for this comparison:
SELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nWHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)\nORDER BY u.date DESC, u.id DESC\nLIMIT 1000;\nFinally, here's the query plan for cursor pagination:
\nEXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nWHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)\nORDER BY u.date DESC, u.id DESC\nLIMIT 1000;\n\n---\nLimit (cost=20605.63..20722.31 rows=1000 width=52) (actual time=37.993..40.958 rows=1000 loops=1)\n -> Gather Merge (cost=20605.63..30419.62 rows=84114 width=52) (actual time=37.992..40.921 rows=1000 loops=1)\n Workers Planned: 2\n Workers Launched: 2\n -> Sort (cost=19605.61..19710.75 rows=42057 width=52) (actual time=24.611..24.630 rows=811 loops=3)\n Sort Key: date DESC, id DESC\n Sort Method: top-N heapsort Memory: 240kB\n Worker 0: Sort Method: top-N heapsort Memory: 239kB\n Worker 1: Sort Method: top-N heapsort Memory: 238kB\n -> Parallel Seq Scan on user_notes u (cost=0.00..17299.67 rows=42057 width=52) (actual time=0.009..21.462 rows=33333 loops=3)\n Filter: ((date < @date::date) OR ((date = @date::date) AND (id <= @lastId::uuid)))\n Rows Removed by Filter: 300000\nPlanning Time: 0.063 ms\nExecution Time: 40.993 ms\nThe total execution time for cursor pagination is 40.993 ms.
A whopping 17x performance improvement with cursor pagination compared to offset pagination!
The performance with cursor pagination is consistent regardless of the page depth.\nThis is because we're directly seeking the rows based on the cursor, which is more efficient than offset pagination.\nIt's a huge advantage over offset pagination, especially for large datasets.
\nI also tested the impact of indexes on cursor pagination.\nI created a composite index on the Date and Id fields to speed up the queries.\nOr so I thought...
Here's the SQL command to create the composite index:
\nCREATE INDEX idx_user_notes_date_id ON user_notes (date DESC, id DESC);\nThe index is created in descending order to match the sort order in our queries.
\nLet's see the query plan for cursor pagination with the composite index:
\nEXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nWHERE u.date < @date OR (u.date = @date AND u.id <= @lastId)\nORDER BY u.date DESC, u.id DESC\nLIMIT 1000;\n\n---\nLimit (cost=0.42..816.55 rows=1000 width=52) (actual time=298.534..298.924 rows=1000 loops=1)\n -> Index Scan using idx_user_notes_date_id on user_notes u (cost=0.42..82376.42 rows=100936 width=52) (actual time=298.532..298.888 rows=1000 loops=1)\n Filter: ((date < @date::date) OR ((date = @date::date) AND (id <= @lastId::uuid)))\n Rows Removed by Filter: 900000\nPlanning Time: 0.068 ms\nExecution Time: 298.955 ms\nWe have an Index Scan using the composite index.\nHowever, the execution time is 298.955 ms, which is slower than the previous query without the index.
This might be because the dataset is too small to benefit from the index.\nI have only 1,000,000 records in the table, which might not be enough to see the performance improvement with the index.
But wait, there's more to it!
\nWhat if we were to use a tuple comparison in SQL?
\nEXPLAIN ANALYZE SELECT u.id, u.date, u.note, u.user_id\nFROM user_notes AS u\nWHERE (u.date, u.id) <= (@date, @lastId)\nORDER BY u.date DESC, u.id DESC\nLIMIT 1000;\n\n---\nLimit (cost=0.42..432.81 rows=1000 width=52) (actual time=0.020..0.641 rows=1000 loops=1)\n -> Index Scan using idx_user_notes_date_id on user_notes u (cost=0.42..43817.85 rows=101339 width=52) (actual time=0.019..0.606 rows=1000 loops=1)\n Index Cond: (ROW(date, id) <= ROW(@date::date, @lastId::uuid))\nPlanning Time: 0.060 ms\nExecution Time: 0.668 ms\nFinally, the index is working.\nThe execution time is 0.668 ms, which is significantly faster than the previous queries.
The query optimizer cannot determine whether the composite index can be used for row-level comparison.\nHowever, the index is effectively used with a tuple comparison.
\nHow do you translate this to EF Core?
\nThe Postgres provider has EF.Functions.LessThanOrEqual, which accepts a ValueTuple as an argument.\nWe can use it to produce a (u.date, u.id) <= (@date, @lastId) comparison in the query.\nAnd this will utilize the composite index.
query = query.Where(x => EF.Functions.LessThanOrEqual(\n ValueTuple.Create(x.Date, x.Id),\n ValueTuple.Create(date, lastId)));\nHere's a small utility class for encoding and decoding the cursor.\nWe'll use this to encode the cursor in the URL and decode it when fetching the next set of results.
\nThe clients will receive the cursor as a Base64-encoded string.\nThey don't need to know the internal structure of the cursor.
\nusing Microsoft.AspNetCore.Authentication; // For Base64UrlTextEncoder\n\npublic sealed record Cursor(DateOnly Date, Guid LastId)\n{\n public static string Encode(DateOnly date, string lastId)\n {\n var cursor = new Cursor(date, lastId);\n string json = JsonSerializer.Serialize(cursor);\n return Base64UrlTextEncoder.Encode(Encoding.UTF8.GetBytes(json));\n }\n\n public static Cursor? Decode(string? cursor)\n {\n if (string.IsNullOrWhiteSpace(cursor))\n {\n return null;\n }\n\n try\n {\n string json = Encoding.UTF8.GetString(Base64UrlTextEncoder.Decode(cursor));\n return JsonSerializer.Deserialize<Cursor>(json);\n }\n catch\n {\n return null;\n }\n }\n}\nHere's an example of encoding and decoding the cursor:
\nstring encodedCursor = Cursor.Encode(\n new DateOnly(2025, 2, 15),\n Guid.Parse("019500f9-8b41-74cf-ab12-25a48d4d4ab4"));\n// Result:\n// eyJEYXRlIjoiMjAyNS0wMi0xNSIsIkxhc3RJZCI6IjAxOTUwMGY5LThiNDEtNzRjZi1hYjEyLTI1YTQ4ZDRkNGFiNCJ9\n\nCursor decodedCursor = Cursor.Decode(encodedCursor);\n// Result:\n// {\n// "Date": "2025-02-15",\n// "LastId": "019500f9-8b41-74cf-ab12-25a48d4d4ab4"\n// }\nWhile offset pagination is simpler to implement, it suffers from significant performance degradation at scale.\nMy tests showed a 17x slowdown compared to cursor pagination when accessing deeper pages.
\nCursor pagination maintains consistent performance regardless of page depth and works particularly well for real-time feeds and infinite scroll interfaces.
\nHowever, cursor pagination comes with tradeoffs.\nIt requires careful implementation, especially around cursor encoding and handling sort orders.\nIt also doesn't provide total page counts, making it unsuitable for interfaces that need to support paged navigation.
\nThe choice between these approaches ultimately depends on your use case:
\nAnother thing to consider: which page will your users typically land on?\nIf most users start at the first page and rarely visit other pages, offset pagination might be sufficient.\nThis will be the case for many applications.
\nRemember to use tuple comparisons and appropriate indexes to get the best performance from cursor pagination.
\nThat's all for today.
\nSee you next week.
\nCQRS is an architectural pattern that separates read and write models, and it prescribes no specific library.\nMediatR is a different tool: it implements the mediator pattern for in-process messaging and pipeline behaviors.\nYou can implement CQRS with your own ICommandHandler and IQueryHandler interfaces and never install MediatR.
"We need to implement CQRS? Great, let me install MediatR."
\nIf you've heard this in your development team - or perhaps said it yourself - you're not alone.\nThe .NET ecosystem has gradually fused these two concepts together, creating an almost reflexive response: CQRS equals MediatR.
\nThis mental shortcut has led countless teams down a path of unnecessary complexity.\nOthers have avoided CQRS entirely, fearing the overhead of yet another messaging framework.
\nIn this article, we'll dispel some common misconceptions and highlight the benefits of each pattern.
\nCQRS is a pattern that separates read and write operations in your application.\nThe pattern suggests that the models used for reading data should be different from those used for writing data.
\nThat's it.
\nNo specific implementation details, no prescribed libraries, just a simple architectural principle.
\nThe pattern emerged from the understanding that in many applications, especially those with complex domains,\nthe requirements for reading and writing data are fundamentally different.\nRead operations often need to combine data from multiple sources or present it in specific formats for UI consumption.\nWrite operations need to enforce business rules, maintain consistency, and manage domain state.
\nThis separation provides several benefits:
\nMediatR is an implementation of the mediator pattern.\nIts primary purpose is to reduce direct dependencies between components by providing a central point of communication.\nInstead of knowing about each other, the mediator connects the components.
\nThe library provides several features:
\nThe indirection MediatR introduces is its most criticized aspect.\nIt can make code harder to follow, especially for newcomers to the codebase.\nHowever, you can easily solve this problem by defining the requests in the same file as the handler.
\nThe frequent pairing of CQRS and MediatR isn't without reason.\nMediatR's request/response model aligns well with CQRS's command/query separation.\nCommands and queries can be implemented as MediatR requests, with handlers containing the actual implementation logic.
\nHere's an example command using MediatR:
\npublic record CreateHabit(string Name, string? Description, int Priority) : IRequest<HabitDto>;\n\npublic sealed class CreateHabitHandler(ApplicationDbContext dbContext, IValidator<CreateHabit> validator)\n : IRequestHandler<CreateHabit, HabitDto>\n{\n public async Task<HabitDto> Handle(CreateHabit request, CancellationToken cancellationToken)\n {\n await validator.ValidateAndThrowAsync(request);\n\n Habit habit = request.ToEntity();\n\n dbContext.Habits.Add(habit);\n\n await dbContext.SaveChangesAsync(cancellationToken);\n\n return habit.ToDto();\n }\n}\nCQRS with MediatR offers several advantages:
\nHowever, this convenience comes at the cost of additional abstraction and complexity.\nWe have to define the request/response classes and handlers, write code for sending the requests, and so on.\nThis can be overkill for simple applications.
\nThe question isn't whether this trade-off is universally good or bad but whether it's appropriate for your specific context.
\nCQRS can be implemented just as easily without MediatR.\nHere's a simple example of what it might look like.
\nYou can define commands and queries as simple interfaces:
\npublic interface ICommandHandler<in TCommand, TResult>\n{\n Task<TResult> Handle(TCommand command, CancellationToken cancellationToken = default);\n}\n\n// Same thing for IQueryHandler\nThen, you can implement your handlers and register them with dependency injection:
\npublic record CreateOrderCommand(string CustomerId, List<OrderItem> Items)\n : ICommand<CreateOrderResult>;\n\npublic class CreateOrderCommandHandler : ICommandHandler<CreateOrderCommand, CreateOrderResult>\n{\n public async Task<CreateOrderResult> Handle(\n CreateOrderCommand command,\n CancellationToken cancellationToken = default)\n {\n // implementation\n }\n}\n\n// DI registration...\nbuilder.Services\n .AddScoped<ICommandHandler<CreateOrderCommand, CreateOrderResult>, CreateOrderCommandHandler>();\nFinally, you can use the handler in your controller:
\n[ApiController]\n[Route("orders")]\npublic class OrdersController : ControllerBase\n{\n [HttpPost]\n public async Task<ActionResult<CreateOrderResult>> CreateOrder(\n CreateOrderCommand command,\n ICommandHandler<CreateOrderCommand, CreateOrderResult> handler)\n {\n var result = await handler.Handle(command);\n\n return Ok(result);\n }\n}\nWhat's the difference between this and the MediatR approach?
\nThis approach provides the same separation of concerns but without the indirection.\nIt's direct, explicit, and often sufficient for many applications.
\nHowever, it lacks some of the conveniences that MediatR offers, such as pipeline behaviors and automatically registering handlers.\nYou also need to inject the specific handlers into your controllers, which can be cumbersome for larger applications.
\nCQRS and MediatR are distinct tools that solve different problems.\nWhile they can work well together, treating them as inseparable does a disservice to both.\nCQRS separates read and write concerns, while MediatR decouples components through a mediator.
\nThe key is understanding what each pattern offers and making informed decisions based on your specific context.\nSometimes, you'll want both, sometimes just one, and sometimes neither.\nThat's the essence of thoughtful architecture: choosing the right tools for your specific needs.
\nIf you want to learn more about implementing CQRS effectively as part of a clean,\nmaintainable architecture, check out Pragmatic Clean Architecture.\nYou'll learn how to apply these patterns in real-world scenarios, avoiding common pitfalls and over-engineering while building scalable applications.
\nThat's all for today. Hope this was helpful.
\nConfigureHttpClientDefaults with AddStandardResilienceHandler applies one Polly pipeline to every HttpClient, and it overrides any per-client pipeline you add afterwards.\nThe workaround is an extension method that strips every ResilienceHandler from the client before you add your own.\nThe .NET team merged a pull request adding proper support for a future release.
Introducing .NET 8 resilience packages\nbuilt on top of Polly\nhas made it much easier to build robust HTTP clients.\nThese packages provide standard resilience handlers that you can easily attach to HttpClient instances.\nThey implement common patterns like retry, circuit breaker, and timeout policies.
However, there is a significant limitation: once you configure the standard resilience handlers globally for all clients,\nthere is no built-in way to override them for specific cases.\nThis can be problematic when different endpoints require different resilience strategies.
\nIn today's issue, I'll show you how to fix this and what the .NET team is doing about it.
\nLet's say you've configured default resilience handlers in your application startup.\nConfigureHttpClientDefaults is a convenient way to add standard resilience handlers to all HttpClient instances:
builder.Services\n .AddHttpClient()\n .ConfigureHttpClientDefaults(http => http.AddStandardResilienceHandler());\nThe .NET team runs many large-scale services in production, and they've found a standard set of resilience strategies that work\nwell for most scenarios.
\nThe standard resilience handler combines five strategies to create a resilience pipeline:
\nYou can customize the standard resilience pipeline by configuring the HttpStandardResilienceOptions.
Here's an example of how to configure it:
\nbuilder.Services.ConfigureHttpClientDefaults(http => http.AddStandardResilienceHandler(options =>\n{\n // Default is 2 seconds.\n options.Retry.Delay = TimeSpan.FromSeconds(1);\n\n // Default is 30 seconds.\n options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(20);\n\n // Default is 0.1.\n options.CircuitBreaker.FailureRatio = 0.2;\n}));\nOkay, so we have our standard resilience pipeline set up.\nNow all your HttpClient instances will use these resilience policies.
But what if you need different retry logic for a specific API endpoint or need to turn off circuit breaking for specific calls?
\nLet's say you have a named HttpClient for calling the GitHub API,\nand you want to configure specific resilience strategies for it:
builder.Services\n .AddHttpClient("github")\n .ConfigureHttpClient(client =>\n {\n client.BaseAddress = new Uri("https://api.github.com");\n })\n .AddResilienceHandler("custom", pipeline =>\n {\n pipeline.AddTimeout(TimeSpan.FromSeconds(10));\n\n pipeline.AddRetry(new HttpRetryStrategyOptions\n {\n MaxRetryAttempts = 3,\n BackoffType = DelayBackoffType.Exponential,\n UseJitter = true,\n Delay = TimeSpan.FromMilliseconds(500)\n });\n\n pipeline.AddTimeout(TimeSpan.FromSeconds(1));\n });\nThe custom policy won't be applied because we have a global resilience pipeline that overrides it.
This is a big oversight in the current implementation of the .NET resilience packages.
\nThe solution is to create an extension method that clears all handlers from the resilience pipeline.\nThis allows you to remove the default handlers and add your custom ones.
\nHere's how to implement it:
\npublic static class ResilienceHttpClientBuilderExtensions\n{\n public static IHttpClientBuilder RemoveAllResilienceHandlers(this IHttpClientBuilder builder)\n {\n builder.ConfigureAdditionalHttpMessageHandlers(static (handlers, _) =>\n {\n for (int i = handlers.Count - 1; i >= 0; i--)\n {\n if (handlers[i] is ResilienceHandler)\n {\n handlers.RemoveAt(i);\n }\n }\n });\n return builder;\n }\n}\nNow you can use this extension method to implement custom resilience strategies:
\nbuilder.Services\n .AddHttpClient("github")\n .ConfigureHttpClient(client =>\n {\n client.BaseAddress = new Uri("https://api.github.com");\n })\n .RemoveAllResilienceHandlers()\n .AddResilienceHandler("custom", pipeline =>\n {\n // Configure the custom resilience pipeline...\n });\n\n// Or use another standard resilience pipeline...\nbuilder.Services\n .AddHttpClient("github-hedged")\n .RemoveAllResilienceHandlers()\n .AddStandardHedgingHandler();\nThe .NET team is aware of this limitation, and better support for overriding default resilience handlers is planned for an upcoming release.\nThe pull request for this API is merged and should be available in a future release.
\nUntil then, this workaround using RemoveAllResilienceHandlers is a drop-in replacement for the missing feature.
The ability to override default resilience handlers is much needed when building robust distributed systems.\nWhile .NET's standard resilience handlers provide excellent defaults, real-world applications often require fine-tuned resilience strategies for different services.\nThe extension method presented here bridges this gap, allowing you to maintain both global defaults and specialized configurations where needed.
\nWant to dive deeper into building resilient cloud applications?\nCheck out my article about building resilient cloud applications with .NET.
\nGood luck out there, and see you next week.
\nAES encryption in C# starts with Aes.Create(), a 256-bit key size, and a fresh random key and IV for every operation.\nEncrypt through a CryptoStream, then store the IV with the ciphertext and keep the key in a key management service such as Azure Key Vault.
A single exposed API key or database password can compromise your entire infrastructure.\nYet many developers still store sensitive data with basic encoding or weak encryption.
\nProperly implemented encryption is your last line of defense.\nWhen other security measures fail, it ensures stolen data remains unreadable.\nThis is especially crucial for API keys, database credentials, and user secrets that grant direct access to your systems.
\nIn today's issue, we will cover implementing AES encryption in .NET with practical code examples and essential security considerations.
\nSymmetric encryption (like AES) uses the same key for encryption and decryption.\nIt's fast and ideal for storing data that only your application needs to read.\nThe main challenge is securely storing the encryption key.
\nAsymmetric encryption (like RSA) uses different keys for encryption and decryption.\nIt's slower but allows secure communication between parties who don't share secrets.\nCommon uses include SSL/TLS and digital signatures.
\nFor storing API keys and application secrets, symmetric encryption with AES is the appropriate choice.
\n![\"AES](\"https://milanjovanovic.tech/blogs/mnw_126/aes_encryption.png\")
\n Let's examine a secure AES (Advanced Encryption Standard) encryption implementation in C#.\nThis implementation uses AES-256, which provides the strongest security currently available in the AES standard.
\npublic class Encryptor\n{\n private const int KeySize = 256;\n private const int BlockSize = 128;\n\n public static EncryptionResult Encrypt(string plainText)\n {\n // Generate a random key and IV\n using var aes = Aes.Create();\n aes.KeySize = KeySize;\n aes.BlockSize = BlockSize;\n\n // Generate a random key and IV for each encryption operation\n aes.GenerateKey();\n aes.GenerateIV();\n\n byte[] encryptedData;\n\n // Create encryptor and encrypt the data\n using (var encryptor = aes.CreateEncryptor())\n using (var msEncrypt = new MemoryStream())\n {\n using (var csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write))\n using (var swEncrypt = new StreamWriter(csEncrypt))\n {\n swEncrypt.Write(plainText);\n }\n\n encryptedData = msEncrypt.ToArray();\n }\n\n // Package everything together, storing IV with the encrypted data\n var result = EncryptionResult.CreateEncryptedData(\n encryptedData,\n aes.IV,\n Convert.ToBase64String(aes.Key)\n );\n\n return result;\n }\n}\n\npublic class EncryptionResult\n{\n // The IV is prepended to the encrypted data\n public string EncryptedData { get; set; }\n public string Key { get; set; }\n\n public static EncryptionResult CreateEncryptedData(byte[] data, byte[] iv, string key)\n {\n // Combine IV and encrypted data\n var combined = new byte[iv.Length + data.Length];\n Array.Copy(iv, 0, combined, 0, iv.Length);\n Array.Copy(data, 0, combined, iv.Length, data.Length);\n\n return new EncryptionResult\n {\n EncryptedData = Convert.ToBase64String(combined),\n Key = key\n };\n }\n\n public (byte[] iv, byte[] encryptedData) GetIVAndEncryptedData()\n {\n var combined = Convert.FromBase64String(EncryptedData);\n\n // Extract IV and data\n var iv = new byte[16]; // AES block size is 16 bytes (128 / 8)\n var encryptedData = new byte[combined.Length - 16];\n\n Array.Copy(combined, 0, iv, 0, 16);\n Array.Copy(combined, 16, encryptedData, 0, encryptedData.Length);\n\n return (iv, encryptedData);\n }\n}\nLet's break down what's happening in this implementation:
\nCryptoStream for efficient encryption of potentially large data.\nThe stream pattern ensures we don't load everything into memory at once.EncryptionResult class provides a way to package the encrypted data with its key and IV.\nIn production, the key should be stored separately in a key management service.Here's the corresponding decryption implementation:
\npublic class Decryptor\n{\n private const int KeySize = 256;\n private const int BlockSize = 128;\n\n public static string Decrypt(EncryptionResult encryptionResult)\n {\n var key = Convert.FromBase64String(encryptionResult.Key);\n var (iv, encryptedData) = encryptionResult.GetIVAndEncryptedData();\n\n using var aes = Aes.Create();\n aes.KeySize = KeySize;\n aes.BlockSize = BlockSize;\n aes.Key = key;\n aes.IV = iv;\n\n // Create decryptor and decrypt the data\n using var decryptor = aes.CreateDecryptor();\n using var msDecrypt = new MemoryStream(encryptedData);\n using var csDecrypt = new CryptoStream(msDecrypt, decryptor, CryptoStreamMode.Read);\n using var srDecrypt = new StreamReader(csDecrypt);\n\n try\n {\n return srDecrypt.ReadToEnd();\n }\n catch (CryptographicException ex)\n {\n // Log the error securely - avoid exposing details\n throw new CryptographicException("Decryption failed", ex);\n }\n }\n}\nThe decryption process reverses the encryption steps.\nNote the error handling - we catch cryptographic exceptions but avoid exposing details that could help an attacker.\nIn production, you should log these errors securely for debugging while keeping security in mind.
\nHere's an example of encrypting and decrypting sensitive data using the implementations above:
\n// Encrypt sensitive data\nvar apiKey = "your-sensitive-api-key";\nvar encryptionResult = Encryptor.Encrypt(apiKey);\n\n// Output example: DCGT9kEwPglBonWWPa7PQPbr2I+6rskJ0lSFybbicvZ+wKMTU7cbJD2s3QSF2Yu6\n\n// Store encrypted data in database\n// IV is stored with the encrypted data\nSaveToDatabase(encryptionResult.EncryptedData);\n\n// Store key in key vault\nawait keyVault.StoreKeyAsync("apikey_1", encryptionResult.Key);\n\n// Later, decrypt when needed\n// IV is retrieved from the encrypted data\nvar encryptedData = LoadFromDatabase();\nvar key = await keyVault.GetKeyAsync("apikey_1");\n\nvar result = new EncryptionResult\n{\n EncryptedData = encryptedData,\n Key = key,\n IV = iv\n};\n\nvar decrypted = Decryptor.Decrypt(result);\nAES encryption provides strong security for sensitive application data when implemented correctly.
\nProper key management is very important.\nUse a dedicated key storage service in production.\nPopular options include Azure Key Vault,\nAWS Key Management Service, and\nHashiCorp Vault.
\nIn my Pragmatic REST APIs course, I cover secure data storage and encryption in more detail.\nThese are critical aspects of building secure and robust APIs and integrating with third-party APIs.\nCheck it out if you're interested in learning more.
\nRemember that encryption is just one part of a comprehensive security strategy.\nKeep your encryption keys separate from encrypted data and rotate them regularly.
\nThanks for reading.
\nAnd stay awesome!
\nA well-designed monolith scales well without moving to microservices.\nStart by tuning queries and adding caching, scale the machine up while that stays cost-effective, then run several stateless instances behind a load balancer.\nDatabase pressure goes to read replicas, materialized views, and eventually sharding, with message queues absorbing traffic spikes.
\nMonoliths get a bad rap in our industry.\nWe're told they're legacy, that they don't scale, and that we need microservices to succeed.\nAfter spending many years scaling systems from startups to enterprises, I can tell you this isn't true.\nA well-designed monolith is often the right architecture choice, and it can scale remarkably well with the right approach.
\nIn my experience building and scaling monolithic systems, I've found that the key to success isn't following trends.\nIt's understanding your scaling needs and applying the right solutions at the right time.\nIn this article, I'll share what I've learned about scaling monoliths effectively and when to use each approach.
\nA monolith puts all your code in one deployable unit.\nThis brings significant advantages: faster development cycles, simpler debugging, and straightforward deployments.\nBut as your system grows, you'll face scaling challenges.
\n![\"Simple](\"https://milanjovanovic.tech/blogs/mnw_125/monolith_system.png\")
\nYour database queries slow down as data volume grows. API endpoints that worked\nfine with hundreds of users start timing out with thousands. Build times creep\nup as your codebase expands. These are natural growing pains that every\nsuccessful system faces.
\nVertical scaling means giving your application more resources on a single machine.\nIt's the simplest scaling strategy and often the most effective first step.\nBefore diving into complex distributed systems, consider whether upgrading your existing infrastructure could solve your performance problems.
\n![\"Example](\"https://milanjovanovic.tech/blogs/mnw_125/vertical_scaling.png\")
\nVertical scaling works particularly well when there are clear resource bottlenecks.\nIf your CPU is consistently above 80% utilization, adding more cores will help.\nIf your database is I/O bound, upgrading to faster storage can dramatically improve performance.\nModern cloud platforms make this especially straightforward.\nYou can often upgrade with a few clicks and minimal downtime.
\nThe benefits of vertical scaling extend beyond just performance.\nIt maintains your system's simplicity.\nYou don't need to redesign your architecture, implement new deployment patterns, or manage distributed system complexity.\nYour monitoring, debugging, and operational procedures all stay the same.
\nHowever, vertical scaling does have limits.\nYou'll eventually hit a ceiling on what a single machine can handle.\nCloud providers have maximum instance sizes, and costs typically increase exponentially with larger instances.\nMore importantly, vertical scaling doesn't provide redundancy - you're still running on a single machine that represents a potential single point of failure.
\nKnowing when to move beyond vertical scaling is crucial.\nWatch for these indicators:
\nHorizontal scaling runs multiple instances of your application behind a load balancer.\nIt's the next step when vertical scaling reaches its limits.\nIt offers improved fault tolerance and nearly linear scaling capabilities.
\n![\"Example](\"https://milanjovanovic.tech/blogs/mnw_125/horizontal_scaling.png\")
\nThe key to successful horizontal scaling lies in application design.\nYour application must be stateless - each request should contain all the information needed to process it.
\nThis means:
\nLoad balancers are crucial in this architecture.\nWhether you call it an API Gateway, Reverse Proxy, or Load Balancer, its job is to distribute traffic across your application instances.\nPopular choices include:
\nHorizontal scaling provides several key benefits:
\nThe main challenge in horizontal scaling isn't technical—it's architectural.\nYour application needs to be designed for horizontal scaling from the start.\nConverting a stateful application to a stateless one often requires significant refactoring.
\nDatabase scaling is where most monoliths first hit real limitations.\nLet's explore each scaling strategy in detail.
\nRead replicas are often your first step in database scaling but come with significant trade-offs.\nRead replicas maintain a copy of your primary database that serves read-only traffic.\nWhen you run a query against a replica, you're not competing with writes on your primary database.
\nEach replica maintains an up-to-date copy of your data through replication.\nChanges flow one-way: from primary to replicas.\nThis means any data written to your primary will eventually show up in your replicas.\nThat "eventually" is important - you're trading consistency for better read performance.
\nMost cloud providers make read replicas easy to set up.\nAWS RDS and Azure SQL all support read replicas with minimal configuration.\nThey handle replication, monitoring, and failover for you.
\n![\"Example](\"https://milanjovanovic.tech/blogs/mnw_125/database_read_replicas.png\")
\nWhen implementing read replicas, consider:
\nSometimes read replicas aren't enough.\nPerhaps you need to reshape your data for specific use cases, or you're running complex analytical queries that are slow even on a replica.\nThis is where materialized views come in.
\nA materialized view is a pre-computed dataset stored as a table.\nUnlike regular views that compute their results on each query, materialized views store their results.\nThis makes them much faster to query but introduces a new challenge: keeping them up to date.
\nMaterialized views excel at:
\nThe key trade-off is freshness versus performance.\nYou need to decide how often to refresh your materialized views.\nToo often, and you're putting load on your database.\nToo rarely, and your data gets stale.
\nSharding becomes necessary when your database grows beyond what a single instance can handle.\nSharding splits your data across multiple database instances, with each shard containing a distinct subset of your data.\nThe key to successful sharding lies in choosing the right sharding strategy for your use case.
\nRange-based sharding splits data based on ranges of a key value - for example, customers A-M go to Shard 1, N-Z to Shard 2.\nThis approach works well with data that has a natural range distribution, like dates or alphabetical order,\nbut can lead to hotspots if certain ranges see more activity than others.
\nHash-based sharding applies a hash function to your sharding key to determine which shard holds the data.\nThe choice of hashing function is crucial.\nIt must distribute data evenly across your shards to prevent any single shard from becoming a bottleneck.\nWhile this approach provides better data distribution, it makes range-based queries more complex since related data might live on different shards.
\nTenant-based sharding gives each tenant their own database.\nThis approach provides natural isolation and makes tenant-specific operations straightforward.\nWhile it makes cross-tenant queries more complex, it's often the cleanest solution for multi-tenant systems where data isolation is important.
\n![\"Example](\"https://milanjovanovic.tech/blogs/mnw_125/database_sharding.png\")
\nCaching is one of the most effective ways to improve your system's performance.\nA well-implemented caching strategy can dramatically reduce database load and improve response times by storing frequently accessed data in memory.
\nModern caching happens at multiple levels.\nBrowser caching reduces unnecessary network requests.\nCDN caching brings your content closer to users.\nApplication-level caching with tools like Redis stores frequently accessed data in memory.\nDatabase query caching reduces expensive computations.
\nThe key to effective caching is understanding your data access patterns.\nFrequently read, rarely changed data benefits most from caching.\nTools like Redis and Memcached excel at storing such data in memory, providing sub-millisecond access times.\nCloud providers offer managed caching services like Azure Cache for Redis,\nhandling the operational complexity of maintaining a distributed cache.
\nMessage queues are a powerful tool for scaling your monolith.\nThey let you defer time-consuming operations and distribute work across multiple processors.\nThis keeps your API responsive while handling heavy tasks in the background.
\nMessage queues transform your system's behavior under load.\nInstead of processing everything synchronously, you can queue work for later.\nThis pattern works especially well for operations like:
\nThe real power of message queues lies in their ability to handle traffic spikes.\nWhen your system gets hit with a surge of requests, queues act as a buffer.\nThey let you accept work at peak rates but process it at a sustainable pace.
\nScaling a monolith isn't about choosing between vertical scaling, horizontal scaling, caching, or any single approach.\nIt's about using the right tool at the right time.\nStart with the simplest solution that solves your immediate problem, then add complexity only when needed.
\nA practical scaling journey often looks like this:
\nA well-designed monolith can handle significant load with just a subset of these techniques.\nThe key is to understand your system's actual bottlenecks and address them specifically.
\nIf you're interested in building maintainable, scalable monoliths, my Modular Monolith Architecture course dives deeper into these concepts.\nYou'll learn how to structure your code for long-term maintainability and scale.
\nRemember: don't let perfect be the enemy of good.\nStart with the simplest solution that could work, measure everything, and scale what's necessary.\nA well-designed monolith can take you further than you might think.
\nThat's all for today. Hope this was helpful.
\nMicrosoft.Extensions.AI gives .NET a single IChatClient abstraction over LLM providers, so the same code runs against Ollama, Azure OpenAI, or OpenAI.\nYou register a client with AddChatClient and call GetResponseAsync, with a generic overload that deserializes the reply into a C# class.\nOllama in Docker covers local development.
I've been experimenting with different approaches to integrating LLMs into .NET apps,\nand I want to share what I've learned about using Microsoft.Extensions.AI.
Large Language Models (LLMs) have revolutionized how we approach AI-powered applications.\nWhile many developers are familiar with cloud-based solutions like OpenAI's GPT models,\nrunning LLMs locally has become increasingly accessible thanks to projects like Ollama.
\nIn this article, we'll explore how to use LLMs in .NET applications using Microsoft.Extensions.AI,\na powerful abstraction that extends the Semantic Kernel SDK.
LLMs are deep learning models trained on vast amounts of data, capable of understanding and generating human-like text.\nThese models can perform various tasks such as text completion, summarization, classification, and engaging in conversation.\nWhile traditionally accessed through cloud APIs, recent advances have made it possible to run them locally on standard hardware.
\n![\"Timeline](\"https://milanjovanovic.tech/blogs/mnw_124/large_language_models.png\")
\n Ollama is an open-source project that simplifies running LLMs locally.\nIt provides a Docker container that can run various open-source models like Llama,\nmaking it easy to experiment with AI without depending on cloud services.\nOllama handles model management and optimization and provides a simple API for interactions.
\nMicrosoft.Extensions.AI is a library that provides a unified interface for working with LLMs in .NET applications.\nBuilt on top of Microsoft's Semantic Kernel, it abstracts away the complexity of different LLM implementations,\nallowing developers to switch between providers (like Ollama, Azure, or OpenAI) without changing application code.
\nBefore diving into the examples, here's what you need to run LLMs locally:
\nllama3 model:# Pull the Ollama container\ndocker run --gpus all -d -v ollama_data:/root/.ollama -p 11434:11434 --name ollama ollama/ollama\n\n# Pull the llama3 model\ndocker exec -it ollama ollama pull llama3\nInstall-Package Microsoft.Extensions.AI # The base AI library\nInstall-Package Microsoft.Extensions.AI.Ollama # Ollama provider implementation\nInstall-Package Microsoft.Extensions.Hosting # For building the DI container\nLet's start with a basic example of chat completion.\nHere's the minimal setup:
\nvar builder = Host.CreateApplicationBuilder();\n\nbuilder.Services.AddChatClient(new OllamaChatClient(new Uri("http://localhost:11434"), "llama3"));\n\nvar app = builder.Build();\n\nvar chatClient = app.Services.GetRequiredService<IChatClient>();\n\nvar response = await chatClient.GetResponseAsync("What is .NET? Reply in 50 words max.");\n\nConsole.WriteLine(response.Message.Text);\nNothing fancy here - we're just setting up dependency injection and asking a simple question.\nIf you're used to using raw API calls, you'll notice how clean this feels.
\nThe AddChatClient extension method registers the chat client with the DI container.\nThis allows you to inject IChatClient into your services and interact with LLMs using a simple API.\nThe implementation uses the OllamaChatClient to communicate with the Ollama container running locally.
Building on the previous example, we can create an interactive chat that maintains conversation history.\nThis is useful for context-aware interactions and real-time chat applications.\nAll we need is a List<ChatMessage to store the chat history:
var chatHistory = new List<ChatMessage>();\n\nwhile (true)\n{\n Console.WriteLine("Enter your prompt:");\n var userPrompt = Console.ReadLine();\n chatHistory.Add(new ChatMessage(ChatRole.User, userPrompt));\n\n Console.WriteLine("Response from AI:");\n var chatResponse = "";\n await foreach (var item in chatClient.GetStreamingResponseAsync(chatHistory))\n {\n // We're streaming the response, so we get each message as it arrives\n Console.Write(item.Text);\n chatResponse += item.Text;\n }\n chatHistory.Add(new ChatMessage(ChatRole.Assistant, chatResponse));\n Console.WriteLine();\n}\nThe cool part here is the streaming response - you get that nice, gradual text appearance like in ChatGPT.\nWe're also maintaining chat history, which lets the model understand context from previous messages, making conversations feel more natural.
\nLet's try something more useful - automatically summarizing articles.\nI've been using this to process blog posts:
\nvar posts = Directory.GetFiles("posts").Take(5).ToArray();\nforeach (var post in posts)\n{\n string prompt = $$"""\n You will receive an input text and the desired output format.\n You need to analyze the text and produce the desired output format.\n You not allow to change code, text, or other references.\n\n # Desired response\n\n Only provide a RFC8259 compliant JSON response following this format without deviation.\n\n {\n "title": "Title pulled from the front matter section",\n "summary": "Summarize the article in no more than 100 words"\n }\n\n # Article content:\n\n {{File.ReadAllText(post)}}\n """;\n\n var response = await chatClient.GetResponseAsync(prompt);\n Console.WriteLine(response.Message.Text);\n Console.WriteLine(Environment.NewLine);\n}\nPro tip: Being specific about the output format (like requesting RFC8259 compliant JSON) helps get consistent results.\nI learned this the hard way after dealing with occasionally malformed responses!
\nHere's where it gets really interesting - we can get strongly typed responses directly from our LLM:
\nclass PostCategory\n{\n public string Title { get; set; } = string.Empty;\n public string[] Tags { get; set; } = [];\n}\n\nvar posts = Directory.GetFiles("posts").Take(5).ToArray();\nforeach (var post in posts)\n{\n string prompt = $$"""\n You will receive an input text and the desired output format.\n You need to analyze the text and produce the desired output format.\n You not allow to change code, text, or other references.\n\n # Desired response\n\n Only provide a RFC8259 compliant JSON response following this format without deviation.\n\n {\n "title": "Title pulled from the front matter section",\n "tags": "Array of tags based on analyzing the article content. Tags should be lowercase."\n }\n\n # Article content:\n\n {{File.ReadAllText(post)}}\n """;\n\n var response = await chatClient.GetResponseAsync<PostCategory>(prompt);\n\n Console.WriteLine(\n $"{response.Result.Title}. Tags: {string.Join(",",response.Result.Tags)}");\n}\nThe strongly typed approach provides compile-time safety and better IDE support, making it easier to maintain and refactor code that interacts with LLM responses.
\nOne of the key advantages of Microsoft.Extensions.AI is support for different providers.\nWhile our examples use Ollama, you can easily switch to other providers:
// Using Azure OpenAI\nbuilder.Services.AddChatClient(new AzureOpenAIClient(\n new Uri("AZURE_OPENAI_ENDPOINT"),\n new DefaultAzureCredential())\n .AsChatClient());\n\n// Using OpenAI\nbuilder.Services.AddChatClient(new OpenAIClient("OPENAI_API_KEY").AsChatClient());\nThis flexibility allows you to:
\nMicrosoft.Extensions.AI makes it very simple to integrate LLMs into .NET applications.\nWhether you're building a chat interface, processing documents, or adding AI-powered features to your application,\nthe library provides a clean, consistent API that works across different LLM providers.
I've only scratched the surface here.\nSince integrating this into my projects, I've found countless uses:
\nI'm also planning a small side project that will use LLMs to process images from a camera feed.\nThe idea is to detect anything unusual and trigger alerts in real-time.
\nWhat are you planning to build with this?\nI'd love to hear about your projects and experiences.\nThe AI space is moving fast, but with tools like Microsoft.Extensions.AI, we can focus on building features rather than wrestling with infrastructure.
Good luck out there, and see you next week.
\nUnit testing a Clean Architecture use case means mocking every dependency the handler takes, then asserting on the Result it returns.\nCover the failure paths, the happy path, and exception propagation, using Arrange-Act-Assert and descriptive test names.\nA mock cannot prove that the real query logic works, which is what integration tests are for.
Writing tests is a crucial part of my daily work.\nOver the years, I've learned that good tests can make or break a project.
\nOne project I worked on remains the best example of this.\nIt was a large, complex system with many moving parts.\nWe had a requirement that code coverage must be above 90%.
\nCode coverage doesn't directly translate to good tests, but it's a good starting point.\nIt's up to you to write quality tests that cover the most critical parts of your system.
\nToday, I want to share my approach to testing Clean Architecture use cases in .NET.
\nI've seen many projects fail because of poor testing practices.\nThe codebase grows, changes become risky, and developers lose confidence in their deployments.\nThis is especially true for Clean Architecture projects, where we need to ensure our use cases work correctly.
\nTesting isn't just about catching bugs.\nIt's about having confidence in your code.\nWhen I make changes, I want to know immediately if I've broken something.\nGood tests give me that confidence.
\nBefore diving into the specific examples, let's talk about testing types.\nIn my experience, there are three main types of tests you'll write:
\nUnit tests focus on testing individual components in isolation.\nThey're fast, reliable, and help you catch issues early.\nI write these tests first, and they make up the majority of my test suite.
\nIntegration tests verify that different components work together correctly.\nThey're slower but essential for testing database operations or external services.
\nEnd-to-end tests check the entire system flow.\nThey're the slowest but provide confidence that everything works together.
\nFor this article, we'll focus on unit tests. They're the foundation of a solid test suite and the most common type you'll write.
\nLooking at our ReserveBookingCommandHandler class, we have a typical Clean Architecture use case.\nIt handles apartment booking reservations with several business rules:
This is a perfect example for unit testing because it has clear inputs, outputs, and dependencies we can mock.
\ninternal sealed class ReserveBookingCommandHandler(\n IApartmentRepository apartmentRepository,\n IBookingRepository bookingRepository,\n IDateTimeProvider dateTimeProvider) : ICommandHandler<ReserveBookingCommand, Guid>\n{\n public async Task<Result<Guid>> Handle(\n ReserveBookingCommand request,\n CancellationToken cancellationToken)\n {\n var apartment = await apartmentRepository.GetByIdAsync(request.ApartmentId, cancellationToken);\n\n if (apartment is null)\n {\n return Result.Failure<Guid>(ApartmentErrors.NotFound);\n }\n\n var duration = DateRange.Create(request.StartDate, request.EndDate);\n\n if (await bookingRepository.IsOverlappingAsync(apartment, duration, cancellationToken))\n {\n return Result.Failure<Guid>(BookingErrors.Overlap);\n }\n\n var booking = Booking.Create(\n apartment,\n duration,\n dateTimeProvider.UtcNow);\n\n bookingRepository.Add(booking);\n\n return booking.Id;\n }\n}\nThe test class setup shows the standard approach I use for all my handler tests. Let's break it down:
\npublic class ReserveBookingCommandHandlerTests\n{\n private readonly ReserveBookingCommandHandler _handler;\n private readonly IApartmentRepository _apartmentRepository;\n private readonly IBookingRepository _bookingRepository;\n private readonly IDateTimeProvider _dateTimeProvider;\n\n private static readonly Guid ApartmentId = Guid.NewGuid();\n private static readonly DateTime UtcNow = DateTime.UtcNow;\n\n public ReserveBookingCommandHandlerTests()\n {\n _apartmentRepository = Substitute.For<IApartmentRepository>();\n _bookingRepository = Substitute.For<IBookingRepository>();\n _dateTimeProvider = Substitute.For<IDateTimeProvider>();\n _dateTimeProvider.UtcNow.Returns(UtcNow);\n\n _handler = new ReserveBookingCommandHandler(\n _apartmentRepository,\n _bookingRepository,\n _dateTimeProvider);\n }\n}\nI'm using NSubstitute to create mocks of our dependencies.\nEach test starts with fresh mocks, preventing test interference.\nThe static fields provide consistent values across all tests.
\nNotice how I mock IDateTimeProvider.\nThis is crucial for testing time-dependent code.\nNever use DateTime.UtcNow directly in your production code - it makes testing much harder.
Our first test verifies the behavior when an apartment doesn't exist:
\n[Fact]\npublic async Task Handle_WhenApartmentDoesNotExist_ShouldReturnNotFoundError()\n{\n // Arrange\n var command = new ReserveBookingCommand(\n ApartmentId,\n new DateOnly(2024, 1, 1),\n new DateOnly(2024, 1, 5));\n\n _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())\n .Returns((Apartment?)null);\n\n // Act\n var result = await _handler.Handle(command, default);\n\n // Assert\n result.IsFailure.Should().BeTrue();\n result.Error.Should().Be(ApartmentErrors.NotFound);\n}\nThis test follows the Arrange-Act-Assert pattern:
\nnullI use FluentAssertions because it provides clear, readable assertions and better error messages than the standard Assert class.
\nThe overlap test ensures we can't double-book apartments:
\n[Fact]\npublic async Task Handle_WhenBookingOverlaps_ShouldReturnOverlapError()\n{\n // Arrange\n var command = new ReserveBookingCommand(\n ApartmentId,\n new DateOnly(2024, 1, 1),\n new DateOnly(2024, 1, 5));\n\n var apartment = new Apartment { Id = ApartmentId };\n _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())\n .Returns(apartment);\n _bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())\n .Returns(true);\n\n // Act\n var result = await _handler.Handle(command, default);\n\n // Assert\n result.IsFailure.Should().BeTrue();\n result.Error.Should().Be(BookingErrors.Overlap);\n}\nHere, we verify the overlap check works correctly.\nNotice how we:
\nThe happy path test ensures everything works when all conditions are met:
\n[Fact]\npublic async Task Handle_WhenValidRequest_ShouldCreateBooking()\n{\n // Arrange\n var command = new ReserveBookingCommand(\n ApartmentId,\n new DateOnly(2024, 1, 1),\n new DateOnly(2024, 1, 5));\n\n var apartment = new Apartment { Id = ApartmentId };\n _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())\n .Returns(apartment);\n _bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())\n .Returns(false);\n\n // Act\n var result = await _handler.Handle(command, default);\n\n // Assert\n result.IsSuccess.Should().BeTrue();\n await _bookingRepository.Received(1)\n .Add(Arg.Is<Booking>(b =>\n b.Id == result.Value &&\n b.ApartmentId == ApartmentId));\n}\nThis test is more complex because we need to:
\nNSubstitute's Received() method lets us verify the Add method was called exactly once with the right booking.
Testing exception scenarios is crucial for robust code:
\n[Fact]\npublic async Task Handle_WhenRepositoryThrowsOverlapException_ShouldPropagateException()\n{\n // Arrange\n var command = new ReserveBookingCommand(\n ApartmentId,\n new DateOnly(2024, 1, 1),\n new DateOnly(2024, 1, 5));\n\n var apartment = new Apartment { Id = ApartmentId };\n _apartmentRepository.GetByIdAsync(ApartmentId, Arg.Any<CancellationToken>())\n .Returns(apartment);\n _bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())\n .Throws<BookingOverlapException>();\n\n // Act\n var act = () => _handler.Handle(command, default);\n\n // Assert\n await act.Should().ThrowAsync<BookingOverlapException>();\n}\nThis test ensures exceptions propagate correctly. We:
\nFluentAssertions makes testing async exceptions clean and readable.
\nWhen we look back at our booking overlap test, there's an important distinction to make.\nOur unit test verifies that our command handler behaves correctly when the booking repository reports an overlap.\nHowever, it doesn't verify that the overlap detection logic itself works correctly.
\nConsider what we're actually testing:
\n_bookingRepository.IsOverlappingAsync(apartment, Arg.Any<DateRange>(), Arg.Any<CancellationToken>())\n .Returns(true);\nWe're simply telling our mock repository to return true.\nThis gives us confidence that our command handler correctly handles the overlap scenario,\nbut it does not tell us whether our actual overlap detection logic works correctly.
This is where integration tests become essential.\nAn integration test for this scenario would:
\nThe combination of unit and integration tests provides complete coverage:
\nThis example highlights why we need different types of tests.\nUnit tests are excellent for verifying behavior and logic flows,\nbut they can't verify the correctness of complex business rules that depend on real data interactions.
\nUnit testing Clean Architecture use cases requires careful thought about dependencies and behavior.\nHere are the key points:
\nGood tests act as documentation.\nThey show how the code should behave and catch issues before they reach production.\nInvest time in writing good tests - your future self will thank you.
\nWant to dive deeper into testing Clean Architecture applications?\nI cover this and much more in my Pragmatic Clean Architecture course.\nYou'll learn how to write effective unit tests, integration tests, and end-to-end tests that give you real confidence in your system.
\nWriting quality tests is a skill that improves with practice and understanding.\nTake the time to write them well.
\nThat's all for today.
\nSee you next week.
\nTo rewrite a legacy system without downtime, migrate gradually while both systems run side by side.\nWe kept the legacy system as the source of truth for everything not yet migrated, synced data both ways, and used RabbitMQ for message-based integration so modules could move over one at a time.\nStart with the core domain instead of peripheral quick wins, because postponing the core means every migrated feature needs complex synchronization with the legacy system.
\n"Your task is to rewrite this system. It powers our entire operation. Oh, and it's written in APL."
\nThat's how my journey with this legacy rewrite began.\nFor those unfamiliar with APL>),\nit's a programming language from the 1960s known for its unique mathematical notation and array manipulation capabilities.\nFinding developers who know APL today is about as easy as finding a floppy disk drive in a modern computer.
\nThe system has grown over four decades.\nIt started as a simple inventory management tool and evolved into a comprehensive ERP system.\nMore than 460+ database tables.\nCountless business rules embedded in the code.\nComplex integrations with every part of the business process.\nThe system is the backbone of a manufacturing operation, that generates over $10 million in annual revenue.
\nOur mission was clear but daunting: modernize this system using .NET, PostgreSQL, and React.
\nThe catch?\nThe business needed to keep running during the transition.\nNo downtime.\nNo data loss.\nNo disruption to daily operations.
\nThis wasn't just a technical challenge.\nIt was a lesson in managing complexity, understanding legacy business processes, and navigating organizational dynamics.
\nSo here's that story and the lessons learned.
\nThe first challenge was understanding how this massive system actually worked.\nThe codebase had grown organically over four decades, maintained by a single development team.\nThey were now in their 60s and looking to retire.
\nWalking into the first codebase review was like opening a time capsule.\nAPL's concise syntax meant that complex business logic could be written in just a few lines.\nBeautiful, if you could read it.\nTerrifying, if you couldn't.\nAnd most of us couldn't.
\nThe original team was invaluable during the knowledge transfer.\nThey knew every quirk, every special case, every business rule that had been added over the decades.\nBut there's only so much you can learn from conversations.\nDocumentation was sparse.\nWhat existed was outdated.\nThe real documentation was in the heads of the original developers.
\nWe spent weeks mapping the system's functionality:
\nTables that started with basic schemas had grown to include hundreds of columns.\nSome columns were no longer used but couldn't be removed because no one was sure if some obscure report still needed them.
\nWhat made this particularly challenging was the disconnect between the business processes and their technical implementation.\nThe business would describe a simple workflow, but the technical implementation would reveal layers of complexity added over years of edge cases and special requirements.
\nWe needed a systematic approach to understanding this beast.\nWe started by mapping business processes and their corresponding technical implementations.\nThis helped us identify the core domains that would later influence our modular architecture.\nMore importantly, it helped us understand the true scope of what we were dealing with.
\nManagement wanted quick wins.\nThey pushed us to start with the simplest components.\nThis created tension between product management and the development team.
\nProduct management's perspective was straightforward: show progress to the business.\nThey needed visible results to justify the investment in the rewrite.\nThe business was spending significant money, and they wanted to see returns quickly.
\nThe development team saw a different reality.\nWe knew that starting with peripheral features meant building on shaky ground.\nThe core business logic would remain in the legacy system, making every integration point more complex.\nThis technical debt would compound over time.
\nAs a technical lead, I strongly opposed this approach.\nMy argument was simple: the core manufacturing process was the heart of the system.\nEvery peripheral feature depended on it.\nBy postponing its migration, we created a tangled web of dependencies between old and new systems.\nEach new feature we migrated would need complex synchronization with the legacy core.\nWe were building on quicksand.
\nI advocated for focusing on the core domain first.\nYes, it would take longer to show the first results.\nBut it would create a solid foundation for everything that followed.\nThe business would have to wait longer for visible progress, but the overall migration would be faster and more reliable.
\nNeither side was wrong in their objectives.\nProduct management had valid concerns about showing progress.\nThe development team had valid concerns about technical sustainability.\nBut this misalignment led to compromises that impacted the project timeline.\nTo this day, I believe we would have finished the migration sooner if we had started with the core business logic.
\nDuring the discovery phase, we identified distinct business domains within the system.\nThis led us to implement a modular monolith architecture.\nEach module would be self-contained but able to communicate with others through a shared event bus:
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_122/legacy_system_with_modular_monolith.png\")
\nKey architectural decisions:
\nModular monolith:\nEach module represented a distinct business domain.\nThis provided a clear path to potential future microservices if needed.
\nAsynchronous communication:\nModules communicated through events using RabbitMQ.\nThis reduced coupling and improved system resilience.
\nShared database with boundaries:\nWhile all modules used the same PostgreSQL database, each had its own set of tables and schemas.\nThis helped us maintain logical separation.
\nCloud-ready design:\nThe system was deployed to AWS using containerization.\nA Jenkins pipeline enabled deployments to multiple environments in minutes.
\nThe two-way data synchronization was more complex than initially anticipated.\nHere's why we couldn't use existing change data capture (CDC) solutions like Debezium:
\nComplex transformations:\nMany legacy tables required data from multiple new tables.\nThis wasn't a simple one-to-one mapping that CDC tools excel at.
\nBusiness logic in sync:\nThe sync process needed to apply business rules during transformation.\nThis went beyond what most replication tools provide.
\nBidirectional requirements:\nWe needed to sync both ways while preventing infinite loops.\nThe legacy system remained the source of truth for non-migrated components.
\n![\"Data](\"https://milanjovanovic.tech/blogs/mnw_122/data_sync.png\")
\nWe built a custom solution using RabbitMQ for message transport.\nWhile this worked for us, the lesson remains: evaluate existing tools thoroughly before building custom solutions.\nEven if you can't use them entirely, you might learn valuable patterns from their approaches.
\nModular architecture pays off:\nThe modular monolith approach made the system easier to understand and maintain.\nEach module had clear boundaries and responsibilities.
\nInvest in deployment automation:\nThe CI/CD pipeline was crucial.\nIt allowed us to deploy confidently and frequently, reducing the risk of each change.
\nMessage-based integration:\nAsync communication between modules provided the flexibility needed for the gradual migration.
\nData sync complexity:\nDon't underestimate the complexity of data synchronization in legacy migrations.\nWhether using existing tools or building custom solutions, this will be a major challenge.
\nTechnical challenges are only part of the story.\nThe success of legacy rewrites depends heavily on managing different stakeholders:
\nFinding the right balance between these competing needs can be tricky.
\nWe found several approaches that helped:
\nI can't stress enough how important it was to document the knowledge acquired over four decades of operating the legacy system.\nWhen the original team retired, we had a comprehensive set of documents that explained every business rule and every edge case.
\nFour years later, the system is thriving.\nThe cloud infrastructure provides reliability and scalability.\nThe modular monolith architecture makes it maintainable.\nThe automated deployment pipeline enables rapid updates.
\nBut the journey taught us valuable lessons about balancing technical needs with business pressures.\nSuccess in legacy rewrites requires more than just technical excellence.\nIt requires understanding the business domain, managing stakeholder expectations, and making pragmatic architectural decisions.
\nSoftware architecture matters, but so does the human factor. Plan for both.
\nThanks for reading.
\nAnd stay awesome!
\nQuartz.NET runs background jobs in ASP.NET Core through the IJob interface, triggered once at a given time or on a cron schedule.\nJobs live in memory by default and are lost on restart, so production setups call UsePersistentStore against a database.\nAddQuartzInstrumentation gives you a trace for every execution.
Most ASP.NET Core applications need to handle background processing -\nfrom sending reminder emails to running cleanup tasks.\nWhile there are many ways to implement background jobs, Quartz.NET\nstands out with its robust scheduling capabilities, persistence options, and production-ready features.
\nIn this article, we'll look at:
\nLet's start with the basic setup and build our way up to a production-ready configuration.
\nFirst, let's set up Quartz with proper instrumentation.
\nWe'll need to install some NuGet packages:
\nInstall-Package Quartz.Extensions.Hosting\nInstall-Package Quartz.Serialization.Json\n\n# This might be in prerelease\nInstall-Package OpenTelemetry.Instrumentation.Quartz\nNext, we'll configure the Quartz services and OpenTelemetry instrumentation and start the scheduler:
\nbuilder.Services.AddQuartz();\n\n// Add Quartz.NET as a hosted service\nbuilder.Services.AddQuartzHostedService(options =>\n{\n options.WaitForJobsToComplete = true;\n});\n\nbuilder.Services.AddOpenTelemetry()\n .WithTracing(tracing =>\n {\n tracing\n .AddHttpClientInstrumentation()\n .AddAspNetCoreInstrumentation()\n .AddQuartzInstrumentation();\n })\n .UseOtlpExporter();\nThis is all we need at the start.
\nTo define a background job, you have to implement the IJob interface.\nAll job implementations run as scoped services, so you can inject dependencies as needed.\nQuartz allows you to pass data to a job using the JobDataMap dictionary.\nIt's recommended to only use primitive types for job data to avoid serialization issues.
When executing the job, there are a few ways to fetch job data:
\nJobDataMap - a dictionary of key-value pairs\nJobExecutionContext.JobDetail.JobDataMap - job-specific dataJobExecutionContext.Trigger.TriggerDataMap - trigger-specific dataMergedJobDataMap - combines job data with trigger dataIt's a best practice to use MergedJobDataMap to retrieve job data.
public class EmailReminderJob(ILogger<EmailReminderJob> logger, IEmailService emailService) : IJob\n{\n public const string Name = nameof(EmailReminderJob);\n\n public async Task Execute(IJobExecutionContext context)\n {\n // Best practice: Prefer using MergedJobDataMap\n var data = context.MergedJobDataMap;\n\n // Get job data - note that this isn't strongly typed\n string? userId = data.GetString("userId");\n string? message = data.GetString("message");\n\n try\n {\n await emailService.SendReminderAsync(userId, message);\n\n logger.LogInformation("Sent reminder to user {UserId}: {Message}", userId, message);\n }\n catch (Exception ex)\n {\n logger.LogError(ex, "Failed to send reminder to user {UserId}", userId);\n\n // Rethrow to let Quartz handle retry logic\n throw;\n }\n }\n}\nOne thing to note: JobDataMap isn't strongly typed. This is a limitation we have to live with, but we can mitigate it by:
Execute methodNow, let's discuss scheduling jobs.
\nHere's how to schedule one-time reminders:
\npublic record ScheduleReminderRequest(\n string UserId,\n string Message,\n DateTime ScheduleTime\n);\n\n// Schedule a one-time reminder\napp.MapPost("/api/reminders/schedule", async (\n ISchedulerFactory schedulerFactory,\n ScheduleReminderRequest request) =>\n{\n var scheduler = await schedulerFactory.GetScheduler();\n\n var jobData = new JobDataMap\n {\n { "userId", request.UserId },\n { "message", request.Message }\n };\n\n var job = JobBuilder.Create<EmailReminderJob>()\n .WithIdentity($"reminder-{Guid.NewGuid()}", "email-reminders")\n .SetJobData(jobData)\n .Build();\n\n var trigger = TriggerBuilder.Create()\n .WithIdentity($"trigger-{Guid.NewGuid()}", "email-reminders")\n .StartAt(request.ScheduleTime)\n .Build();\n\n await scheduler.ScheduleJob(job, trigger);\n\n return Results.Ok(new { scheduled = true, scheduledTime = request.ScheduleTime });\n})\n.WithName("ScheduleReminder")\n.WithOpenApi();\n\nThe endpoint schedules one-time email reminders using Quartz.\nIt creates a job with user data, sets up a trigger for the specified time, and schedules them together.\nThe EmailReminderJob receives a unique identity in the email-reminders group.
Here's a sample request you can use to test this out:
\nPOST /api/reminders/schedule\n{\n "userId": "user123",\n "message": "Important meeting!",\n "scheduleTime": "2024-12-17T15:00:00"\n}\nFor recurring background jobs, you can use cron schedules:
\npublic record RecurringReminderRequest(\n string UserId,\n string Message,\n string CronExpression\n);\n\n// Schedule a recurring reminder\napp.MapPost("/api/reminders/schedule/recurring", async (\n ISchedulerFactory schedulerFactory,\n RecurringReminderRequest request) =>\n{\n var scheduler = await schedulerFactory.GetScheduler();\n\n var jobData = new JobDataMap\n {\n { "userId", request.UserId },\n { "message", request.Message }\n };\n\n var job = JobBuilder.Create<EmailReminderJob>()\n .WithIdentity($"recurring-{Guid.NewGuid()}", "recurring-reminders")\n .SetJobData(jobData)\n .Build();\n\n var trigger = TriggerBuilder.Create()\n .WithIdentity($"recurring-trigger-{Guid.NewGuid()}", "recurring-reminders")\n .WithCronSchedule(request.CronExpression)\n .Build();\n\n await scheduler.ScheduleJob(job, trigger);\n\n return Results.Ok(new { scheduled = true, cronExpression = request.CronExpression });\n})\n.WithName("ScheduleRecurringReminder")\n.WithOpenApi();\nCron triggers are more powerful than simple triggers.\nThey allow you to define complex schedules like "every weekday at 10 AM" or "every 15 minutes".\nQuartz supports cron expressions with seconds, minutes, hours, days, months, and years.
\nHere's a sample request if you want to test this:
\nPOST /api/reminders/schedule/recurring\n{\n "userId": "user123",\n "message": "Daily standup",\n "cronExpression": "0 0 10 ? * MON-FRI"\n}\nBy default, Quartz uses in-memory storage, which means your jobs are lost when the application restarts.\nFor production environments, you'll want to use a persistent store.\nQuartz supports several database providers,\nincluding SQL Server, PostgreSQL, MySQL, and Oracle.
\nLet's look at how to set up persistent storage with proper schema isolation:
\nbuilder.Services.AddQuartz(options =>\n{\n options.AddJob<EmailReminderJob>(c => c\n .StoreDurably()\n .WithIdentity(EmailReminderJob.Name));\n\n options.UsePersistentStore(persistenceOptions =>\n {\n persistenceOptions.UsePostgres(cfg =>\n {\n cfg.ConnectionString = connectionString;\n cfg.TablePrefix = "scheduler.qrtz_";\n },\n dataSourceName: "reminders"); // Database name\n\n persistenceOptions.UseNewtonsoftJsonSerializer();\n persistenceOptions.UseProperties = true;\n });\n});\nA few important things to note here:
\nTablePrefix setting helps organize Quartz tables in your database - in this case, placing them in a dedicated scheduler schemaNotice how we're configuring the EmailReminderJob with StoreDurably?\nThis is a powerful pattern that lets you define your jobs once and reuse them with different triggers.\nHere's how to schedule a stored job:
public async Task ScheduleReminder(string userId, string message, DateTime scheduledTime)\n{\n var scheduler = await _schedulerFactory.GetScheduler();\n\n // Reference the stored job by its identity\n var jobKey = new JobKey(EmailReminderJob.Name);\n\n var trigger = TriggerBuilder.Create()\n .ForJob(jobKey) // Reference the durable job\n .WithIdentity($"trigger-{Guid.NewGuid()}")\n .UsingJobData("userId", userId)\n .UsingJobData("message", message)\n .StartAt(scheduledTime)\n .Build();\n\n await scheduler.ScheduleJob(trigger); // Note: just passing the trigger\n}\nThis approach has several benefits:
\nGetting Quartz set up properly in .NET involves more than just adding the NuGet package.
\nPay attention to:
\nJobDataMapEach of these elements contributes to a reliable background processing system that can grow with your application's needs.\nA good example of using background jobs is when you want to build asynchronous APIs.
\nGood luck out there, and I'll see you next week.
\nA module's public API is the explicit contract other modules are allowed to call, while its domain model, services, and database schema stay internal.\nExpose only what another module actually needs, shaped around its use case: GetOrderForShippingAsync rather than a generic GetOrderAsync.\nQueries that span modules get their own read model, updated through events.
Every article about modular monoliths tells you to use public APIs between modules.\nBut they rarely tell you why these APIs exist or how to design them properly.
\nA modular monolith organizes an application into independent modules that have clear boundaries.\nThe module boundaries are logical and group related business capabilities together.
\nAfter building several large-scale modular monoliths, I've learned that public APIs are not just about clean code - they're about controlling chaos.\nLet me show you what I mean.
\nHere's what nobody tells you about public APIs in modular monoliths: they represent intentional coupling points.\nYes, you read that right.\nPublic APIs don't eliminate coupling - they make it explicit and controllable.
\nWhen Module A needs something from Module B, you have three options:
\n![\"Module](\"https://milanjovanovic.tech/blogs/mnw_120/module_communication_options.png\")
\nThe first two options lead to chaos.\nI've seen entire systems become unmaintainable because every module was freely accessing the data and services of other modules.
\nThe previous options are examples of synchronous communication between modules.\nBut you can also implement asynchonrous module communication using messaging.\nWe have to adjust the technical implementation.\nHowever, modules still have a public API in message contracts.
\nPublic APIs serve three critical purposes:
\nHere's a practical example. Imagine you have an Orders module and a Shipping module.
\nThis is what you want to avoid:
\npublic class ShippingService\n{\n private readonly OrdersDbContext _ordersDb; // Direct database access\n\n public async Task ShipOrder(string orderId)\n {\n // Directly reading from another module's database\n var order = await _ordersDb.Orders\n .Include(o => o.Lines)\n .FirstOrDefaultAsync(o => o.Id == orderId);\n\n // What happens if the Orders module changes its schema?\n // What if it moves to a different database?\n }\n}\nThis is what you want to achieve instead:
\npublic class ShippingService\n{\n private readonly IOrdersModule _orders; // Public API access\n\n public async Task ShipOrder(string orderId)\n {\n // Using the public API\n var order = await _orders.GetOrderForShippingAsync(orderId);\n\n // The Orders module can change its internals\n // as long as it maintains this contract\n }\n}\nThe hardest part of designing public APIs is deciding what to expose.\nHere's my rule of thumb:
\nHere's how this looks in practice:
\npublic interface IOrdersModule\n{\n // Don't expose generic CRUD operations\n // Task<Order> GetOrderAsync(string orderId); // Bad\n\n // Instead, expose specific use cases\n Task<OrderShippingInfo> GetOrderForShippingAsync(string orderId);\n Task<OrderPaymentInfo> GetOrderForPaymentAsync(string orderId);\n Task<OrderSummary> GetOrderForCustomerAsync(string orderId);\n}\nPublic APIs aren't enough.\nYou also need to protect your module's data.\nHere's what I've found works:
\nCREATE SCHEMA Orders;\nCREATE SCHEMA Shipping;\n\n-- Orders module can only access its schema\nCREATE USER OrdersUser WITH DEFAULT_SCHEMA = Orders;\nGRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::Orders TO OrdersUser;\n\n-- Shipping module can only access its schema\nCREATE USER ShippingUser WITH DEFAULT_SCHEMA = Shipping;\nGRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::Shipping TO ShippingUser;\nWe can also lock down the user's access to a given schema to only allow reading and writing data.
\nbuilder.Services.AddDbContext<OrdersDbContext>(options =>\n options.UseSqlServer(builder.Configuration.GetConnectionString("OrdersConnection")));\n\nbuilder.Services.AddDbContext<ShippingDbContext>(options =>\n options.UseSqlServer(builder.Configuration.GetConnectionString("ShippingConnection")));\nIf you want to learn more about this, check out this article about using multiple EF Core DbContexts.
\ninternal class Order\n{\n // Internal domain model with full complexity\n}\n\npublic class OrderShippingInfo\n{\n // Public DTO with only what shipping needs\n public string OrderId { get; init; }\n public Address ShippingAddress { get; init; }\n public List<ShippingItem> Items { get; init; }\n}\nSome features naturally span multiple modules.\nFor example, when a customer views their order history, you might need data from the Orders, Shipping, and Payments modules.
\nDon't try to force this through module APIs.\nInstead:
\npublic class OrderHistoryModule\n{\n public async Task<CustomerOrderHistory> GetOrderHistoryAsync(string customerId)\n {\n // Read from a dedicated read model that's kept\n // updated through events from other modules\n return await _orderHistoryRepository.GetCustomerHistoryAsync(customerId);\n }\n}\nPublic APIs in modular monoliths are not about preventing coupling - they're about controlling it.\nEvery public API is a contract that says: "Yes, these modules are coupled, and this is exactly how they depend on each other."
\nThe goal isn't to eliminate dependencies between modules.\nThe goal is to make them explicit, controlled, and maintainable.
\nGet this right, and your modular monolith will be easier to maintain, test, and evolve.\nGet it wrong, and you'll end up with a distributed big ball of mud.
\nWant to master building modular monoliths with clean APIs and event-driven patterns?\nCheck out my Modular Monolith Architecture course, where I'll show you how to build maintainable systems\nusing practical examples from real projects.
\nThat's all for today. Stay awesome, and I'll see you next week.
\nCentral Package Management lets you define every NuGet version once, in a Directory.Packages.props file at the solution root.\nProjects then reference packages without a Version attribute, so all of them stay on the same version.\nIt needs NuGet 6.2 and .NET SDK 6.0.300 or newer.
I remember the days when managing NuGet packages across multiple projects was a real pain.\nYou know what I mean - you open a large solution and find out every project uses a different version of the same package.\nNot fun!
\nLet me show you how Central Package Management (CPM) in .NET can fix this problem once and for all.
\nI often work with solutions that have lots of projects.\nIt's not uncommon to have solutions with 30 or more projects.\nEach one needs similar packages like Serilog or Polly.\nMost test projects I create depend on xUnit.\nBefore CPM, keeping track of package versions was a mess:
\n4.1.04.0.23.1.1This causes real problems.\nDifferent versions can behave differently, leading to weird bugs that are hard to track down.\nI've wasted many hours fixing issues caused by version mismatches.
\nThink of CPM as a control center for all your package versions.\nInstead of setting versions in each project, you set them once in one place.\nThen, you just reference a package you want to use without specifying the version.\nIt's that simple.
\nHere's what you need to use Central Package Management:
\nLet me show you how to set up CPM.\nIt's easier than you might think.
\nDirectory.Packages.props in your solution's main folder:<Project>\n <PropertyGroup>\n <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>\n </PropertyGroup>\n <ItemGroup>\n <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />\n <PackageVersion Include="Serilog" Version="4.1.0" />\n <PackageVersion Include="Polly" Version="8.5.0" />\n </ItemGroup>\n</Project>\nNote the use of PackageVersion to define NuGet dependencies.
PackageReference without the version component:<ItemGroup>\n <PackageReference Include="Newtonsoft.Json" />\n <PackageReference Include="AutoMapper" />\n <PackageReference Include="Polly" />\n</ItemGroup>\nThat's it!\nNow all your projects will use the same package versions.
\nSometimes you might need a specific project to use a different version.\nNo problem!\nJust add this to your project file:
\n<PackageReference Include="Serilog" VersionOverride="3.1.1" />\nThe VersionOverride property lets you define the specific version you want to use.
If you have packages that every project needs, you can make them global.\nDefine a GlobalPackageReference in your props file:
<ItemGroup>\n <GlobalPackageReference Include="SonarAnalyzer.CSharp" Version="10.3.0.106239" />\n</ItemGroup>\nNow every project gets this package automatically!
\nDirectory.Packages.props file at the solution root.csproj filesPackageReference elementsHere's a Powershell script that will list all NuGet package versions in your solution:
\n# Scan all .csproj files and aggregate unique package versions\n$packages = Get-ChildItem -Filter *.csproj -Recurse |\n Get-Content |\n Select-String -Pattern '<PackageReference Include="([^"]+)" Version="([^"]+)"' -AllMatches |\n ForEach-Object { $_.Matches } |\n Group-Object { $_.Groups[1].Value } |\n ForEach-Object { @{\n Name = $_.Name\n Versions = $_.Group.ForEach({ $_.Groups[2].Value }) | Select-Object -Unique\n }} |\n Sort-Object { $_.Name }\n\n# Display results\n$packages | ForEach-Object {\n "$($_.Name) versions:"\n $_.Versions | ForEach-Object { " $_" }\n}\nThere's also a CLI tool called CentralisedPackageConverter,\nwhich you can use to automate the migration.\nIt will scan for all .NET project files within that folder tree, gather all the versioned references in the projects,\nremove the versions from the project files, and write the entries to the Directory.Packages.props file.
# Install the tool globally\ndotnet tool install CentralisedPackageConverter --global\n\n# Convert your solution to use Central Package Management\ncentral-pkg-converter /PATH_TO_YOUR_SOLUTION_FOLDER\nI don't see a compelling reason for not using this by default.
\nI recommend using CPM when:
\nI recently added CPM to a solution with 30 projects.
\nHere's what happened:
\nThis was especially helpful while migrating from .NET 8 to .NET 9.
\nYou can combine CPM with build configuration and static code analysis.
\nMy tips for success with Central Package Management:
\nSince I started using Central Package Management, managing NuGet packages has become much easier.\nIt's like having a single source of truth for all your package versions.
\nHope this was helpful.\nSee you next week.
\nA saga breaks a distributed transaction into a sequence of local steps, each with a compensating action that undoes it when a later step fails.\nMassTransit implements this as a state machine: you define states, correlated events, and transitions in a MassTransitStateMachine, and persist the instance with the EF Core saga repository.
Long-running business processes often involve multiple services working together.\nThink about an e-commerce order: you need to process the payment, update inventory, and notify shipping.\nTraditional distributed transactions using two-phase commit (2PC) seem like a solution, but they come with significant drawbacks.
\nThe main issue?\nServices can't make assumptions about how other services operate or how long they'll take.\nWhat if the payment service needs manual approval?\nWhat if the inventory check is delayed?\nHolding database locks across multiple services for extended periods isn't practical and can lead to system-wide issues.
\nLet's look at how the Saga pattern solves these problems and implement it using MassTransit.
\nA Saga is a sequence of related local transactions where each step has a defined action and a compensating action if something goes wrong.\nInstead of one big atomic transaction, we break the process into manageable steps that can be coordinated.
\nHere's a simple order processing flow:
\n![\"Sequence](\"https://milanjovanovic.tech/blogs/mnw_118/order_flow.png\")
\nEach step is independent and can be compensated if needed.\nIf the inventory service reports items are out of stock, we can refund the payment.\nThis approach gives us flexibility and reliability without tight coupling.
\nMassTransit provides a state machine-based approach to implementing Sagas through its integration with Automatonymous.\nUnderstanding how state machines work is crucial for implementing effective sagas.
\nA state machine consists of several key components:
\nHere's the state machine diagram for our order processing saga:
\n![\"State](\"https://milanjovanovic.tech/blogs/mnw_118/order_saga_state_machine.png\")
\nEvery state machine automatically includes Initial and Final states.\nThe Initial state is where new saga instances begin, and the Final state marks the end of a saga's lifecycle.
The saga instance holds the data for a specific process:
\npublic class OrderState : SagaStateMachineInstance\n{\n public Guid CorrelationId { get; set; }\n public string CurrentState { get; set; }\n\n // Business data\n public decimal OrderTotal { get; set; }\n public string? PaymentIntentId { get; set; }\n public DateTime? OrderDate { get; set; }\n public string? CustomerEmail { get; set; }\n}\nThe CorrelationId uniquely identifies the saga instance, while CurrentState tracks its current state.\nAny additional properties store business data needed for the process.
Events are messages that can trigger state transitions. They must be correlated to a specific saga instance:
\npublic record OrderSubmitted\n{\n public Guid OrderId { get; init; }\n public decimal Total { get; init; }\n public string Email { get; init; }\n}\n\npublic record PaymentProcessed\n{\n public Guid OrderId { get; init; }\n public string PaymentIntentId { get; init; }\n}\n\npublic record InventoryReserved\n{\n public Guid OrderId { get; init; }\n}\n\npublic record OrderFailed\n{\n public Guid OrderId { get; init; }\n public string Reason { get; init; }\n}\nLet's implement the order processing flow as a state machine:
\npublic class OrderStateMachine : MassTransitStateMachine<OrderState>\n{\n public OrderStateMachine()\n {\n Event(() => OrderSubmitted, x => x.CorrelateById(m => m.Message.OrderId));\n Event(() => PaymentProcessed, x => x.CorrelateById(m => m.Message.OrderId));\n Event(() => InventoryReserved, x => x.CorrelateById(m => m.Message.OrderId));\n Event(() => OrderFailed, x => x.CorrelateById(m => m.Message.OrderId));\n\n InstanceState(x => x.CurrentState);\n\n Initially(\n When(OrderSubmitted)\n .Then(context =>\n {\n context.Saga.OrderTotal = context.Message.Total;\n context.Saga.CustomerEmail = context.Message.Email;\n context.Saga.OrderDate = DateTime.UtcNow;\n })\n .PublishAsync(context => context.Init<ProcessPayment>(new\n {\n OrderId = context.Saga.CorrelationId,\n Amount = context.Saga.OrderTotal\n }))\n .TransitionTo(ProcessingPayment)\n );\n\n During(ProcessingPayment,\n When(PaymentProcessed)\n .PublishAsync(context => context.Init<ReserveInventory>(new\n {\n OrderId = context.Saga.CorrelationId\n }))\n .TransitionTo(ReservingInventory),\n When(OrderFailed)\n .TransitionTo(Failed)\n .Finalize()\n );\n\n During(ReservingInventory,\n When(InventoryReserved)\n .PublishAsync(context => context.Init<OrderConfirmed>(new\n {\n OrderId = context.Saga.CorrelationId\n }))\n .TransitionTo(Completed)\n .Finalize(),\n When(OrderFailed)\n .PublishAsync(context => context.Init<RefundPayment>(new\n {\n OrderId = context.Saga.CorrelationId,\n Amount = context.Saga.OrderTotal\n }))\n .TransitionTo(Failed)\n .Finalize()\n );\n\n SetCompletedWhenFinalized();\n }\n\n public State ProcessingPayment { get; private set; }\n public State ReservingInventory { get; private set; }\n public State Completed { get; private set; }\n public State Failed { get; private set; }\n\n public Event<OrderSubmitted> OrderSubmitted { get; private set; }\n public Event<PaymentProcessed> PaymentProcessed { get; private set; }\n public Event<InventoryReserved> InventoryReserved { get; private set; }\n public Event<OrderFailed> OrderFailed { get; private set; }\n}\nThe state machine defines the possible states and transitions.\nEach step can trigger compensating actions if needed.\nFor example, if inventory reservation fails, we automatically trigger a payment refund.
\nServices interact with the saga by consuming and publishing messages.\nHere's an example of a payment processing consumer:
\npublic class ProcessPaymentConsumer(\n IPaymentService paymentService,\n ILogger<ProcessPaymentConsumer> logger) : IConsumer<ProcessPayment>\n{\n public async Task Consume(ConsumeContext<ProcessPayment> context)\n {\n try\n {\n var paymentResult = await paymentService.ProcessPaymentAsync(\n context.Message.OrderId,\n context.Message.Amount\n );\n\n if (paymentResult.Succeeded)\n {\n await context.Publish<PaymentProcessed>(new\n {\n OrderId = context.Message.OrderId,\n PaymentIntentId = paymentResult.PaymentIntentId\n });\n }\n else\n {\n await context.Publish<OrderFailed>(new\n {\n OrderId = context.Message.OrderId,\n Reason = paymentResult.FailureReason\n });\n }\n }\n catch (Exception ex)\n {\n logger.LogError(\n ex,\n "Failed to process payment for order {OrderId}",\n context.Message.OrderId);\n\n await context.Publish<OrderFailed>(new\n {\n OrderId = context.Message.OrderId,\n Reason = "Payment processing error"\n });\n }\n }\n}\nEach consumer handles a specific part of the business process and communicates back to the saga through events.\nThis separation of concerns allows each service to focus on its specific responsibility while the saga coordinates the overall process.
\nTo persist the saga state, we'll use PostgreSQL.\nFirst, let's install the required packages:
\nInstall-Package MassTransit.EntityFrameworkCore\nInstall-Package Npgsql.EntityFrameworkCore.PostgreSQL\nCreate a DbContext for saga persistence:
public class OrderSagaDbContext : SagaDbContext\n{\n public OrderSagaDbContext(DbContextOptions options) : base(options)\n {\n }\n\n protected override IEnumerable<ISagaClassMap> Configurations\n {\n get\n {\n yield return new OrderStateMap();\n }\n }\n}\n\npublic class OrderStateMap : SagaClassMap<OrderState>\n{\n protected override void Configure(EntityTypeBuilder<OrderState> entity, ModelBuilder model)\n {\n entity.Property(x => x.CurrentState).HasMaxLength(64);\n entity.Property(x => x.CustomerEmail).HasMaxLength(256);\n entity.Property(x => x.PaymentIntentId).HasMaxLength(64);\n }\n}\nConfigure MassTransit in your application:
\nbuilder.Services.AddDbContext<OrderSagaDbContext>(options =>\n options.UseNpgsql(builder.Configuration.GetConnectionString("Postgres")));\n\nbuilder.Services.AddMassTransit(x =>\n{\n x.AddSagaStateMachine<OrderStateMachine, OrderState>()\n .EntityFrameworkRepository(r =>\n {\n r.ConcurrencyMode = ConcurrencyMode.Pessimistic;\n r.AddDbContext<DbContext, OrderSagaDbContext>();\n r.UsePostgres();\n });\n\n x.UsingRabbitMq((context, cfg) =>\n {\n cfg.Host(builder.Configuration.GetConnectionString("RabbitMQ"));\n cfg.ConfigureEndpoints(context);\n });\n});\nUsing sagas with MassTransit provides several advantages:
\nThe state machine approach also makes the business process explicit.\nEach state and transition is clearly defined, making it easier to understand and maintain the workflow.
\nThe Saga pattern with MassTransit provides a robust solution for managing distributed business processes.\nInstead of dealing with distributed transactions, you get clear state management, automatic compensation for failures,\nand the ability to handle long-running operations without blocking resources.
\nWant to dive deeper into event-driven architecture and distributed systems?\nCheck out my Modular Monolith Architecture course,\nwhere we explore sagas, event-driven patterns, and other essential techniques for building maintainable systems.
\nGood luck out there, and see you next week.
\nP.S. You can find the code for the saga pattern implementation with MassTransit in this repository.
\nAn async API accepts the request, returns a tracking ID immediately, and does the heavy work in the background.\nThe client gets 202 Accepted with a status URL in the Location header, then checks progress by ID.\nThis keeps long-running work like image processing off the HTTP request.
Most APIs follow a simple pattern.\nThe client sends a request.\nThe server does some work.\nThe server sends back a response.
\nThis works well for fast operations like fetching data or simple updates.\nBut what about operations that take longer?
\nThink about processing large files, generating reports, or converting videos.\nThese operations can take minutes or even hours.
\nMaking clients wait for these operations causes problems.
\nThe key to handling long-running operations is to change how we think about API responses.\nAn async API splits work into two parts:
\nFirst, we accept the request and return a tracking ID immediately.\nThis gives users a quick response.\nThen, we process the actual work in the background, which won't block other requests.\nUsers can check the status of their request using the tracking ID whenever they want.
\nThis is different from async/await in C#.\nThat's about handling many requests at once (concurrently).\nThis is about handling long-running tasks better.\nWe're not just making the code asynchronous - we're making the entire operation asynchronous from the user's perspective.
Let's see this in practice with image processing. A typical image upload API might look like this:
\n[HttpPost]\npublic async Task<IActionResult> UploadImage(IFormFile file)\n{\n if (file is null)\n {\n return BadRequest();\n }\n\n // Save original image\n var originalPath = await SaveOriginalAsync(file);\n\n // Generate thumbnails\n var thumbnails = await GenerateThumbnailsAsync(originalPath);\n\n // Optimize all images\n await OptimizeImagesAsync(originalPath, thumbnails);\n\n return Ok(new { originalPath, thumbnails });\n}\nThe client must wait while we save the file, generate thumbnails, and optimize images.\nOn a slow connection or with a large file, this request could time out.\nThe server is also stuck processing one image at a time.
\n![\"Sequence](\"https://milanjovanovic.tech/blogs/mnw_117/sync_api_request.png\")
\nLet's fix these problems. We'll split the work into two parts:
\n![\"Sequence](\"https://milanjovanovic.tech/blogs/mnw_117/async_api_request.png\")
\nHere's the new upload endpoint:
\n[HttpPost]\npublic async Task<IActionResult> UploadImage(IFormFile? file)\n{\n if (file is null)\n {\n return BadRequest("No file uploaded.");\n }\n\n if (!imageService.IsValidImage(file))\n {\n return BadRequest("Invalid image file.");\n }\n\n // Phase 1: Accept the work\n var id = Guid.NewGuid().ToString();\n var folderPath = Path.Combine(_uploadDirectory, "images", id);\n var fileName = $"{id}{Path.GetExtension(file.FileName)}";\n var originalPath = await imageService.SaveOriginalImageAsync(\n file,\n folderPath,\n fileName\n );\n\n // Queue Phase 2 for background processing\n var job = new ImageProcessingJob(id, originalPath, folderPath);\n await jobQueue.EnqueueAsync(job);\n\n // Return status URL immediately\n var statusUrl = GetStatusUrl(id);\n return Accepted(statusUrl, new { id, status = "queued" });\n}\nThis new version only saves the original file during the HTTP request.\nThe heavy work moves to a background process.\nThe client immediately gets a status URL in the Location header instead of waiting.
Clients can check their image's status using a separate endpoint:
\n[HttpGet("{id}/status")]\npublic IActionResult GetStatus(string id)\n{\n if (!statusTracker.TryGetStatus(id, out var status))\n {\n return NotFound();\n }\n\n var response = new\n {\n id,\n status,\n links = new Dictionary<string, string>()\n };\n\n if (status == "completed")\n {\n response.links = new Dictionary<string, string>\n {\n ["original"] = GetImageUrl(id),\n ["thumbnail"] = GetThumbnailUrl(id, width: 200),\n ["preview"] = GetThumbnailUrl(id, width: 800)\n };\n }\n\n return Ok(response);\n}\nThe real work happens in the background processor.\nWhile the API handles new requests, a separate process works through the queued jobs.\nThis separation gives us flexibility in how we handle the processing.
\nFor single-server deployments, we can use .NET's Channel type to queue jobs in memory:
\npublic class JobQueue\n{\n private readonly Channel<ImageProcessingJob> _channel;\n\n public JobQueue()\n {\n var options = new BoundedChannelOptions(1000)\n {\n FullMode = BoundedChannelFullMode.Wait\n };\n _channel = Channel.CreateBounded<ImageProcessingJob>(options);\n }\n\n public async ValueTask EnqueueAsync(ImageProcessingJob job,\n CancellationToken ct = default)\n {\n await _channel.Writer.WriteAsync(job, ct);\n }\n\n public IAsyncEnumerable<ImageProcessingJob> DequeueAsync(\n CancellationToken ct = default)\n {\n return _channel.Reader.ReadAllAsync(ct);\n }\n}\nFor multi-server setups, we need a distributed queue like RabbitMQ or even Redis.
\nThe background processor handles the time-consuming work:
\npublic class ImageProcessor : BackgroundService\n{\n protected override async Task ExecuteAsync(CancellationToken ct)\n {\n await foreach (var job in jobQueue.DequeueAsync(ct))\n {\n try\n {\n await statusTracker.SetStatusAsync(\n job.Id,\n "processing"\n );\n\n // Generate thumbnails\n await GenerateThumbnailsAsync(\n job.OriginalPath,\n job.OutputPath\n );\n\n // Optimize images\n await OptimizeImagesAsync(\n job.OriginalPath,\n job.OutputPath\n );\n\n await statusTracker.SetStatusAsync(\n job.Id,\n "completed"\n );\n }\n catch (Exception ex)\n {\n await statusTracker.SetStatusAsync(\n job.Id,\n "failed"\n );\n\n logger.LogError(ex, "Failed to process image {Id}", job.Id);\n }\n }\n }\n}\nThe background processor needs to handle failures gracefully.\nWe can improve resilience by adding a retry policy with Polly.\nStatus updates keep users informed throughout the process.\nInstead of just "processing", we tell them exactly what's happening.\nThis improves the user experience and helps with debugging.
\nOur status endpoint works, but it puts the burden on clients.\nThey must repeatedly check for updates, leading to unnecessary server load.\nA client polling every second creates 60 requests per minute, yet most of these requests return the same status.
\nWe can flip this model around.\nInstead of clients asking for updates, the server can push updates when they happen.\nThis creates a more efficient and responsive system.
\n![\"Sequence](\"https://milanjovanovic.tech/blogs/mnw_117/async_api_request_with_push.png\")
\nSignalR and WebSockets enable real-time communication between server and client.\nWhen a job's status changes, the server immediately notifies interested clients.\nThis approach reduces network traffic and gives users instant feedback.
\nFor longer-running jobs, email notifications make more sense.\nUsers don't need to keep their browsers open.\nThey can close the tab and come back when notified.\nThis works well for reports that take hours to generate or batch processes that run overnight.
\nWebhooks offer another option, especially for system-to-system communication.\nWhen a job completes, your server can notify other systems.\nThis enables workflow automation and system integration without constant polling.
\nProcessing tasks asynchronously creates better experiences for everyone.\nUsers get immediate responses instead of watching spinning loading indicators.\nThey can start other tasks while waiting, and they'll know if something goes wrong.
\nThe benefits extend beyond user experience.\nServers can handle more requests because they're not tied up with long-running tasks.\nBackground processors can retry failed operations without affecting the main application.\nYou can even scale your processing separately from your web servers.
\nError handling improves too.\nWhen a long operation fails halfway through, you can save the progress and try again.\nUsers know exactly what's happening because they can check the status.\nThe system stays stable because one slow operation can't bring down your entire API.
\nThat's all for today. Hope this was helpful.
\nHybridCache is a caching library introduced in .NET 9 that combines a fast in-memory L1 cache with a distributed L2 cache like Redis or SQL Server.\nIt protects against cache stampede and supports tag-based invalidation.\nThis issue covers the setup, the core methods, and adding Redis as the L2 cache.
Caching is essential for building fast, scalable applications.\nASP.NET Core has traditionally offered two caching options: in-memory caching and distributed caching.\nEach has its trade-offs.\nIn-memory caching using IMemoryCache is fast but limited to a single server.\nDistributed caching with IDistributedCache works across multiple servers using a backplane.
.NET 9 introduces HybridCache, a new library that combines the best of both approaches.\nIt prevents common caching problems like cache stampede.\nIt also adds useful features like tag-based invalidation and better performance monitoring.
In this week's issue, I'll show you how to use HybridCache in your applications.
The traditional caching options in ASP.NET Core have limitations.\nIn-memory caching is fast but limited to one server.\nDistributed caching works across servers but is slower.
\nHybridCache combines both approaches and adds important features:
\nThe L1 cache runs in your application's memory.\nThe L2 cache can be Redis, SQL Server, or any other distributed cache.\nYou can use HybridCache with just the L1 cache if you don't need distributed caching.
\nInstall the Microsoft.Extensions.Caching.Hybrid NuGet package:
Install-Package Microsoft.Extensions.Caching.Hybrid\nAdd HybridCache to your services:
builder.Services.AddHybridCache(options =>\n{\n // Maximum size of cached items\n options.MaximumPayloadBytes = 1024 * 1024 * 10; // 10MB\n options.MaximumKeyLength = 512;\n\n // Default timeouts\n options.DefaultEntryOptions = new HybridCacheEntryOptions\n {\n Expiration = TimeSpan.FromMinutes(30),\n LocalCacheExpiration = TimeSpan.FromMinutes(30)\n };\n});\nFor custom types, you can add your own serializer:
\nbuilder.Services.AddHybridCache()\n .AddSerializer<CustomType, CustomSerializer>();\nHybridCache provides several methods to work with cached data.\nThe most important ones are GetOrCreateAsync, SetAsync, and various remove methods.\nLet's see how to use each one in real-world scenarios.
The GetOrCreateAsync method is your main tool for working with cached data.\nIt handles both cache hits and misses automatically.\nIf the data isn't in the cache, it calls your factory method to get the data, caches it, and returns it.
Here's an endpoint that gets product details:
\napp.MapGet("/products/{id}", async (\n int id,\n HybridCache cache,\n ProductDbContext db,\n CancellationToken ct) =>\n{\n var product = await cache.GetOrCreateAsync(\n $"product-{id}",\n async token =>\n {\n return await db.Products\n .Include(p => p.Category)\n .FirstOrDefaultAsync(p => p.Id == id, token);\n },\n cancellationToken: ct\n );\n\n return product is null ? Results.NotFound() : Results.Ok(product);\n});\nIn this example:
\nSometimes you need to update the cache directly, like after modifying data.\nThe SetAsync method handles this:
app.MapPut("/products/{id}", async (int id, Product product, HybridCache cache) =>\n{\n // First update the database\n await UpdateProductInDatabase(product);\n\n // Then update the cache with custom expiration\n var options = new HybridCacheEntryOptions\n {\n Expiration = TimeSpan.FromHours(1),\n LocalCacheExpiration = TimeSpan.FromMinutes(30)\n };\n\n await cache.SetAsync(\n $"product-{id}",\n product,\n options\n );\n\n return Results.NoContent();\n});\nKey points about SetAsync:
Tags are powerful for managing groups of related cache entries.\nYou can invalidate multiple entries at once using tags:
\napp.MapGet("/categories/{id}/products", async (\n int id,\n HybridCache cache,\n ProductDbContext db,\n CancellationToken ct) =>\n{\n var tags = [$"category-{id}", "products"];\n\n var products = await cache.GetOrCreateAsync(\n $"products-by-category-{id}",\n async token =>\n {\n return await db.Products\n .Where(p => p.CategoryId == id)\n .Include(p => p.Category)\n .ToListAsync(token);\n },\n tags: tags,\n cancellationToken: ct\n );\n\n return Results.Ok(products);\n});\n\n// Endpoint to invalidate all products in a category\napp.MapPost("/categories/{id}/invalidate", async (\n int id,\n HybridCache cache,\n CancellationToken ct) =>\n{\n await cache.RemoveByTagAsync($"category-{id}", ct);\n\n return Results.NoContent();\n});\nTags are useful for:
\nFor direct cache invalidation of specific items, use RemoveAsync:
app.MapDelete("/products/{id}", async (int id, HybridCache cache) =>\n{\n // First delete from database\n await DeleteProductFromDatabase(id);\n\n // Then remove from cache\n await cache.RemoveAsync($"product-{id}");\n\n return Results.NoContent();\n});\nRemoveAsync:
Remember that HybridCache handles all the complexity of distributed caching, serialization, and stampede protection for you.\nYou just need to focus on your cache keys and when to invalidate the cache.
To use Redis as your distributed cache:
\nMicrosoft.Extensions.Caching.StackExchangeRedis NuGet package:Install-Package Microsoft.Extensions.Caching.StackExchangeRedis\nHybridCache:// Add Redis\nbuilder.Services.AddStackExchangeRedisCache(options =>\n{\n options.Configuration = "your-redis-connection-string";\n});\n\n// Add HybridCache - it will automatically use Redis as L2\nbuilder.Services.AddHybridCache();\nHybridCache will automatically detect and use Redis as the L2 cache.
HybridCache simplifies caching in .NET applications.\nIt combines fast in-memory caching with distributed caching, prevents common problems like cache stampede,\nand works well in both single-server and distributed systems.
Start with the default settings and basic usage patterns - the library is designed to be simple to use while solving complex caching problems.
\nOne thing HybridCache can't solve for you is the key.\nIf you're caching a value you derive from other data, content-addressed caching hashes every input into the key, so an entry can never go stale.
Thanks for reading.
\nAnd stay awesome!
\nC# supports functional programming through records, LINQ, and lambda expressions.\nThe practical parts are the patterns you can use today: higher-order functions, errors as values, monadic binding, pure functions, and immutability.\nThis issue shows each one with concrete C# examples.
\nFunctional programming patterns can feel academic and abstract.\nTerms like "monads" and "functors" scare many developers away.\nBut beneath the intimidating terminology are practical patterns that can make your code safer and more maintainable.
\nC# has embraced many functional programming features over the years.
\nThese features aren't just syntax sugar - they help prevent bugs and make code easier to reason about.
\nLet's look at five practical patterns you can use in your C# projects today.
\nHigher-order functions can take other functions as parameters or return them as results.\nThey let you write code that's more flexible and composable because you can pass behavior around like data.
\nCommon examples of higher-order functions are LINQ's Where and Select, which take functions to transform data.
Let's refactor this validation example with higher-order functions:
\npublic class OrderValidator\n{\n public bool ValidateOrder(Order order)\n {\n if (order.Items.Count == 0) return false;\n if (order.TotalAmount <= 0) return false;\n if (order.ShippingAddress == null) return false;\n return true;\n }\n}\n\n// What if we need:\n// - different validation rules for different countries?\n// - to reuse some validations but not others?\n// - to combine validations differently?\nHere's how higher-order functions make this more flexible:
\npublic static class OrderValidation\n{\n public static Func<Order, bool> CreateValidator(string countryCode, decimal minimumOrderValue)\n {\n var baseValidations = CombineValidations(\n o => o.Items.Count > 0,\n o => o.TotalAmount >= minimumOrderValue,\n o => o.ShippingAddress != null\n );\n\n return countryCode switch\n {\n "US" => CombineValidations(\n baseValidations,\n order => IsValidUSAddress(order.ShippingAddress)),\n "EU" => CombineValidations(\n baseValidations,\n order => IsValidVATNumber(order.VatNumber)),\n _ => baseValidations\n };\n }\n\n private static Func<Order, bool> CombineValidations(params Func<Order, bool>[] validations) =>\n order => validations.All(v => v(order));\n}\n\n// Usage\nvar usValidator = OrderValidation.CreateValidator("US", minimumOrderValue: 25.0m);\nvar euValidator = OrderValidation.CreateValidator("EU", minimumOrderValue: 30.0m);\nThe higher-order function approach makes validators composable, testable, and easy to extend.\nEach validation rule is a simple function that we can compose.
\nError handling in C# often looks like this:
\npublic class UserService\n{\n public User CreateUser(string email, string password)\n {\n if (string.IsNullOrEmpty(email))\n {\n throw new ArgumentException("Email is required");\n }\n\n if (password.Length < 8)\n {\n throw new ArgumentException("Password too short");\n }\n\n if (_userRepository.EmailExists(email))\n {\n throw new DuplicateEmailException(email);\n }\n\n // Create user...\n }\n}\nThe problem?
\nWe can make errors explicit using the OneOf library.\nIt provides discriminated unions for C#, using a custom type OneOf<T0, ... Tn>.
public class UserService\n{\n public OneOf<User, ValidationError, DuplicateEmailError> CreateUser(string email, string password)\n {\n if (string.IsNullOrEmpty(email))\n {\n return new ValidationError("Email is required");\n }\n\n if (password.Length < 8)\n {\n return new ValidationError("Password too short");\n }\n\n if (_userRepository.EmailExists(email))\n {\n return new DuplicateEmailError(email);\n }\n\n return new User(email, password);\n }\n}\nBy making the errors explicit:
\nHere's how you use it:
\nvar result = userService.CreateUser(email, password);\n\nresult.Switch(\n user => SendWelcomeEmail(user),\n validationError => HandleError(validationError),\n duplicateError => HandleError(duplicateError)\n);\nA monad is a container for values - like List<T>, IEnumerable<T>, or Task<T>.\nWhat makes it special is that you can chain operations on the contained values without dealing with the container directly.\nThis chaining is called monadic binding.
You use monadic binding daily with LINQ, but you might not know it.\nIt's what allows us to chain operations that transform data.
\nMap (Select) transforms values:
// Simple transformations with Select (Map)\nvar numbers = new[] { 1, 2, 3, 4 };\n\nvar doubled = numbers.Select(x => x * 2);\nBind (SelectMany) transforms and flattens:
// Operations that return multiple values use SelectMany (Bind)\nvar folders = new[] { "docs", "photos" };\n\nvar files = folders.SelectMany(folder => Directory.GetFiles(folder));\nA popular example of applying monads in practice is the Result pattern,\nwhich provides a clean way to chain operations that might fail.
\nPure functions are predictable: they depend only on their inputs and don't change anything in the system.\nNo database calls, no API requests, no global state.\nThis constraint makes them easier to understand, test, and debug.
\n// Impure - relies on hidden state\npublic class PriceCalculator\n{\n private decimal _taxRate;\n private List<Discount> _activeDiscounts;\n\n public decimal CalculatePrice(Order order)\n {\n var price = order.Items.Sum(i => i.Price);\n\n foreach (var discount in _activeDiscounts)\n {\n price -= discount.Calculate(price);\n }\n\n return price * (1 + _taxRate);\n }\n}\nHere's the same example as a pure function:
\n// Pure - everything is explicit\npublic static class PriceCalculator\n{\n public static decimal CalculatePrice(\n Order order,\n decimal taxRate,\n IReadOnlyList<Discount> discounts)\n {\n var basePrice = order.Items.Sum(i => i.Price);\n\n var afterDiscounts = discounts.Aggregate(\n basePrice,\n (price, discount) => price - discount.Calculate(price));\n\n return afterDiscounts * (1 + taxRate);\n }\n}\nPure functions are thread-safe, easy to test, and simple to reason about because all dependencies are explicit.
\nImmutable objects can't be changed after creation.\nInstead, they create new instances for every change.\nThis simple constraint eliminates entire categories of bugs: race conditions, accidental modifications, and inconsistent state.
\nHere's an example of a mutable type:
\npublic class Order\n{\n public List<OrderItem> Items { get; set; }\n public decimal Total { get; set; }\n public OrderStatus Status { get; set; }\n\n public void AddItem(OrderItem item)\n {\n Items.Add(item);\n Total += item.Price;\n // Bug: Thread safety issues\n // Bug: Can modify shipped orders\n // Bug: Total might not match Items\n }\n}\nLet's make this an immutable type:
\npublic record Order\n{\n public ImmutableList<OrderItem> Items { get; init; }\n public OrderStatus Status { get; init; }\n public decimal Total => Items.Sum(x => x.Price);\n\n public Order AddItem(OrderItem item)\n {\n if (Status != OrderStatus.Created)\n {\n throw new InvalidOperationException("Can't modify shipped orders");\n }\n\n return this with\n {\n Items = Items.Add(item)\n };\n }\n}\nThe immutable version:
\nFunctional programming isn't just about writing "cleaner" code.\nThese patterns fundamentally change how you handle complexity:
\nYou can adopt these patterns gradually.\nStart with one class, one module, one feature.\nThe goal isn't to write purely functional code.\nThe goal is to write code that's safer, more predictable, and easier to maintain.
\nHope this was helpful.\nSee you next week.
\nClean Architecture is about managing dependencies, and the famous diagram was never meant to be a project structure.\nSimon Brown's "missing chapter" for the Clean Architecture book shows how to organize code around business capabilities, using package by feature or package by component.\nThis issue covers both approaches and how to enforce the boundaries in .NET.
\nI see the same mistake happen over and over again.
\nDevelopers discover Clean Architecture, get excited about its principles, and then... they turn the famous Clean Architecture diagram into a project structure.
\nBut here's the thing: Clean Architecture is not about folders.\nIt's about dependencies.
\nSimon Brown wrote a "missing chapter" for Uncle Bob's Clean Architecture book that addresses exactly this issue.\nYet somehow, this crucial message got lost along the way.
\nToday, I'll show you what Uncle Bob's Clean Architecture diagram really means and how you should actually organize your code.\nWe'll look at practical examples that you can use in your projects right now.
\nLet's clear up this common misconception once and for all.
\nAlmost every .NET developer has built a solution that looks like this:
\nMyApp.Web for controllers and viewsMyApp.Business for services and business logicMyApp.Data for repositories and data accessIt's the default approach. It's what we see in tutorials. It's what we teach juniors.
\nAnd it's completely wrong.
\nWhen you organize code by technical layers, you scatter related components across multiple projects.\nA single feature, like managing policies, ends up spread across your entire codebase:
\nHere's what you'll see when looking at the folder structure:
\n📁 MyApp.Web\n|__ 📁 Controllers\n |__ #️⃣ PoliciesController.cs\n📁 MyApp.Business\n|__ 📁 Services\n |__ #️⃣ PolicyService.cs\n📁 MyApp.Data\n|__ 📁 Repositories\n |__ #️⃣ PolicyRepository.cs\nHere's a visual representation of the layer-based architecture:
\n![\"Feature](\"https://milanjovanovic.tech/blogs/mnw_114/layered_architecture.png\")
\nThis fragmentation creates several problems:
\nViolates Common Closure Principle - Classes that change together should stay together.\nWhen your "Policies" feature changes, you're touching three different projects.
\nHidden dependencies - Public interfaces everywhere make it possible to bypass layers.\nNothing stops a controller from directly accessing a repository.
\nNo business intent - Opening your solution tells you nothing about what the application does.\nIt only shows technical implementation details.
\nHarder maintenance - Making changes requires jumping between multiple projects.
\nThe worst part? This approach doesn't even achieve what it promises.\nDespite the separate projects, you often end up with a "big ball of mud" because public access modifiers allow any class to reference any other class.
\nClean Architecture's circles were never meant to represent projects or folders.\nThey represent different levels of policy, with dependencies pointing inward toward business rules.
\nYou can achieve this without splitting your code into artificial technical layers.
\nLet me show you a better way.
\nInstead of splitting your code by technical layers, you have two better options: package by feature or package by component.
\nLet's look at both.
\nOrganizing by feature is a solid option.\nEach feature gets its own namespace and contains everything needed to implement that feature.
\n📁 MyApp.Policies\n|__ 📁 RenewPolicy\n |__ #️⃣ RenewPolicyCommand.cs\n |__ #️⃣ RenewPolicyHandler.cs\n |__ #️⃣ PolicyValidator.cs\n |__ #️⃣ PolicyRepository.cs\n|__ 📁 ViewPolicyHistory\n |__ #️⃣ PolicyHistoryQuery.cs\n |__ #️⃣ PolicyHistoryHandler.cs\n |__ #️⃣ PolicyHistoryViewModel.cs\nHere's a diagram representing this structure:
\n![\"Vertical](\"https://milanjovanovic.tech/blogs/mnw_114/feature_folder_architecture.png\")
\nThis approach:
\nIf you want to learn more, check out my article about vertical slice architecture.
\nA component is a cohesive group of related functionality with a well-defined interface.\nComponent-based organization is more coarse-grained than feature folders.\nThink of it as a mini application that handles one specific business capability.
\nThis is very similar to how I define modules in a modular monolith.
\nHere's what a component-based organization looks like:
\n📁 MyApp.Web\n|__ 📁 Controllers\n |__ #️⃣ PoliciesController.cs\n📁 MyApp.Policies\n|__ #️⃣ PoliciesComponent.cs // Public interface\n|__ #️⃣ PolicyService.cs // Implementation detail\n|__ #️⃣ PolicyRepository.cs // Implementation detail\nThe key difference? Only PoliciesComponent is public.\nEverything else is internal to the component.
![\"Feature](\"https://milanjovanovic.tech/blogs/mnw_114/component_architecture.png\")
\nThis means:
\nChoose Package by Feature when:
\nChoose Package by Component when:
\nBoth approaches achieve what Clean Architecture really wants: proper dependency management and business focus.
\nHere's a side-by-side comparison of these architectural approaches:
\n![\"Comparison](\"https://milanjovanovic.tech/blogs/mnw_114/architecture_comparison.png\")
\n In the Missing Chapter of Clean Architecture, Simon Brown argues strongly for package by component.\nThe key insight is that components are the natural way to slice a system.\nThey represent complete business capabilities, not just technical features.
\nMy recommendation?\nStart with package by component.\nWithin the component, organize around features.
\nLet's transform a typical layered application into a clean, component-based structure.\nWe'll use an insurance policy system as an example.
\nHere's how most developers structure their solution:
\n// MyApp.Data\npublic interface IPolicyRepository\n{\n Task<Policy> GetByIdAsync(string policyNumber);\n Task SaveAsync(Policy policy);\n}\n\n// MyApp.Business\npublic class PolicyService : IPolicyService\n{\n private readonly IPolicyRepository _repository;\n\n public PolicyService(IPolicyRepository repository)\n {\n _repository = repository;\n }\n\n public async Task RenewPolicyAsync(string policyNumber)\n {\n var policy = await _repository.GetByIdAsync(policyNumber);\n // Business logic here\n await _repository.SaveAsync(policy);\n }\n}\n\n// MyApp.Web\npublic class PoliciesController : ControllerBase\n{\n private readonly IPolicyService _policyService;\n\n public PoliciesController(IPolicyService policyService)\n {\n _policyService = policyService;\n }\n\n [HttpPost("renew/{policyNumber}")]\n public async Task<IActionResult> RenewPolicy(string policyNumber)\n {\n await _policyService.RenewPolicyAsync(policyNumber);\n return Ok();\n }\n}\nThe problem?\nEverything is public.\nAny class can bypass the service and go straight to the repository.
\nHere's the same functionality organized as a proper component:
\n// The only public contract\npublic interface IPoliciesComponent\n{\n Task RenewPolicyAsync(string policyNumber);\n}\n\n// Everything below is internal to the component\ninternal class PoliciesComponent : IPoliciesComponent\n{\n private readonly IRenewPolicyHandler _renewPolicyHandler;\n\n // Public constructor for DI\n public PoliciesComponent(IRenewPolicyHandler renewPolicyHandler)\n {\n _renewPolicyHandler = renewPolicyHandler;\n }\n\n public async Task RenewPolicyAsync(string policyNumber)\n {\n await _renewPolicyHandler.HandleAsync(policyNumber);\n }\n}\n\ninternal interface IRenewPolicyHandler\n{\n Task HandleAsync(string policyNumber);\n}\n\ninternal class RenewPolicyHandler : IRenewPolicyHandler\n{\n private readonly IPolicyRepository _repository;\n\n internal RenewPolicyHandler(IPolicyRepository repository)\n {\n _repository = repository;\n }\n\n public async Task HandleAsync(string policyNumber)\n {\n var policy = await _repository.GetByIdAsync(policyNumber);\n // Business logic for policy renewal here\n await _repository.SaveAsync(policy);\n }\n}\n\ninternal interface IPolicyRepository\n{\n Task<Policy> GetByIdAsync(string policyNumber);\n Task SaveAsync(Policy policy);\n}\nThe key improvements are:
\nSingle public interface - Only IPoliciesComponent is public. Everything else is internal.
Protected dependencies - No way to bypass the component and access the repository directly.
\nClear dependencies - All dependencies flow inward through the component.
\nProper encapsulation - Implementation details are truly hidden.
\nThis is how you would register the services with dependency injection:
\nservices.AddScoped<IPoliciesComponent, PoliciesComponent>();\nservices.AddScoped<IRenewPolicyHandler, RenewPolicyHandler>();\nservices.AddScoped<IPolicyRepository, SqlPolicyRepository>();\nThis structure enforces Clean Architecture principles through compiler-checked boundaries, not just conventions.
\nThe compiler won't let you bypass the component's public interface.\nThat's much stronger than hoping developers follow the rules.
\nLet's discuss something that is often overlooked: the practical limitations of enforcing Clean Architecture in .NET.
\nThe internal keyword in .NET provides protection within a single assembly.\nHere's what that means in practice:
// In a single project:\npublic interface IPoliciesComponent { } // Public contract\ninternal class PoliciesComponent : IPoliciesComponent { }\ninternal class PolicyRepository { }\n\n// Someone could still do this:\npublic class BadPoliciesComponent : IPoliciesComponent\n{\n public BadPoliciesComponent()\n {\n // Nothing stops them from creating a bad implementation\n }\n}\nWhile internal helps, it doesn't prevent all architectural violations.
Some teams split their code into separate assemblies for stronger encapsulation:
\nMyCompany.Policies.Core.dll\nMyCompany.Policies.Infrastructure.dll\nMyCompany.Policies.Api.dll\nThis comes with trade-offs:
\nHere's what I recommend:
\nUse a single assembly
\ninternal for implementation detailssealed to prevent inheritance when possibleEnforce through architecture testing
\n[Fact]\npublic void Controllers_Should_Only_Depend_On_Component_Interfaces()\n{\n var allTypes = Types.InAssembly(Assembly.GetExecutingAssembly());\n\n TestResult? result = allTypes\n .That()\n .ResideInNamespace("MyApp.Controllers")\n .Should()\n .OnlyHaveDependenciesOn(\n allTypes\n .That()\n .HaveNameEndingWith("Component")\n .Or()\n .HaveNameStartingWith("IPolicy")\n .GetTypes()\n .Select(t => t.FullName!)\n .ToArray())\n .GetResult();\n\n result.IsSuccessful.Should().BeTrue();\n}\nWant to learn more about enforcing architecture through testing?\nCheck out my article on architecture testing.
\nRemember: Clean Architecture is about managing dependencies, not about achieving perfect encapsulation.\nUse the tools the language gives you, but don't over-complicate things chasing an impossible ideal.
\nClean Architecture isn't about projects, folders, or perfect encapsulation.
\nIt's about:
\nStart with a single project.\nUse components.\nMake interfaces public and implementations internal.\nAdd architecture tests if you need more control.
\nAnd remember: pragmatism beats purism.\nYour architecture should help you ship features faster, not slow you down with artificial constraints.
\nWant to learn more?\nCheck out my Pragmatic Clean Architecture course,\nwhere I'll show you how to build maintainable applications with proper boundaries, clear dependencies, and business-focused components.
\nThat's all for today. Stay awesome, and I'll see you next week.
\nAn idempotent REST API returns the same result no matter how many times a client repeats a request.\nIn ASP.NET Core, you can implement it with idempotency keys: the client sends a unique key in a header, and the server caches the response so retries execute the operation only once.\nThis issue shows implementations for both controllers and Minimal APIs.
\nIdempotency is a crucial concept for REST APIs that ensures the reliability and consistency of your system.\nAn idempotent operation can be repeated multiple times without changing the result beyond the initial API request.\nThis property is especially important in distributed systems, where network failures or timeouts can lead to repeated requests.
\nImplementing idempotency in your API brings several benefits:
\nIn this week's issue, we'll explore how to implement idempotency in ASP.NET Core APIs, ensuring your system remains robust and reliable.
\nIdempotence, in the context of web APIs, means that making multiple identical requests should have the same effect as making a single request.\nIn other words, no matter how many times a client sends the same request, the server-side effect should only occur once.
\nThe RFC 9110 standard about HTTP Semantics offers a definition we could use.\nHere's what it says about idempotent methods:
\n\n\nA request method is considered "idempotent" if the intended effect on the server of multiple identical requests with\nthat method is the same as the effect for a single such request.
\nOf the request methods defined by this specification,\nPUT, DELETE, and safe request methods [(GET, HEAD, OPTIONS, and TRACE) - author's note] are idempotent.
\n
However, the following paragraph is quite interesting.\nIt clarifies that the server can implement "other non-idempotent side effects" that don't apply to the resource.
\n\n\n... the idempotent property only applies to what has been requested by the user;\na server is free to log each request separately, retain a revision control history, or implement other non-idempotent side effects for each idempotent request.
\n
The benefits of implementing idempotency extend beyond just adhering to HTTP method semantics.\nIt significantly improves the reliability of your API, especially in distributed systems where network issues can lead to retried requests.\nBy implementing idempotency, you prevent duplicate operations that could occur due to client retries.
\nSeveral HTTP methods are inherently idempotent:
\nGET, HEAD: Retrieve data without modifying the server state.PUT: Update a resource, resulting in the same state regardless of repetition.DELETE: Remove a resource with the same outcome for multiple requests.OPTIONS: Retrieve communication options information.POST is not inherently idempotent, as it typically creates resources or processes data.\nRepeated POST requests could create multiple resources or trigger multiple actions.
However, we can implement idempotency for POST methods using custom logic.
Note: While POST requests aren't naturally idempotent, we can design them to be.\nFor example, checking for existing resources before creation ensures that repeated POST requests don't result in duplicate actions or resources.
To implement idempotency, we'll use a strategy involving idempotency keys:
\nThis ensures that retried requests (e.g., due to network issues) are processed only once on the server.
\nWe can implement idempotency for controllers by combining an Attribute and IAsyncActionFilter.\nNow, we can specify the IdempotentAttribute to apply idempotency to a controller endpoint.
Note: When a request fails (returns 4xx/5xx), we don't cache the response.\nThis allows clients to retry with the same idempotency key.\nHowever, this means a failed request followed by a successful one with the same key will succeed - make sure this aligns with your business requirements.
\n[AttributeUsage(AttributeTargets.Method)]\ninternal sealed class IdempotentAttribute : Attribute, IAsyncActionFilter\n{\n private const int DefaultCacheTimeInMinutes = 60;\n private readonly TimeSpan _cacheDuration;\n\n public IdempotentAttribute(int cacheTimeInMinutes = DefaultCacheTimeInMinutes)\n {\n _cacheDuration = TimeSpan.FromMinutes(cacheTimeInMinutes);\n }\n\n public async Task OnActionExecutionAsync(\n ActionExecutingContext context,\n ActionExecutionDelegate next)\n {\n // Parse the Idempotence-Key header from the request\n if (!context.HttpContext.Request.Headers.TryGetValue(\n "Idempotence-Key",\n out StringValues idempotenceKeyValue) ||\n !Guid.TryParse(idempotenceKeyValue, out Guid idempotenceKey))\n {\n context.Result = new BadRequestObjectResult("Invalid or missing Idempotence-Key header");\n return;\n }\n\n IDistributedCache cache = context.HttpContext\n .RequestServices.GetRequiredService<IDistributedCache>();\n\n // Check if we already processed this request and return a cached response (if it exists)\n string cacheKey = $"Idempotent_{idempotenceKey}";\n string? cachedResult = await cache.GetStringAsync(cacheKey);\n if (cachedResult is not null)\n {\n IdempotentResponse response = JsonSerializer.Deserialize<IdempotentResponse>(cachedResult)!;\n\n var result = new ObjectResult(response.Value) { StatusCode = response.StatusCode };\n context.Result = result;\n\n return;\n }\n\n // Execute the request and cache the response for the specified duration\n ActionExecutedContext executedContext = await next();\n\n if (executedContext.Result is ObjectResult { StatusCode: >= 200 and < 300 } objectResult)\n {\n int statusCode = objectResult.StatusCode ?? StatusCodes.Status200OK;\n IdempotentResponse response = new(statusCode, objectResult.Value);\n\n await cache.SetStringAsync(\n cacheKey,\n JsonSerializer.Serialize(response),\n new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = _cacheDuration }\n );\n }\n }\n}\n\ninternal sealed class IdempotentResponse\n{\n [JsonConstructor]\n public IdempotentResponse(int statusCode, object? value)\n {\n StatusCode = statusCode;\n Value = value;\n }\n\n public int StatusCode { get; }\n public object? Value { get; }\n}\nNote: There's a small race condition window between checking and setting the cache.\nFor absolute consistency, we should consider using a distributed lock pattern, though this adds complexity and latency.
\nNow, we can apply this attribute to our controller actions:
\n[ApiController]\n[Route("api/[controller]")]\npublic class OrdersController : ControllerBase\n{\n [HttpPost]\n [Idempotent(cacheTimeInMinutes: 60)]\n public IActionResult CreateOrder([FromBody] CreateOrderRequest request)\n {\n // Process the order...\n\n return CreatedAtAction(nameof(GetOrder), new { id = orderDto.Id }, orderDto);\n }\n}\nIdempotency with Minimal APIs
\nTo implement idempotency with Minimal APIs, we can use an IEndpointFilter.
internal sealed class IdempotencyFilter(int cacheTimeInMinutes = 60)\n : IEndpointFilter\n{\n public async ValueTask<object?> InvokeAsync(\n EndpointFilterInvocationContext context,\n EndpointFilterDelegate next)\n {\n // Parse the Idempotence-Key header from the request\n if (TryGetIdempotenceKey(out Guid idempotenceKey))\n {\n return Results.BadRequest("Invalid or missing Idempotence-Key header");\n }\n\n IDistributedCache cache = context.HttpContext\n .RequestServices.GetRequiredService<IDistributedCache>();\n\n // Check if we already processed this request and return a cached response (if it exists)\n string cacheKey = $"Idempotent_{idempotenceKey}";\n string? cachedResult = await cache.GetStringAsync(cacheKey);\n if (cachedResult is not null)\n {\n IdempotentResponse response = JsonSerializer.Deserialize<IdempotentResponse>(cachedResult)!;\n return new IdempotentResult(response.StatusCode, response.Value);\n }\n\n object? result = await next(context);\n\n // Execute the request and cache the response for the specified duration\n if (result is IStatusCodeHttpResult { StatusCode: >= 200 and < 300 } statusCodeResult\n and IValueHttpResult valueResult)\n {\n int statusCode = statusCodeResult.StatusCode ?? StatusCodes.Status200OK;\n IdempotentResponse response = new(statusCode, valueResult.Value);\n\n await cache.SetStringAsync(\n cacheKey,\n JsonSerializer.Serialize(response),\n new DistributedCacheEntryOptions\n {\n AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(cacheTimeInMinutes)\n }\n );\n }\n\n return result;\n }\n}\n\n// We have to implement a custom result to write the status code\ninternal sealed class IdempotentResult : IResult\n{\n private readonly int _statusCode;\n private readonly object? _value;\n\n public IdempotentResult(int statusCode, object? value)\n {\n _statusCode = statusCode;\n _value = value;\n }\n\n public Task ExecuteAsync(HttpContext httpContext)\n {\n httpContext.Response.StatusCode = _statusCode;\n\n return httpContext.Response.WriteAsJsonAsync(_value);\n }\n}\nNow, we can apply this endpoint filter to our Minimal API endpoint:
\napp.MapPost("/api/orders", CreateOrder)\n .RequireAuthorization()\n .WithOpenApi()\n .AddEndpointFilter<IdempotencyFilter>();\nAn alternative to the previous two implementations is implementing idempotency logic in a custom middleware.
\nHere are the key things I always keep in mind when implementing idempotency.
\nCache duration is tricky.\nI aim to cover reasonable retry windows without holding onto stale data.\nA reasonable cache time typically ranges from a few minutes to 24-48 hours, depending on your specific use case.
\nConcurrency can be a pain, especially in high-traffic APIs.\nA thread-safe implementation using a distributed lock works great.\nIt keeps things in check when multiple requests hit at once.\nBut this should be a rare occurrence.
\nFor distributed setups, Redis is my go-to.\nIt's perfect as a shared cache, keeping idempotency consistent across all your API instances.\nPlus, it handles distributed locking.
\nWhat if a client reuses an idempotency key with a different request body?\nI return an error in this case.\nMy approach is to hash the request body and store it with the idempotency key.\nWhen a request comes in, I compare the request body hashes.\nIf they differ, I return an error.\nThis prevents misuse of idempotency keys and maintains the integrity of your API.
\nImplementing idempotency in REST APIs enhances service reliability and consistency.\nIt ensures identical requests yield the same result, preventing unintended duplicates and gracefully handling network issues.
\nWhile our implementation provides a foundation, I recommend adapting it to your needs.\nFocus on critical operations in your APIs, especially those that modify the system state or trigger important business processes.
\nBy embracing idempotency, you're building more robust and user-friendly APIs.
\nThat's all for today.
\nSee you next week.
\nProblem Details is a machine-readable JSON format for describing errors in HTTP API responses, standardized by RFC 9457.\nIn ASP.NET Core, you call AddProblemDetails and UseExceptionHandler, and unhandled exceptions become application/problem+json responses.\nThis issue also covers the .NET 8 IExceptionHandler and how to customize every Problem Details response.
When developing HTTP APIs, providing consistent and informative error responses is crucial for a smooth developer experience.\nProblem Details in ASP.NET Core offers a standardized solution to this challenge, ensuring your APIs communicate errors effectively and uniformly.
\nIn this article, we'll explore the latest developments in Problem Details, including:
\nIExceptionHandler for global exception handlingIProblemDetailsService for customizing Problem DetailsLet's dive into these features and see how they can improve your API's error handling.
\nProblem Details is a machine-readable format for specifying errors in HTTP API responses.\nHTTP status codes don't always contain enough details about errors to be helpful.\nThe Problem Details specification defines a JSON (and XML) document format to describe problems.
\nProblem Details includes:
\ntype: A URI reference that identifies the problem typetitle: A short, human-readable summary of the problem typestatus: The HTTP status codedetail: A human-readable explanation specific to this occurrence of the probleminstance: A URI reference that identifies the specific occurrence of the problemRFC 9457, which replaces RFC 7807,\nintroduces improvements such as clarifying the use of the type field and providing guidelines for extending Problem Details.
\nHere's an example Problem Details response:
\nContent-Type: application/problem+json\n\n{\n "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",\n "title": "Not Found",\n "status": 404,\n "detail": "The habit with the specified identifier was not found",\n "instance": "PUT /api/habits/aadcad3f-8dc8-443d-be44-3d99893ba18a"\n}\nLet's see how to implement Problem Details in ASP.NET Core.\nWe want to return a Problem Details response for unhandled exceptions.\nBy calling AddProblemDetails, we're configuring the application to use the Problem Details format for failed requests.\nWith UseExceptionHandler, we introduce an exception handling middleware to the request pipeline.\nBy adding UseStatusCodePages, we're introducing a middleware that will convert error responses with an empty body to a Problem Details response.
var builder = WebApplication.CreateBuilder(args);\n\n// Adds services for using Problem Details format\nbuilder.Services.AddProblemDetails();\n\nvar app = builder.Build();\n\n// Converts unhandled exceptions into Problem Details responses\napp.UseExceptionHandler();\n\n// Returns the Problem Details response for (empty) non-successful responses\napp.UseStatusCodePages();\n\napp.Run();\nWhen we encounter an unhandled exception, it will be translated to a Problem Details response:
\nContent-Type: application/problem+json\n\n{\n "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",\n "title": "An error occurred while processing your request.",\n "status": 500\n}\nNow, let's explore how we can customize this response.
\nWe have a few options for implementing global error handling.\nThe most popular approach is creating a custom exception handling middleware.\nYou wrap the API request in a try-catch statement and return a response based on any caught exception.
With .NET 8, we can use the IExceptionHandler that runs in the built-in exception handling middleware.\nThis handler allows you to tailor the Problem Details response for specific exceptions.\nReturning true from the TryHandleAsync method short-circuits the pipeline and returns the API response.\nIf we return false, the next handler in the chain attempts to handle the exception.
We can map different exception types to appropriate HTTP status codes, providing more precise error information to API consumers.
\nHere's an example CustomExceptionHandler implementation:
internal sealed class CustomExceptionHandler : IExceptionHandler\n{\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n int status = exception switch\n {\n ArgumentException => StatusCodes.Status400BadRequest,\n _ => StatusCodes.Status500InternalServerError\n };\n httpContext.Response.StatusCode = status;\n\n var problemDetails = new ProblemDetails\n {\n Status = status,\n Title = "An error occurred",\n Type = exception.GetType().Name,\n Detail = exception.Message\n };\n\n await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);\n\n return true;\n }\n}\n\n// In Program.cs\nbuilder.Services.AddExceptionHandler<CustomExceptionHandler>();\nCalling AddProblemDetails registers a default implementation of the IProblemDetailsService.\nThe IProblemDetailsService will set the response status code based on the ProblemDetails.Status.
Here's how we can use it in the CustomExceptionHandler:
public class CustomExceptionHandler(IProblemDetailsService problemDetailsService) : IExceptionHandler\n{\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n var problemDetails = new ProblemDetails\n {\n Status = exception switch\n {\n ArgumentException => StatusCodes.Status400BadRequest,\n _ => StatusCodes.Status500InternalServerError\n },\n Title = "An error occurred",\n Type = exception.GetType().Name,\n Detail = exception.Message\n };\n\n return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext\n {\n Exception = exception,\n HttpContext = httpContext,\n ProblemDetails = problemDetails\n });\n }\n}\nThis approach seems very similar to the previous one, where we wrote to the response body.\nHowever, using the IProblemDetailsService gives an easy way to customize all Problem Details responses.
We can return Problem Details in controllers using the Problem method, or Results.Problem in Minimal APIs.\nThese methods respect the configured Problem Details customizations (more on this in the next section).
IdentityUser identityUser = new() { UserName = registerUserDto.UserName, Email = registerUserDto.Email };\nIdentityResult result = await userManager.CreateAsync(identityUser, registerUserDto.Password);\n\nif (!result.Succeeded)\n{\n // return Results.Problem - Minimal APIs\n return Problem(\n type: "Bad Request",\n title: "Identity failure",\n detail: result.Errors.First().Description,\n statusCode: StatusCodes.Status400BadRequest);\n}\nWe can pass a delegate to the AddProblemDetails method to set the CustomizeProblemDetails.\nYou can use this to add extra information to all Problem Details responses.
This is an excellent place for solving cross-cutting concerns, like setting the instance value and adding diagnostics information.
builder.Services.AddProblemDetails(options =>\n{\n options.CustomizeProblemDetails = context =>\n {\n context.ProblemDetails.Instance =\n $"{context.HttpContext.Request.Method} {context.HttpContext.Request.Path}";\n\n context.ProblemDetails.Extensions.TryAdd("requestId", context.HttpContext.TraceIdentifier);\n\n Activity? activity = context.HttpContext.Features.Get<IHttpActivityFeature>()?.Activity;\n context.ProblemDetails.Extensions.TryAdd("traceId", activity?.Id);\n };\n});\nThis customization adds the request path, a request ID, and a trace ID to every Problem Details response, enhancing debuggability and traceability of errors.
\nContent-Type: application/problem+json\n\n{\n "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",\n "title": "Not Found",\n "status": 404,\n "instance": "PUT /api/habits/aadcad3f-8dc8-443d-be44-3d99893ba18a",\n "traceId": "00-63d4af1807586b0d98901ae47944192d-9a8635facb90bf76-01",\n "requestId": "0HN7C8PRNMGIA:00000001"\n}\nYou can use the traceId to find the distributed traces and logs in a monitoring system like Seq.
![\"Seq](\"https://milanjovanovic.tech/blogs/mnw_112/seq_tracing.png\")
\n.NET 9 introduces a simpler way to map exceptions to status codes.\nGreat news for fans of throwing exceptions.\nYou can use the StatusCodeSelector to define the mappings.\nThis makes it easier to maintain consistent error responses across your API.
app.UseExceptionHandler(new ExceptionHandlerOptions\n{\n StatusCodeSelector = ex => ex switch\n {\n ArgumentException => StatusCodes.Status400BadRequest,\n NotFoundException => StatusCodes.Status404NotFound,\n _ => StatusCodes.Status500InternalServerError\n }\n});\nIf you use this together with an IExceptionHandler that sets the StatusCode, then the StatusCodeSelector is ignored.
Implementing Problem Details in your ASP.NET Core APIs is more than just a best practice -\nit's a standard for improving the developer experience of your API consumers.\nBy providing consistent, detailed, and well-structured error responses, you make it easier for clients to understand and handle error scenarios gracefully.
\nAs you implement these practices in your own projects, you'll discover even more ways to tailor Problem Details to your specific needs.\nI shared what worked well for my use cases.
\nProblem Details is just one of the best practices covered in my REST APIs course.\nCheck it out if you're looking for a comprehensive guide.
\nGood luck out there, and I'll see you next week.
\nA covering index on the unprocessed-message query, batched publishes, one batched UPDATE, and five parallel workers took my Outbox processor from 1,350 to about 32,500 messages per second.\nThat is over 2.8 billion messages per day.\nOrdering is no longer guaranteed, and consumers still have to be idempotent.
In last week's newsletter, I talked about implementing the Outbox pattern.\nIt's a crucial tool for reliable distributed messaging.\nBut implementing it is just the first step.
\nThe real challenge? Scaling it to handle massive message volumes.
\nToday, we're taking it up a notch.\nWe'll start with a basic Outbox processor and transform it into a high-performance engine capable of handling over 2 billion messages daily.
\nLet's dive in!
\nThis is our starting point.\nWe have an OutboxProcessor that polls for unprocessed messages and publishes them to a queue.\nThe first few things we can tweak are the frequency and batch size.
internal sealed class OutboxProcessor(NpgsqlDataSource dataSource, IPublishEndpoint publishEndpoint)\n{\n private const int BatchSize = 1000;\n\n public async Task<int> Execute(CancellationToken cancellationToken = default)\n {\n await using var connection = await dataSource.OpenConnectionAsync(cancellationToken);\n await using var transaction = await connection.BeginTransactionAsync(cancellationToken);\n\n var messages = await connection.QueryAsync<OutboxMessage>(\n @"""\n SELECT *\n FROM outbox_messages\n WHERE processed_on_utc IS NULL\n ORDER BY occurred_on_utc LIMIT @BatchSize\n """,\n new { BatchSize },\n transaction: transaction);\n\n foreach (var message in messages)\n {\n try\n {\n var messageType = Messaging.Contracts.AssemblyReference.Assembly.GetType(message.Type);\n var deserializedMessage = JsonSerializer.Deserialize(message.Content, messageType);\n\n await publishEndpoint.Publish(deserializedMessage, messageType, cancellationToken);\n\n await connection.ExecuteAsync(\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = @ProcessedOnUtc\n WHERE id = @Id\n """,\n new { ProcessedOnUtc = DateTime.UtcNow, message.Id },\n transaction: transaction);\n }\n catch (Exception ex)\n {\n await connection.ExecuteAsync(\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = @ProcessedOnUtc, error = @Error\n WHERE id = @Id\n """,\n new { ProcessedOnUtc = DateTime.UtcNow, Error = ex.ToString(), message.Id },\n transaction: transaction);\n }\n }\n\n await transaction.CommitAsync(cancellationToken);\n\n return messages.Count;\n }\n}\nLet's assume that we run the OutboxProcessor continuously.\nI increased that batch size to 1000.
How many messages are we able to process?
\nI'll run the Outbox processing for 1 minute and count how many messages were processed.
\nThe baseline implementation processed 81,000 messages in one minute or 1,350 MPS (messages per second).
\nNot bad, but let's see how much we can improve this.
\nYou can't improve what you can't measure. Right?\nSo, I'll use a Stopwatch to measure the total execution time and the time each step takes.
Notice that I also split the publish and update steps.\nIt's so I can measure the time for publishing and updating separately.\nThis will be important later because I want to optimize each step separately.
\nWith the baseline implementation, here are the execution times for each step:
\ninternal sealed class OutboxProcessor(\n NpgsqlDataSource dataSource,\n IPublishEndpoint publishEndpoint,\n ILogger<OutboxProcessor> logger)\n{\n private const int BatchSize = 1000;\n\n public async Task<int> Execute(CancellationToken cancellationToken = default)\n {\n var totalStopwatch = Stopwatch.StartNew();\n var stepStopwatch = new Stopwatch();\n\n await using var connection = await dataSource.OpenConnectionAsync(cancellationToken);\n await using var transaction = await connection.BeginTransactionAsync(cancellationToken);\n\n stepStopwatch.Restart();\n var messages = (await connection.QueryAsync<OutboxMessage>(\n @"""\n SELECT *\n FROM outbox_messages\n WHERE processed_on_utc IS NULL\n ORDER BY occurred_on_utc LIMIT @BatchSize\n """,\n new { BatchSize },\n transaction: transaction)).AsList();\n var queryTime = stepStopwatch.ElapsedMilliseconds;\n\n var updateQueue = new ConcurrentQueue<OutboxUpdate>();\n\n stepStopwatch.Restart();\n foreach (var message in messages)\n {\n try\n {\n var messageType = Messaging.Contracts.AssemblyReference.Assembly.GetType(message.Type);\n var deserializedMessage = JsonSerializer.Deserialize(message.Content, messageType);\n\n await publishEndpoint.Publish(deserializedMessage, messageType, cancellationToken);\n\n updateQueue.Enqueue(new OutboxUpdate\n {\n Id = message.Id,\n ProcessedOnUtc = DateTime.UtcNow\n });\n }\n catch (Exception ex)\n {\n updateQueue.Enqueue(new OutboxUpdate\n {\n Id = message.Id,\n ProcessedOnUtc = DateTime.UtcNow,\n Error = ex.ToString()\n });\n }\n }\n var publishTime = stepStopwatch.ElapsedMilliseconds;\n\n stepStopwatch.Restart();\n foreach (var outboxUpdate in updateQueue)\n {\n await connection.ExecuteAsync(\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = @ProcessedOnUtc, error = @Error\n WHERE id = @Id\n """,\n outboxUpdate,\n transaction: transaction);\n }\n var updateTime = stepStopwatch.ElapsedMilliseconds;\n\n await transaction.CommitAsync(cancellationToken);\n\n totalStopwatch.Stop();\n var totalTime = totalStopwatch.ElapsedMilliseconds;\n\n OutboxLoggers.Processing(logger, totalTime, queryTime, publishTime, updateTime, messages.Count);\n\n return messages.Count;\n }\n\n private struct OutboxUpdate\n {\n public Guid Id { get; init; }\n public DateTime ProcessedOnUtc { get; init; }\n public string? Error { get; init; }\n }\n}\nNow, onto the fun part!
\nThe first thing I want to optimize is the query for fetching unprocessed messages.\nPerforming a SELECT * query will have an impact if we don't need all the columns (hint: we don't).
Here's the current SQL query:
\nSELECT *\nFROM outbox_messages\nWHERE processed_on_utc IS NULL\nORDER BY occurred_on_utc LIMIT @BatchSize\nWe can modify the query to return only the columns we need.\nThis will save us some bandwidth but will not significantly improve performance.
\nSELECT id AS Id, type AS Type, content as Content\nFROM outbox_messages\nWHERE processed_on_utc IS NULL\nORDER BY occurred_on_utc LIMIT @BatchSize\nLet's examine the execution plan for this query.\nYou'll see it's performing a table scan.\nI'm running this on PostgreSQL, and here's what I get from EXPLAIN ANALYZE:
Limit (cost=86169.40..86286.08 rows=1000 width=129) (actual time=122.744..124.234 rows=1000 loops=1)\n -> Gather Merge (cost=86169.40..245080.50 rows=1362000 width=129) (actual time=122.743..124.198 rows=1000 loops=1)\n Workers Planned: 2\n Workers Launched: 2\n -> Sort (cost=85169.38..86871.88 rows=681000 width=129) (actual time=121.478..121.492 rows=607 loops=3)\n Sort Key: occurred_on_utc\n Sort Method: top-N heapsort Memory: 306kB\n Worker 0: Sort Method: top-N heapsort Memory: 306kB\n Worker 1: Sort Method: top-N heapsort Memory: 306kB\n -> Parallel Seq Scan on outbox_messages (cost=0.00..47830.88 rows=681000 width=129) (actual time=0.016..67.481 rows=666667 loops=3)\n Filter: (processed_on_utc IS NULL)\nPlanning Time: 0.051 ms\nExecution Time: 124.298 ms\nNow, I'll create an index that "covers" the query for fetching unprocessed messages.\nA covered index contains all the columns needed to satisfy a query without accessing the table itself.
\nThe index will be on the occurred_on_utc and processed_on_utc columns.\nIt will include the id, type, and content columns.\nLastly, we'll apply a filter to index unprocessed messages only.
CREATE INDEX IF NOT EXISTS idx_outbox_messages_unprocessed\nON public.outbox_messages (occurred_on_utc, processed_on_utc)\nINCLUDE (id, type, content)\nWHERE processed_on_utc IS NULL\nLet me explain the reasoning behind each decision:
\noccurred_on_utc will store the entries in the index in ascending order.\nThis matches the ORDER BY occurred_on_utc statement in the query.\nThis means the query can scan the index without sorting the results.\nThe results are already in the correct sort order.WHERE processed_on_utc IS NULL statement.Caveat: PostgreSQL has a maximum index row size of 2712B (don't ask how I know).\nThe columns in the INCLUDE list are also part of the index row (B-tree tuple).\nThe content column contains the serialized JSON message, so it's the most likely culprit to make us exceed this limit.\nThere's no way around it, so my advice is to keep your messages as small as possible.\nYou could exclude this column from the INCLUDE list for a minor performance hit.
Here's the updated execution plan after creating this index:
\nLimit (cost=0.43..102.82 rows=1000 width=129) (actual time=0.016..0.160 rows=1000 loops=1)\n -> Index Only Scan using idx_outbox_messages_unprocessed on outbox_messages (cost=0.43..204777.36 rows=2000000 width=129) (actual time=0.015..0.125 rows=1000 loops=1)\n Heap Fetches: 0\nPlanning Time: 0.059 ms\nExecution Time: 0.189 ms\nBecause we have a covered index, the execution plan only contains an Index Only Scan and Limit operation.\nThere's no filtering or sorting that needs to happen, which is why we see a massive performance improvement.
What's the performance impact on the query time?
\nThe next thing we can optimize is how we're publishing messages to the queue.\nI'm using the IPublishEndpoint from MassTransit to publish to RabbitMQ.
To be more precise here, we're publishing to an exchange.\nThe exchange will then route the message to the appropriate queue.
\nBut how can we optimize this?
\nA micro-optimization we can do is introduce a cache for the message types used in serialization.\nPerforming reflection constantly for every message type is expensive, so we'll do the reflection once, and store the result.
\nvar messageType = Messaging.Contracts.AssemblyReference.Assembly.GetType(message.Type);\nThe cache can be a ConcurrentDictionary, and we'll use GetOrAdd to retrieve the cached types.
I'll extract this piece of code to the GetOrAddMessageType helper method:
private static readonly ConcurrentDictionary<string, Type> TypeCache = new();\n\nprivate static Type GetOrAddMessageType(string typeName)\n{\n return TypeCache.GetOrAdd(\n typeName,\n name => Messaging.Contracts.AssemblyReference.Assembly.GetType(name));\n}\nThis is what our message publishing step looks like.\nThe biggest problem is we're waiting for the Publish to complete by awaiting it.\nThe Publish takes some time because it's waiting for confirmation from the message broker.\nWe're doing this in a loop, which makes it even less efficient.
var updateQueue = new ConcurrentQueue<OutboxUpdate>();\n\nforeach (var message in messages)\n{\n try\n {\n var messageType = Messaging.Contracts.AssemblyReference.Assembly.GetType(message.Type);\n var deserializedMessage = JsonSerializer.Deserialize(message.Content, messageType);\n\n // We're waiting for the message broker confirmation here.\n await publishEndpoint.Publish(deserializedMessage, messageType, cancellationToken);\n\n updateQueue.Enqueue(new OutboxUpdate\n {\n Id = message.Id,\n ProcessedOnUtc = DateTime.UtcNow\n });\n }\n catch (Exception ex)\n {\n updateQueue.Enqueue(new OutboxUpdate\n {\n Id = message.Id,\n ProcessedOnUtc = DateTime.UtcNow,\n Error = ex.ToString()\n });\n }\n}\nWe can improve this by publishing the messages in a batch.\nIn fact, the IPublishEndpoint has a PublishBatch extension method.\nIf we peek inside, here's what we'll find:
// MassTransit implementation\npublic static Task PublishBatch(\n this IPublishEndpoint endpoint,\n IEnumerable<object> messages,\n CancellationToken cancellationToken = default)\n{\n return Task.WhenAll(messages.Select(x => endpoint.Publish(x, cancellationToken)));\n}\nSo we can transform the collection of messages into a list of publishing tasks that we can await using Task.WhenAll.
var updateQueue = new ConcurrentQueue<OutboxUpdate>();\n\nvar publishTasks = messages\n .Select(message => PublishMessage(message, updateQueue, publishEndpoint, cancellationToken))\n .ToList();\n\nawait Task.WhenAll(publishTasks);\n\n// I extracted the message publishing into a separate method for readability.\nprivate static async Task PublishMessage(\n OutboxMessage message,\n ConcurrentQueue<OutboxUpdate> updateQueue,\n IPublishEndpoint publishEndpoint,\n CancellationToken cancellationToken)\n{\n try\n {\n var messageType = GetOrAddMessageType(message.Type);\n var deserializedMessage = JsonSerializer.Deserialize(message.Content, messageType);\n\n await publishEndpoint.Publish(deserializedMessage, messageType, cancellationToken);\n\n updateQueue.Enqueue(new OutboxUpdate\n {\n Id = message.Id,\n ProcessedOnUtc = DateTime.UtcNow\n });\n }\n catch (Exception ex)\n {\n updateQueue.Enqueue(new OutboxUpdate\n {\n Id = message.Id,\n ProcessedOnUtc = DateTime.UtcNow,\n Error = ex.ToString()\n });\n }\n}\nWhat's the improvement for the message publishing step?
\nAs you can see, it's not significantly faster.\nBut this is needed for us to benefit from other optimizations I have in store.
\nThe next step in our optimization journey is addressing the query updating the processed Outbox messages.
\nThe current implementation is inefficient because we send one query to the database for each Outbox message.
\nforeach (var outboxUpdate in updateQueue)\n{\n await connection.ExecuteAsync(\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = @ProcessedOnUtc, error = @Error\n WHERE id = @Id\n """,\n outboxUpdate,\n transaction: transaction);\n}\nIf you didn't get the memo by now, batching is the name of the game.\nWe want a way to send one large UPDATE query to the database.
We have to construct the SQL for this batch query manually.\nWe'll use the DynamicParameters type from Dapper to provide all the parameters.
var updateSql =\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = v.processed_on_utc,\n error = v.error\n FROM (VALUES\n {0}\n ) AS v(id, processed_on_utc, error)\n WHERE outbox_messages.id = v.id::uuid\n """;\n\nvar updates = updateQueue.ToList();\nvar paramNames = string.Join(",", updates.Select((_, i) => $"(@Id{i}, @ProcessedOn{i}, @Error{i})"));\n\nvar formattedSql = string.Format(updateSql, paramNames);\n\nvar parameters = new DynamicParameters();\n\nfor (int i = 0; i < updates.Count; i++)\n{\n parameters.Add($"Id{i}", updates[i].Id.ToString());\n parameters.Add($"ProcessedOn{i}", updates[i].ProcessedOnUtc);\n parameters.Add($"Error{i}", updates[i].Error);\n}\n\nawait connection.ExecuteAsync(formattedSql, parameters, transaction: transaction);\nThis will produce a SQL query that looks something like this:
\nUPDATE outbox_messages\nSET processed_on_utc = v.processed_on_utc,\n error = v.error\nFROM (VALUES\n (@Id0, @ProcessedOn0, @Error0),\n (@Id1, @ProcessedOn1, @Error1),\n (@Id2, @ProcessedOn2, @Error2),\n -- A few hundred rows in beteween\n (@Id999, @ProcessedOn999, @Error999)\n) AS v(id, processed_on_utc, error)\nWHERE outbox_messages.id = v.id::uuid\nInstead of sending one update query per message, we can send one query to update all messages.
\nThis will obviously give us a noticeable performance benefit:
\nLet's test out the performance improvement with the current optimizations.\nThe changes we made so far focus on improving the speed of the OutboxProcessor.
Here are the rough numbers I'm seeing for the individual steps:
\nI'll run the Outbox processing for 1 minute and count the number of processed messages.
\nThe optimized implementation processed 162,000 messages in one minute or 2,700 MPS.
\nFor reference, this allows us to process more than 230 million messages per day.
\nBut we're just getting started.
\nIf we want to take this further, we have to scale out the OutboxProcessor.\nThe problem we could face here is processing the same message more than once.\nSo, we need to implement some form of locking on the current batch of messages.
PostgreSQL has a convenient FOR UPDATE statement that we can use here.\nIt will lock the selected rows for the duration of the current transaction.\nHowever, we must add the SKIP LOCKED statement to allow other queries to skip the locked rows.\nOtherwise, any other query will be blocked until the current transaction is completed.
Here's the updated query:
\nSELECT id AS Id, type AS Type, content as Content\nFROM outbox_messages\nWHERE processed_on_utc IS NULL\nORDER BY occurred_on_utc LIMIT @BatchSize\nFOR UPDATE SKIP LOCKED\nTo scale out the OutboxProcessor, we simply run multiple instances of the background job.
I'll simulate this using Parallel.ForEachAsync, where I can control the MaxDegreeOfParallelism.
var parallelOptions = new ParallelOptions\n{\n MaxDegreeOfParallelism = _maxParallelism,\n CancellationToken = cancellationToken\n};\n\nawait Parallel.ForEachAsync(\n Enumerable.Range(0, _maxParallelism),\n parallelOptions,\n async (_, token) =>\n {\n await ProcessOutboxMessages(token);\n });\nWe can process 179,000 messages in one minute or 2,983 MPS with five (5) workers.
\nI thought this was supposed to be much faster. What gives?
\nWithout parallel processing, we were able to get ~2,700 MPS.
\nA new bottleneck appears: publishing the messages in batches.
\nThe publish time went from ~289ms to ~1,540ms.
\nInterestingly, if you multiply the base publish time (for one worker) by the number of workers, you roughly get to the new publish time.
\nWe're wasting a lot of time waiting for the acknowledgment from the message broker.
\nHow can we fix this?
\nRabbitMQ supports publishing messages in batches.\nWe can enable this feature when configuring MassTransit by calling the ConfigureBatchPublish method.\nMassTransit will buffer messages before sending them to RabbitMQ, to increase throughput.
builder.Services.AddMassTransit(x =>\n{\n x.UsingRabbitMq((context, cfg) =>\n {\n cfg.Host(builder.Configuration.GetConnectionString("Queue"), hostCfg =>\n {\n hostCfg.ConfigureBatchPublish(batch =>\n {\n batch.Enabled = true;\n });\n });\n\n cfg.ConfigureEndpoints(context);\n });\n});\nWith only this small change, let's rerun our test with five workers.
\nThis time around, we're able to process 1,956,000 messages in one minute.
\nWhich gives us a blazing ~32,500 MPS.
\nThis is more than 2.8 billion processed messages per day.
\nI could call it a day here, but there's one more thing I want to show you.
\nOne more thing you can do (which I don't recommend) is turn off publisher confirmation.\nThis means that calling Publish won't wait until the message is confirmed by the broker (ack'd).\nIt could lead to reliability issues and potentially losing messages.
That being said, I did manage to get ~37,000 MPS with publisher confirmation turned off.
\ncfg.Host(builder.Configuration.GetConnectionString("Queue"), hostCfg =>\n{\n hostCfg.PublisherConfirmation = false; // Dangerous. I don't recommend it.\n hostCfg.ConfigureBatchPublish(batch =>\n {\n batch.Enabled = true;\n });\n});\nWhile we've achieved impressive throughput, consider these factors when implementing these techniques in a real-world system:
\nConsumer Capacity:\nCan your consumers keep up?\nBoosting producer throughput without matching consumer capacity can create backlogs.\nConsider the entire pipeline when scaling.
\nDelivery Guarantees:\nOur optimizations maintain at-least-once delivery.\nDesign consumers to be idempotent to handle occasional duplicate messages.
\nMessage Ordering:\nParallel processing with FOR UPDATE SKIP LOCKED may cause out-of-order messages.\nFor strict ordering, consider the Inbox pattern on the consumer side to buffer messages.\nAn Inbox allows us to process messages in the correct order, even if they arrive out of sequence.
Reliability vs. Performance Trade-offs:\nTurning off publisher confirmation increases speed but risks message loss.\nWeigh performance against reliability based on your specific needs.
\nBy addressing these factors, you'll create a high-performance Outbox processor that integrates smoothly with your system architecture.
\nWe've come a long way from our initial Outbox processor.\nHere's what we accomplished:
\nThe result?\nWe boosted processing from 1,350 messages per second to an impressive 32,500 MPS.\nThat's over 2.8 billion messages per day!
\nScaling isn't just about raw speed - it's about identifying and addressing bottlenecks at each step.\nBy measuring, optimizing, and rethinking our approach, we achieved massive performance gains.
\nThat's all for today. Hope this was helpful.
\nP.S. You can find the source code here.
\nThe Outbox pattern fixes the dual-write problem: saving data and publishing a message are two separate steps that can fail independently.\nYou write the message to an outbox table in the same transaction as the business data, and a background processor publishes it later.\nDelivery is at-least-once, so consumers must be idempotent.
\nIn distributed systems, we often face the challenge of keeping our database and external systems in sync.\nImagine saving an order to a database and then publishing a message to a message broker.\nIf either operation fails, your system ends up in an inconsistent state.
\nThe Outbox pattern solves this problem by treating message publication as part of your database transaction.\nInstead of publishing messages directly, we save them to an Outbox table in our database, ensuring atomic operations.\nA separate process then reliably publishes these messages.
\nIn this newsletter, we'll dive into implementing this pattern in .NET, covering everything from setup to scaling.
\nThe transactional Outbox pattern fixes a common problem in distributed systems.\nThis problem happens when you need to do two things at once: save data and communicate with an external component.
\nConsider scenarios like sending order confirmation emails, notifying other systems about new client registrations,\nor updating inventory levels after an order is placed.\nEach of these involves a local data change coupled with an external communication or update.
\nFor example, imagine a microservice that needs to:
\nIf one of these steps fails, your system could end up in an inconsistent state.\nMaybe the order is saved, but no one else knows about it.\nOr everyone thinks there's a new order, but it's not actually in the database.
\nHere's a CreateOrderCommandHandler without the Outbox pattern:
public class CreateOrderCommandHandler(\n IOrderRepository orderRepository,\n IProductInventoryChecker inventoryChecker,\n IUnitOfWork unitOfWork,\n IEventBus eventBus) : IRequestHandler<CreateOrderCommand, OrderDto>\n{\n public async Task<OrderDto> Handle(CreateOrderCommand request, CancellationToken cancellationToken)\n {\n var order = new Order(request.CustomerId, request.ProductId, request.Quantity, inventoryChecker);\n\n await orderRepository.AddAsync(order);\n\n await unitOfWork.CommitAsync(cancellationToken);\n\n // The database transaction is completed at this point.\n\n await eventBus.Send(new OrderCreatedIntegrationEvent(order.Id));\n\n return new OrderDto { Id = order.Id, Total = order.Total };\n }\n}\nThis code has a potential consistency problem.\nAfter the database transaction is committed, two things could go wrong:
\nThe application might crash right after the transaction is committed but before the event is sent.\nThe order would be created in the database, but other systems wouldn't know about it.
\nThe event bus might be down or unreachable when we try to send the event.\nThis would result in the order being created without notifying other systems.
\nThe transactional Outbox pattern helps solve this problem by ensuring that the database update and event publication are treated as a single atomic operation.
\n![\"Flow](\"https://milanjovanovic.tech/blogs/mnw_110/outbox_pattern.png\")
\nThe sequence diagram illustrates how the Outbox pattern solves our consistency challenge.\nInstead of trying to save data and send a message as separate steps, we save both the order and an Outbox message in a single database transaction.\nThis is an all-or-nothing operation - we can't end up in an inconsistent state.
\nA separate Outbox processor handles the actual message sending.\nIt continuously checks for unsent messages in the Outbox table and publishes them to the message queue.\nThe processor marks messages as sent after successful publishing, preventing duplicates.
\nAn important thing to realize here is that the Outbox pattern gives us at-least-once delivery.\nThe Outbox message will be sent at least once, but it could also be sent multiple times in case of retries.\nThis means we have to make our message consumers idempotent.
\nFirst, let's create our Outbox table where we will store messages:
\nCREATE TABLE outbox_messages (\n id UUID PRIMARY KEY,\n type VARCHAR(255) NOT NULL,\n content JSONB NOT NULL,\n occurred_on_utc TIMESTAMP WITH TIME ZONE NOT NULL,\n processed_on_utc TIMESTAMP WITH TIME ZONE NULL,\n error TEXT NULL\n);\n\n-- We can consider adding this index since we will be querying for unprocessed messages often\n-- and it will contain the rows in the correct sort order for our query.\nCREATE INDEX IF NOT EXISTS idx_outbox_messages_unprocessed\nON outbox_messages (occurred_on_utc, processed_on_utc)\nINCLUDE (id, type, content)\nWHERE processed_on_utc IS NULL;\nI'll use PostgreSQL as the database for this example.\nNotice the jsonb type for the content column.\nIt allows for indexing and querying of the JSON data if needed in the future.
Now, let's create a class to represent our Outbox entry:
\npublic sealed class OutboxMessage\n{\n public Guid Id { get; init; }\n public string Type { get; init; }\n public string Content { get; init; }\n public DateTime OccurredOnUtc { get; init; }\n public DateTime? ProcessedOnUtc { get; init; }\n public string? Error { get; init; }\n}\nHere's how we can add a message to the Outbox:
\npublic async Task AddToOutbox<T>(T message, NpgsqlDataSource dataSource)\n{\n var outboxMessage = new OutboxMessage\n {\n Id = Guid.NewGuid(),\n OccurredOnUtc = DateTime.UtcNow,\n Type = typeof(T).FullName, // We'll need this for deserialization\n Content = JsonSerializer.Serialize(message)\n };\n\n await using var connection = await dataSource.OpenConnectionAsync();\n await connection.ExecuteAsync(\n @"""\n INSERT INTO outbox_messages (id, occurred_on_utc, type, content)\n VALUES (@Id, @OccurredOnUtc, @Type, @Content::jsonb)\n """,\n outboxMessage);\n}\nHere's the CreateOrderCommandHandler using the Outbox pattern:
public class CreateOrderCommandHandler(\n IOrderRepository orderRepository,\n IProductInventoryChecker inventoryChecker,\n IUnitOfWork unitOfWork,\n NpgsqlDataSource dataSource) : IRequestHandler<CreateOrderCommand, OrderDto>\n{\n public async Task<OrderDto> Handle(CreateOrderCommand request, CancellationToken cancellationToken)\n {\n var order = new Order(request.CustomerId, request.ProductId, request.Quantity, inventoryChecker);\n\n await orderRepository.AddAsync(order);\n\n // We can add the Outbox message before committing the transaction,\n // so both operations are part of the same transaction.\n await AddToOutbox(new OrderCreatedIntegrationEvent(order.Id), dataSource);\n\n await unitOfWork.CommitAsync(cancellationToken);\n\n return new OrderDto { Id = order.Id, Total = order.Total };\n }\n}\nAn elegant approach to implementing this is using domain events to represent notifications.\nWhen something significant happens in the domain, we will raise a domain event.\nBefore completing the transaction, we can pick up all events and store them as Outbox messages.\nYou could do this from the unit of work or with an EF Core interceptor.
\nThe Outbox processor is the next component we'll need.\nThis could be a physically separate process or a background worker in the same process.
\nI'll use Quartz to schedule background jobs for Outbox processing.\nIt's a robust library with excellent support for scheduling recurring jobs.
\nNow, let's implement the OutboxProcessorJob:
[DisallowConcurrentExecution]\npublic class OutboxProcessorJob(\n NpgsqlDataSource dataSource,\n IPublishEndpoint publishEndpoint,\n Assembly integrationEventsAssembly) : IJob\n{\n public async Task Execute(IJobExecutionContext context)\n {\n await using var connection = await dataSource.OpenConnectionAsync();\n await using var transaction = await connection.BeginTransactionAsync();\n\n // You can make the limit a parameter, to control the batch size.\n // We can also select just the id, type, and content columns.\n var messages = await connection.QueryAsync<OutboxMessage>(\n @"""\n SELECT id AS Id, type AS Type, content AS Content\n FROM outbox_messages\n WHERE processed_on_utc IS NULL\n ORDER BY occurred_on_utc LIMIT 100\n """,\n transaction: transaction);\n\n foreach (var message in messages)\n {\n try\n {\n var messageType = integrationEventsAssembly.GetType(message.Type);\n var deserializedMessage = JsonSerializer.Deserialize(message.Content, messageType);\n\n // We should introduce retries here to improve reliability.\n await publishEndpoint.Publish(deserializedMessage);\n\n await connection.ExecuteAsync(\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = @ProcessedOnUtc\n WHERE id = @Id\n """,\n new { ProcessedOnUtc = DateTime.UtcNow, message.Id },\n transaction: transaction);\n }\n catch (Exception ex)\n {\n // We can also introduce error logging here.\n\n await connection.ExecuteAsync(\n @"""\n UPDATE outbox_messages\n SET processed_on_utc = @ProcessedOnUtc, error = @Error\n WHERE id = @Id\n """,\n new { ProcessedOnUtc = DateTime.UtcNow, Error = ex.ToString(), message.Id },\n transaction: transaction);\n }\n }\n\n await transaction.CommitAsync();\n }\n}\nThis approach uses polling to periodically fetch unprocessed messages from the database.\nPolling can increase the load on the database, as we'll need to query for unprocessed messages frequently.
\nAn alternative way to process Outbox messages is by using Transaction log tailing.\nWe can implement this using Postgres logical replication.\nThe database will stream changes from the Write-Ahead Log (WAL) to our application, and we'll process these messages and publish them to the message broker.\nYou can use this to implement a push-based Outbox processor.
\nThe Outbox pattern, while effective, introduces additional complexity and database writes.\nIn high-throughput systems, it's crucial to monitor its performance to ensure it doesn't become a bottleneck.
\nI recommend implementing retry mechanisms in the Outbox processor to improve reliability.\nConsider using exponential backoff for transient failures and a circuit breaker for persistent issues to prevent system overload during outages.
\nIt's essential that you implement idempotent message consumers.\nNetwork issues or processor restarts can lead to multiple deliveries of the same message, so your consumers must handle repeated processing safely.
\nOver time, the Outbox table can grow significantly, potentially impacting database performance.\nIt's important to implement an archiving strategy early on.\nConsider moving processed messages to cold storage or deleting them after a set period.
\nAs your system grows, you may find that a single Outbox processor can't keep up with the volume of messages.\nThis can lead to increased latency between when an event occurs and when it's processed by consumers.
\nOne straightforward approach is to increase the frequency of the Outbox processor job.\nYou should consider running it every few seconds.\nThis can significantly reduce the delay in message processing.
\nAnother effective strategy is to increase the batch size when fetching unprocessed messages.\nBy processing more messages in each run, you can improve throughput.\nHowever, be cautious not to make the batches so large that they cause long-running transactions.
\nFor high-volume systems, processing the Outbox in parallel can be very effective.\nImplement a locking mechanism to claim batches of messages, allowing multiple processors to work simultaneously without conflict.\nYou can use SELECT ... FOR UPDATE SKIP LOCKED to claim a batch of messages.\nThis approach can dramatically increase your processing capacity.
Here's an in-depth article on scaling the outbox pattern\nthat covers these strategies in more detail.\nI'll show you how we can reach more than 30,000 messages per second (2B+ messages per day).
\nThe Outbox pattern is a powerful tool for maintaining data consistency in distributed systems.\nBy decoupling database operations from message publishing, the Outbox pattern ensures that your system remains reliable even in the face of failures.
\nRemember to keep your consumers idempotent, implement proper scaling strategies, and manage your Outbox table growth.
\nWhile it adds some complexity, the benefits of guaranteed message delivery make it a valuable pattern in many scenarios.
\nIf you're looking to implement the Outbox pattern in a robust, production-ready way, you can check out Pragmatic Clean Architecture.\nIt includes an entire section on implementing the Outbox pattern, along with other essential patterns for building maintainable and scalable .NET applications.
\nThat's all for today. Stay awesome, and I'll see you next week.
\nMigrate one module at a time.\nTighten module boundaries and data ownership first, then extract a low-coupling module into its own project and database.\nDirect method calls become HTTP or messaging calls, and an API gateway gives clients one entry point.
\nAs your application grows, you might find yourself considering a move from a modular monolith to microservices.\nThis transition isn't just a technical shift.\nIt's a strategic move that can reshape how your entire system operates.\nBut let's be clear: it's not a magic solution and comes with its own challenges.
\nIn this article, I'll share my experience of migrating from a modular monolith to microservices.
\nWe'll explore why you might consider microservices, how to prepare for the migration and the critical steps in the migration process -\nfrom choosing your first module to implementing inter-service communication and managing data migration.
\nLet's dive in!
\nA modular monolith serves as an excellent starting point for many applications.\nIt's simpler to develop, easier to understand, and faster to deploy than a distributed system.\nBut as your application grows, you might start facing some problems.
\nHere are the key challenges I've encountered with modular monoliths:
\nMicroservices can address these issues, but it's not a decision to be taken lightly.
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_109/modular_monolith_vs_microservices.png\")
\nHere's how microservices can help:
\nThe good news? If you've built a well-designed modular monolith, you're already halfway there.\nThe clear boundaries between modules in your monolith can serve as a blueprint for your microservices architecture.
\nRemember, microservices come with their own complexities in areas like data consistency and inter-service communication.\nBut for the right use cases, they can provide the flexibility and scalability needed for growing applications.
\nThe success of your migration largely depends on how well you prepare.\nYour best starting point is a well-structured modular monolith.
\nHere are key areas to focus on:
\nReview module boundaries:\nI can't stress this enough: clear module boundaries are crucial.\nEach module should have a distinct responsibility and minimal dependencies on others.\nIf boundaries are blurry, refactor before migrating.
\nEnsure proper data encapsulation:\nModules should not directly access each other's data stores.\nI make sure each module owns and manages its data exclusively.\nNo shared tables, no direct database access across modules.\nThis clean separation makes it much easier to extract modules into microservices later.
\nImplement clean public APIs:\nDefine clear contracts between modules to facilitate future separation.\nModules should communicate through well-defined APIs, not by accessing each other's internals.
\nHere's an example of the above:
\n// Good: Clear module boundary\nnamespace BookingsModule;\n\npublic class CreateBooking\n{\n private readonly IBookingRepository _bookingRepository;\n private readonly IPaymentGateway _paymentGateway; // Public API\n\n public CreateBooking(IBookingRepository bookingRepository, IPaymentGateway paymentGateway)\n {\n _bookingRepository = bookingRepository;\n _paymentGateway = paymentGateway;\n }\n\n public async Task<BookingResult> CreateBookingAsync(BookingRequest request)\n {\n var booking = await _bookingRepository.CreateAsync(Booking.FromRequest(request));\n\n // Accessing the other module's data through an abstraction\n var paymentResult = await _paymentGateway.ProcessPaymentAsync(booking.Id, booking.TotalAmount);\n\n return new BookingResult(booking, paymentResult);\n }\n}\nBy focusing on these areas, you're not just preparing for migration - you're improving your modular monolith.\nEven if you decide not to migrate, these steps will make your system more maintainable and scalable.
\nSelecting the right module to extract first can set the tone for your entire migration.\nIn my experience, it's crucial to start with a module that's self-contained and has clear boundaries.
\nWhen I'm evaluating modules, I look for these characteristics:
\nFor instance, in an e-commerce system, I might choose the product catalog module.\nIt typically has a clear purpose, doesn't heavily depend on other modules, and could benefit from independent scaling.
\nOnce you've chosen your module, here's the extraction process I follow:
\nHere's what this might look like in practice:
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_109/modular_monolith_extraction.png\")
\nRemember, the goal isn't perfection on the first try.\nI often iterate on this process, gradually refining the separation between the new microservice and the monolith.
\nThe first extraction is a learning experience.\nIt'll show you how to approach subsequent modules and help you refine the overall migration strategy.
\nOnce you've extracted a module into a microservice, you have to update the module's communication\nwith the rest of the system.\nThis typically involves transitioning from direct method calls to network-based communication.
\nHere's how I approach this transition:
\n// Before: Direct method call\nBookingDto booking = await _bookingService.GetAsync(bookingId);\n\n// After: HTTP API call\nvar response = await _httpClient.GetAsync($"http://bookings-service/api/bookings/{bookingId}");\n\nvar booking = await response.Content.ReadFromJsonAsync<BookingDto>();\nFor asynchronous communication, consider implementing a messaging system.\nWhile the implementation details vary, tools like RabbitMQ,\nAmazon SQS and SNS,\nor Azure Service Bus\ncan significantly improve system resilience and decoupling.
\nNetwork communication introduces new failure modes, so I always implement resilience patterns.\nHere's how I use Polly with resilience pipelines:
\nusing Polly;\n\nvar pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()\n .AddRetry(new RetryStrategyOptions\n {\n ShouldHandle = new PredicateBuilder().Handle<ConflictException>(),\n Delay = TimeSpan.FromSeconds(1),\n MaxRetryAttempts = 2,\n BackoffType = DelayBackoffType.Exponential,\n UseJitter = true\n })\n .AddTimeout(new TimeoutStrategyOptions\n {\n Timeout = TimeSpan.FromSeconds(10)\n })\n .Build();\n\nvar response = await pipeline.ExecuteAsync(\n async ct => await _httpClient.GetAsync($"http://bookings-service/api/bookings/{bookingId}", ct),\n cancellationToken);\nTransitioning to HTTP-based communication always brings new problems to solve.\nSerialization, error handling, and API versioning become crucial.\nI've learned to plan for these aspects from the start to avoid headaches down the line.
\nAs you extract more services, managing the communication between clients and your microservices can become complex.\nAn API Gateway can help manage this complexity by providing a single entry point for all clients.
\nYARP (Yet Another Reverse Proxy) is an excellent tool for implementing an API Gateway in .NET.\nHere's how I typically set it up:
\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddReverseProxy()\n .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));\n\nvar app = builder.Build();\n\napp.MapReverseProxy();\n\napp.Run();\nThen, I configure the routing in appsettings.json:
{\n "ReverseProxy": {\n "Routes": {\n "bookings-route": {\n "ClusterId": "bookings-cluster",\n "Match": {\n "Path": "/api/bookings/{**catch-all}"\n }\n },\n "payments-route": {\n "ClusterId": "payments-cluster",\n "Match": {\n "Path": "/api/payments/{**catch-all}"\n }\n }\n },\n "Clusters": {\n "bookings-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "http://bookings-service/"\n }\n }\n },\n "payments-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "http://payments-service/"\n }\n }\n }\n }\n }\n}\nThis setup routes requests to the appropriate microservice based on the path.\nFor example, any request to /api/bookings/* will be routed to the bookings-service.
![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_109/modular_monolith_extraction_api_gateway.png\")
\nIn my projects, I've found that an API Gateway often becomes a critical point for implementing cross-cutting concerns.\nAs your architecture evolves, consider adding features like:
\nStart simple, but be prepared to evolve your gateway as you learn more about your system's needs and usage patterns.
\nData migration is often the trickiest part of moving from a modular monolith to microservices. In my experience, there are two main approaches:
\nThe "One and Done" Approach
\nFor simpler systems or those that can handle some downtime, I use this method:
\nIt's quick and simple but requires a brief downtime.
\nThe Synchronization Approach
\nFor complex systems needing minimal disruption, I use this method:
\nThis approach is more complex but allows for a smoother transition.
\nIn both cases, I always ensure I have a solid backup and rollback plan.\nThe key is to choose the method that best fits your system's needs and tolerance for complexity.
\nRemember, if your modular monolith already uses separate database schemas for each module, you're starting with an advantage.\nThis logical isolation makes the migration process significantly easier.
\nMigrating from a modular monolith to microservices is a journey I've taken several times, and it's always both challenging and rewarding.\nThe process we've covered here - from preparing your monolith and choosing the right module to extract\nto implementing proper communication patterns - forms the foundation of a successful migration.
\nDon't rush the process.\nCareful planning and incremental changes are key.\nEach step teaches you something valuable about your system.
\nWhile we've covered the fundamentals, there's always more to learn. I recommend exploring these advanced topics:
\nIf you're ready to master this process and gain hands-on experience, I've put together a comprehensive\nModular Monolith Architecture course.\nThere's an entire chapter dedicated to extracting modules and moving to microservices.\nYou'll gain practical skills to confidently navigate your microservices transformation.
\nRemember, the goal isn't to blindly adopt microservices but to evolve your architecture to best serve your business needs.\nSometimes, a well-structured modular monolith is the right solution.\nOther times, a full microservices architecture is the way to go.\nThe key is understanding the trade-offs and making informed decisions.
\nGood luck out there, and I'll see you next week.
\nI replaced an exact-match filter over a JSON file with a Lunr.js full-text index built at build time.\nThe client loads the index, ranks results with TF-IDF, and sorts by relevance instead of date.\nBrotli compression took the index from 2.5MB to 193KB.
\nSo, I've got this blog I've been running for a couple of years now.\nIt's a Next.js and TypeScript static site, all optimized for SEO.\nSounds pretty standard, right?\nWell, it was, until I ran into a problem.
\nAs my content grew, finding specific articles became a real pain.\nIt wasn't just me - readers were struggling too.\nWhat's the point of writing all this stuff if no one can find it when they need it?
\nThat's when I decided to look into full-text search.\nNow, implementing full-text search on a static site isn't exactly straightforward.\nIt's not like you can just slap a database on there and call it a day.\nYou've got to get creative.
\nIn this article, I'll walk you through how I turned my site's search from useless to actually functional.
\nHere's how the search function worked before:
\nHere's the code that would generate the search data JSON document:
\nexport const generateSearchData = () => {\n const posts = getAllPosts();\n\n const searchData = posts.map((post) => ({\n slug: post.meta.slug,\n title: post.meta.title,\n excerpt: post.meta.excerpt,\n coverImage: post.meta.coverImage,\n date: post.meta.date,\n searchableContent:\n `${post.meta.title} ${post.meta.excerpt} ${post.content}`.toLowerCase()\n }));\n\n fs.mkdirSync('./search', { recursive: true });\n fs.writeFileSync(\n path.join(process.cwd(), 'search', 'search-data.json'),\n JSON.stringify(searchData)\n );\n};\nAnd then the search function is pretty simple (but not very smart):
\nexport const search(keyword) = () => {\n const res = await fetch('/search/search-data.json');\n\n const searchData = await res.json();\n\n return searchData.filter((p) =>\n p.searchableContent.includes(keyword.toLowerCase())\n );\n}\nThis approach has a few issues:
\nI wasn't happy with this, so here's how I implemented a much better solution.
\nTo fix these problems, I turned to full-text search using Lunr.js.\nBut what exactly is full-text search?
\nFull-text search is a technique that allows fast and efficient searching of large volumes of text by creating an index of all words in a document collection\nand returning ranked results based on relevance to the search query.
\nFull-text search works by:
\nAnother common operation is stop word removal.\nCommon words that don't add much meaning (like "the", "and", "is") are often removed to save space and improve relevance.
\nAt the heart of full-text search is an inverted index.\nIt's a data structure that maps each unique term to the documents containing it.\nIt's "inverted" because it goes from terms to documents, rather than documents to terms.
\nWhen searching, results are often ranked using TF-IDF (Term Frequency-Inverse Document Frequency).\nThis gives higher scores to terms that are frequent in a document but rare across all documents.
\nThat's the rundown on full-text search. Let's see how to implement it.
\nI chose Lunr.js because it's lightweight and works great for static websites. No server required.
\nI updated the generateSearchData function to create and store a full-text search index.\nThis function runs once at build time, so it's not expensive.
export const generateSearchData = () => {\n const posts = getAllPosts();\n\n // Generate search data as before.\n\n const index = lunr(function () {\n this.ref('slug');\n this.field('title', { boost: 10 });\n this.field('content', { boost: 5 });\n\n searchData.forEach((doc) => {\n this.add(doc);\n });\n });\n\n // Store search data as before.\n\n // And store the search index.\n fs.writeFileSync(\n path.join(process.cwd(), 'search', 'search-index.json'),\n JSON.stringify(index)\n );\n};\nI'm boosting the title with a factor of 10 and the content with a factor of 5.\nIf the search term matches the title, it will have a higher relevance score.
\nThe downside (for now) is that the index file is big, 2.5MB.\nIf I were to download this on the client every time, the costs would quickly add up.\nI have 100,000 unique visitors per month, which would equate to 250GB of network egress.
Now, I have to update the search function to use the full-text index:
\nexport const search(keyword) = () => {\n const res = await fetch('/search/search-data.json');\n const searchData = await res.json();\n\n const res = await fetch('/search/search-index.json');\n const searchIndex = lunr.Index.load(indexJson);\n\n return searchIndex\n .search(keyword)\n .map((result) => {\n const post = searchData?.find((post) => post.slug === result.ref);\n return post ? { ...post, score: result.score } : null;\n })\n .filter((result) => result !== null)\n .sort((a, b) => b.score - a.score);\n}\nWhat's happening here:
\nlunr.Index.loadsearch function allowing us to perform full-text searchThis allows me to sort the search results based on relevance instead of chronologically.
\nHere's what the old search implementation returns when searching for "resilience":
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_108/old_search.png\")
\nThe most relevant article is at the fourth spot, sorted chronologically.\nYou can see how this isn't a good user experience.
\nBut with full-text search, when you search for a keyword like "resilience", you get nicer results:
\n![\"The](\"https://milanjovanovic.tech/blogs/mnw_108/full_text_search.png\")
\nI also added a relevance score next to each article because it looks cool.
\nNow, I have a powerful search, but the index was huge (a whopping 2.5MB) and will continue to grow.\nThe search data file is also 861KB.
\nEnter Brotli compression:
\nimport { compress } from 'brotli';\n\nexport const generateSearchData = () => {\n // Create the search data and index\n\n fs.writeFileSync(\n path.join(process.cwd(), 'search', 'search-index.br'),\n compress(Buffer.from(JSON.stringify(index)))\n );\n fs.writeFileSync(\n path.join(process.cwd(), 'search', 'search-data.br'),\n compress(Buffer.from(JSON.stringify(searchData)))\n );\n};\nThe results:
\nIf you want to learn more about compression algorithms, check out this article about response compression.
\nAfter fetching the compressed search data and full-text index on the client, I cache them for subsequent searches.
\nThe searches are lightning-fast now, and the results are more relevant.
\nWhile Lunr.js works great for my static site, larger apps with more data need a robust full-text search solution.\nSo, here are some some server-side options you could explore.
\nLucene is the foundation of many search engines.\nIt's written in Java but has ports to other languages.\nLucene provides robust full-text indexing and search capabilities.\nIt is also highly efficient and customizable, making it a popular choice for developers who need fine-grained control over their search functionality.
\nApache Solr builds on top of Lucene, offering additional features like distributed indexing, replication, and load-balanced querying.\nSolr includes powerful capabilities such as faceting and highlighting, which can greatly enhance the search experience.
\nIf you're already using PostgreSQL, the built-in full-text search is worth considering.\nPostgreSQL uses its own text search engine, which supports multiple languages and custom dictionaries.\nWhile not as feature-rich as dedicated search engines, it can be a convenient option for applications that want to keep their stack simple.
\nI've been tinkering with PostgreSQL full-text search using EF Core.\nHere's what a full-text search query looks like:
\nvar blogs = context\n .BlogPosts\n .Where(b =>\n EF.Functions.ToTsVector("english", b.Title + " " + b.Excerpt + " " + b.Content)\n .Matches(EF.Functions.PhraseToTsQuery("english", searchTerm)))\n .Select(b => new\n {\n b.Slug,\n b.Title,\n b.Excerpt,\n b.Date,\n Rank = EF.Functions.ToTsVector("english", b.Title + " " + b.Excerpt + " " + b.Content)\n .Rank(EF.Functions.PhraseToTsQuery("english", searchTerm))\n })\n .OrderByDescending(b => b.Rank)\n .ToList();\nBut I'll have to write a dedicated article to cover this, so let's wrap it up.
\nThe old search functionality was, frankly, embarrassing.
\nIt was slow, dumb as a rock, and about as useful as a chocolate teapot.
\nNow? It's actually not half bad.
\nI'm not gonna lie, there was a moment of frustration when I thought about giving up.\nBut I'm glad I stuck with it.\nThere's something satisfying about building it yourself, you know?
\nIt might not be pretty, but it works.\nAnd sometimes, that's all that matters.
\nThe Brotli compression bit was a pleasant surprise.\nI thought I'd end up with a massive index file that would make mobile users cry.\nBut nope, it all works smoothly.\nGo figure.
\nHave you tried implementing search on your site? How'd it go?
\nThat's all for today.
\nSee you next week.
\n.NET Aspire is Microsoft's opinionated stack for building distributed .NET applications.\nAn AppHost project declares your projects, databases, and message brokers in C#, and Aspire wires up connection strings, health checks, and OpenTelemetry for you.\nWhen I reviewed it in 2024, it replaced my docker-compose.yml for local development.
I've been tinkering with .NET Aspire lately, and I've got some thoughts to share.\nIf you're curious about this new cloud-native development tool from Microsoft, stick around.\nI'll break down what's great, what's not, and how you can start using it.
\n\n\n.NET Aspire is an opinionated, cloud-ready stack for building observable, production-ready, distributed applications.
\n
.NET Aspire is Microsoft's latest offering for cloud-native application development.\nIt aims to simplify the process of building, deploying, and managing distributed applications.
\nDistributed applications often consist of small applications that consume external services like databases, message brokers, and caching.\n.NET Aspire gives you a set of tools to make building distributed applications easier.
\nHow are you setting up a local development environment?\nI often use Docker Compose to configure my applications and run external services.\nIt's a simple setup, but you need to manage environment variables and connection strings.\nIf you're not familiar with Docker, it can prove to be quite tricky sometimes.
\nHere's a docker-compose.yml file from a recent project:
services:\n contentplatform-api:\n image: ${DOCKER_REGISTRY-}contentplatform-api\n container_name: ContentPlatform.Api\n build:\n context: .\n dockerfile: ContentPlatform.Api/Dockerfile\n ports:\n - 5000:8080\n - 5001:8081\n\n contentplatform-reporting-api:\n image: ${DOCKER_REGISTRY-}contentplatform-reporting-api\n container_name: ContentPlatform.Reporting.Api\n build:\n context: .\n dockerfile: ContentPlatform.Reporting.Api/Dockerfile\n ports:\n - 6000:8080\n - 6001:8081\n\n contentplatform-presentation:\n image: contentplatform-ui:latest\n container_name: ContentPlatform.Presentation\n environment:\n - ASPNETCORE_ENVIRONMENT=Development\n ports:\n - 3000:80\n\n contentplatform-db:\n image: postgres:latest\n container_name: ContentPlatform.Db\n environment:\n - POSTGRES_DB=contentplatform\n - POSTGRES_USER=postgres\n - POSTGRES_PASSWORD=postgres\n volumes:\n - ./.containers/db:/var/lib/postgresql/data\n ports:\n - 5432:5432\n\n contentplatform-mq:\n image: rabbitmq:management\n container_name: ContentPlatform.RabbitMq\n hostname: contentplatform-mq\n volumes:\n - ./.containers/queue/data/:/var/lib/rabbitmq\n - ./.containers/queue/log/:/var/log/rabbitmq\n environment:\n RABBITMQ_DEFAULT_USER: guest\n RABBITMQ_DEFAULT_PASS: guest\nThis sets up two APIs, a client application, PostgreSQL, and RabbitMQ.\nI also have to configure the connection strings manually to connect to these services.
\nSo, I decided to migrate this application to .NET Aspire and documented the process.
\nYou can right-click an existing project in Visual Studio and select Add > .NET Aspire Orchestrator Support....
![\"Context](\"https://milanjovanovic.tech/blogs/mnw_107/aspire_orchestration.png\")
\n This will add an AppHost and ServiceDefaults project to your solution.\nYou will then repeat this for the remaining projects in your solution to enlist them all in Aspire orchestration.
The AppHost project is responsible for orchestration.\nYou can define your entire application stack in a single, readable file.\nRunning the AppHost project from Visual Studio will start the required applications and services.
Here's the setup for my application using Aspire:
\nIDistributedApplicationBuilder builder = DistributedApplication.CreateBuilder(args);\n\nvar postgres = builder.AddPostgres("contentplatform-db")\n .WithPgAdmin();\n\nvar rabbitMq = builder.AddRabbitMQ("contentplatform-mq")\n .WithManagementPlugin();\n\nbuilder.AddProject<Projects.ContentPlatform_Api>("contentplatform-api")\n .WithReference(postgres)\n .WithReference(rabbitMq);\n\nbuilder.AddProject<Projects.ContentPlatform_Reporting_Api>("contentplatform-reporting-api")\n .WithReference(postgres)\n .WithReference(rabbitMq);\n\nbuilder.AddProject<Projects.ContentPlatform_Presentation>("contentplatform-presentation");\n\nbuilder.Build().Run();\nThe Aspire version is much more concise and readable.\nAdding new services or changing configurations is straightforward.\nYou also get built-in observability.\nAspire includes tools for logging, metrics, and distributed tracing out of the box, making it easier to monitor and debug your applications.
\nWhen you run the application, you can see your applications and services on the Aspire dashboard:
\n![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_107/content_platfrom_resources.png\")
\nThere are a few things I don't like with the current Aspire setup.
\nThe AppHost project needs to reference all other projects to enlist them in orchestration.\nIf your services are all in one solution, this might be fine.\nBut what about large microservices systems?
We can go around this limitation by building a Docker image for an external service.\nThere's an AddContainer method that allows us to configure container resources.\nHowever, we won't be able to debug these services.
The ServiceDefaults projects needs to be visible to all other applications.\nAgain, this works perfectly fine if everything is in one solution.\nWe can also distribute this project as a NuGet package for complex systems.
If you're wondering how I configured PostgreSQL and RabbitMQ in the previous example, this is made available using Aspire Integrations.\nThese are NuGet packages that allow you to integrate with popular services, such as Redis or PostgreSQL.\nAspire integrations take care of many cloud-native concerns for you, like adding health checks and telemetry.
\nYou can right-click on the AppHost project and select Add > .NET Aspire package... to see the list of available integrations:
![\"NuGet](\"https://milanjovanovic.tech/blogs/mnw_107/aspire_integrations.png\")
\nIf we want to add Redis to our project, we can install the Aspire.Hosting.Redis package.\nThen, we would configure the Redis integration in the AppHost project:
var builder = DistributedApplication.CreateBuilder(args);\n\n// Other service omitted for brevity\n\nvar redis = builder.AddRedis("contentplatform-cache");\n\nbuilder.AddProject<Projects.ContentPlatform_Api>("contentplatform-api")\n .WithReference(postgres)\n .WithReference(rabbitMq)\n .WithReference(redis);\n\nbuilder.Build().Run();\nYou can find a list of supported Aspire integrations in the documentation.
\nWhen you configure a resource with a known connection string format, Aspire automatically injects an environment variable.\nThe connection string name will have the same name as the respective resource.
\nWithReference(postgres) produces ConnectionStrings__contentplatform-db="<VALUE>"WithReference(rabbitMq) produces ConnectionStrings__contentplatform-mq="<VALUE>"WithReference(redis) produces ConnectionStrings__contentplatform-cache="<VALUE>"This lets you use logical connection string names when configuring your services:
\nbuilder.Services.AddDbContext<ApplicationDbContext>(o =>\n o.UseNpgsql(builder.Configuration.GetConnectionString("contentplatform-db")));\nOne of Aspire's killer features is its built-in observability stack.\nIt integrates OpenTelemetry, providing distributed tracing, metrics, and logging out of the box.
\nWhen you enlist a project in .NET Aspire orchestration, there are some updates made to the Program file automatically:
AddServiceDefaults is called to configure OpenTelemetry, health checks, and service discoveryMapDefaultEndpoints is called to expose the health check endpointvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.AddServiceDefaults();\n\n// Other code omitted for brevity\n\nvar app = builder.Build();\n\napp.MapDefaultEndpoints();\n\n// Other code omitted for brevity\n\napp.Run();\nYou can customize AddServiceDefaults according to your requirements.\nFor example, if you're using MassTransit, you can add the respective tracing configuration for this library.
Here's the distributed traces view on the Aspire dashboard.\nYou can see a POST request hitting the contentplatform-api service, publishing an ArticleCreatedEvent, and consuming that message in the contentplatform-reporting-api service.
![\"Aspire](\"https://milanjovanovic.tech/blogs/mnw_107/content_platfrom_traces.png\")
\nFor local development, the .NET Aspire dashboard provides a UI for viewing telemetry data.\nIn a production environment, you can configure the OpenTelemetry server to receive telemetry data using the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
.NET Aspire simplifies the deployment process for distributed applications, especially when targeting Azure.\nTo deploy an Aspire application, you first generate a manifest file using the dotnet run command with specific parameters.\nThis manifest is a JSON file that describes all the resources defined in your Aspire project, including services, databases, and other dependencies.
![\".NET](\"https://milanjovanovic.tech/blogs/mnw_107/aspire_manifest.png\")
\n Deployment tools can use the manifest to set up the necessary infrastructure in your target environment.\nAspire generates the required configuration for Azure Container Apps or Kubernetes for Azure deployments.\nIt handles tasks like setting up networking, scaling services, and configuring monitoring automatically.
\nHere's a simple example of generating a manifest:
\ndotnet run --project ContentPlatform.AppHost\\ContentPlatform.AppHost.csproj `\n -- --publisher manifest --output-path ../aspire-manifest.json\nThis command creates a JSON manifest file that deployment tools can use to set up your application in the cloud or on-premises infrastructure.
\nYou can learn more about Aspire deployment in the documentation.
\nI've used .NET Aspire a lot lately, and I'm genuinely impressed.
\nAspire makes building complex systems much easier.\nI can set up a distributed system with just a few lines of C# code.\nThis is much simpler than using Docker Compose.\nThe built-in observability and monitoring tools are also great.
\nWhile .NET Aspire is now production-ready, the ecosystem around it is still growing.\nDevelopers, particularly those new to cloud-native concepts, might face a learning curve.
\nShould you adopt Aspire in your .NET projects?
\nIf you're building distributed applications, especially for Azure, I'd say give it a try.\nHowever, you might want to evaluate carefully if you work on simpler applications or use non-Azure cloud services.
\nThat's all for today.
\nSee you next week.
\nP.S. You can find the source code for this example in this repository.
\nRefit turns an HTTP API into a C# interface.\nYou declare methods with attributes like [Get] and [Post], and Refit generates the client that handles the requests and JSON serialization.\nRegister it with AddRefitClient<T>() and inject the interface wherever you need it.
As a .NET developer, I've spent countless hours working with external APIs.\nIt's a crucial part of modern software development, but let's be honest - it can be a real pain sometimes.
\nWe've all been there, wrestling with HttpClient, writing repetitive code, and hoping we didn't miss a parameter or header somewhere.
That's why I want to introduce you to Refit, a library that's been a game-changer for me.
\nImagine turning your API into a live interface - sounds too good to be true, right?\nBut that's exactly what Refit does.\nIt handles all the HTTP heavy lifting, letting you focus on what matters: your application logic.
\nIn this article, I'll explain how Refit can transform the way you work with APIs in your .NET projects.
\nRefit is a type-safe REST library for .NET.\nIt allows you to define your API as an interface, which Refit then implements for you.\nThis approach reduces boilerplate code and makes your API calls more readable and maintainable.
\nYou describe your API endpoints using method signatures and attributes, and Refit takes care of the rest.
\nLet me break down why I find Refit so powerful:
\nBut what I appreciate most about Refit is how it promotes clean, readable code.\nYour API calls become self-documenting.\nAnyone reading your code can quickly understand what each method does without diving into implementation details.
\nLet's set up Refit and see it in action using the JSONPlaceholder API.\nWe'll implement a full CRUD interface and demonstrate its usage in a Minimal API application.
\nFirst, install the required NuGet packages:
\nInstall-Package Refit\nInstall-Package Refit.HttpClientFactory\nNow, let's create our Refit interface:
\nusing Refit;\n\npublic interface IBlogApi\n{\n [Get("/posts/{id}")]\n Task<Post> GetPostAsync(int id);\n\n [Get("/posts")]\n Task<List<Post>> GetPostsAsync();\n\n [Post("/posts")]\n Task<Post> CreatePostAsync([Body] Post post);\n\n [Put("/posts/{id}")]\n Task<Post> UpdatePostAsync(int id, [Body] Post post);\n\n [Delete("/posts/{id}")]\n Task DeletePostAsync(int id);\n}\n\npublic class Post\n{\n public int Id { get; set; }\n public string Title { get; set; }\n public string Body { get; set; }\n public int UserId { get; set; }\n}\nWe define our IBlogApi interface with methods for all CRUD operations: GET (single and list), POST, PUT, and DELETE.\nThe Post class represents the structure of our blog posts.
Then you have to register Refit in your dependency injection container:
\nusing Refit;\n\nbuilder.Services\n .AddRefitClient<IBlogApi>()\n .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://jsonplaceholder.typicode.com"));\nFinally, we can use IBlogApi in our Minimal API endpoints:
app.MapGet("/posts/{id}", async (int id, IBlogApi api) =>\n await api.GetPostAsync(id));\n\napp.MapGet("/posts", async (IBlogApi api) =>\n await api.GetPostsAsync());\n\napp.MapPost("/posts", async ([FromBody] Post post, IBlogApi api) =>\n await api.CreatePostAsync(post));\n\napp.MapPut("/posts/{id}", async (int id, [FromBody] Post post, IBlogApi api) =>\n await api.UpdatePostAsync(id, post));\n\napp.MapDelete("/posts/{id}", async (int id, IBlogApi api) =>\n await api.DeletePostAsync(id));\nWhat I love about this setup is its simplicity.\nWe've created a fully functional API that communicates with an external service, all in just a few lines of code.\nNo manual HTTP requests, no raw JSON handling - Refit takes care of all that for us.
\nWhen working with APIs, you often need to send data as part of the URL, either in the route or as query parameters.\nRefit makes this process simple and type-safe.
\nLet's extend our IBlogApi interface with some more complex scenarios:
public interface IBlogApi\n{\n // Other methods omitted for brevity\n\n [Get("/posts")]\n Task<List<Post>> GetPostsAsync([Query] PostQueryParameters parameters);\n\n [Get("/users/{userId}/posts")]\n Task<List<Post>> GetUserPostsAsync(int userId);\n}\n\npublic class PostQueryParameters\n{\n public int? UserId { get; set; }\n public string? Title { get; set; }\n}\nLet's break this down:
\nGetPostsAsync uses an object to represent query parameters.\nThis approach is excellent for endpoints with many optional parameters.\nRefit will automatically convert this object into a query string.GetUserPostsAsync demonstrates passing in route parameters (userId) directly.Using an object for query parameters makes your code type-safe and refactoring-friendly.\nIf you need to add a new query parameter, you just add a property to PostQueryParameters.\nYour existing code won't break, and your IDE can help you discover the new options.
Another common requirement when integrating with APIs is including custom headers or authentication tokens with your requests.\nRefit provides several ways to handle this, from simple static headers to dynamic, request-specific authentication.
\nLet's explore some scenarios:
\npublic interface IBlogApi\n{\n [Headers("User-Agent: MyAwesomeApp/1.0")]\n [Get("/posts")]\n Task<List<Post>> GetPostsAsync();\n\n [Get("/secure-posts")]\n Task<List<Post>> GetSecurePostsAsync([Header("Authorization")] string bearerToken);\n\n [Get("/user-posts")]\n Task<List<Post>> GetUserPostsAsync([Authorize(scheme: "Bearer")] string token);\n}\nHeaders attributeHeader attribute, you can pass a header value dynamically as a parameterAuthorize attribute is a convenient way to add Bearer token authenticationBut what if you need to add the same dynamic header to all requests?
\nThat's where DelegatingHandler comes in handy.
You can learn more about using delegating handlers in this article.
\nI've found delegating handlers especially helpful in providing API keys, which are typically static.
\nRefit gives you flexibility when choosing and configuring your JSON serializer.\nBy default, Refit uses System.Text.Json, is the built-in JSON serializer in modern .NET versions.
However, you can easily switch to Newtonsoft.Json if you need its features.
Here's how you can configure Refit to use it.
\nFirst, install the Newtonsoft.Json support package:
\nInstall-Package Refit.Newtonsoft.Json\nThen, configure Refit to use Newtonsoft.Json:
\nusing Newtonsoft.Json;\nusing Newtonsoft.Json.Serialization;\nusing Refit;\n\nbuilder.Services.AddRefitClient<IBlogApi>(new RefitSettings\n{\n ContentSerializer = new NewtonsoftJsonContentSerializer(new JsonSerializerSettings\n {\n ContractResolver = new CamelCasePropertyNamesContractResolver(),\n NullValueHandling = NullValueHandling.Ignore\n })\n})\n.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://jsonplaceholder.typicode.com"));\nThis setup uses camel case for property names and ignores null values when serializing.
\nSystem.Text.Json is faster and uses less memory, making it a great default choice.\nHowever, Newtonsoft.Json offers more features and might be necessary for compatibility with older systems or specific serialization needs.
While Refit's default behavior of automatically deserializing responses into your defined types is convenient, there are times when you need more control over the HTTP response.
\nRefit provides two options for these scenarios:\nHttpResponseMessage and ApiResponse<T>.
Let's update the IBlogApi to use these types:
public interface IBlogApi\n{\n [Get("/posts/{id}")]\n Task<HttpResponseMessage> GetPostRawAsync(int id);\n\n [Get("/posts/{id}")]\n Task<ApiResponse<Post>> GetPostWithMetadataAsync(int id);\n\n [Post("/posts")]\n Task<ApiResponse<Post>> CreatePostAsync([Body] Post post);\n}\nNow, let's break down how to use these, starting with HttpResponseMessage:
HttpResponseMessage response = await blogApi.GetPostRawAsync(1);\n\nif (response.IsSuccessStatusCode)\n{\n var content = await response.Content.ReadAsStringAsync();\n var post = JsonSerializer.Deserialize<Post>(content);\n Console.WriteLine($"Retrieved post: {post.Title}");\n}\nelse\n{\n Console.WriteLine($"Error: {response.StatusCode}");\n}\nThis approach gives you full control over the HTTP response. You can access status codes, headers, and the raw content.\nBut you will have to deal with deserialization manually.
\nApiResponse<T> is a Refit-specific type that wraps the deserialized content and response metadata.\nIt's a great middle ground when you need the typed response and access to headers or status codes.
Here's a more complex example using ApiResponse<T> for creating a post:
var newPost = new Post { Title = "New Post", Body = "Content", UserId = 1 };\n\nApiResponse<Post> createResponse = await blogApi.CreatePostAsync(newPost);\n\nif (createResponse.IsSuccessStatusCode)\n{\n var createdPost = createResponse.Content;\n var locationHeader = createResponse.Headers.Location;\n Console.WriteLine($"Created post with ID: {createdPost.Id}");\n Console.WriteLine($"Location: {locationHeader}");\n}\nelse\n{\n Console.WriteLine($"Error: {createResponse.Error.Content}");\n Console.WriteLine($"Status: {createResponse.StatusCode}");\n}\nThis approach allows you to access the created resource, check specific headers like Location, and handle errors gracefully.
Refit transforms the way we interact with APIs in .NET applications.\nConverting your API into a strongly typed interface simplifies your code, enhances type safety, and improves maintainability.
\nThe key Refit benefits we've explored include:
\nIn my experience, Refit shines in projects of all sizes.\nI've used it in small applications and large-scale microservices architectures.\nIt eliminates boilerplate code, reduces the risk of errors, and allows you to focus on your application's core logic rather than the intricacies of HTTP communication.
\nRemember, while Refit makes API interactions more straightforward, it's not a substitute for understanding the underlying principles of RESTful communication and HTTP.
\nThat's all for today. Stay awesome, and I'll see you next week.
\nP.S. You can find the source code for this example in this repository.
\nEvent sourcing stores every change to your data as an immutable event in an append-only log instead of storing only the current state.\nYou rebuild state by replaying the events in order.\nThe tradeoff is a steep learning curve, plus slower state reconstruction as the event history grows.
\nI've been coding in .NET for years, but I never built an event sourced system.\nEvent sourcing has always intrigued me, though.\nThe idea of capturing every change and having a complete history of your data - it's fascinating.
\nSo, I decided to dive in.\nNot as an expert but as a curious developer.
\nIn this newsletter, I'm sharing my journey into event sourcing.
\nWe'll look at the core concepts of event sourcing, potential benefits, and even some practical examples.
\n\n\n\nEvent Sourcing is an architectural design pattern where changes that occur in a domain are immutably stored as events in an append-only log.
\n
When I first encountered event sourcing, it seemed complex.\nBut stripped down, it's a surprisingly simple idea: store changes, not just the current state.
\nThink of a bank account or wallet.\nNormally, we'd just save the balance.\nWith event sourcing, we record every deposit and withdrawal.\nThe balance is then calculated from these events.
\nThis diagram illustrates the difference:
\n![\"Event](\"https://milanjovanovic.tech/blogs/mnw_105/event_sourcing.png\")
\nThis shift from storing state to storing events is the essence of event sourcing.\nIt's like keeping a detailed diary of your application's data rather than just a snapshot.\nIt's not just about where you are but how you got there.\nFor me, this was a lightbulb moment.
\nAs I dug deeper into event sourcing, I kept asking myself: "Why would I use this instead of traditional data storage?"
\nHere's what I've discovered:
\nReal-world use cases for event sourcing started to make sense:
\nWhile it's not a silver bullet (what is in programming?), I'm beginning to see why so many developers are excited about event sourcing.\nIt's not just about storing data; it's about intent and behavior.
\nAs I started to implement event sourcing, understanding the core concepts became much easier with a concrete example.\nLet's walk through a simple bank account scenario to see how event sourcing works.
\nEvents are immutable records of something that happened.\nIn our bank account example, we might have events like AccountOpened, MoneyDeposited, and MoneyWithdrawn.
Here's how we might define these in C#:
\npublic record AccountOpened(Guid AccountId, DateTime OpenedAt);\npublic record MoneyDeposited(decimal Amount, DateTime DepositedAt);\npublic record MoneyWithdrawn(decimal Amount, DateTime WithdrawnAt);\nRecords are a perfect fit for events, as they are immutable by design.
\nIn event sourcing, the current state is calculated by applying all events in order.
\nHere's how our Account class looks:
public class Account\n{\n public Guid Id { get; private set; }\n public decimal Balance { get; private set; }\n\n private List<object> _events = new List<object>();\n\n public Account(Guid id)\n {\n ApplyEvent(new AccountCreated(id));\n }\n\n public void Deposit(decimal amount)\n {\n ApplyEvent(new MoneyDeposited(amount));\n }\n\n public void Withdraw(decimal amount)\n {\n if (Balance >= amount)\n {\n ApplyEvent(new MoneyWithdrawn(amount));\n }\n else\n {\n throw new InvalidOperationException("Insufficient funds");\n }\n }\n\n private void ApplyEvent(object @event)\n {\n _events.Add(@event);\n\n switch (@event)\n {\n case AccountCreated e:\n Id = e.AccountId;\n Balance = 0;\n break;\n case MoneyDeposited e:\n Balance += e.Amount;\n break;\n case MoneyWithdrawn e:\n Balance -= e.Amount;\n break;\n }\n }\n}\nNotice how the Account class maintains its state.\nEach method (Deposit, Withdraw) doesn't directly modify the balance.\nInstead, it creates and applies an event.\nThe ApplyEvent method then updates the state based on these events.
In our simple example, we're using a list (_events) to store events.\nIn a real system, we would persist these events in a database.\nThe key principle remains: events are appended, never modified.
For production systems, there are specialized event sourcing databases like EventStoreDB.
\nThere's also Marten, a .NET library that adds document database and event sourcing capabilities to PostgreSQL.
\nHere's how we might use our event sourced Account:
_events list).Account.var account = new Account(Guid.NewGuid());\naccount.Deposit(100);\naccount.Withdraw(30);\naccount.Deposit(50);\n\nConsole.WriteLine($"Final balance: {account.Balance}"); // Output: Final balance: 120\nWe'd store these events in a database in a real event sourcing system.\nThis allows us to replay the events on demand to produce the current state.
\nSince I started researching event sourcing, I've seen its potential and its hurdles.
\nEvent sourcing itself is a simple idea.\nHowever, the underlying complexity of this approach concerns me.\nThere's a significant learning curve from event sourcing basics to applying event sourcing in production.
\nIt's not just about storing data differently.\nIt's a fundamental shift in how you model and think about your domain.\nThis complexity extends to the infrastructure level.
\nPerformance is another consideration that's often overlooked.\nWhile appending events is typically fast, reconstructing the current state from a long history of events can be slow.\nReal-world systems often need to implement caching strategies or snapshots to mitigate this.\nEvent sourcing is also eventually consistent on the read side.
\nOne of the trickiest aspects I've encountered is event schema evolution (event versioning).\nAs your system grows and changes, so will your events.\nManaging these changes without breaking existing event streams is a challenge that requires careful planning and design.\nI'm still researching best practices.
\nEvent sourcing has a steep learning curve, even for an experienced developer.\nIt requires a fundamental shift in how you think about data and system design.
\nIf you want to give it a try, start small.\nImplement a simple event-sourced system in a side project.\nIt's the best way to grapple with the concepts hands-on.\nAs you do, you might find that Domain-Driven Design (DDD) principles align well with event sourcing.
\nRemember, the goal isn't to use event sourcing everywhere but to understand where it can add value.
\nIf you're ready to explore this topic further, check out Modular Monolith Architecture.\nThere's an entire chapter on Event-Driven Architecture, which directly complements what you've learned about event sourcing here.
\nIn a future newsletter, we'll explore a more real-world application of event sourcing.
\nGood luck out there, and I'll see you next week.
\nScreaming architecture means your folder structure tells a reader what the system does, not which framework it runs on.\nYou get there by making use cases and feature folders the top-level concept instead of Controllers, Services, and Repositories.\nThe payoff is higher cohesion and easier navigation.
If you were to glance at the folder structure of your system, could you tell what the system is about?\nAnd here's a more interesting question.\nCould a new developer on your team easily understand what the system does based on the folder structure?
\nYour architecture should communicate what problems it solves.\nOrganizing your system around use cases leads to a structure aligned with the business domain.\nThis approach is called screaming architecture.
\nScreaming architecture is a term coined by Robert Martin (Uncle Bob).\nHe argues that a software system's structure should communicate what the system is about.\nHe draws a parallel between looking at a blueprint for a building, where you can tell the purpose of the building based on the blueprint.
\nIn this article, I want to show some practical examples and discuss the benefits of screaming architecture.
\nA use case represents a specific interaction or task that a user wants to achieve within your system.\nIt encapsulates the business logic required to fulfill that task.\nA use case is a high-level description of a user's goal.\nFor example, "reserving an apartment" or "purchasing a ticket".\nIt focuses on the what of the system's behavior, not the how.
\nWhen you look at the folder structure and source code files of your system:
\nHere's an example of a folder structure organized around technical concerns:
\n📁 Api/\n|__ 📁 Controllers\n|__ 📁 Entities\n|__ 📁 Exceptions\n|__ 📁 Repositories\n|__ 📁 Services\n |__ #️⃣ ApartmentService.cs\n |__ #️⃣ BookingService.cs\n |__ ...\n|__ 📁 Models\nSomewhere inside these folders, we'll find concrete classes that contain the system's behavior.\nYou'll notice that the cohesion with this folder structure is low.
\nHow does screaming architecture help?
\nA use case driven approach will place the system's use cases as the top-level concept.\nI also like to group related use cases into a top-level feature folder.\nInside a use case folder, we may find technical concepts required to implement it.
\nVertical slice architecture also approaches this from a similar perspective.
\n📁 Api/\n|__ 📁 Apartments\n |__ 📁 ReserveApartment\n |__ ...\n|__ 📁 Bookings\n |__ 📁 CancelBooking\n |__ ...\n|__ 📁 Payments\n|__ 📁 Reviews\n|__ 📁 Disputes\n|__ 📁 Invoicing\nThe use case driven folder structure helps us better understand user needs and aligns development efforts with business goals.
\nThe benefits of organizing our system around use cases are:
\nWe have many techniques for discovering the high-level modules within our system.\nFor example, we could use event storming to explore the system's use cases.\nDomain exploration happens before we write a single line of code.
\nThe next step is decomposing the larger problem domain into smaller sub-domains and later bounded contexts.\nThis gives us loosely coupled high-level modules that we can translate into code.
\n![\"Bounded](\"https://milanjovanovic.tech/blogs/mnw_104/bounded_contexts.png\")
\nThe overarching idea here is thinking about cohesion around functionalities.\nWe want to organize our system so that the cohesion between the components is high.\nBounded contexts, vertical slices, and screaming architecture are complementary concepts.
\nHere's a screaming architecture example for this system.\nLet's say the Ticketing module uses Clean Architecture internally.\nBut we can still organize the system around feature folders and use cases.\nAn alternative approach could be organizing around vertical slices, resulting in a less nested folder structure.
📁 Modules/\n|__ 📁 Attendance\n |__ ...\n|__ 📁 Events\n |__ ...\n|__ 📁 Ticketing\n |__ 📁 Application\n |__ 📁 Carts\n |__ 📁 AddItemToCart\n |__ 📁 ClearCart\n |__ 📁 GetCart\n |__ 📁 RemoveItemFromCart\n |__ 📁 Orders\n |__ 📁 SubmitOrder\n |__ 📁 CancelOrder\n |__ 📁 GetOrder\n |__ 📁 Payments\n |__ 📁 RefundPayment\n |__ ...\n |__ 📁 Domain\n |__ 📁 Customers\n |__ 📁 Orders\n |__ 📁 Payments\n |__ 📁 Tickets\n |__ ...\n |__ 📁 infrastructure\n |__ 📁 Authentication\n |__ 📁 Customers\n |__ 📁 Database\n |__ 📁 Orders\n |__ 📁 Payments\n |__ 📁 Tickets\n |__ ...\n|__ 📁 Users\n |__ ...\nThe example above is a small part of the system I built inside of Modular Monolith Architecture.
\nScreaming Architecture isn't just a catchy phrase, it's an approach that can profoundly impact how you build software.\nBy organizing your system around use cases, you align your codebase with the core business domain.\nYour system exists to solve the business domain problems.
\nRemember, the goal is to create a system that communicates its purpose through its structure.\nEmbrace a use case-driven approach, break down complex domains into bounded contexts.\nBuild a system that truly "screams" about the problems it solves.
\nIf you want to explore these powerful ideas further, check out Pragmatic Clean Architecture.\nI share my entire framework for building robust applications from the ground up and organizing the system around use cases.
\nThat's all for today.
\nSee you next week.
\nAmazon SQS is a fully managed message queue, and Amazon SNS is a pub/sub service that can fan out a copy of every message to multiple SQS queues.\nMassTransit provides messaging abstractions on top of both and provisions the queues, topics, and subscriptions in AWS automatically.\nThis guide covers the core concepts and the full MassTransit setup in .NET.
\nHave you ever wondered how large-scale systems handle traffic spikes or maintain performance even when parts of the system are temporarily down?\nThe answer lies in asynchronous messaging.
\nAsynchronous messaging is, at its core, about decoupling.\nOur components can operate independently and communicate through a message queue or topic.\nIf one service (component) is temporarily unavailable, the others can continue working.\nThis improves our system's scalability, resilience, and fault tolerance.
\nIn this article, we'll explore how to use Amazon SQS and SNS for asynchronous messaging in .NET applications.
\nWe'll also see how MassTransit simplifies the process, enabling you to build robust message-driven systems.
\nLet's dive in.
\nAmazon Simple Queue Service (SQS) is a fully managed message queueing service.\nIt facilitates the decoupling and scaling of microservices and distributed systems.
\nSQS acts as a reliable middleman for asynchronous communication.\nIt enables different components of your architecture to exchange messages without needing to be online or directly connected at the same time.\nMessages are stored in queues and consumed on demand.
\nSQS offers two distinct queue types depending on your requirements:
\nLet's say we have two services - Stock and Reporting.\nWhen a user creates a purchase order in the Stock service, we want to notify the Reporting service.
SQS allows us to create decoupled communication between these services.\nThe Stock service sends a message to an SQS queue, and the Reporting service can poll from the queue to consume messages.
![\"Amazon](\"https://milanjovanovic.tech/blogs/mnw_103/amazon_sqs.png\")
\nIt's interesting to highlight that SQS uses a polling mechanism for message consumers.\nWhen a consumer polls for new messages, SQS starts a visibility timeout.\nSQS doesn't automatically delete the messages.\nInstead, messages are hidden from other consumers until the timeout expires.
\nWhen the consumer successfully processes a message, it's removed from the queue.\nBut if the visibility timeout expires, the message becomes visible and can be delivered again.\nOther consumers can receive this message when polling from SQS.\nThis is why SQS offers at-least-once delivery (for standard queues).\nYou will have to implement idempotency in the consumer.
\nLet's introduce another service into our system - the Risk Management service.\nWhen multiple consumers (services) poll an SQS queue, each wants to retrieve and process messages as they become available.\nHowever, once a message is successfully received and processed by one consumer, it's removed from the queue.
Why is this a problem?
\nOther consumers who might have been polling will miss out on that specific message.\nThis is known as competing consumers.
\nLet's consider the example of Reporting and Risk Management services polling the same queue.\nIf a new message arrives, only one of these services will "win" the race and retrieve it for processing.\nThe other service won't find that message even if it polls moments later.
![\"Amazon](\"https://milanjovanovic.tech/blogs/mnw_103/amazon_sqs_competing_consumers.png\")
\nSo, how can we solve this?
\nWe could introduce a dedicated queue for each service.\nHowever, the producer now needs to publish to multiple queues.\nThis creates a possibility for some (not so) interesting partial failures.\nWhat happens if we successfully publish to one queue but fail to publish to the other?
\nYou can see how this becomes difficult to scale while maintaining reliability.
\nLuckily, there's a solution.
\nAmazon Simple Notification Service (SNS) is a fully managed pub/sub messaging service.\nIt allows publishers to send messages to multiple subscribers (topics) simultaneously.
\nSNS operates on the principle of publishers and subscribers.\nPublishers send messages to an SNS topic, while subscribers express interest in specific topics and receive messages published to those topics.\nThis decoupled architecture allows you to add or remove subscribers without impacting the publisher or other subscribers.
\nSNS seamlessly integrates with SQS, allowing you to create a powerful combination where SNS handles the fan-out of messages,\nand SQS queues ensure that each message is processed exclusively by a single consumer (service).
\nInstead of sending a message to the queue, the Stock service now publishes to an SNS topic.\nBoth the Reporting and Risk Management services create their own SQS queues and subscribe these queues to the SNS topic.\nWhen a new message is published to the SNS topic, SNS delivers it to both SQS queues.\nEach queue receives its own copy of the message.
If we want to introduce a new service, we'll create a new SQS queue and subscribe it to the topic.
\n![\"Amazon](\"https://milanjovanovic.tech/blogs/mnw_103/amazon_sns.png\")
\nHow can we use SNS and SQS from a .NET application?
\nYou could use the official AWS SDKs.\nThe benefit is you'll have more control over messaging.\nHowever, you will need to write more code to receive and handle messages successfully.
\nSo, I want to suggest a different approach.
\nMassTransit is one of the most popular messaging libraries in .NET.\nIt provides a set of messaging abstractions on top of the supported message transports.
\nI wrote an article about using MassTransit with RabbitMQ and Azure Service Bus.
\nBut we'll focus on using MassTransit with SQS and SNS.
\nLet's start by installing the NuGet package we'll need:
\nInstall-Package MassTransit.AmazonSQS\nNext, we'll need to configure MassTransit with our .NET applications.
\nHere's the MassTransit configuration for the Stock service:
builder.Services.AddMassTransit(configure =>\n{\n configure.AddConsumer<PurchaseOrderSentConsumer>().Endpoint(e => e.InstanceId = "stocks");\n\n configure.UsingAmazonSqs((context, cfg) =>\n {\n cfg.Host("eu-central-1", h =>\n {\n h.AccessKey(builder.Configuration["AmazonSqs:AccessKey"]!);\n h.SecretKey(builder.Configuration["AmazonSqs:SecretKey"]!);\n\n h.Scope("stocks-platform", scopeTopics: true);\n });\n\n cfg.ConfigureEndpoints(context, new KebabCaseEndpointNameFormatter("stocks-platform-", false));\n });\n});\nHere are a few things I want to highlight here:
\nUsingAmazonSqs - Configures SQS (and SNS) as the message transport.Scope - Adds a prefix to SNS topic names. This helps distinguish topics from other applications and environments.Endpoint - Sets the InstanceId, which is appended to the endpoint (queue) name.ConfigureEndpoints - Allows us to specify a prefix for endpoint (queue) names. The idea is the same as the topic name prefix.You'll also need to configure an IAM policy\nthat gives MassTransit the required permissions for AWS resources.
\nAnd with this setup in place, you can use MassTransit to publish messages.\nHere's an endpoint that accepts a purchase order and publishes a PurchaseOrderSent message.
app.MapPost("purchase-orders", async (PurchaseOrderRequest request, IPublishEndpoint publishEndpoint) =>\n{\n var purchaseOrder = new PurchaseOrder\n {\n Id = Guid.NewGuid(),\n Ticker = request.Ticker,\n LimitPrice = request.LimitPrice,\n Quantity = request.Quantity\n };\n\n OrdersDb.Add(purchaseOrder);\n\n await publishEndpoint.Publish(new PurchaseOrderSent(purchaseOrder.Id));\n\n return Results.Ok(purchaseOrder);\n});\nWe will process the purchase order in the PurchaseOrderSentConsumer.\nIf it's successfully processed (filled), we will publish an OrderFilled message.
The Risk Management service can subscribe to this message using MassTransit.\nThe configuration is almost identical, with the only difference being the endpoint's InstanceId.
builder.Services.AddMassTransit(configure =>\n{\n configure.AddConsumer<OrderFilledConsumer>().Endpoint(e => e.InstanceId = "risk-management");\n\n configure.UsingAmazonSqs((context, cfg) =>\n {\n cfg.Host("eu-central-1", h =>\n {\n h.AccessKey(builder.Configuration["AmazonSqs:AccessKey"]!);\n h.SecretKey(builder.Configuration["AmazonSqs:SecretKey"]!);\n\n h.Scope("stocks-platform", true);\n });\n\n cfg.ConfigureEndpoints(context, new KebabCaseEndpointNameFormatter("stocks-platform-", false));\n });\n});\nMassTransit will automatically create the required queues, topics, and subscriptions in AWS.\nIf needed, you can further configure the SQS and SNS resources.
\nOf course, you can also create the required infrastructure in AWS and tell MassTransit to use it.
\nBut let's keep it simple and allow MassTransit to provision the AWS resources.
\nBy default, MassTransit creates standard SQS queues.\nHere's what we get in Amazon SQS.
\n![\"Amazon](\"https://milanjovanovic.tech/blogs/mnw_103/amazon_sqs_queues.png\")
\nAnd here's what we get in Amazon SNS:
\n![\"Amazon](\"https://milanjovanovic.tech/blogs/mnw_103/amazon_sns_topics.png\")
\nMassTransit automatically configures the required subscriptions between the topic and queues.
\nAnd we are ready to start publishing and consuming messages.
\nAsynchronous communication and decoupling are pivotal in achieving scalability, resilience, and fault tolerance.\nAmazon SQS and SNS provide the building blocks of message-driven architectures in the AWS cloud.
\nWe explored the core concepts of SQS and SNS, understanding how they enable reliable message delivery and fan-out capabilities.
\nMassTransit provides an excellent abstraction layer over SQS and SNS, simplifying development.\nWe can focus on solving the business problems and delivering value to our users.
\nThe combination of Amazon SQS, SNS, and MassTransit gives us robust tools for building modern, event-driven applications.
\nThanks for reading, and I'll see you next week!
\nP.S. You can find the source code for this article in this repository, under the Amazon SQS and SNS folder.
The five EF Core features worth knowing are query splitting, bulk updates and deletes with ExecuteUpdate and ExecuteDelete, raw SQL queries for unmapped types, global query filters, and eager loading.\nEach solves a specific problem, from the cartesian explosion to updating many rows in one round trip.\nHere is how they work and when to reach for each one.
Okay, let's be honest.\nWe all have a million things on our plates, and diving deep into every nook and cranny of EF Core might not be\nat the top of your priority list.
\nBut here's the deal: EF Core is powerful, and knowing a few key features can save you lots of time and frustration.
\nSo, I won't bombard you with every single EF Core feature under the sun.
\nInstead, I've cherry-picked five essential ones that you really need to know.
\nWe'll go through:
\nLet's get started!
\nQuery splitting is one of those EF Core features that you rarely need.\nUntil one day, you do.\nQuery splitting is helpful in scenarios where you're eager loading multiple collections.\nIt helps us avoid the cartesian explosion problem.
\nLet's say we want to retrieve a department with all its teams and employees.\nWe might write a query like this:
\nDepartment department =\n context.Departments\n .Include(d => d.Teams)\n .Include(d => d.Employees)\n .Where(d => d.Id == departmentId)\n .First();\nThis translates to a single SQL query with two JOINs.\nHowever, since these JOIN statements are on the same level, the database will return a cross product.\nEach row from Teams will be joined with each row Employees.\nIn that case, the database returns many rows, significantly impacting performance.
Here's how we can avoid these performance issues with query splitting:
\nDepartment department =\n context.Departments\n .Include(d => d.Teams)\n .Include(d => d.Employees)\n .Where(d => d.Id == departmentId)\n .AsSplitQuery()\n .First();\nWith AsSplitQuery, EF Core will execute an additional SQL query for each collection navigation.
However, be cautious not to overuse query splitting.\nI use split queries when I've measured that they consistently perform better.
\nSplit queries have more round trips to the database, which might be slower if database latency is high.\nThere is also no consistency guarantee across multiple SQL queries.
\nEF Core 7 added two new APIs for performing bulk updates and deletes,\nExecuteUpdate and ExecuteDelete.\nThey allow you to efficiently update a large number of rows in one round trip to the database.
Here's a practical example.
\nThe company has decided to give a 5% raise to all employees in the "Sales" department.\nWithout bulk updates, we might iterate through each employee and update their salary individually:
\nvar salesEmployees = context.Employees\n .Where(e => e.Department == "Sales")\n .ToList();\n\nforeach (var employee in salesEmployees)\n{\n employee.Salary *= 1.05m;\n}\n\ncontext.SaveChanges();\nThis approach involves multiple database roundtrips, which can be inefficient, especially for large datasets.
\nWe can achieve the same in one roundtrip using ExecuteUpdate:
context.Employees\n .Where(e => e.Department == "Sales")\n .ExecuteUpdate(s => s.SetProperty(e => e.Salary, e => e.Salary * 1.05m));\nThis executes a single SQL UPDATE statement, directly modifying the salaries in the database without loading entities into memory, giving us improved performance.
Here's another example.\nLet's say an e-commerce platform wants to delete all shopping carts older than one year.
\nHere's how we could do this with ExecuteDelete:
context.Carts\n .Where(o => o.CreatedOn < DateTime.Now.AddYears(-1))\n .ExecuteDelete();\nThis results in a single SQL DELETE statement, directly removing the old shopping carts from the database.
However, bulk updates bypass the EF change tracker.\nThis could be problematic, and I wrote about the caveats of bulk updates in this article.
\nEF Core 8 added a new feature that allows us to query unmapped types with raw SQL.
\nSuppose we want to retrieve data from a database view, stored procedure, or a table that doesn't directly correspond to any of our entity classes.
\nFor example, we want to retrieve a sales summary for each product.\nWith EF Core 8, we can define a simple ProductSummary class representing the structure of the result set and query it directly:
public class ProductSummary\n{\n public int ProductId { get; set; }\n public string ProductName { get; set; }\n public decimal TotalSales { get; set; }\n}\n\nvar productSummaries = await context.Database\n .SqlQuery<ProductSummary>(\n @$"""\n SELECT p.ProductId, p.ProductName, SUM(oi.Quantity * oi.UnitPrice) AS TotalSales\n FROM Products p\n JOIN OrderItems oi ON p.ProductId = oi.ProductId\n WHERE p.CategoryId = {categoryId}\n GROUP BY p.ProductId, p.ProductName\n """)\n .ToListAsync();\nThe SqlQuery method returns an IQueryable, which allows you to compose raw SQL queries with LINQ.\nThis combines the power of raw SQL with the expressiveness of LINQ.
Remember to use parameterized queries to prevent SQL injection vulnerabilities.\nThe SqlQuery method accepts a FormattableString, which means you can safely use an interpolated string.\nEach argument is converted to a SQL parameter.
You can learn more about raw SQL queries in this article.
\nQuery filters are like reusable WHERE clauses you can apply to your entities.\nThese filters are automatically added to LINQ queries whenever you retrieve entities of the corresponding type.\nThis saves you from repeatedly writing the same filtering logic in multiple places within your application.
Query Filters are commonly used for scenarios like:
\nIn a multi-tenant application, you often need to filter data based on the current tenant.\nQuery filters allow us to handle this requirement easily:
\npublic class Product\n{\n public int Id { get; set; }\n public string Name { get; set; }\n // Associate products with tenants\n public int TenantId { get; set; }\n}\n\nprotected override void OnModelCreating(ModelBuilder modelBuilder)\n{\n // The current TenantId is set based on the current request/context\n modelBuilder.Entity<Product>().HasQueryFilter(p => p.TenantId == _currentTenantId);\n}\n\n// Now, queries automatically filter based on the tenant:\nvar productsForCurrentTenant = context.Products.ToList();\nConfiguring multiple query filters on the same entity will only apply the last one.\nYou can combine multiple query filters using && (AND) and || (OR) operators.
You can use IgnoreQueryFilters to bypass the filters in specific queries when needed.
Eager Loading is a feature in EF Core that allows you to load related entities along with your main entity in a single database query.\nBy fetching all necessary data in a single query, you can improve application performance.\nThis is especially true when dealing with complex object graphs or when lazy loading would result in many small, inefficient queries.
\nHere's an example VerifyEmail use case.\nWe want to load an EmailVerificationToken and eagerly load a User with the Include method because we want to modify both entities at the same time.
internal sealed class VerifyEmail(AppDbContext context)\n{\n public async Task<bool> Handle(Guid tokenId)\n {\n EmailVerificationToken? token = await context.EmailVerificationTokens\n .Include(e => e.User)\n .FirstOrDefaultAsync(e => e.Id == tokenId);\n\n if (token is null || token.ExpiresOnUtc < DateTime.UtcNow || token.User.EmailVerified)\n {\n return false;\n }\n\n token.User.EmailVerified = true;\n\n context.EmailVerificationTokens.Remove(token);\n\n await context.SaveChangesAsync();\n\n return true;\n }\n}\nEF Core will generate a single SQL query that joins the EmailVerificationToken and User tables, retrieving all the necessary data in one go.
Eager loading (and query splitting, which we mentioned earlier) isn't a silver bullet.\nConsider using projections if you only need specific properties from related entities to avoid fetching unnecessary data.
\nSo, there you have it!\nFive EF Core features that, frankly, you can't afford not to know.\nRemember, mastering EF Core takes time, but these features provide a solid foundation to build upon.
\nAnother piece of advice is to deeply understand how your database works.\nMastering SQL also allows you to get the most value from EF Core.
\nWhile we focused on five key features, there are many other EF Core features worth exploring:
\nEF Core is continuously evolving, so keep an eye on the latest updates and releases to stay ahead.
\nGood luck out there, and see you next week.
\nStatic code analysis examines your C# code without running it and reports security, performance, and style issues.\n.NET ships with Roslyn analyzers enabled by default for .NET 5 and later, and SonarAnalyzer.CSharp adds more rules.\nYou configure both from Directory.Build.props and tune individual rules in .editorconfig.
Writing good code is important for any software project.\nIt's also something I deeply care about.\nHowever, it can be hard to spot problems by just reading through everything.
\nLuckily, there's a tool that can help: static code analysis.
\nIt's like having an extra pair of eyes automatically checking your code.\nStatic code analysis helps you build secure, maintainable, and high-quality C# code.
\nHere's what we are going to cover in this week's newsletter:
\nLet's see how static code analysis can help us improve our code quality.
\nStatic code analysis is a way to examine your code without actually running it.\nIt reports any issues related to security, performance, coding style, or best practices.
\nWith static code analysis, you can "shift left".\nThis allows you to find and fix issues early in the development process when they're less expensive to solve.
\nBy writing high-quality code, you'll be able to build systems that are more reliable, scalable, and easier to maintain over time.\nInvesting in code quality will pay dividends in the later stages of any project.
\nYou can integrate static code analysis into your CI pipeline for a quick feedback loop.\nWe can also pair this with architecture testing to enforce additional coding standards.
\n.NET has built-in Roslyn analyzers that inspect your C# code for code style and quality issues.\nCode analysis is enabled by default if your project targets .NET 5 or later.
\nThe best way I found to configure static code analysis is using Directory.Build.props.\nIt's an XML file where you can configure common project properties.\nYou can place the Directory.Build.props file in the root folder so it will apply to all projects.
You can configure the TargetFramework, ImplicitUsings, Nullable (nullable reference types), etc.\nBut what we care about is configuring static code analysis.
Here are some properties we can configure:
\nTreatWarningsAsErrors - Treat all warnings as errors.CodeAnalysisTreatWarningsAsErrors - Treat code quality (CAxxxx) warnings as errors.EnforceCodeStyleInBuild - Enables code-style analysis ("IDExxxx") rules.AnalysisLevel - Specifies which analyzers to enable. The default value is latest.AnalysisMode - Configures the predefined code analysis configuration.We can also install additional NuGet packages to our projects.\nSonarAnalyzer.CSharp contains additional code analyzers to help us write clean, safe, and reliable code.\nThis library comes from the same company that built SonarQube.
<Project>\n <PropertyGroup>\n <TargetFramework>net8.0</TargetFramework>\n <ImplicitUsings>enable</ImplicitUsings>\n <Nullable>enable</Nullable>\n\n <!-- Configure code analysis. -->\n <AnalysisLevel>latest</AnalysisLevel>\n <AnalysisMode>All</AnalysisMode>\n <TreatWarningsAsErrors>true</TreatWarningsAsErrors>\n <CodeAnalysisTreatWarningsAsErrors>true</CodeAnalysisTreatWarningsAsErrors>\n <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>\n </PropertyGroup>\n\n <ItemGroup Condition="'$(MSBuildProjectExtension)' != '.dcproj'">\n <PackageReference Include="SonarAnalyzer.CSharp" Version="*">\n <PrivateAssets>all</PrivateAssets>\n <IncludeAssets>\n runtime; build; native; contentfiles; analyzers; buildtransitive\n </IncludeAssets>\n </PackageReference>\n </ItemGroup>\n</Project>\nThe built-in .NET analyzers and the ones from SonarAnalyzer.CSharp can be very helpful.\nBut they can also make a lot of noise with too many build warnings.
When you encounter code analysis rules that you don't consider helpful, you can turn them off.\nYou can configure individual code analysis rules in the .editorconfig file.
# S125: Sections of code should not be commented out\ndotnet_diagnostic.S125.severity = none\n\n# S1075: URIs should not be hardcoded\ndotnet_diagnostic.S1075.severity = none\n\n# S2094: Classes should not be empty\ndotnet_diagnostic.S2094.severity = none\n\n# S3267: Loops should be simplified with "LINQ" expressions\ndotnet_diagnostic.S3267.severity = none\nStatic code analysis can help you detect potential security vulnerabilities in your code.\nHere's an example of a PasswordHasher using only 10,000 iterations to generate a password hash.\nThe S5344 rule, from SonarAnalyzer.CSharp, detects this issue and warns us.\nThe recommended minimal number of iterations is 100,000.
You can navigate to the explanation for S5344 to learn more:
\n\n\nWeakly hashed password storage poses a significant security risk to software applications.
\n
With TreatWarningsAsErrors turned on, your build will fail until you solve this issue.\nThis reduces the chance of introducing security risks in production.
![\"Example](\"https://milanjovanovic.tech/blogs/mnw_101/static_code_analysis.png\")
\nStatic code analysis is a powerful tool I include in all my C# projects.\nIt helps me catch problems early, leads to more reliable and secure code, and saves time and effort.\nWhile the initial setup and fine-tuning of rules might take some time, the long-term benefits are undeniable.
\nRemember, static code analysis is a tool that complements your existing development practices.
\nYou can create a robust development process that consistently delivers high-quality software by combining\nstatic code analysis with other techniques like code reviews, unit testing, and continuous integration.
\nEmbrace static code analysis.\nYour future self (and your team) will thank you.
\nThat's all for today.
\nSee you next week.
\nP.S. Here's a sample .editorconfig file you can add to your projects and customize to fit your needs.
\nRedis Pub/Sub sends messages to named channels, and every subscriber listening at that moment receives them.\nNothing is stored, so a message published with no subscribers is discarded, which gives you at-most-once delivery.\nIn .NET you publish and subscribe through an ISubscriber from StackExchange.Redis.
Redis is a popular choice for caching data, but its capabilities go far beyond that.\nOne of its lesser-known features is Pub/Sub support.\nRedis channels offer an interesting approach for implementing real-time messaging in your .NET applications.\nHowever, as you'll soon see, channels also have some drawbacks.
\nIn this week's newsletter, we'll explore:
\nLet's dive in.
\nRedis channels are named communication channels that implement the Publish/Subscribe messaging paradigm.\nEach channel is identified by a unique name (e.g., notifications, updates).\nChannels facilitate message delivery from publishers to subscribers.
Publishers use the PUBLISH command to send messages to a specific channel.\nSubscribers use the SUBSCRIBE command to register interest in receiving messages from a channel.
![\"Redis](\"https://milanjovanovic.tech/blogs/mnw_100/redis_channel.png\")
\nRedis channels follow a topic-based publish-subscribe model.\nMultiple publishers can send messages to a channel, and multiple subscribers can receive messages from that channel.
\nHowever, it's crucial to note that Redis channels do not store messages.\nIf there are no subscribers for a channel when a message is published, that message is immediately discarded.
\nRedis channels have an at-most-once delivery semantics.
\nGiven that Redis channels operate with at-most-once delivery (messages might be lost if there are no subscribers),\nthey are well-suited for scenarios where occasional message loss is acceptable and real-time or near-real-time communication is desired.
\nHere are a few possible use cases:
\nRedis channels aren't the best choice for critical data where message loss is unacceptable.\nIn such cases, you should consider a more reliable messaging system.
\nLet's see how we can use Redis channels in .NET.
\nWe will use the StackExchange.Redis library to send messages with Redis channels.
Let's start by installing it:
\nInstall-Package StackExchange.Redis\nYou can run Redis locally in a Docker container.\nThe default port is 6379.
docker run -it -p 6379:6379 redis\nHere's a simple background service that'll act as our message Producer.
We're creating a ConnectionMultiplexer by connecting to our Redis instance.\nThis allows us to obtain an ISubscriber that we can use for pub/sub messaging.\nThe ISubscriber will enable us to publish a message to a channel by specifying the channel name.
public class Producer(ILogger<Producer> logger) : BackgroundService\n{\n private static readonly string ConnectionString = "localhost:6379";\n private static readonly ConnectionMultiplexer Connection =\n ConnectionMultiplexer.Connect(ConnectionString);\n\n private const string Channel = "messages";\n\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n var subscriber = Connection.GetSubscriber();\n\n while (!stoppingToken.IsCancellationRequested)\n {\n var message = new Message(Guid.NewGuid(), DateTime.UtcNow);\n\n var json = JsonSerializer.Serialize(message);\n\n await subscriber.PublishAsync(Channel, json);\n\n logger.LogInformation(\n "Sending message: {Channel} - {@Message}",\n message);\n\n await Task.Delay(5000, stoppingToken);\n }\n }\n}\nLet's also introduce a separate background service for consuming messages.
\nThe Consumer connects to the same Redis instance and obtains an ISubscriber.\nThe ISubscriber exposes a SubscribeAsync method that we can use to subscribe to messages from a given channel.\nThis method accepts a callback delegate that we can use to handle the message.
public class Consumer(ILogger<Consumer> logger) : BackgroundService\n{\n private static readonly string ConnectionString = "localhost:6379";\n private static readonly ConnectionMultiplexer Connection =\n ConnectionMultiplexer.Connect(ConnectionString);\n\n private const string Channel = "messages";\n\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n var subscriber = Connection.GetSubscriber();\n\n await subscriber.SubscribeAsync(Channel, (channel, message) =>\n {\n var message = JsonSerializer.Deserialize<Message>(message);\n\n logger.LogInformation(\n "Received message: {Channel} - {@Message}",\n channel,\n message);\n });\n }\n}\nFinally, here's what we get when we run both the Producer and Consumer services:
![\"Redis](\"https://milanjovanovic.tech/blogs/mnw_100/redis_pub_sub.gif\")
\nIn a recent project, I tackled a common challenge in distributed systems: keeping the caches in sync.\nWe were using a two-level caching approach.\nFirst, we had an in-memory cache on each web server for super-fast access.\nSecond, we had a shared Redis cache to avoid hitting our database too often.
\nThe problem was that when data changed in the database, we needed a way to quickly tell all the web servers to clear their in-memory caches.\nThis is where Redis Pub/Sub came to the rescue.\nWe set up a Redis channel specifically for cache invalidation messages.
\nEach application would run a CacheInvalidationBackgroundService that subscribes to messages from the cache invalidation channel.
public class CacheInvalidationBackgroundService(\n IServiceProvider serviceProvider)\n : BackgroundService\n{\n public const string Channel = "cache-invalidation";\n\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n await subscriber.SubscribeAsync(Channel, (channel, key) =>\n {\n var cache = serviceProvider.GetRequiredService<IMemoryCache>();\n\n cache.Remove(key);\n\n return Task.CompletedTask;\n });\n }\n}\nWhenever data changes in the database, we publish a message on this channel with the cache key of the updated data.\nAll the web servers are subscribed to this channel, so they instantly know to remove the old data from their in-memory caches.\nSince the in-memory cache is wiped if the application isn't running, losing cache invalidation messages isn't a problem.\nThis keeps our caches consistent and ensures our users always see the most up-to-date information.
\nRedis Pub/Sub is not a silver bullet for every messaging need, but its simplicity and speed make it a valuable tool.\nChannels allow us to easily implement communication between loosely coupled components.
\nRedis channels have at-most-once delivery semantics, so they're best suited for cases where the occasional dropped message is acceptable.
\nI used it to solve the challenge of synchronizing caches across multiple servers.\nThis allowed our system to serve up-to-date data without sacrificing performance.
\nP.S. When you're ready to dive deeper into creating message-driven systems, check out Modular Monolith Architecture.\nI have an entire module dedicated to building reliable distributed messaging and event-driven architecture.
\nGood luck out there, and see you next week.
\nSystem integration testing verifies how the modules of a single system interact, including the external services they depend on.\nFor a modular monolith, you run the app in memory with WebApplicationFactory and its dependencies in Docker with Testcontainers, then drive real use cases by sending commands and queries.\nBecause modules communicate asynchronously, the test polls until the system becomes consistent.
Modular monoliths strike a balance between the simplicity of monolithic architecture and the flexibility of microservices.\nBy breaking down applications into cohesive modules, modular monoliths enable easier development and maintenance.\nHowever, they still have a single codebase and deployment unit.
\nA critical aspect of the success of a modular monolith is the interaction between its modules.
\nSystem integration testing (SIT) is an approach to verifying the collaboration of these modules.\nIt involves testing the integration points and communication mechanisms between modules.
\nSystem integration testing allows us to validate the entire system's behavior.\nThis allows us to catch problems early before they become big headaches.
\nIn this article, we'll learn how to test a modular monolith using system integration testing.
\nWe'll look at real-world examples and discuss why this testing approach is useful.
\nSystem integration testing (SIT) is an approach to testing the interactions between various modules within a single system.\nThe system could contain many external services, which should also be included during testing.
\nSystem integration testing is the perfect testing approach for modular monoliths.\nIt allows you to mimic the real-world execution of your application (as you'll see later).
\nThe key benefits of system integration testing are:
\nA modular monolith consists of multiple modules, each with a distinct responsibility.\nModules represent high-level components with well-defined boundaries.\nThe modules essentially group together related functionalities (use cases).\nIf you want to learn more about this software architecture, check out this introduction to modular monoliths.
\nLet's consider a hypothetical ticketing system that consists of several modules:
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_099/modular_monolith.png\")
\n During system integration testing, we want to ensure that all these modules interact correctly and\nfulfill the business requirements of the ticketing system.
\nThe modules in our ticketing system represent different bounded contexts.\nThe Users Module uses the term User as its core entity.\nHowever, the Ticketing Module uses the term Customer because it's more aligned with its core responsibility of selling tickets.\nConceptually, both entities represent the same person within our system.
Here's the scenario we want to test:
\n![\"User](\"https://milanjovanovic.tech/blogs/mnw_099/user_registration.png\")
\nIf you haven't figured it out by now, our modules communicate asynchronously using messaging.
\nWhy is this important for our tests?
\nThere is a time delay from when something occurs in one module until the other modules are notified and handle the integration events.\nOur system integration tests will have to take into account this delay.
\nHere's the test for this scenario:
\npublic class RegisterUserTests : BaseIntegrationTest\n{\n public RegisterUserTests(IntegrationTestWebAppFactory factory)\n : base(factory)\n {\n }\n\n [Fact]\n public async Task RegisterUser_Should_PropagateToTicketingModule()\n {\n // [Users Module] - Register user\n var command = new RegisterUserCommand(\n Faker.Internet.Email(),\n Faker.Internet.Password(6),\n Faker.Name.FirstName(),\n Faker.Name.LastName());\n\n Result<Guid> userResult = await Sender.Send(command);\n\n userResult.IsSuccess.Should().BeTrue();\n\n // [Ticketing Module] - Get customer\n Result<CustomerResponse> customerResult = await Poller.WaitAsync(\n TimeSpan.FromSeconds(15),\n async () =>\n {\n var query = new GetCustomerQuery(userResult.Value);\n\n var customerResult = await Sender.Send(query);\n\n return customerResult;\n });\n\n // Assert\n customerResult.IsSuccess.Should().BeTrue();\n customerResult.Value.Should().NotBeNull();\n }\n}\nA lot is going on here, so let's unpack the steps:
\nWebApplicationFactory to run an in-memory application instanceRegisterUserCommand to register a user in the Users ModuleGetCustomerQueryPoller allows us to wait until the system eventually becomes consistentYou can learn more about integration testing with Testcontainers in this article.
\nSystem integration tests take longer to execute than integration tests for one module.\nThis is a side effect of testing a bigger slice of the overall system in each test case.
\nThe Poller class allows you to execute a delegate until you receive a successful result or a timeout occurs.\nYou can customize the timeout duration based on the scenario you are testing.
internal static class Poller\n{\n private static readonly Error Timeout =\n Error.Failure("Poller.Timeout", "The poller has time out");\n\n internal static async Task<Result<T>> WaitAsync<T>(\n TimeSpan timeout,\n Func<Task<Result<T>>> func)\n {\n using var timer = new PeriodicTimer(TimeSpan.FromSeconds(1));\n\n DateTime endTimeUtc = DateTime.UtcNow.Add(timeout);\n while (DateTime.UtcNow < endTimeUtc &&\n await timer.WaitForNextTickAsync())\n {\n Result<T> result = await func();\n\n if (result.IsSuccess)\n {\n return result;\n }\n }\n\n return Result.Failure<T>(Timeout);\n }\n}\nHere's a more complex scenario testing adding a ticket to the customer's cart:
\nThis scenario mimics a user registering with our system, finding a ticket they want to purchase, and adding it to their cart.\nWe can extend this scenario with more test cases, like ticket purchases.
\npublic sealed class AddItemToCartTests : BaseIntegrationTest\n{\n private const decimal Quantity = 10;\n\n public AddItemToCartTests(IntegrationTestWebAppFactory factory)\n : base(factory)\n {\n }\n\n [Fact]\n public async Task Customer_ShouldBeAbleTo_AddItemToCart()\n {\n // [Users Module] - Register user\n var command = new RegisterUserCommand(\n Faker.Internet.Email(),\n Faker.Internet.Password(6),\n Faker.Name.FirstName(),\n Faker.Name.LastName());\n\n Result<Guid> userResult = await Sender.Send(command);\n\n userResult.IsSuccess.Should().BeTrue();\n\n // [Ticketing Module] - Get customer\n Result<CustomerResponse> customerResult = await Poller.WaitAsync(\n TimeSpan.FromSeconds(15),\n async () =>\n {\n var query = new GetCustomerQuery(userResult.Value);\n var customerResult = await Sender.Send(query);\n return customerResult;\n });\n\n customerResult.IsSuccess.Should().BeTrue();\n\n // [Ticketing Module] - Add item to cart\n CustomerResponse customer = customerResult.Value;\n var ticketTypeId = Guid.NewGuid();\n\n await Sender.CreateEventAsync(Guid.NewGuid(), ticketTypeId, Quantity);\n\n Result result = await Sender.Send(\n new AddItemToCartCommand(customer.Id, ticketTypeId, Quantity));\n\n // Assert\n result.IsSuccess.Should().BeTrue();\n }\n}\nWhat I like about system integration testing is that the test cases aren't complicated to write.\nThe tests execute the use cases of our system and verify the side effects.\nBuilding your system around use cases has a few advantages,\nthe main one being that you can focus on the core business logic.\nBut it also makes (integration) testing easier.\nThe use case runs by sending a command or a query.\nWe can execute the use cases in some logical order and check that we get the expected result.
\nSystem integration testing is a crucial step in creating a successful modular monolith.\nBy testing how different modules work together, you can find and fix problems before they become bigger issues.\nThis makes your software more reliable and saves you time and resources in the long run.
\nIf you want to dive deeper into building modular systems, check out Modular Monolith Architecture.\nThere's an entire chapter dedicated to testing,\nincluding advanced techniques like system integration testing, using Testcontainers for external services, and automated testing with CI/CD pipelines.
\nThat's all for today.
\nSee you next week.
\nIn Clean Architecture, a use case lives in the Application layer and orchestrates the flow of data to and from domain entities.\nAny external system it needs, like a database or password hasher, is abstracted behind an interface and injected as a dependency.\nThe guiding rule is the Dependency Rule: source code dependencies can only point inward.
\nThis is a question I often hear: how do I design my use case with Clean Architecture?
\nI understand the confusion.\nFiguring out what to place in the Domain, Application, and Infrastructure layer can seem complicated.\nIf that's not enough, we also have to decide what makes up a use case and what should be abstracted away.
\nHowever, things become simpler if we adhere to the main rule in Clean Architecture — the Dependency Rule.\nThis rule states that source code dependencies can only point inwards.
\nIn this newsletter, we'll explore a practical example of how to apply Clean Architecture principles by building a user registration feature.
\nClean Architecture has emerged as a guiding principle for crafting maintainable, scalable, and testable applications.\nAt its core, Clean Architecture emphasizes the separation of concerns and the dependency rule.\nThe dependency rule dictates that dependencies should point inward toward higher-level modules.\nBy following this rule, you create a system where the core business logic of your application is decoupled from external dependencies.\nThis makes it more adaptable to changes and easier to test.
\n![\"Clean](\"https://milanjovanovic.tech/blogs/mnw_098/clean_architecture.png\")
\nThe Domain layer encapsulates enterprise-wide business rules.\nIt contains domain entities, where an entity is typically an object with methods.
\nThe Application layer contains application-specific business rules and encapsulates all of the system's use cases.\nA use case orchestrates the flow of data to and from the domain entities and calls the methods exposed by the entities\nto achieve its goals.
\nThe Infrastructure and Presentation layers deal with external concerns.\nHere, you will implement any abstractions defined in the inner layers.
\nWhat does it mean for a user to register with our application?\nIt means they reserve an email address (or username) to identify themselves and be able to interact with our system.\nThe user could provide other information, such as a first and last name, an address, and a phone number.
\nThe first step in building any feature is clearly defining the desired result.
\nFor user registration, this is what the required operations are:
\nWe could also consider any domain-specific rules or validations that we must enforce.\nA good example is password strength, where we could implement minimum length and complexity requirements.
\nNow that we have our requirements let's see how to translate them into a use case.
\nWith our requirements in place, we can now define the user registration use case.\nIn Clean Architecture, use cases live in the Application layer and orchestrate the interactions between domain entities and external dependencies.
\nLet's name our use case RegisterUser.\nIts input will be a RegistrationRequest object containing the user's registration data,\nand its output will be a RegistrationResult object indicating the outcome of the registration attempt.\nNotice that we are using a feature-driven name for the use case.
What about any external dependencies?\nIf the use case needs to interact with an external system or infrastructure component, we abstract that behind an interface.\nRemember, your application's core business logic should be decoupled from external dependencies.
\nThe RegisterUser class will use dependency injection to get the necessary dependencies:
IUserRepository: An interface for accessing user data from the database.IPasswordHasher: An interface for hashing passwords securely.The RegisterUser use case will follow these steps:
UserUser entityUser to the databaseFinally, here's the code for our RegisterUser use case:
public class RegisterUser(\n IUserRepository userRepository,\n IPasswordHasher passwordHasher)\n{\n public async Task<RegistrationResult> Handle(RegistrationRequest request)\n {\n // Validation omitted for brevity\n\n if (await userRepository.ExistsAsync(request.Email))\n {\n return RegistrationResult.EmailNotUnique;\n }\n\n var passwordHash = passwordHasher.Hash(request.Password);\n\n var user = User.Create(\n request.FirstName, request.LastName, request.Email, passwordHash);\n\n await userRepository.InsertAsync(user);\n\n return RegistrationResult.Success;\n }\n}\nA big benefit of this approach is that we can immediately write tests for the RegisterUser use case.\nWe can provide mocks for external dependencies in the tests.\nWe don't need the implementations to exist for this code to compile.\nWith mocks, we can test our business rules and validate our implementation.
Action step: How would you extend the RegisterUser use case with more functionality?
Here are two examples:
\nBy designing our application with Clean Architecture, we produce a system independent of external concerns.\nWe define abstractions in the Application layer and implement them in the Infrastructure layer.\nSo far, so good.
\nHowever, this doesn't mean you can disregard how you integrate with external dependencies.
\nIn theory, we should be able to "swap" the implementation for any external concern and call it a day.\nIn practice, this couldn't be further from the truth.
\nLet me give you two practical examples using the user registration flow.
\nThe RegisterUser use case has a race condition.\nConcurrent requests could pass the check for email uniqueness and proceed to register the user.
We could prevent this race condition by introducing a lock before checking for email uniqueness.\nThat way, only one request will pass the check and proceed to save the user in the database.
\nif (await userRepository.ExistsAsync(request.Email))\n{\n return RegistrationResult.EmailNotUnique;\n}\nHowever, there is a much more elegant way to solve this.\nWe can introduce a unique index on the Email column in the database.\nA unique index guarantees that only one transaction can write the unique value to the database.\nThe losing transaction will return an error.
We can handle this exception on the application side and return an appropriate error message to the user.\nThe IUserRepository.InsertAsync method implementation can encapsulate this logic.
Let's say we found a security flaw in the hash function used in the IPasswordHasher implementation.\nSo, we spend a few minutes switching to a more secure hash function.\nThe tests for the RegisterUser use case are all green, and everything seems fine.
The problem? All existing users can no longer log in to the system.
\nWhen an existing user tries to log in with their email and password, the new IPasswordHasher.Hash implementation\nreturns a different password hash from the one stored in the database.
The correct approach is to phase out the old password hash for existing users.\nWe can add a column in the database that says which hash function produced the hash.\nWe will verify the user's password using the correct hashing function during the login process.
\nIf the user's password hash still uses the old hashing function, we will verify their password first.\nThen, we can use the password (which we have in memory) to produce a hash using the new hash function.\nWe will store the hash in the database and update the hash function column to the new algorithm.
\nSlowly, we will phase out passwords using the old hash function.
\nI hope this was helpful in understanding how to apply Clean Architecture principles to a real-world scenario.\nBy focusing on the core business logic first (what it means for a user to register), we can define the requirements for our use case.\nTranslating these requirements into a series of steps within the use case is the easy part.
\nBut Clean Architecture won't save you from bad engineering.\nIf you don't understand what you are abstracting away, it will become a problem in the long term.
\nIf you want to go deeper, my flagship course, Pragmatic Clean Architecture,\ntakes the guesswork out of structuring your project the right way.\nI share my entire framework for building robust applications from the ground up -\nfrom building a rich domain model to creating use cases to getting your application ready for production.
\nAnd that's all for this week.
\nSee you next Saturday.
\nService discovery is a pattern that lets services refer to each other by logical names instead of physical IP addresses and ports.\nServices register themselves in a central registry, and clients query the registry to resolve the physical address before sending a request.\nIn .NET, you can implement it with a Consul server and the Steeltoe Discovery library.
\nMicroservices have revolutionized how we build and scale applications.\nBy breaking down larger systems into smaller, independent services, we gain flexibility, agility, and the ability to adapt to changing requirements quickly.\nHowever, microservices systems are also very dynamic.\nServices can come and go, scale up or down, and even move around within your infrastructure.
\nThis dynamic nature presents a significant challenge. How do your services find and communicate with each other reliably?
\nHardcoding IP addresses and ports is a recipe for fragility.\nIf a service instance changes location or a new instance spins up, your entire system could grind to a halt.
\nService discovery acts as a central directory for your microservices.\nIt provides a mechanism for services to register themselves and discover the locations of other services.
\nIn this week's issue, we'll see how to implement service discovery in your .NET microservices with Consul.
\nService discovery is a pattern that allows developers to use logical names to refer to external services instead of physical IP addresses and ports.\nIt provides a centralized location for services to register themselves.\nClients can query the service registry to find out the service's physical address.\nThis is a common pattern in large-scale distributed systems, such as Netflix and Amazon.
\nHere's what the service discovery flow looks like:
\n![\"Service](\"https://milanjovanovic.tech/blogs/mnw_097/service_discovery_flow.png\")
\nThe same concept applies when we have multiple services we want to call.\nEach service would register itself with the service registry.\nThe client uses a logical name to reference a service and resolves the physical address from the service registry.
\n![\"Service](\"https://milanjovanovic.tech/blogs/mnw_097/service_discovery_microservices.png\")
\nThe most popular solutions for service discovery are Netflix Eureka and HashiCorp Consul.
\nThere is also a lightweight solution from Microsoft in the Microsoft.Extensions.ServiceDiscovery library.\nIt uses application settings to resolve the physical addresses for services, so some manual work is still required.\nHowever, you can store service locations in Azure App Configuration for a centralized service registry.\nI will explore this service discovery library in some future articles.
But now I want to show you how to integrate Consul with .NET applications.
\nThe simplest way to run the Consul server locally is using a Docker container.\nYou can create a container instance of the hashicorp/consul image.
Here's an example of configuring the Consul service as part of the docker-compose file:
consul:\n image: hashicorp/consul:latest\n container_name: Consul\n ports:\n - '8500:8500'\nIf you navigate to localhost:8500, you will be greeted by the Consul Dashboard.
![\"Consul](\"https://milanjovanovic.tech/blogs/mnw_097/consul_dashboard.png\")
\nNow, let's see how to register our services with Consul.
\nWe'll use the Steeltoe Discovery library to implement service discovery with Consul.\nThe Consul client implementation lets your applications register services with a Consul server and discover services registered by other applications.
\nLet's install the Steeltoe.Discovery.Consul library:
Install-Package Steeltoe.Discovery.Consul\nWe have to configure some services by calling AddServiceDiscovery and explicitly configuring the Consul service discovery client.\nThe alternative is calling AddDiscoveryClient which uses reflection at runtime to determine which service registry is available.
using Steeltoe.Discovery.Client;\nusing Steeltoe.Discovery.Consul;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddServiceDiscovery(o => o.UseConsul());\n\nvar app = builder.Build();\n\napp.Run();\nFinally, our service can register with Consul by configuring the logical service name through application settings.\nWhen the application starts, the reporting-service logical name will be added to the Consul service registry.\nConsul will store the respective physical address of this service.
{\n "Consul": {\n "Host": "localhost",\n "Port": 8500,\n "Discovery": {\n "ServiceName": "reporting-service",\n "Hostname": "reporting-api",\n "Port": 8080\n }\n }\n}\nWhen we start the application and open the Consul dashboard, we should be able to see the reporting-service and its respective physical address.
![\"Consul](\"https://milanjovanovic.tech/blogs/mnw_097/consul_dashboard_with_service.png\")
\nWe can use service discovery when making HTTP calls with an HttpClient.\nService discovery allows us to use a logical name for the service we want to call.\nWhen sending a network request, the service discovery client will replace the logical name with a correct physical address.
In this example, we're configuring the base address of the ReportingServiceClient typed client to http://reporting-service\nand adding service discovery by calling AddServiceDiscovery.
Load balancing is an optional step, and we can configure it by calling AddRoundRobinLoadBalancer or AddRandomLoadBalancer.\nYou can also configure a custom load balancing strategy by providing an ILoadBalancer implementation.
builder.Services\n .AddHttpClient<ReportingServiceClient>(client =>\n {\n client.BaseAddress = new Uri("http://reporting-service");\n })\n .AddServiceDiscovery()\n .AddRoundRobinLoadBalancer();\nWe can use the ReportingServiceClient typed client like a regular HttpClient to make requests.\nThe service discovery client sends the request to the external service's IP address.
app.MapGet("articles/{id}/report",\n async (Guid id, ReportingServiceClient client) =>\n {\n var response = await client\n .GetFromJsonAsync<Response>($"api/reports/article/{id}");\n\n return response;\n });\nService discovery simplifies the management of microservices by automating service registration and discovery.\nThis eliminates the need for manual configuration updates, reducing the risk of errors.
\nServices can discover each other's locations on demand, ensuring that communication channels remain open even as the service landscape evolves.\nBy enabling services to discover alternative service instances in case of outages or failures, service discovery enhances the overall resilience of the microservices system.
\nMastering service discovery gives you a powerful tool to build modern distributed applications.
\nYou can grab the source code for this example here.
\nThanks for reading, and I'll see you next week!
\nTo generate PDF reports in .NET, build the report template as a Razor view, render it to an HTML string, and convert that HTML into a PDF with an HTML-to-PDF library.\nYou get full control over formatting and can style the document with modern CSS.
\nI'll never forget when I was working on a project that required generating weekly sales reports for a client.\nThe initial solution involved a clunky process of exporting data, manipulating it in spreadsheets, and manually creating PDFs.\nIt was tedious, error-prone, and it sucked up way too much of my time.\nI knew there had to be a better way.
\nThat's when I discovered the power of combining Razor views with HTML-to-PDF conversion.\nYou have more control over formatting the document.\nYou can use modern CSS to style the HTML markup, which will be applied when exporting to a PDF document.\nIt's also simple to implement in ASP.NET Core.
\nHere's what we'll cover:
\nLet's dive in!
\nRazor views\nare an HTML template with embedded Razor markup.\nRazor allows you to write and execute .NET code inside a web page.\nViews have a special .cshtml file extension.\nThey're commonly used in ASP.NET Core MVC,\nRazor Pages,\nand Blazor.
However, you can define Razor views in a class library or ASP.NET Core Web API project.
\nYou can use the Model object to pass in data to a Razor view.\nInside the .cshtml file, you'll specify the model type with the @model keyword.\nIn the example below, I'm specifying that the Invoice class is the model for this view.\nYou can access the model instance with the Model property in the view.
This is the InvoiceReport.cshtml view we'll use to generate a PDF invoice.
You can write CSS in the Razor view inline or reference a stylesheet.\nI'm using the Tailwind CSS utility framework, which uses inline CSS.\nI usually delegate this to a front-end engineer on my team so they can stylize the report as needed.
\n@using System.Globalization\n@using HtmlToPdf.Contracts\n\n@model HtmlToPdf.Contracts.Invoice\n\n@{\n IFormatProvider cultureInfo = CultureInfo.CreateSpecificCulture("en-US");\n var subtotal = Model.LineItems.Sum(li => li.Price * li.Quantity).ToString("C", cultureInfo);\n var total = Model.LineItems.Sum(li => li.Price * li.Quantity).ToString("C", cultureInfo);\n}\n\n<script src="https://cdn.tailwindcss.com"></script>\n\n<div class="min-w-7xl flex flex-col bg-gray-200 space-y-4 p-10">\n <h1 class="text-2xl font-semibold">Invoice #@Model.Number</h1>\n\n <p>Issued date: @Model.IssuedDate.ToString("dd/MM/yyyy")</p>\n <p>Due date: @Model.DueDate.ToString("dd/MM/yyyy")</p>\n\n <div class="flex justify-between space-x-4">\n <div class="bg-gray-100 rounded-lg flex flex-col space-y-1 p-4 w-1/2">\n <p class="font-medium">Seller:</p>\n <p>@Model.SellerAddress.CompanyName</p>\n <p>@Model.SellerAddress.Street</p>\n <p>@Model.SellerAddress.City</p>\n <p>@Model.SellerAddress.State</p>\n <p>@Model.SellerAddress.Email</p>\n </div>\n <div class="bg-gray-100 rounded-lg flex flex-col space-y-1 p-4 w-1/2">\n <p class="font-medium">Bill to:</p>\n <p>@Model.CustomerAddress.CompanyName</p>\n <p>@Model.CustomerAddress.Street</p>\n <p>@Model.CustomerAddress.City</p>\n <p>@Model.CustomerAddress.State</p>\n <p>@Model.CustomerAddress.Email</p>\n </div>\n </div>\n\n <div class="flex flex-col bg-white rounded-lg p-4 space-y-2">\n <h2 class="text-xl font-medium">Items:</h2>\n <div class="">\n <div class="flex space-x-4 font-medium">\n <p class="w-10">#</p>\n <p class="w-52">Name</p>\n <p class="w-20">Price</p>\n <p class="w-20">Quantity</p>\n </div>\n\n @foreach ((int index, LineItem item) in Model.LineItems.Select((li, i) => (i + 1, li)))\n {\n <div class="flex space-x-4">\n <p class="w-10">@index</p>\n <p class="w-52">@item.Name</p>\n <p class="w-20">@item.Price.ToString("C", cultureInfo)</p>\n <p class="w-20">@item.Quantity.ToString("N2")</p>\n </div>\n }\n </div>\n </div>\n\n <div class="flex flex-col items-end bg-gray-50 space-y-2 p-4 rounded-lg">\n <p>Subtotal: @subtotal</p>\n <p>Total: <span class="font-semibold">@total</span></p>\n </div>\n</div>\nThe next thing we'll need is a way to convert the Razor view into HTML.\nWe can do this with the Razor.Templating.Core library.\nIt provides a simple API to render a .cshtml file into a string.
Install-Package Razor.Templating.Core\nYou can use the RazorTemplateEngine static class to call the RenderAsync method.\nIt accepts the path to the Razor view and the model instance that will be passed to the view.
Here's what that will look like:
\nInvoice invoice = invoiceFactory.Create();\n\nstring html = await RazorTemplateEngine.RenderAsync(\n "Views/InvoiceReport.cshtml",\n invoice);\nAlternatively, you can use the IRazorTemplateEngine instead of the static class.\nIn that case, you must call AddRazorTemplating to register the required services with DI.\nThis is also required if you want to use dependency injection inside the Razor views with @inject.\nIt's recommended that you call AddRazorTemplating after registering all dependencies.
services.AddRazorTemplating();\nNow that we've converted our Razor view into HTML, we can use it to generate a PDF report.\nMany libraries offer this functionality.\nThe library I've used most often is IronPDF.\nIt's a paid library (and well worth it), but I know developers also want free options, so I'll list some alternatives at the end.
\nWe can use IronPDF's ChromePdfRenderer, which uses an embedded Chrome browser.\nThe renderer exposes the RenderHtmlAsPdf method, which generates a PdfDocument.\nOnce you have the document, you can store it on the file system or export it as binary data.
var renderer = new ChromePdfRenderer();\n\nusing var pdfDocument = renderer.RenderHtmlAsPdf(html);\n\npdfDocument.SaveAs($"invoice-{invoice.Number}.pdf");\nIf you're looking for free options, check out Puppeteer Sharp.\nIt's a .NET port of the Puppeteer library, which allows you to run a headless Chrome browser.
\nAnother (conditionally) free option to consider is NReco.PdfGenerator.\nHowever, it's only free for single-server deployments.
\nLet's use everything we discussed to create a Minimal API endpoint to generate an invoice PDF report and return it as a file response.\nHere's the code snippet:
\napp.MapGet("invoice-report", async (InvoiceFactory invoiceFactory) =>\n{\n Invoice invoice = invoiceFactory.Create();\n\n var html = await RazorTemplateEngine.RenderAsync(\n "Views/InvoiceReport.cshtml",\n invoice);\n\n var renderer = new ChromePdfRenderer();\n\n using var pdfDocument = renderer.RenderHtmlAsPdf(html);\n\n return Results.File(\n pdfDocument.BinaryData,\n "application/pdf",\n $"invoice-{invoice.Number}.pdf");\n});\nThis is what the generated PDF report looks like:
\n![\"Invoice](\"https://milanjovanovic.tech/blogs/mnw_096/invoice.png\")
\nYou can grab the source code for this sample here.\nFeel free to try out a different library for HTML to PDF conversion.
\nIn this article, we've explored the power of using Razor views for flexible PDF reporting in .NET.\nWe've seen how to create report templates with Razor views, convert them to HTML, and then transform that HTML into beautifully formatted PDF documents.
\nWhether you need to generate invoices, sales reports, or any other kind of structured document, this approach offers a simple and customizable solution.
\nHere's what you can explore next:
\n\nThat's all for this week. Stay awesome!
\nEF Core 7 introduced ExecuteUpdate and ExecuteDelete, which translate a bulk operation directly into a single SQL UPDATE or DELETE statement.\nThat gives them significant performance advantages over loading entities and calling SaveChanges.\nThe important caveat is that they bypass the EF Core Change Tracker, so entities already loaded in memory keep their old values.
When you're dealing with thousands or even millions of records, efficiency is king.\nThat's where EF Core bulk update capabilities come into play.
\nEF Core 7 introduced two powerful new methods, ExecuteUpdate and ExecuteDelete.\nThey're designed to simplify bulk updates in your database.\nBoth methods have their respective async overloads - ExecuteUpdateAsync and ExecuteDeleteAsync.\nEF bulk updates offer significant performance advantages over traditional approaches.
However, there's an important caveat: these bulk operations bypass the EF Core Change Tracker.\nThis disconnect can lead to unexpected behavior if you're not aware of it.
\nIn this week's issue, we'll dive into the details of bulk updates in EF Core.
\nWhen you load entities from the database with EF Core, the ChangeTracker starts tracking them.\nAs you update properties, delete entities, or add new ones, the ChangeTracker records these changes.
using (var context = new AppDbContext())\n{\n // Load a product\n var product = context.Products.FirstOrDefault(p => p.Id == 1);\n product.Price = 99.99; // Modify a property\n\n // At this point, the ChangeTracker knows that 'product' has been modified\n\n // Add a new product\n var newProduct = new Product { Name = "New Gadget", Price = 129.99 };\n context.Products.Add(newProduct);\n\n // Delete a product\n context.Products.Remove(product);\n\n context.SaveChanges(); // Persist all changes to the database\n}\nWhen you call SaveChanges, EF Core uses the ChangeTracker to determine which SQL commands to execute.\nThis ensures that the database is perfectly synchronized with your modifications.\nThe ChangeTracker acts as a bridge between your in-memory object model and your database.
If you're already familiar with how EF Core works, this serves mostly as a reminder.
\nNow, let's focus on how bulk updates in EF Core\ninteract with the ChangeTracker - or rather, how they don't interact with it.\nThis design decision might seem counterintuitive, but there's a solid reason behind it: performance.
By directly executing SQL statements against the database, EF Core eliminates the overhead of tracking individual entity modifications.
\nusing (var context = new AppDbContext())\n{\n // Increase price of all electronics by 10%\n context.Products\n .Where(p => p.Category == "Electronics")\n .ExecuteUpdate(\n s => s.SetProperty(p => p.Price, p => p.Price * 1.10));\n\n // In-memory Product instances with Category == "Electronics"\n // will STILL have their old price\n}\nIn this example, we're increasing the price of all products in the Electronics category by 10%.\nThe ExecuteUpdate method efficiently translates the operation into a single SQL UPDATE statement.
UPDATE [p]\nSET [p].[Price] = [p].[Price] * 1.10\nFROM [Products] as [p];\nHowever, if you inspect the Product instances that EF Core has already loaded into memory, you'll find that their Price properties haven't changed.\nThis might seem surprising if you aren't aware of how bulk updates interact with the change tracker.
Everything we discussed up to this point also applies to the ExecuteDelete method.
EF Core interceptors do not trigger for ExecuteUpdate and ExecuteDelete operations.\nIf you need to track or modify bulk update operations, you can create database triggers that fire whenever a relevant table is updated or deleted.\nThis allows you to log details and perform additional actions.
If ExecuteUpdate completes successfully, the changes are directly committed to the database.\nThis is because bulk operations bypass the ChangeTracker and don't participate in the usual transaction managed by SaveChanges.
If SaveChanges subsequently fails due to an error (e.g., validation error, database constraint violation, connection issue),\nyou'll be in an inconsistent state.\nThe changes made by ExecuteUpdate are already persisted.\nAny changes made "in memory" are lost.
The most reliable way to ensure consistency is to wrap both ExecuteUpdate and the operations that lead to SaveChanges in a transaction:
using (var context = new AppDbContext())\nusing (var transaction = context.Database.BeginTransaction())\n{\n try\n {\n context.Products\n .Where(p => p.Category == "Electronics")\n .ExecuteUpdate(\n s => s.SetProperty(p => p.Price, p => p.Price * 1.10));\n\n // ... other operations that modify entities\n\n context.SaveChanges();\n\n transaction.Commit();\n }\n catch (Exception ex)\n {\n // You could also let the transaction go out of scope.\n // This would automatically rollback any changes.\n transaction.Rollback();\n\n // Proceed to handle the exception...\n }\n}\nIf SaveChanges fails, the transaction will be rolled back, reverting the changes made by both ExecuteUpdate and any other operations within the transaction.\nThis keeps your database in a consistent state.
EF Core bulk update features, ExecuteUpdate and ExecuteDelete, are invaluable tools for optimizing performance.\nBy bypassing the ChangeTracker and executing raw SQL directly, they deliver significant speed improvements compared to traditional methods.
However, it's crucial to be mindful of the potential pitfalls associated with this approach.\nThe disconnect between in-memory entities and the database state can lead to unexpected results if not handled correctly.
\nMy rule of thumb is to create an explicit database transaction when I want to make additional entity changes.\nWe can be confident that all the changes will persist in the database or none of them will.
\nI hope this was helpful, and I'll see you next week.
\nP.S. Get the source code and try out the examples from this issue.
\nA Transaction Script organizes business logic by procedures, where each procedure handles a single request from the presentation layer.\nIt's a simple and effective approach early on, but as business rules accumulate and similar logic gets duplicated across scripts, the code becomes difficult to maintain.\nThe fix is to push the domain logic down into a Domain Model, an object model of the domain that incorporates both behavior and data.
\nI once led the development of a fitness tracking app.\nWe started with Transaction Scripts to handle features like workout creation and exercise logging.\nIt was a simple and effective approach for the app's early stages.
\nHowever, as we added more complex features, our business logic became bloated.\nNew business rules intertwined with existing logic, making the code difficult to maintain.\nEach change could introduce unintended consequences.
\nWe solved our problem by introducing a Domain Model.\nThe domain model shifts the focus from procedures to domain objects.\nOur code became more expressive, easier to reason about, and less prone to errors.
\nThis experience taught me a valuable lesson, that I want to share in this newsletter.
\nAt its core, business applications operate through distinct interactions (transactions) with their users.\nThese transactions can range from simple data retrieval to complex operations involving multiple validations, calculations, and updates to the system's database.
\nThe Transaction Script pattern provides a simple way to encapsulate the logic behind each transaction.\nIt organizes all the necessary steps, from data access to business rules, into a single, self-contained procedure.
\n\n\nOrganizes business logic by procedures where each procedure handles a single request from the presentation.
\n
— Transaction Script, Patterns of Enterprise Application Architecture
\nHere's an example of adding exercises to a workout:
\ninternal sealed class AddExercisesCommandHandler(\n IWorkoutRepository workoutRepository,\n IUnitOfWork unitOfWork)\n : ICommandHandler<AddExercisesCommand>\n{\n public async Task<Result> Handle(\n AddExercisesCommand request,\n CancellationToken cancellationToken)\n {\n Workout? workout = await workoutRepository.GetByIdAsync(\n request.WorkoutId,\n cancellationToken);\n\n if (workout is null)\n {\n return Result.Failure(WorkoutErrors.NotFound(request.WorkoutId));\n }\n\n List<Error> errors = [];\n foreach (ExerciseRequest exerciseDto in request.Exercises)\n {\n if (exerciseDto.TargetType == TargetType.Distance &&\n exerciseDto.DistanceInMeters is null)\n {\n errors.Add(ExerciseErrors.MissingDistance);\n\n continue;\n }\n\n if (exerciseDto.TargetType == TargetType.Time &&\n exerciseDto.DurationInSeconds is null)\n {\n errors.Add(ExerciseErrors.MissingDuration);\n\n continue;\n }\n\n var exercise = new Exercise(\n Guid.NewGuid(),\n workout.Id,\n exerciseDto.ExerciseType,\n exerciseDto.TargetType,\n exerciseDto.DistanceInMeters,\n exerciseDto.DurationInSeconds);\n\n workouts.Exercises.Add(exercise);\n }\n\n if (errors.Count != 0)\n {\n return Result.Failure(new ValidationError(errors.ToArray()));\n }\n\n await unitOfWork.SaveChangesAsync(cancellationToken);\n\n return Result.Success();\n }\n}\nThere isn't much logic here. We're just checking whether the workout exists and whether the exercises are valid.
\nWhat happens when we start to add more logic?
\nLet's add another business rule.\nWe must enforce a limit on the number of exercises allowed in a single workout (e.g., no more than 10 exercises).
\ninternal sealed class AddExercisesCommandHandler(\n IWorkoutRepository workoutRepository,\n IUnitOfWork unitOfWork)\n : ICommandHandler<AddExercisesCommand>\n{\n public async Task<Result> Handle(\n AddExercisesCommand request,\n CancellationToken cancellationToken)\n {\n Workout? workout = await workoutRepository.GetByIdAsync(\n request.WorkoutId,\n cancellationToken);\n\n if (workout is null)\n {\n return Result.Failure(WorkoutErrors.NotFound(request.WorkoutId));\n }\n\n List<Error> errors = [];\n foreach (ExerciseRequest exerciseDto in request.Exercises)\n {\n if (exerciseDto.TargetType == TargetType.Distance &&\n exerciseDto.DistanceInMeters is null)\n {\n errors.Add(ExerciseErrors.MissingDistance);\n\n continue;\n }\n\n if (exerciseDto.TargetType == TargetType.Time &&\n exerciseDto.DurationInSeconds is null)\n {\n errors.Add(ExerciseErrors.MissingDuration);\n\n continue;\n }\n\n var exercise = new Exercise(\n Guid.NewGuid(),\n workout.Id,\n exerciseDto.ExerciseType,\n exerciseDto.TargetType,\n exerciseDto.DistanceInMeters,\n exerciseDto.DurationInSeconds);\n\n workouts.Exercises.Add(exercise);\n\n if (workouts.Exercise.Count > 10)\n {\n return Result.Failure(\n WorkoutErrors.MaxExercisesReached(workout.Id));\n }\n }\n\n if (errors.Count != 0)\n {\n return Result.Failure(new ValidationError(errors.ToArray()));\n }\n\n await unitOfWork.SaveChangesAsync(cancellationToken);\n\n return Result.Success();\n }\n}\nWe can continue adding more business logic to the transaction script.\nFor example, we can introduce exercise type restrictions or enforce a specific exercise order.\nYou can imagine how the complexity will keep increasing over time.
\nAnother concern is code duplication between transaction scripts.\nThis could happen if we need similar logic in multiple transaction scripts.\nYou may be tempted to solve this by calling one transaction script from the other, but this will introduce a different set of problems.
\nSo, how can we solve these problems?
\nWhat is a domain model?
\n\n\nAn object model of the domain that incorporates both behavior and data.
\n
— Domain Model, Patterns of Enterprise Application Architecture
\nA domain model lets you encapsulate domain logic (behavior) and state changes (data) inside an object.\nIn Domain-Driven Design terminology, we would call this an aggregate.
\nAn aggregate in DDD is a cluster of objects treated as a single unit for data changes.\nThe aggregate represents a consistency boundary.\nIt helps maintain consistency by ensuring that certain invariants always hold true for the entire aggregate.\nIn our workout example, the Workout class can be treated as an aggregate root that encompasses all the exercises within it.
What does this have to do with a transaction script?
\nWe can move the domain logic and state changes from the transaction script into the aggregate.\nThis is often called "pushing logic down" into the domain.
\nHere's what the domain model will look like when we extract the domain logic:
\npublic sealed class Workout\n{\n private readonly List<Exercise> _exercises = [];\n\n // Omitting the constructor and other propreties for brevity.\n\n public Result AddExercises(ExerciseModel[] exercises)\n {\n List<Error> errors = [];\n foreach (var exerciseModel in exercises)\n {\n if (exerciseModel.TargetType == TargetType.Distance &&\n exerciseModel.DistanceInMeters is null)\n {\n errors.Add(ExerciseErrors.MissingDistance);\n\n continue;\n }\n\n if (exerciseModel.TargetType == TargetType.Time &&\n exerciseModel.DurationInSeconds is null)\n {\n errors.Add(ExerciseErrors.MissingDuration);\n\n continue;\n }\n\n var exercise = new Exercise(\n Guid.NewGuid(),\n workout.Id,\n exerciseDto.ExerciseType,\n exerciseDto.TargetType,\n exerciseDto.DistanceInMeters,\n exerciseDto.DurationInSeconds);\n\n workouts.Exercises.Add(exercise);\n\n if (workouts.Exercise.Count > 10)\n {\n return Result.Failure(\n WorkoutErrors.MaxExercisesReached(workout.Id));\n }\n }\n\n if (errors.Count != 0)\n {\n return Result.Failure(new ValidationError(errors.ToArray()));\n }\n\n return Result.Success();\n }\n}\nWith the domain logic inside of the domain model, we can easily share it between transaction scripts.\nTesting the domain model is simpler than testing the transaction script.\nWith a transaction script, we must provide any dependencies (possibly as mocks) for testing.\nHowever, we can test the domain model in isolation.
\nThe updated transaction script becomes much more straightforward and focused on its primary task:
\ninternal sealed class AddExercisesCommandHandler(\n IWorkoutRepository workoutRepository,\n IUnitOfWork unitOfWork)\n : ICommandHandler<AddExercisesCommand>\n{\n public async Task<Result> Handle(\n AddExercisesCommand request,\n CancellationToken cancellationToken)\n {\n Workout? workout = await workoutRepository.GetByIdAsync(\n request.WorkoutId,\n cancellationToken);\n\n if (workout is null)\n {\n return Result.Failure(WorkoutErrors.NotFound(request.WorkoutId));\n }\n\n var exercises = request.Exercises.Select(e => e.ToModel()).ToArray();\n\n var result = workout.AddExercises(exercises);\n\n if (result.IsFailure)\n {\n return result;\n }\n\n await unitOfWork.SaveChangesAsync(cancellationToken);\n\n return Result.Success();\n }\n}\nTransaction Scripts are a practical starting point for simple applications.\nThey offer a straightforward approach to implementing use cases.\nTransaction scripts are the recommended approach to start building vertical slices.\nHowever, transaction scripts can become difficult to maintain as the application grows.
\nRefactoring toward a Domain Model allows you to encapsulate business logic in domain objects.\nThis promotes code reusability and makes your application more adaptable to changes.\nPushing logic down also improves testability and maintainability.
\nShould you use a Transaction Script or a Domain Model?
\nHere's a pragmatic approach you should consider.\nStart with a transaction script, but pay attention to growing complexity.\nWhen you notice a transaction script has too many concerns, consider adding a domain model.\nRemember, the domain model should encapsulate some of the complexity of the domain logic.
\nThanks for reading, and I'll see you next week!
\nCaching temporarily stores the results of expensive operations in a faster access location, so subsequent requests are served from the cache instead of the source.\nASP.NET Core gives you two primary abstractions for this: IMemoryCache for in-memory caching and IDistributedCache for distributed caches like Redis.\nThe most common strategy is the cache-aside pattern: check the cache first, and on a miss fetch the data from the source and store it for the next request.
Caching is one of the simplest techniques to significantly improve your application's performance.\nIt's the process of temporarily storing data in a faster access location.\nYou will typically cache the results of expensive operations or frequently accessed data.
\nCaching allows subsequent requests for the same data to be served from the cache instead of fetching the data from its source.
\nASP.NET Core offers several types of caches, such as IMemoryCache, IDistributedCache, and the upcoming HybridCache (.NET 9).
In this newsletter, we will explore how to implement caching in ASP.NET Core applications.
\nCaching improves your application's performance by reducing latency and server load while enhancing scalability and user experience.
\nIn a recent project I worked on, we used Redis to scale to more than 1,000,000 users.\nWe only had one SQL Server instance with a read-replica for reporting.\nThe power of caching, eh?
\nASP.NET Core provides two primary abstractions for working with caches:
\nIMemoryCache: Stores data in the memory of the web server.\nSimple to use but not suitable for distributed scenarios.IDistributedCache: Offers a more robust solution for distributed applications.\nIt allows you to store cached data in a distributed cache like Redis.We have to register these services with DI to use them.\nAddDistributedMemoryCache will configure the in-memory implementation of IDistributedCache, which isn't distributed.
builder.Services.AddMemoryCache();\n\nbuilder.Services.AddDistributedMemoryCache();\nHere's how you can use the IMemoryCache.\nWe will first check if the cached value is present and return it directly if it's there.\nOtherwise, we must fetch the value from the database and cache it for subsequent requests.
app.MapGet(\n "products/{id}",\n (int id, IMemoryCache cache, AppDbContext context) =>\n {\n if (!cache.TryGetValue(id, out Product product))\n {\n product = context.Products.Find(id);\n\n var cacheEntryOptions = new MemoryCacheEntryOptions()\n .SetAbsoluteExpiration(TimeSpan.FromMinutes(10))\n .SetSlidingExpiration(TimeSpan.FromMinutes(2));\n\n cache.Set(id, product, cacheEntryOptions);\n }\n\n return Results.Ok(product);\n });\nCache expiration is another important topic to discuss.\nWe want to remove cache entries that aren't used and become stale.\nYou can pass in the MemoryCacheEntryOptions, allowing you to configure cache expiration.\nFor example, we can set the AbsoluteExpiration and SlidingExpiration values to control when the cache entry will expire.
The cache-aside pattern is the most common caching strategy. Here's how it works:
\n![\"Cache-aside](\"https://milanjovanovic.tech/blogs/mnw_093/cache_aside.png\")
\nHere's how you can implement the cache-aside pattern as an extension method for IDistributedCache:
public static class DistributedCacheExtensions\n{\n public static DistributedCacheEntryOptions DefaultExpiration => new()\n {\n AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(2)\n };\n\n public static async Task<T> GetOrCreateAsync<T>(\n this IDistributedCache cache,\n string key,\n Func<Task<T>> factory,\n DistributedCacheEntryOptions? cacheOptions = null)\n {\n var cachedData = await cache.GetStringAsync(key);\n\n if (cachedData is not null)\n {\n return JsonSerializer.Deserialize<T>(cachedData);\n }\n\n var data = await factory();\n\n await cache.SetStringAsync(\n key,\n JsonSerializer.Serialize(data),\n cacheOptions ?? DefaultExpiration);\n\n return data;\n }\n}\nWe're using JsonSerializer to manage serialization to and from a JSON string.\nThe SetStringAsync method also accepts a DistributedCacheEntryOptions argument to control cache expiration.
Here's how we would use this extension method:
\napp.MapGet(\n "products/{id}",\n (int id, IDistributedCache cache, AppDbContext context) =>\n {\n var product = cache.GetOrCreateAsync($"products-{id}", async () =>\n {\n var productFromDb = await context.Products.FindAsync(id);\n\n return productFromDb;\n });\n\n return Results.Ok(product);\n });\nPros:
\nCons:
\nRedis is a popular in-memory data store often used as a high-performance distributed cache.\nTo use Redis in your ASP.NET Core application, you can use the StackExchange.Redis library.
However, there's also the Microsoft.Extensions.Caching.StackExchangeRedis library,\nallowing you to integrate Redis with IDistributedCache.
Install-Package Microsoft.Extensions.Caching.StackExchangeRedis\nHere's how you can configure it with DI by providing a connection string to Redis:
\nstring connectionString = builder.Configuration.GetConnectionString("Redis");\n\nbuilder.Services.AddStackExchangeRedisCache(options =>\n{\n options.Configuration = connectionString;\n});\nAn alternative approach is to register an IConnectionMultiplexer as a service.\nThen, we will use it to provide a function for the ConnectionMultiplexerFactory.
string connectionString = builder.Configuration.GetConnectionString("Redis");\n\nIConnectionMultiplexer connectionMultiplexer =\n ConnectionMultiplexer.Connect(connectionString);\n\nbuilder.Services.AddSingleton(connectionMultiplexer);\n\nbuilder.Services.AddStackExchangeRedisCache(options =>\n{\n options.ConnectionMultiplexerFactory =\n () => Task.FromResult(connectionMultiplexer);\n});\nNow, when you inject IDistributedCache, it will use Redis under the hood.
The in-memory cache implementations in ASP.NET Core are susceptible to race conditions, which can cause a cache stampede.\nA cache stampede happens when concurrent requests encounter a cache miss and try to fetch the data from the source.\nThis can overload your application and negate the benefits of caching.
\nLocking is one solution for the cache stampede problem.\n.NET offers many options for locking and concurrency control.\nThe most commonly used locking primitives are the lock statement and the Semaphore (or SemaphoreSlim) class.
Here's how we could use SemaphoreSlim to introduce locking before fetching data:
public static class DistributedCacheExtensions\n{\n private static readonly SemaphoreSlim Semaphore = new SemaphoreSlim(1, 1);\n\n // Arguments omitted for brevity\n public static async Task<T> GetOrCreateAsync<T>(...)\n {\n // Fetch data from cache, and return if present\n\n // Cache miss\n try\n {\n await Semaphore.WaitAsync();\n\n // Check if the data was added to the cache by another request\n\n // If not, proceed to fetch data and cache it\n var data = await factory();\n\n await cache.SetStringAsync(\n key,\n JsonSerializer.Serialize(data),\n cacheOptions ?? DefaultExpiration);\n }\n finally\n {\n Semaphore.Release();\n }\n\n return data;\n }\n}\nThe previous implementation has a lock contention issue since all requests have to wait for the semaphore.\nA much better solution would be locking based on the key value.
.NET 9 introduces a new caching abstraction called HybridCache, which aims to solve the shortcomings of IDistributedCache.\nLearn more about this in the Hybrid cache documentation.
Caching is a powerful technique for improving web application performance.\nASP.NET Core's caching abstractions make it easy to implement various caching strategies.
\nWe can choose from IMemoryCache for in-memory cache and IDistributedCache for distributed caching.
Here are a few guidelines to wrap up this week's issue:
\nIMemoryCache for simple, in-memory cachingIDistributedCache for sharing cached data across multiple applicationsThat's all for today.
\nSee you next week.
\nVertical Slice Architecture organizes code by feature instead of by horizontal layers like Presentation, Application, and Domain.\nEach slice is a self-contained unit of functionality that cuts through the whole stack, from the API endpoint down to data access.\nOne way to structure a slice in .NET is a static class per feature that groups a Request, a Response, a Validator, and a Minimal API endpoint holding the use case logic.
\nAre you tired of organizing your project across layers?
\nVertical Slice Architecture is a compelling alternative to traditional layered architectures.\nVSA flips the script on how we structure code.
\nInstead of horizontal layers (Presentation, Application, Domain), VSA organizes code by feature.\nEach feature encompasses everything it needs, from API endpoints to data access.
\nIn this newsletter, we will explore how you can structure vertical slices in VSA.
\nAt its core, a vertical slice represents a self-contained unit of functionality.\nIt's a slice through the entire application stack.\nIt encapsulates all the code and components necessary to fulfill a specific feature.
\nIn traditional layered architectures, code is organized horizontally across the various layers.\nOne feature implementation can be scattered across many layers.\nChanging a feature requires modifying the code in multiple layers.
\nVSA addresses this by grouping all the code for a feature into a single slice.
\nThis shift in perspective brings several advantages:
\n![\"Vertical](\"https://milanjovanovic.tech/blogs/mnw_092/vertical_slices.png\")
\nHere's an example vertical slice representing the CreateProduct feature.\nWe use a static class to represent the feature and group the related types.\nEach feature can have a respective Request and Response class.\nThe use case with the business logic can be in a Minimal API endpoint.
A vertical slice is likely either a command or a query.\nThis approach gives us CQRS out of the box.
\npublic static class CreateProduct\n{\n public record Request(string Name, decimal Price);\n public record Response(int Id, string Name, decimal Price);\n\n public class Endpoint : IEndpoint\n {\n public void MapEndpoint(IEndpointRouteBuilder app)\n {\n app.MapPost("products", Handler).WithTags("Products");\n }\n\n public static IResult Handler(Request request, AppDbContext context)\n {\n var product = new Product\n {\n Name = request.Name,\n Price = request.Price\n };\n\n context.Products.Add(product);\n\n context.SaveChanges();\n\n return Results.Ok(\n new Response(product.Id, product.Name, product.Price));\n }\n }\n}\nI want to mention a few benefits of structuring your application like this.
\nThe code for the entire CreateProduct feature is tightly grouped within a single file.\nThis makes it extremely easy to locate, understand, and modify everything related to this functionality.\nWe don't need to navigate multiple layers (like controllers, services, repositories, etc.).
Directly using AppDbContext within the endpoint might tightly couple the slice to your database technology.\nDepending on your project's size and requirements, you could consider abstracting data access (using a repository pattern)\nto make the slice more adaptable to changes in the persistence layer.
Vertical slices usually need to solve some cross-cutting concerns, one of which is validation.\nValidation is the gatekeeper, preventing invalid or malicious data from entering your system.\nWe can easily implement validation with the FluentValidation library.
\nWithin your slice, you'd define a Validator class that encapsulates the rules specific to your feature's request model.\nIt also supports dependency injection, so we can run complex validations here.
public class Validator : AbstractValidator<Request>\n{\n public Validator()\n {\n RuleFor(x => x.Name).NotEmpty().MaximumLength(100);\n RuleFor(x => x.Price).GreaterThanOrEqualTo(0);\n // ... other rules\n }\n}\nThis validator can then be injected into your endpoint using dependency injection, allowing you to perform validation before processing the request.
\npublic static class CreateProduct\n{\n public record Request(string Name, decimal Price);\n public record Response(int Id, string Name, decimal Price);\n\n public class Validator : AbstractValidator<Request> // { ... }\n\n public class Endpoint : IEndpoint\n {\n public void MapEndpoint(IEndpointRouteBuilder app)\n {\n app.MapPost("products", Handler).WithTags("Products");\n }\n\n public static IResult Handler(\n Request request,\n IValidator<Request> validator,\n AppDbContext context)\n {\n var validationResult = await validator.Validate(request);\n if (!validationResult.IsValid)\n {\n return Results.BadRequest(validationResult.Errors);\n }\n\n // ... (Create product and return response)\n }\n }\n}\nThe previous examples were simple.\nBut what do we do with complex features and shared logic?
\nVSA excels at managing self-contained features.\nHowever, real-world applications often involve complex interactions and shared logic.
\nHere are a few strategies you can consider to address this:
\nExtract method and Extract class.You and your team will need to understand code smells and refactorings to make the most of VSA.
\nVertical Slice Architecture is more than just a way to structure your code.\nBy focusing on features, VSA allows you to create cohesive and maintainable applications.\nVertical slices are self-contained, making unit and integration testing more straightforward.
\nVSA brings benefits in terms of code organization and development speed, making it a valuable tool in your toolbox.\nCode is grouped by feature, making it easier to locate and understand.\nThe structure aligns with the way business users think about features.\nChanges are localized, reducing the risk of regressions and enabling faster iterations.
\nConsider embracing Vertical Slice Architecture in your next project.\nIt's a big mindset shift from Clean Architecture.\nHowever, they both have their place and even share similar ideas.
\nThat's all for this week. Stay awesome!
\nArchitecture tests are automated tests that check whether your code follows your architectural rules, such as which layers or modules may depend on each other.\nIn .NET you write them with a library such as NetArchTest or ArchUnitNET and run them in CI.\nA violation fails the build, so you catch the problem while it is cheap to fix.
\nPicture this: You're part of a team building a shiny new .NET application.\nYou've carefully chosen your software architecture.\nIt could be microservices, a modular monolith, or something else entirely.\nYou've decided which database you will use and all the other tools you need.\nEveryone's excited, the code is flowing, and features are getting shipped.
\nFast forward a few months (or years), and things might look different.
\nThe codebase has grown, and new features have been added.\nMaybe your team has even changed, with new developers coming on board.\nAdding new features becomes a pain, and bugs are popping up left and right.
\nAnd slowly but surely, the neat architecture you started with has turned into a big ball of mud.\nWhat went wrong? And more importantly, what can we do about it?
\nToday, I want to show you how architecture testing can prevent this problem.
\nTechnical debt is the consequence of prioritizing development speed over well-designed code.\nIt happens when teams cut corners to meet deadlines, make quick fixes, or don't understand the architecture clearly.
\nEach shortcut or hack adds to the pile, making the code harder to understand, change, and maintain.\nBut why do developers take these shortcuts in the first place?
\nDon't developers care about keeping the code clean?
\nWell, the truth is, most developers do care.\nIf you're reading this newsletter, odds are you also care.\nBut, developers are often under pressure to deliver features quickly.\nSometimes, the quickest way to do that is to take a shortcut.
\nPlus, not everyone has a deep understanding of software architecture, or they might disagree on what the "right" architecture is.\nAnd let's be honest: some developers want to get their code working and move on to the next thing.
\nLuckily, there's a way to enforce software architecture on your project before things get out of hand.\nIt's called architecture testing.\nThese are automated tests that check whether your code follows the architectural rules you've set up.
\nWith architecture testing, you can "shift left".\nThis enables you to find and fix problems early in the development process when they're much easier and cheaper to deal with.
\nThink of it like a safety net for your software architecture and design rules.\nIf someone accidentally breaks a rule, the test will catch it and alert you.\nBonus points if you integrate architecture testing into your CI pipeline.
\nThere are a few libraries you can use for architecture testing.\nI prefer working with the NetArchTest library, which I'll use for the examples.
\nYou can check out this article to learn the fundamentals of architecture testing.
\nLet's see how to write some architecture tests.
\nYou built an application using the modular monolith architecture.\nBut how can you maintain the constraints between the modules?
\nHere's an architecture test that enforces these module constraints.\nThe Ticketing module is not allowed to reference the other modules directly.\nHowever, it can reference the public API of other modules (integration events in this example).\nThe entry point is the Types class, which exposes a fluent API to build the rules you want to enforce.\nNetArchTest allows us to enforce the direction of dependencies between modules.
[Fact]\npublic void TicketingModule_ShouldNotHaveDependencyOn_AnyOtherModule()\n{\n string[] otherModules = [\n UsersNamespace,\n EventsNamespace,\n AttendanceNamespace];\n\n string[] integrationEventsModules = [\n UsersIntegrationEventsNamespace,\n EventsIntegrationEventsNamespace,\n AttendanceIntegrationEventsNamespace];\n\n List<Assembly> ticketingAssemblies =\n [\n typeof(Order).Assembly,\n Modules.Ticketing.Application.AssemblyReference.Assembly,\n Modules.Ticketing.Presentation.AssemblyReference.Assembly,\n typeof(TicketingModule).Assembly\n ];\n\n Types.InAssemblies(ticketingAssemblies)\n .That()\n .DoNotHaveDependencyOnAny(integrationEventsModules)\n .Should()\n .NotHaveDependencyOnAny(otherModules)\n .GetResult()\n .ShouldBeSuccessful();\n}\nIf you want to learn how to build robust and scalable systems using this architectural approach, check out Modular Monolith Architecture.
\nWe can also write architecture tests for Clean Architecture.\nThe inner layers aren't allowed to reference the outer layers.\nInstead, the inner layers define abstractions and the outer layers implement these abstractions.
\nFor example, the Domain layer isn't allowed to reference the Application layer.\nHere's an architecture test enforcing this rule:
[Fact]\npublic void DomainLayer_ShouldNotHaveDependencyOn_ApplicationLayer()\n{\n Types.InAssembly(DomainAssembly)\n .Should()\n .NotHaveDependencyOn(ApplicationAssembly.GetName().Name)\n .GetResult()\n .ShouldBeSuccessful();\n}\nIt's also simple introduce a rule that the Application layer isn't allowed to reference the Infrastructure layer.\nThe architecture test will fail whenever someone in the team breaks the dependency rule.
[Fact]\npublic void ApplicationLayer_ShouldNotHaveDependencyOn_InfrastructureLayer()\n{\n Types.InAssembly(ApplicationAssembly)\n .Should()\n .NotHaveDependencyOn(InfrastructureAssembly.GetName().Name)\n .GetResult()\n .ShouldBeSuccessful();\n}\nWe can introduce more architecture tests for the Infrastructure and Presentation layers, if needed.
Ready to learn more about building production-ready applications using this architectural approach?\nYou should check out Pragmatic Clean Architecture.
\nArchitecture testing is also useful for enforcing design rules in your code.\nIf your team has coding standards everyone should follow, architecture testing can help you enforce them.
\nFor example, we want to ensure that all domain events are sealed types.\nYou can use the BeSealed method to enforce a design rule that types implementing IDomainEvent or DomainEvent should be sealed.
[Fact]\npublic void DomainEvents_Should_BeSealed()\n{\n Types.InAssembly(DomainAssembly)\n .That()\n .ImplementInterface(typeof(IDomainEvent))\n .Or()\n .Inherit(typeof(DomainEvent))\n .Should()\n .BeSealed()\n .GetResult()\n .ShouldBeSuccessful();\n}\nAn interesting design rule could be requiring all domain entities not to have a public constructor.\nInstead, you would create an Entity instance through a static factory method.\nThis approach improves the encapsulation of your Entity.
Here's an architecture test enforcing this design rule:
\n[Fact]\npublic void Entities_ShouldOnlyHave_PrivateConstructors()\n{\n IEnumerable<Type> entityTypes = Types.InAssembly(DomainAssembly)\n .That()\n .Inherit(typeof(Entity))\n .GetTypes();\n\n var failingTypes = new List<Type>();\n foreach (Type entityType in entityTypes)\n {\n ConstructorInfo[] constructors = entityType\n .GetConstructors(BindingFlags.Public | BindingFlags.Instance);\n\n if (constructors.Any())\n {\n failingTypes.Add(entityType);\n }\n }\n\n failingTypes.Should().BeEmpty();\n}\nAnother thing you can do with architecture tests is enforce naming conventions in your code.\nHere's an example of requiring all command handlers to have a name ending with CommandHandler:
[Fact]\npublic void CommandHandler_ShouldHave_NameEndingWith_CommandHandler()\n{\n Types.InAssembly(ApplicationAssembly)\n .That()\n .ImplementInterface(typeof(ICommandHandler<>))\n .Or()\n .ImplementInterface(typeof(ICommandHandler<,>))\n .Should()\n .HaveNameEndingWith("CommandHandler")\n .GetResult()\n .ShouldBeSuccessful();\n}\nEven the most well-planned software projects decay because of technical debt.\nMost developers have good intentions.\nHowever, time pressure, misunderstandings, and resistance to rules all contribute to this problem.
\nArchitecture testing acts as a safeguard.\nIt prevents your codebase from turning into a big ball of mud.\nBy catching architectural violations early on, you can shift left.\nShort feedback loops avoid costly rework and improve developer productivity.\nIt also ensures the long-term health of your project.
\nA few key takeaways:
\nAction point: Start by exploring popular .NET architecture testing libraries like ArchUnitNET\nor NetArchTest.\nExperiment with writing tests for common architectural rules and gradually integrate them into your development workflow.\nI walked through the ArchUnitNET setup, the rules worth writing first, and the ways these tests quietly pass when they shouldn't in architecture fitness functions with ArchUnitNET.
\nThat's all for today.
\nSee you next week.
\nEF Core migrations version your database schema in code instead of hand-written SQL scripts.\nEach migration captures one change to the data model and contains Up and Down methods, so you can apply or revert it.\nYou can apply migrations with SQL scripts, the CLI, a migration bundle, or from code at startup.
Managing database schemas as your applications grow can quickly become a headache.\nManual changes are error-prone and time-consuming.\nThis can easily lead to inconsistencies between development and production environments.\nI've seen these issues firsthand on countless projects, and it's not pretty.\nHow can we do better?
\nEnter Entity Framework (EF) Migrations, a powerful tool that lets you version your database schemas.
\nImagine this: Instead of writing SQL scripts, you define your changes in code.\nNeed to add a column?\nRename a table?\nNo problem - EF Migrations has you covered.\nIt tracks every modification to the data model.\nYou can review, test, and apply changes confidently, even across different environments.
\nIn this newsletter, we'll break down the essentials of EF Migrations:
\nWe have many examples to cover, so let's dive in.
\nIf you're completely new to EF migrations, I recommend checking out the EF migrations docs\nto grasp the fundamentals.\nMoving forward, I'll assume you have some prior knowledge of EF Core.
\nWe'll need an entity and a database context before we can create migrations with EF.
\nLet's define a simple Product entity:
public class Product\n{\n public int Id { get; set; }\n\n public string Name { get; set; } = string.Empty;\n\n public string? Description { get; set; }\n\n public decimal Price { get; set; }\n}\nWe will also need a DbContext implementation, so let's define the AppDbContext class.\nIn the OnModelCreating method, we're going to configure the Product entity.
public class AppDbContext : DbContext\n{\n public AppDbContext(DbContextOptions<AppDbContext> options)\n : base(options)\n {\n }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.Entity<Product>(builder =>\n {\n builder.ToTable("Products", tableBuilder =>\n {\n tableBuilder.HasCheckConstraint(\n "CK_Price_NotNegative",\n sql: $"{nameof(Product.Price)} > 0");\n });\n\n builder.HasKey(p => p.Id);\n\n builder.Property(p => p.Name).HasMaxLength(100);\n\n builder.Property(p => p.Description).HasMaxLength(1000);\n\n builder.Property(p => p.Price).HasPrecision(18, 2);\n\n builder.HasIndex(p => p.Name).IsUnique();\n });\n }\n}\nLet's break down a few of the methods we're using:
\nToTable - Configures the table name for the specific entity.\nIt also allows us to provide TableBuilder delegate.\nWe can use it to configure a check constraint using HasCheckConstraint.HasKey - Configures the table's primary key.\nEF will also pick up the Id property by convention, so this step is optional.HasProperty - Represents the entry point for configuring individual properties of the entity.HasIndex - Defines an index on the specified property (or properties).\nWe can also declare that the index should be unique by calling IsUnique.We're now ready to create our first migration.\nI'm going to use the PowerShell syntax:
\nAdd-Migration Create_Database\nThis will create the first database migration called Create_Database.\nThe migration will apply the configuration we defined in the OnModelCreating method.\nIt contains the Up and Down methods, allowing us to apply or revert changes to the database.
Note that some operations are destructive (like removing a column) and can't be easily reverted.\nIt's up to you to examine the generated migration and prevent any possible data loss.
\nusing Microsoft.EntityFrameworkCore.Migrations;\nusing Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;\n\npublic partial class Create_Database : Migration\n{\n protected override void Up(MigrationBuilder migrationBuilder)\n {\n migrationBuilder.CreateTable(\n name: "Products",\n columns: table => new\n {\n Id = table.Column<int>(type: "integer", nullable: false)\n .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),\n Name = table.Column<string>(type: "character varying(100)", maxLength: 100, nullable: false),\n Description = table.Column<string>(type: "character varying(1000)", maxLength: 1000, nullable: true),\n Price = table.Column<decimal>(type: "numeric(18,2)", precision: 18, scale: 2, nullable: false)\n },\n constraints: table =>\n {\n table.PrimaryKey("PK_Products", x => x.Id);\n table.CheckConstraint("CK_Price_NotNegative", "Price > 0");\n });\n\n migrationBuilder.CreateIndex(\n name: "IX_Products_Name",\n table: "Products",\n column: "Name",\n unique: true);\n }\n\n protected override void Down(MigrationBuilder migrationBuilder)\n {\n migrationBuilder.DropTable(\n name: "Products");\n }\n}\nWe can also modify the migration files if we need to apply some custom changes.
\nA notable example is renaming a column.\nLet's say we rename the Description property to ShortDescription.\nIn some EF versions, this would result in the following migration:
migrationBuilder.DropColumn(\n name: "Description",\n table: "Customers");\n\nmigrationBuilder.AddColumn<string>(\n name: "ShortDescription",\n table: "Products",\n nullable: true);\nWhat's the problem here?\nBy calling DropColumn first, we will remove the column from the database and lose valuable data.
What we actually want to do is rename the existing column.\nSo, we can modify the migration file to use the RenameColumn method:
migrationBuilder.RenameColumn(\n name: "Description",\n table: "Products",\n newName: "ShortDescription");\nAnother example is executing custom SQL commands from your migrations.\nCustom SQL commands are helpful when we can't express something through the EF fluent API.\nI've used it in the past to migrate data from one column to another or define a complex index.
\npublic partial class Update_Products : Migration\n{\n protected override void Up(MigrationBuilder migrationBuilder)\n {\n migrationBuilder.Sql("<YOUR CUSTOM SQL HERE>");\n }\n\n protected override void Down(MigrationBuilder migrationBuilder)\n {\n // You are also responsible for reverthing any changes.\n }\n}\nYou can use the Script-Migration command to generate SQL scripts from your migrations.\nThis is useful for reviewing changes before applying them to the database.\nSQL scripts allow us to execute migrations in environments without direct access to the EF tooling.
Remember, you are responsible for preventing any data loss when executing EF migrations.\nReview the migrations carefully before applying them to the database.
\nHere are a few ways you can execute the Script-Migration command:
Script-Migration\n\nScript-Migration <FromMigration>\n\nScript-Migration <FromMigration> <ToMigration>\nThe <FromMigration> argument should be the name of the last migration applied to the database.\nIt's your responsibility to apply the script appropriately, and only to databases in the correct migration state.
Here's what the SQL script for the Create_Database migration looks like:
CREATE TABLE IF NOT EXISTS "__EFMigrationsHistory" (\n "MigrationId" character varying(150) NOT NULL,\n "ProductVersion" character varying(32) NOT NULL,\n CONSTRAINT "PK___EFMigrationsHistory" PRIMARY KEY ("MigrationId")\n);\n\nSTART TRANSACTION;\n\nCREATE TABLE "Products" (\n "Id" integer GENERATED BY DEFAULT AS IDENTITY,\n "Name" character varying(100) NOT NULL,\n "Description" character varying(1000),\n "Price" numeric(18,2) NOT NULL,\n CONSTRAINT "PK_Products" PRIMARY KEY ("Id"),\n CONSTRAINT "CK_Price_NotNegative" CHECK (Price > 0)\n);\n\nCREATE UNIQUE INDEX "IX_Products_Name" ON "Products" ("Name");\n\nINSERT INTO "__EFMigrationsHistory" ("MigrationId", "ProductVersion")\nVALUES ('20240516095344_Create_Database', '8.0.5');\n\nCOMMIT;\nYou can also specify an -Idempotent argument to the Script-Migration command.\nThe Script-Migration command will generate SQL scripts that only apply migrations that haven't been applied already.\nThis is useful if you're not sure what the last migration applied to the database.
Script-Migration -Idempotent\nHere's what the idempotent SQL script looks like:
\nCREATE TABLE IF NOT EXISTS "__EFMigrationsHistory" (\n "MigrationId" character varying(150) NOT NULL,\n "ProductVersion" character varying(32) NOT NULL,\n CONSTRAINT "PK___EFMigrationsHistory" PRIMARY KEY ("MigrationId")\n);\n\nSTART TRANSACTION;\n\nDO $EF$\nBEGIN\n IF NOT EXISTS(SELECT 1 FROM "__EFMigrationsHistory" WHERE "MigrationId" = '20240516095344_Create_Database') THEN\n CREATE TABLE "Products" (\n "Id" integer GENERATED BY DEFAULT AS IDENTITY,\n "Name" character varying(100) NOT NULL,\n "Description" character varying(1000),\n "Price" numeric(18,2) NOT NULL,\n CONSTRAINT "PK_Products" PRIMARY KEY ("Id"),\n CONSTRAINT "CK_Price_NotNegative" CHECK (Price > 0)\n );\n END IF;\nEND $EF$;\n\nDO $EF$\nBEGIN\n IF NOT EXISTS(SELECT 1 FROM "__EFMigrationsHistory" WHERE "MigrationId" = '20240516095344_Create_Database') THEN\n CREATE UNIQUE INDEX "IX_Products_Name" ON "Products" ("Name");\n END IF;\nEND $EF$;\n\nDO $EF$\nBEGIN\n IF NOT EXISTS(SELECT 1 FROM "__EFMigrationsHistory" WHERE "MigrationId" = '20240516095344_Create_Database') THEN\n INSERT INTO "__EFMigrationsHistory" ("MigrationId", "ProductVersion")\n VALUES ('20240516095344_Create_Database', '8.0.5');\n END IF;\nEND $EF$;\nCOMMIT;\nHow do we apply EF migrations to the database?
\nWe have a few options:
\nWe discussed SQL scripts in the previous section, so I won't mention them again.
\nThe most common approach to applying database migrations is using the CLI.\nYou can use either the dotnet ef tool or the PowerShell commands.\nFor example, you can execute the Update-Database command from PowerShell to apply any pending migrations.
Update-Database -Migration <ToMigration> -Connection <ConnectionString>\nHere are the documentation links if you want to learn more:
\n\nHere's a helper method for applying database migrations.\nIt uses an IServiceScope to resolve a DbContext instance and uses it to call the Migrate method.
public static void ApplyMigration<TDbContext>(IServiceScope scope)\n where TDbContext : DbContext\n{\n using TDbContext context = scope.ServiceProvider\n .GetRequiredService<TDbContext>();\n\n context.Database.Migrate();\n}\nYou can apply migrations when the application is starting.\nI don't recommend using this approach for production environments.\nMigration can fail, concurrency issues exist, and rolling back migrations is challenging.\nHowever, this approach can be helpful in local development and when scaffolding databases for integration testing.
\nvar builder = WebApplication.CreateBuilder(args);\n\nvar app = builder.Build();\n\nif (app.Environment.IsDevelopment())\n{\n using IServiceScope scope = app.ApplicationServices.CreateScope();\n\n ApplyMigration<AppDbContext>(scope);\n}\n\napp.Run();\nMigration bundles are executable files that you can use to apply database migrations.\nThey're self-contained and can be executed from CI pipelines.
\nYou can use the Bundle-Migration command to create a migration bundle:
Bundle-Migration -Connection <ConnectionString>\nThis will create an efbundle.exe file that we can run to apply any pending database migrations.
I recommend reading the migration bundles documentation to learn more.
\nWhat can you do if you don't want to use EF Core migrations?
\nI wanted to mention some additional tools you can use for database schema versioning and running migrations:
\nWe won't do a deep dive on these tools, but I recommend you check out their documentation.
\nI want to wrap up this issue with a few tips from my experience of working with EF Core migrations over the years:
\nAddProductsTable, RenameDescriptionToShortDescription.\nThis makes it much easier to understand your migration history and find specific changes.My preferred approach to applying migrations is using SQL scripts.\nDepending on the project scope and complexity, we could do this manually or through a tool that automates the process.\nThis allows me to review the migration and identify any potential problems.
\nI hope this was helpful!
\nThanks for reading, and I'll see you next week.
\n.NET 8 introduced the Microsoft.Extensions.Resilience and Microsoft.Extensions.Http.Resilience packages, both built on top of Polly.\nYou compose retry, timeout, circuit breaker, fallback, hedging, and rate limiter strategies into a resilience pipeline, and the order you configure them matters.\nFor outgoing HTTP calls, AddStandardResilienceHandler applies a ready-made pipeline.
From my experience working with microservices systems, things don't always go as planned.\nNetwork requests randomly fail, application servers become overloaded, and unexpected errors appear.\nThat's where resilience comes in.
\nResilient applications can recover from transient failures and continue to function.\nResilience is achieved by designing applications that can handle failures gracefully and recover quickly.
\nBy designing your applications with resilience in mind, you can create robust and reliable systems, even when the going gets tough.
\nIn this newsletter, we'll explore the tools and techniques we have in .NET to build resilient systems.
\nSending HTTP requests is a common approach for remote communication between services.\nHowever, HTTP requests are susceptible to failures from network or server issues.\nThese failures can disrupt service availability, especially as dependencies increase and the risk of cascading failures grows.
\nSo, how can you improve the resilience of your applications and services?
\nHere are a few strategies you can consider to increase resilience:
\nYou can use these strategies individually or in combination for optimal HTTP request resilience.
\nLet's see how we can introduce resilience in a .NET application.
\nWith .NET 8, integrating resilience into your applications has become much simpler.\nWe can use Microsoft.Extensions.Resilience and Microsoft.Extensions.Http.Resilience, which are built on top of Polly.\nPolly is a .NET resilience and transient fault-handling library.\nPolly allows us to define resilience strategies such as retry, circuit breaker, timeout, rate-limiting, fallback, and hedging.
Polly received a new API surface in its latest version (V8), which was implemented in collaboration with Microsoft.\nYou can learn more about the Polly V8 API in this video.
\nIf you were previously using Microsoft.Extensions.Http.Polly, it is recommended that you switch to one of the previously mentioned packages.
Let's start by installing the required NuGet packages:
\nInstall-Package Microsoft.Extensions.Resilience\nInstall-Package Microsoft.Extensions.Http.Resilience\nTo use resilience, you must first build a pipeline consisting of resilience strategies.\nEach strategy that we configure as part of the pipeline will execute in order of configuration.\nOrder is important with resilience pipelines.\nKeep that in mind.
\nWe start by creating an instance of ResiliencePipelineBuilder, which allows us to configure resilience strategies.
ResiliencePipeline pipeline = new ResiliencePipelineBuilder()\n .AddRetry(new RetryStrategyOptions\n {\n ShouldHandle = new PredicateBuilder().Handle<ConflictException>(),\n Delay = TimeSpan.FromSeconds(1),\n MaxRetryAttempts = 2,\n BackoffType = DelayBackoffType.Exponential,\n UseJitter = true\n })\n .AddTimeout(new TimeoutStrategyOptions\n {\n Timeout = TimeSpan.FromSeconds(10)\n })\n .Build();\n\nawait pipeline.ExecuteAsync(\n async ct => await httpClient.GetAsync("https://modularmonolith.com", ct),\n cancellationToken);\nHere's what we're adding to the resilience pipeline:
\nAddRetry - Configures a retry resilience strategy, which we can further configure by passing in a RetryStrategyOptions instance.\nWe can provide a predicate for the ShouldHandle property to define which exceptions the resilience strategy should handle.\nThe retry strategy also comes with some sensible default values.AddTimeout - Configures a timeout strategy that will throw a TimeoutRejectedException if the delegate does not complete before the timeout.\nWe can provide a custom timeout by passing in a TimeoutStrategyOptions instance.\nThe default timeout is 30 seconds.Finally, we can Build the resilience pipeline and get back a configured ResiliencePipeline instance that will apply the respective resilience strategies.\nTo use the ResiliencePipeline, we can call the ExecuteAsync method and pass in a delegate.
Configuring a resilience pipeline every time we want to use it is cumbersome.\n.NET 8 introduces a new extension method for the IServiceCollection interface that allows us to register resilience pipelines with dependency injection.
Instead of manually configuring resilience every time, you ask for a pre-made pipeline by name.
\nWe start by calling the AddResiliencePipeline method, which allows us to configure the resilience pipeline.\nEach resilience pipeline needs to have a unique key.\nWe can use this key to resolve the respective resilience pipeline instance.
In this example, we're passing in a string key which allows us to configure the non-generic ResiliencePipelineBuilder.
services.AddResiliencePipeline("retry", builder =>\n{\n builder.AddRetry(new RetryStrategyOptions\n {\n Delay = TimeSpan.FromSeconds(1),\n MaxRetryAttempts = 2,\n BackoffType = DelayBackoffType.Exponential,\n UseJitter = true\n });\n});\nHowever, we can also specify generic arguments when calling AddResiliencePipeline.\nThis allows us to configure a typed resilience pipeline using ResiliencePipelineBuilder<TResult>.\nUsing this approach, we can access the hedging and fallback strategies.
In the following example, we're configuring a fallback strategy by calling AddFallback.\nThis allows us to provide a fallback value that we can return in case of a failure.\nThe fallback could be a static value or come from another HTTP request or the database.
services.AddResiliencePipeline<string, GitHubUser?>("gh-fallback", builder =>\n{\n builder.AddFallback(new FallbackStrategyOptions<GitHubUser?>\n {\n FallbackAction = _ =>\n Outcome.FromResultAsValueTask<GitHubUser?>(GitHubUser.Empty)\n });\n});\nTo use resilience pipelines configured with dependency injection, we can use the ResiliencePipelineProvider.\nIt exposes a GetPipeline method for obtaining the pipeline instance.\nWe have to provide the key used to register the resilience pipeline.
app.MapGet("users", async (\n HttpClient httpClient,\n ResiliencePipelineProvider<string> pipelineProvider) =>\n{\n ResiliencePipeline<GitHubUser?> pipeline =\n pipelineProvider.GetPipeline<GitHubUser?>("gh-fallback");\n\n var user = await pipeline.ExecuteAsync(async token =>\n await httpClient.GetAsync("api/users", token),\n cancellationToken);\n});\nResilience strategies are the core component of Polly.\nThey're designed to run custom callbacks while introducing an additional layer of resilience.\nWe can't run these strategies directly.\nInstead, we execute them through a resilience pipeline.
\nPolly categorizes resilience strategies into reactive and proactive.\nReactive strategies handle specific exceptions or results.\nProactive strategies decide to cancel or reject the execution of callbacks using a rate limiter or a timeout resilience strategy.
\nPolly has the following built-in resilience strategies:
\nSending HTTP calls to external services is how your application interacts with the outside world.\nThese could be third-party services like payment gateways and identity providers or other services your team owns and operates.
\nThe Microsoft.Extensions.Http.Resilience library comes with ready-to-use resilience pipelines for sending HTTP requests.
We can add resilience to outgoing HttpClient requests using the AddStandardResilienceHandler method.
services.AddHttpClient<GitHubService>(static (httpClient) =>\n{\n httpClient.BaseAddress = new Uri("https://api.github.com/");\n})\n.AddStandardResilienceHandler();\nThis also means you can eliminate any delegating handlers you previously used for resilience.
\nThe standard resilience handler combines five Polly strategies to create a resilience pipeline suitable for most scenarios.\nThe standard pipeline contains the following strategies:
\nYou can customize any aspect of the standard resilience pipeline by configuring the HttpStandardResilienceOptions.
Resilience isn't just a buzzword; it's a core principle for building reliable software systems.\nWe're fortunate to have powerful tools like Microsoft.Extensions.Resilience and Polly at our disposal.\nWe can use them to design systems that gracefully handle any transient failures.
Good monitoring and observability\nare essential to understand how your resilience mechanisms work in production.\nRemember, the goal isn't to eliminate failures but to gracefully handle them and keep your application functioning.
\nReady to dive deeper into resilient architecture?\nMy advanced course on building modular monoliths will equip you with the skills to design and implement robust, scalable systems.\nCheck out Modular Monolith Architecture.
\nChallenge: Take a look at your existing .NET projects.\nAre there any critical areas where a little resilience could go a long way?\nPick one and try applying some of the techniques we've discussed here.
\nThat's all for today.
\nSee you next week.
\nYARP does not authenticate or authorize requests until you enable it.\nAdd the ASP.NET Core authentication and authorization middleware before MapReverseProxy, then set AuthorizationPolicy on each route.\nThe default value requires an authenticated user, anonymous skips authorization, and a named policy gives you custom claim-based rules.
API gateways provide clients with a single point of entry.\nThis streamlines their interactions with your system and ensures the security of your microservices or distributed system.
\nOne critical aspect of API gateways is authentication - ensuring only authorized users and applications can access your valuable data and resources.
\nIn this newsletter, we'll explore how you can implement API gateway authentication using YARP (Yet Another Reverse Proxy),\na powerful and flexible reverse proxy library for .NET applications.
\nHere's what we will cover:
\nLet's dive in.
\nAn API gateway is the "front door" to your backend services and APIs.\nIt acts as an intermediary layer, handling client requests and routing them to the appropriate destinations.
\nThe key benefits of API gateways are:
\n![\"API](\"https://milanjovanovic.tech/blogs/mnw_088/api_gateway.png\")
\n We can use the API gateway to authenticate and authorize requests before they are proxied to the destination servers.\nThis can reduce the load on the destination servers, and introduce a layer of security.\nImplementing authentication on the API gateway ensures consistent policies are implemented across your applications.
\nIf you're new to YARP, I recommend first reading about how to implement an API gateway with YARP.
\nBy default, YARP won't authenticate or authorize requests unless enabled in the route or application configuration.
\nWe can start by introducing authentication\nand authorization middleware:
\napp.UseAuthentication();\napp.UseAuthorization();\n\napp.MapReverseProxy();\nThis allows us to configure the authorization policy by providing the AuthorizationPolicy value in the route configuration.
There are two special values we can specify in a route's authorization parameter:
\ndefault - The route will require an authenticated user.anonymous - The route will not require authorization regardless of any other configuration.Here's how we can enforce that all incoming requests must be authenticated:
\n{\n // This is how we define reverse proxy routes.\n "Routes": {\n "api-route": {\n "ClusterId": "api-cluster",\n "AuthorizationPolicy": "default",\n "Match": {\n "Path": "api/{**catch-all}"\n }\n }\n }\n}\nWe want to authorize any incoming request as soon as it hits the API gateway.\nHowever, the destination server may still need to know who the user is (authentication) and what they can do (authorization).
\nYARP will pass any credentials to the proxied request.\nBy default, cookies, bearer tokens, and API keys will flow to the destination server.
\nYARP can utilize the powerful authorization policies feature in ASP.NET Core.\nWe can specify a policy per route in the proxy configuration, and the rest is handled by existing ASP.NET Core authentication and authorization components.
\n{\n // This is how we define auth policies for reverse proxy routes.\n "Routes": {\n "api-route1": {\n "ClusterId": "api-cluster",\n "AuthorizationPolicy": "is-vip",\n "Match": {\n "Path": "api/hello-vip"\n }\n },\n "api-route2": {\n "ClusterId": "api-cluster",\n "AuthorizationPolicy": "default",\n "Match": {\n "Path": "api/{**catch-all}"\n }\n }\n }\n}\nHere's how we can create a custom is-vip policy with two components.\nIt requires an authenticated user and vip claim with one of the defined allowed values to be present .\nTo use this policy, we can just specify it as the value for the AuthorizationPolicy in the route configuration.
services.AddAuthorization(options =>\n{\n options.AddPolicy("is-vip", policy =>\n policy\n .RequireAuthenticatedUser()\n .RequireClaim("vip", allowedValues: true.ToString()));\n});\nAPI gateways provide a unified access point, streamlining client interactions and securing your backend services.\nAuthentication is an essential element of API gateway security, controlling who can access your resources.
\nYARP offers a versatile solution for building .NET API gateways.\nBy integrating with ASP.NET Core's authentication and authorization frameworks, YARP enables robust security mechanisms.
\nThis flexibility really shines with support for custom authorization policies.\nThis allows you to define granular access control\nbased on user roles, claims, or other attributes.
\nThanks for reading, and I'll see you next week.
\nP.S. Here's the complete source code for this article if you want to try it out.
\nThe request-response messaging pattern works like a function call, except the request and the response travel over a message bus.\nMassTransit supports it out of the box through a request client: you inject an IRequestClient<T>, send the request, and await the response.\nThe services stay loosely coupled because they only share message contracts.
Building distributed applications might seem simple at first. It's just servers talking to each other. Right?
\nHowever, it opens a set of potential problems you must consider.\nWhat if the network has a hiccup?\nA service unexpectedly crashes?\nYou try to scale, and everything crumbles under the load?\nThis is where the way your distributed system communicates becomes critical.
\nTraditional synchronous communication, where services call each other directly, is inherently fragile.\nIt creates tight coupling, making your whole application vulnerable to single points of failure.
\nTo combat this, we can turn to distributed messaging\n(and introduce an entirely different set of problems, but that's a story for another issue).
\nOne powerful tool for achieving this in the .NET world is MassTransit.
\nIn this week's issue, we'll explore MassTransit's implementation of the request-response pattern.
\nLet's start by explaining how the request-response messaging pattern works.
\nThe request-response pattern is just like making a traditional function call but over the network.\nOne service, the requester, sends a request message and waits for a corresponding response message.\nThis is a synchronous communication approach from the requester's side.
\nThe good parts:
\nThe bad parts:
\n![\"Request](\"https://milanjovanovic.tech/blogs/mnw_087/request_response.png\")
\nMassTransit\nsupports the request-response messaging pattern out of the box.\nWe can use a request client to send requests and wait for a response.\nThe request client is asynchronous and supports the await keyword.\nThe request will also have a timeout of 30 seconds by default, to prevent waiting for the response for too long.
Let's imagine a scenario where you have an order processing system that needs to fetch an order's latest status.\nWe can fetch the status from an Order Management service.\nWith MassTransit, you'll create a request client to initiate the process.\nThis client will send a GetOrderStatusRequest message onto the bus.
public record GetOrderStatusRequest\n{\n public string OrderId { get; init; }\n}\nOn the Order Management side, a responder (or consumer) will be listening for GetOrderStatusRequest messages.\nIt receives the request, potentially queries a database to get the status,\nand then sends a GetOrderStatusResponse message back onto the bus.\nThe original request client will be waiting for this response and can then process it accordingly.
public class GetOrderStatusRequestConsumer : IConsumer<GetOrderStatusRequest>\n{\n public async Task Consume(ConsumeContext<GetOrderStatusRequest> context)\n {\n // Get the order status from a database.\n\n await context.ResponseAsync<GetOrderStatusResponse>(new\n {\n // Set the respective response properties.\n });\n }\n}\nHere's a real-world scenario where my team decided to implement this pattern.\nWe were building a modular monolith,\nand one of the modules was responsible for managing user permissions.\nThe other modules could call out to the Users module to get the user's permissions.\nAnd this works great while we are still inside a monolith system.
\nHowever, at one point we needed to extract one module into a separate service.\nThis meant that the communication with the Users module using simple method calls would no longer work.
\nLuckily, we were already using MassTransit and RabbitMQ for messaging inside the system.
\nSo, we decided to use the MassTransit request-response feature to implement this.
\nThe new service will inject an IRequestClient<GetUserPermissions>.\nWe can use it to send a GetUserPermissions message and await a response.
A very powerful feature of MassTransit is that you can await more than one response message.\nIn this example, we're waiting for a PermissionsResponse or an Error response.\nThis is great, because we also have a way to handle failures in the consumer.
internal sealed class PermissionService(\n IRequestClient<GetUserPermissions> client)\n : IPermissionService\n{\n public async Task<Result<PermissionsResponse>> GetUserPermissionsAsync(\n string identityId)\n {\n var request = new GetUserPermissions(identityId);\n\n Response<PermissionsResponse, Error> response =\n await client.GetResponse<PermissionsResponse, Error>(request);\n\n if (response.Is(out Response<Error> errorResponse))\n {\n return Result.Failure<PermissionsResponse>(errorResponse.Message);\n }\n\n if (response.Is(out Response<PermissionsResponse> permissionResponse))\n {\n return permissionResponse.Message;\n }\n\n return Result.Failure<PermissionsResponse>(NotFound);\n }\n}\nIn the Users module, we can easily implement the GetUserPermissionsConsumer.\nIt will respond with a PermissionsResponse if the permissions are found or an Error in case of a failure.
public sealed class GetUserPermissionsConsumer(\n IPermissionService permissionService)\n : IConsumer<GetUserPermissions>\n{\n public async Task Consume(ConsumeContext<GetUserPermissions> context)\n {\n Result<PermissionsResponse> result =\n await permissionService.GetUserPermissionsAsync(\n context.Message.IdentityId);\n\n if (result.IsSuccess)\n {\n await context.RespondAsync(result.Value);\n }\n else\n {\n await context.RespondAsync(result.Error);\n }\n }\n}\nBy embracing messaging patterns with MassTransit, you're building on a much sturdier foundation.\nYour .NET services are now less tightly coupled, giving you the flexibility to evolve them independently\nand weather those inevitable network glitches or service outages.
\nThe request-response pattern is a powerful tool in your messaging arsenal.\nMassTransit makes it remarkably easy to implement, ensuring that requests and responses are delivered reliably.
\nWe can use request-response to implement communication between modules in a modular monolith.\nHowever, don't take this to the extreme, or your system might suffer from increased latency.
\nStart small, experiment, and see how the reliability and flexibility of messaging can transform your development experience.
\nThat's all for this week. Stay awesome!
\nDistributed tracing follows a single request as it flows across services, databases, and message buses.\nIn .NET, you collect those traces with OpenTelemetry, an open-source standard that also covers metrics and logs.\nYou install the instrumentation packages, configure AddOpenTelemetry, and export the data to a backend like Jaeger.
If you're building or maintaining distributed .NET applications, understanding how they behave is key to ensuring reliability and performance.
\nDistributed systems offer flexibility but introduce complexity, making troubleshooting a headache.\nUnderstanding how requests flow through your system is crucial for debugging and performance optimization.
\nOpenTelemetry is an open-source observability framework that makes this possible.
\nIn this article, we'll dive into what OpenTelemetry is, how to use it in your .NET projects, and the powerful insights it provides.
\nOpenTelemetry (OTel) is a vendor-neutral, open-source standard for instrumenting applications to generate telemetry data.\nOpenTelemetry contains APIs, SDKs, tools, and integrations for creating and managing this telemetry data (traces, metrics, and logs).
\nTelemetry data includes:
\n![\"OpenTelemetry](\"https://milanjovanovic.tech/blogs/mnw_086/otel.png\")
\n OpenTelemetry provides a unified way to collect this data, making it easier to understand the behavior and health of complex distributed applications.
\nWe can export the telemetry data we are collecting to a service capable of processing it and providing us with an interface to analyze it.
\nWe're going to configure OpenTelemetry to export traces directly to Jaeger.
\nOpenTelemetry provides libraries and SDKs to add code (instrumentation) into your .NET applications.\nThese instrumentations automatically capture the traces, metrics, and logs we are interested in.
\nWe're going to install the following NuGet packages:
\n# Automatic tracing, metrics\nInstall-Package OpenTelemetry.Extensions.Hosting\n\n# Telemetry data exporter\nInstall-Package OpenTelemetry.Exporter.OpenTelemetryProtocol\n\n# Instrumentation packages\nInstall-Package OpenTelemetry.Instrumentation.Http\nInstall-Package OpenTelemetry.Instrumentation.AspNetCore\nInstall-Package OpenTelemetry.Instrumentation.EntityFrameworkCore\nInstall-Package OpenTelemetry.Instrumentation.StackExchangeRedis\nInstall-Package Npgsql.OpenTelemetry\nOnce we have these NuGet packages installed, it's time to configure some services.
\nservices\n .AddOpenTelemetry()\n .ConfigureResource(resource => resource.AddService(serviceName))\n .WithTracing(tracing =>\n {\n tracing\n .AddAspNetCoreInstrumentation()\n .AddHttpClientInstrumentation()\n .AddEntityFrameworkCoreInstrumentation()\n .AddRedisInstrumentation()\n .AddNpgsql();\n\n tracing.AddOtlpExporter();\n });\nAddAspNetCoreInstrumentation - This enables ASP.NET Core instrumentation.AddHttpClientInstrumentation - This enables HttpClient instrumentation for outgoing requests.AddEntityFrameworkCoreInstrumentation - This enables EF Core instrumentation.AddRedisInstrumentation - This enables Redis instrumentation.AddNpgsql - This enables PostgreSQL instrumentation.With all of these instrumentations configured, our application will start collecting a lot of valuable traces at runtime.
\nWe also need to configure an environment variable for the exporter added with AddOtlpExporter to work correctly.\nWe can set OTEL_EXPORTER_OTLP_ENDPOINT through application settings.\nThe address specified here will point to a local Jaeger instance.
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317\nJaeger is an open source, distributed tracing platform.\nJaeger maps the flow of requests and data as they travel through a distributed system.\nThese requests could be calling out to multiple services, and Jaeger knows how to piece all of this information together.
\nHere's how to run Jaeger inside a Docker container:
\ndocker run -d -p 4317:4317 -p 16686:16686 jaegertracing/all-in-one:latest\nWe're using the jaegertracing/all-in-one:latest image, and exposing the 4317 to accept telemetry data.\nThe Jaeger user interface will be exposed on the 16686 port.
After installing the OpenTelemetry libraries and configuring tracing in our applications, we can send some requests to generate telemetry data.\nWe can then access Jaeger to start analyzing our distributed traces.
\nRegistering a new user
\nHere's an example of registering a new user with the system.\nWe're accessing the API gateway (Evently.Gateway) service, which proxies the request to the Evently.Api service.\nAnd you can see that the Evently.Api service makes a few HTTP requests before persisting a new record in the database.
![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_086/trace_1.png\")
\nPublishing a message with MassTransit
\nHere's another distributed trace where we publish the UserRegisteredIntegrationEvent over a message bus.\nYou can see that it's being consumed by two different services that write some data to the database.
![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_086/trace_2.png\")
\nExamining additional trace information
\nDistributed traces can include some useful contextual information.\nHere's an example trace representing a database command.\nThis comes from the PostgreSQL instrumentation, and we can see the SQL query that we are executing.
\n![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_086/trace_3.png\")
\nComplex distributed traces
\nHere's a more complex distributed trace, which includes:
\nWe're sending a request to get the customer's cart.\nThe request will first hit the API gateway, which proxies it to the Evently.Ticketing.Api service that owns the data.\nHowever, the Evently.Ticketing.Api service needs to reach out to the Evently.Api service to get the authorization information.\nAnd all of this leads to the distributed trace you can see below.
![\"Distributed](\"https://milanjovanovic.tech/blogs/mnw_086/trace_4.png\")
\nUnderstanding modern applications, especially distributed ones, can be a real mind-bender.\nOpenTelemetry is like having X-ray vision into your system.
\nWhile adding OpenTelemetry takes some upfront work, consider it an investment.\nThat investment pays off big time when problems pop up.\nInstead of frantic guesswork, you have precise data to zero in on issues fast.
\nIs OpenTelemetry a magic bullet for all your problems? Nope.
\nBut it's an excellent tool to add to your troubleshooting arsenal, especially as your .NET applications grow and get more complex.
\nIf you're curious where the distributed traces come from, it's from the application we're building in my Modular Monolith course.
\nThat's all for today. Stay awesome, and I'll see you next week.
\nEF Core has no built-in mechanism for pessimistic locking, so you implement it with a raw SQL query.\nIn PostgreSQL, SELECT FOR UPDATE acquires a row-level lock and blocks competing transactions until the current transaction releases the lock.\nOn SQL Server, the WITH (UPDLOCK, READPAST) query hint gives you a similar effect.
Sometimes, especially in high-traffic scenarios, you absolutely need to ensure that only one process can modify a piece of data at a time.
\nImagine you're building the ticket sales system for a wildly popular concert.\nCustomers are eagerly grabbing tickets, and the last few could sell out simultaneously.\nIf you're not careful, multiple customers might think they've secured the final seat, leading to overbooking and disappointment!
\nEntity Framework Core is a fantastic tool, but it doesn't have a direct mechanism for pessimistic locking.\nOptimistic locking (using versions) can work, but in high-contention scenarios, it can lead to a lot of retries.
\nSo, how can we solve this problem with EF Core?
\nHere's a simplified code snippet to illustrate our ticketing challenge:
\npublic async Task Handle(CreateOrderCommand request)\n{\n await using DbTransaction transaction = await unitOfWork\n .BeginTransactionAsync();\n\n Customer customer = await customerRepository.GetAsync(request.CustomerId);\n\n Order order = Order.Create(customer);\n Cart cart = await cartService.GetAsync(customer.Id);\n\n foreach (CartItem cartItem in cart.Items)\n {\n // Uh-oh... what if two requests hit this at the same time?\n TicketType ticketType = await ticketTypeRepository.GetAsync(\n cartItem.TicketTypeId);\n\n ticketType.UpdateQuantity(cartItem.Quantity);\n\n order.AddItem(ticketType, cartItem.Quantity, cartItem.Price);\n }\n\n orderRepository.Insert(order);\n\n await unitOfWork.SaveChangesAsync();\n\n await transaction.CommitAsync();\n\n await cartService.ClearAsync(customer.Id);\n}\nThe example above is contrived, but it should be enough to explain the problem.\nDuring checkout, we verify the AvailableQuantity for each ticket.
What will happen if we get concurrent requests trying to purchase the same ticket?
\nThe worst-case scenario is we end up "overselling" the tickets.\nConcurrent requests could see available tickets for sale and complete the checkout.
\nSo, how do we solve this?
\nSince EF Core doesn't offer pessimistic locking directly, we'll dip into a bit of good old-fashioned SQL.\nWe will replace the GetAsync call to fetch the ticket with GetWithLockAsync.
Thankfully, EF Core makes this easy with raw SQL queries:
\npublic async Task<TicketType> GetWithLockAsync(Guid id)\n{\n return await context\n .TicketTypes\n .FromSql(\n $@"\n SELECT id, event_id, name, price, currency, quantity\n FROM ticketing.ticket_types\n WHERE id = {id}\n FOR UPDATE NOWAIT") // PostgreSQL: Lock or fail immediately\n .SingleAsync();\n}\nUnderstanding the magic:
\nFOR UPDATE NOWAIT: This is the heart of pessimistic locking in PostgreSQL.\nIt tells the database "Grab this row, lock it for me, and if it's already locked, raise an error right now."GetWithLockAsync call in a try-catch block to gracefully handle locking failures, either retrying or notifying the user.Since there isn't a built-in way in EF Core to add query hints, we have to write raw SQL queries.\nWe can use the PostgreSQL SELECT FOR UPDATE statement to acquire a row-level lock on the selected rows.\nAny competing transactions will be blocked until the current transaction releases the lock.\nThis is a very simple way to implement pessimistic locking.
To prevent the operation from waiting for other transactions to release any locked rows, you can combine FOR UPDATE with:
NO WAIT - Reports an error if the row can't be locked instead of waiting.SKIP LOCKED - Skips any selected rows that cannot be locked.Skipping locked rows comes with a caveat - you will get inconsistent results from the database.\nHowever, this can be useful to avoid lock contention when multiple consumers access a queue-like table.\nImplementing the Outbox pattern is a great example of this.
\nSQL Server: You'd use the WITH (UPDLOCK, READPAST) query hint for a similar effect.
Serializable transactions offer the highest level of data consistency.\nThey guarantee that all transactions are executed as if they happened in a strict, sequential order, even if they occur simultaneously.\nThis eliminates the possibility of anomalies like dirty reads (seeing uncommitted data) or non-repeatable reads (data changing between reads).
\nHere's how it works:
\nWhile Serializable transactions provide the ultimate isolation, they come with a significant cost:
\nPessimistic locking with SELECT FOR UPDATE offers a more targeted approach to data isolation.\nYou explicitly lock the specific rows you need to modify.\nOther transactions attempting to access the locked rows are blocked until the lock is released.
By locking only the necessary data, pessimistic locking avoids the performance overhead associated with locking everything.\nSince you're locking fewer resources, the chances of deadlocks are lower.
\nThe best approach depends on your specific needs:
\nI hope this exploration of pessimistic locking has been helpful.\nIt's a powerful tool to have in your arsenal if you have scenarios where absolute data consistency is paramount.
\nBoth Serializable transactions and pessimistic locking with SELECT FOR UPDATE are excellent options for ensuring data consistency.\nConsider the level of isolation required, potential performance impact, and the likelihood of deadlocks when making your choice.
That's all for today. Stay awesome, and I'll see you next week.
\nClaims transformation modifies the claims of the current ClaimsPrincipal before ASP.NET Core uses them for authorization.\nIt bridges the gap between the claims your identity provider issues in the access token and the claims your application needs for its internal authorization logic.\nYou implement it with the IClaimsTransformation interface.
Claims-based authorization mechanisms are central to modern authorization in ASP.NET Core.\nHowever, the access tokens issued by your Identity Provider (IDP) might not always perfectly align with your application's internal authorization needs.
\nExternal IDPs like Microsoft Entra ID (previously Azure AD) or\nAuth0 might have their own schema for claims or might not directly issue all the claims your application needs for its authorization logic.
\nThe solution? Claims transformation.
\nClaims transformation allows you to modify the claims before the application uses them for authorization.
\nIn today's issue, we will:
\nIClaimsTransformation interface with practical examplesThey say a picture is worth a thousand words.\nIn software engineering, we have something called UML diagrams that we can use to paint a picture.
\nHere's a sequence diagram showing the claims transformation flow:
\n![\"Claims](\"https://milanjovanovic.tech/blogs/mnw_084/claims_transformation_sequence_diagram.png\")
\nLet's see how to implement this in ASP.NET Core.
\nClaims can be created from any user or identity data issued by a trusted identity provider.\nA claim is a name-value pair that represents the subject's identity, not what the subject can do.
\nThe core of claims transformation\nin ASP.NET Core is the IClaimsTransformation interface.
It exposes a single method to transform claims:
\npublic interface IClaimsTransformation\n{\n Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal);\n}\nHere's a simple example of using IClaimsTransformation to add a custom claim:
internal static class CustomClaims\n{\n internal const string CardType = "card_type";\n}\n\ninternal sealed class CustomClaimsTransformation : IClaimsTransformation\n{\n public Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)\n {\n if (principal.HasClaim(claim => claim.Type == CustomClaims.CardType))\n {\n return Task.FromResult(principal);\n }\n\n ClaimsIdentity claimsIdentity = new ClaimsIdentity();\n\n claimsIdentity.AddClaim(new Claim(CustomClaims.CardType, "platinum"));\n\n principal.AddIdentity(claimsIdentity);\n\n return Task.FromResult(principal);\n }\n}\nThe CustomClaimsTransformation class should be registered as a service:
builder.Services\n .AddTransient<IClaimsTransformation, CustomClaimsTransformation>();\nFinally, you can define a custom authorization policy that uses this claim:
\nbuilder.Services.AddAuthorization(options =>\n{\n options.AddPolicy(\n "HasPlatinumCard",\n builder => builder\n .RequireAuthenticatedUser()\n .RequireClaim(CustomClaims.CardType, "platinum"));\n});\nThere are a few caveats with using IClaimsTransformation you should be aware of:
TransformAsync method might get called multiple times.\nClaims transformation should be idempotent to avoid adding the same claim multiple times to the ClaimsPrincipal.Role-Based Access Control (RBAC) is an authorization model where permissions are assigned to roles,\nand users are granted roles.\nClaims transformation helps implement RBAC smoothly.\nBy adding role claims and potentially permission claims, authorization logic throughout your application can be simplified.\nAnother benefit is that you can keep the access token smaller and free of any role or permission claims.
\nLet's consider a scenario where your application manages resources at a granular level,\nbut your identity provider only provides coarse-grained roles like Registered or Member.\nYou could use claims transformation to map the Member role to specific fine-grained permissions like SubmitOrder and PurchaseTicket.
Here's a more complex CustomClaimsTransformation implementation.\nWe send a database query using GetUserPermissionsQuery and get the PermissionsResponse back.\nThe PermissionsResponse contains the user's permissions, which are added as custom claims.
internal sealed class CustomClaimsTransformation(\n IServiceProvider serviceProvider)\n : IClaimsTransformation\n{\n public async Task<ClaimsPrincipal> TransformAsync(\n ClaimsPrincipal principal)\n {\n if (principal.HasClaim(c => c.Type == CustomClaims.Sub ||\n c.Type == CustomClaims.Permission))\n {\n return principal;\n }\n\n using IServiceScope scope = serviceProvider.CreateScope();\n\n ISender sender = scope.ServiceProvider.GetRequiredService<ISender>();\n\n string identityId = principal.GetIdentityId();\n\n Result<PermissionsResponse> result = await sender.Send(\n new GetUserPermissionsQuery(identityId));\n\n if (result.IsFailure)\n {\n throw new ClaimsAuthorizationException(\n nameof(GetUserPermissionsQuery), result.Error);\n }\n\n var claimsIdentity = new ClaimsIdentity();\n\n claimsIdentity.AddClaim(\n new Claim(CustomClaims.Sub, result.Value.UserId.ToString()));\n\n foreach (string permission in result.Value.Permissions)\n {\n claimsIdentity.AddClaim(\n new Claim(CustomClaims.Permission, permission));\n }\n\n principal.AddIdentity(claimsIdentity);\n\n return principal;\n }\n}\nNow that the ClaimsPrincipal contains the permissions as custom claims, you can do some interesting things.\nFor example, you can implement a permission-based AuthorizationHandler:
internal sealed class PermissionAuthorizationHandler\n : AuthorizationHandler<PermissionRequirement>\n{\n protected override Task HandleRequirementAsync(\n AuthorizationHandlerContext context,\n PermissionRequirement requirement)\n {\n HashSet<string> permissions = context.User.GetPermissions();\n\n if (permissions.Contains(requirement.Permission))\n {\n context.Succeed(requirement);\n }\n\n return Task.CompletedTask;\n }\n}\nClaims transformation is an elegant way to bridge the gap between claims provided by identity providers and the needs of your ASP.NET Core application.\nThe IClaimsTransformation interface enables you to customize the claims of the current ClaimsPrincipal.\nWhether you need to add roles, map external groups to internal permissions, or extract additional information from a user profile,\nclaims transformation offers the flexibility to do so.
However, it's important to use claims transformation with a few key considerations in mind:
\nIClaimsTransformation should be idempotent. It should not add existing claims to the ClaimsPrincipal if executed multiple times.If you want to see a complete implementation of RBAC in ASP.NET Core, check out this Authentication & Authorization playlist.
\nHope this was helpful.
\nSee you next week.
\nYou can horizontally scale an ASP.NET Core API by running multiple instances behind YARP, Microsoft's reverse proxy library, and letting a load balancing policy like RoundRobin distribute the traffic.\nIn the k6 test from this issue, going from 1 to 5 API instances cut the average request duration from 9.68 ms to 4.65 ms and raised throughput from 2260 to 3881 requests per second.
Modern web applications need to serve increasing numbers of users and handle surges in traffic.\nWhen a single server reaches its limits, performance degrades, leading to slow response times, errors, or complete downtime.
\nLoad balancing is a key technique to address these challenges and improve the scalability of your application.
\nIn this article, we will explore:
\nWe'll dive into load balancing, why it matters, and how YARP simplifies the process for .NET applications.
\nBefore exploring YARP and load balancing further, let's cover the fundamentals of scaling.
\nThere are two main approaches:
\nHorizontal scaling is where load balancing comes in, and YARP shines bright in this approach.
\nYARP is a high-performance reverse proxy library from Microsoft.\nIt's designed with modern microservice architectures in mind.\nA reverse proxy sits in front of your backend servers, acting as a traffic director.
\nSetting up YARP is quite straightforward.\nYou'll install the YARP NuGet package, create a basic configuration to define your backend destinations, and then activate the YARP middleware.\nYARP allows you to perform routing and transformation tasks on incoming requests before they reach your backend servers.
\nFirst, let's install the Yarp.ReverseProxy NuGet package:
Install-Package Yarp.ReverseProxy\nThen, we're going to configure the required application services and introduce the YARP middleware to the request pipeline:
\nvar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddReverseProxy()\n .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));\n\nvar app = builder.Build();\n\napp.MapReverseProxy();\n\napp.Run();\nAll that's left is adding the YARP configuration to our appsettings.json file.\nYARP uses Routes to represent incoming requests to the reverse proxy and Clusters to define the downstream services.\nThe {**catch-all} pattern allows us to easily route all incoming requests.
{\n "ReverseProxy": {\n "Routes": {\n "api-route": {\n "ClusterId": "api-cluster",\n "Match": {\n "Path": "{**catch-all}"\n },\n "Transforms": [{ "PathPattern": "{**catch-all}" }]\n }\n },\n "Clusters": {\n "api-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "http://api:8080"\n }\n }\n }\n }\n }\n}\nThis configures YARP as a pass-through proxy, but let's update it to support horizontal scaling.
\nThe core of horizontal scaling with YARP lies in its various load balancing strategies:
\nPowerOfTwoChoices: Selects two random destinations and selects the one with the least assigned requests.FirstAlphabetical: Selects the alphabetically first available destination server.LeastRequests: Sends requests to servers with the least assigned requests.RoundRobin: Distributes requests evenly across backend servers.Random: Randomly selects a backend server for each request.You configure these strategies within YARP's configuration file.\nThe load balancing strategy can be configured using the LoadBalancingPolicy property on the cluster.
Here's what the updated YARP configuration looks like with RoundRobin load balancing:
{\n "ReverseProxy": {\n "Routes": {\n "api-route": {\n "ClusterId": "api-cluster",\n "Match": {\n "Path": "{**catch-all}"\n },\n "Transforms": [{ "PathPattern": "{**catch-all}" }]\n }\n },\n "Clusters": {\n "api-cluster": {\n "LoadBalancingPolicy": "RoundRobin",\n "Destinations": {\n "destination1": {\n "Address": "http://api-1:8080"\n },\n "destination2": {\n "Address": "http://api-2:8080"\n },\n "destination3": {\n "Address": "http://api-3:8080"\n }\n }\n }\n }\n }\n}\nHere's a diagram of what our system could look like with a YARP load balancer and horizontally scaled application servers.
\nThe incoming API requests will first hit YARP, distributing the traffic to the application servers based on the load balancing strategy.\nIn this example, there's one database serving multiple application instances.
\n![\"Horizontal](\"https://milanjovanovic.tech/blogs/mnw_083/horizontal_scaling.png\")
\nAnd now, let's do some performance testing.
\nTo see the impact of our horizontal scaling efforts, we need to do some load testing.\nK6 is a modern, developer-friendly load testing tool.\nWe'll write K6 scripts to simulate user traffic on our application and compare metrics like average response time and the number of successful requests per second.
\nThe application we're going to scale horizontally has two API endpoints.\nThe POST /users endpoint creates a new user, saves the user to a PostgreSQL database, and returns the user's identifier.\nThe GET /users/id endpoint returns a user with the given identifer if it exists.
Here's a k6 performance test that will:
\nPOST request to the /users endpoint201 CreatedGET request to the /users/{id} endpoint200 OKNote that all API requests go through the YARP load balancer.
\nimport { check } from 'k6';\nimport http from 'k6/http';\n\nexport const options = {\n stages: [\n { duration: '10s', target: 20 },\n { duration: '1m40s', target: 20 },\n { duration: '10s', target: 0 }\n ]\n};\n\nexport default function () {\n const proxyUrl = 'http://localhost:3000';\n\n const response = http.post(`${proxyUrl}/users`);\n\n check(response, {\n 'response code was 201': (res) => res.status == 201\n });\n\n const userResponse = http.get(`${proxyUrl}/users/${response.body}`);\n\n check(userResponse, {\n 'response code was 200': (res) => res.status == 200\n });\n}\nTo make the performance testing results more consistent, we can limit the available resources on the Docker containers to 1 CPU and 0.5G of RAM.
services:\n api:\n image: ${DOCKER_REGISTRY-}loadbalancingapi\n cpus: 1\n mem_limit: '0.5G'\n ports:\n - 5000:8080\n networks:\n - proxybackend\nFinally, here are the k6 performance testing results:
\n| API Instances | Request Duration | Requests Per Second |\n|------------------- |------------------------- |---------------------------:\n| 1 | 9.68 ms | 2260/s |\n|--------------------|------------------------- |---------------------------|\n| 2 | 6.57 ms | 2764/s |\n|--------------------|------------------------- |---------------------------|\n| 3 | 5.62 ms | 3227/s |\n|--------------------|------------------------- |---------------------------|\n| 5 | 4.65 ms | 3881/s |\nHorizontal scaling, coupled with effective load balancing, can significantly enhance the performance and scalability of your web applications.\nThe benefits of horizontal scaling become especially apparent in high-traffic scenarios where a single server can no longer cope with the demand.
\nYARP is a powerful and user-friendly reverse proxy server for .NET applications.\nHowever, highly complex, large-scale distributed systems might benefit from specialized, standalone load-balancing solutions.\nThese dedicated solutions can offer more granular control and sophisticated features.
\nIf you want to learn more, here's how to build an API Gateway using YARP.
\nYou can find the source code for this example on GitHub.
\nThat's all for today. I'll see you next week.
\nThe fastest way to bulk insert with EF Core depends on your requirements.\nEFCore.BulkExtensions and Entity Framework Extensions bypass EF's change tracker and generate optimized SQL, while SqlBulkCopy is typically the fastest option for SQL Server.\nIn this issue, I benchmark them against Dapper and EF Core's built-in batching, from 100 to 1,000,000 records.
Whether you're building a data analytics platform, migrating a legacy system, or onboarding a surge of new users,\nthere will likely come a time when you'll need to insert a massive amount of data into your database.
\nInserting the records one by one feels like watching paint dry in slow motion.\nTraditional methods won't cut it.
\nSo, understanding fast bulk insert techniques with C# and EF Core becomes essential.
\nIn today's issue, we'll explore several options for performing bulk inserts in C#:
\nThe examples are based on a User class with a respective Users table in SQL Server.
public class User\n{\n public int Id { get; set; }\n public string Email { get; set; }\n public string FirstName { get; set; }\n public string LastName { get; set; }\n public string PhoneNumber { get; set; }\n}\nThis isn't a complete list of bulk insert implementations.\nThere are a few options I didn't explore, like manully generating SQL statements\nand using Table-Valued parameters.
\nWhen working with large datasets, standard EF Core patterns quickly become a bottleneck.\nUsing Add and SaveChanges for thousands of records means EF tracks every entity in memory\nand generates individual SQL INSERT statements, each requiring its own round trip to the database.
EF Core bulk insert techniques solve this by taking one of two approaches:\neither batching many INSERT statements into a single network round trip (the built-in AddRange),\nor bypassing EF's change tracker entirely and streaming data using the database's native bulk copy protocol\n(like SQL Server's SqlBulkCopy).\nThe result can reduce insert time from minutes to seconds for large datasets.
Let's start with a simple example using EF Core.\nWe're creating an ApplicationDbContext instance, adding a User object, and calling SaveChangesAsync.\nThis will insert each record to the database one by one.\nIn other words, each record requires one round trip to the database.
using var context = new ApplicationDbContext();\n\nforeach (var user in GetUsers())\n{\n context.Users.Add(user);\n\n await context.SaveChangesAsync();\n}\nThe results are as poor as you'd expect:
\nEF Core - Add one and save, for 100 users: 20 ms\nEF Core - Add one and save, for 1,000 users: 260 ms\nEF Core - Add one and save, for 10,000 users: 8,860 ms\nI omitted the results with 100,000 and 1,000,000 records because they took too long to execute.
We'll use this as a "how not to do bulk inserts" example.
\nDapper is a simple SQL-to-object mapper for .NET.\nIt allows us to easily insert a collection of objects into the database.
\nI'm using Dapper's feature to unwrap a collection into a SQL INSERT statement.
using var connection = new SqlConnection(connectionString);\nconnection.Open();\n\nconst string sql =\n @"\n INSERT INTO Users (Email, FirstName, LastName, PhoneNumber)\n VALUES (@Email, @FirstName, @LastName, @PhoneNumber);\n ";\n\nawait connection.ExecuteAsync(sql, GetUsers());\nThe results are much better than the initial example:
\nDapper - Insert range, for 100 users: 10 ms\nDapper - Insert range, for 1,000 users: 113 ms\nDapper - Insert range, for 10,000 users: 1,028 ms\nDapper - Insert range, for 100,000 users: 10,916 ms\nDapper - Insert range, for 1,000,000 users: 109,065 ms\nHowever, EF Core still didn't throw in the towel.\nThe first example was poorly implemented on purpose.\nEF Core can batch multiple SQL statements together, so let's use that.
\nIf we make a simple change, we can get significantly better performance.\nFirst, we're adding all the objects to the ApplicationDbContext.\nThen, we're going to call SaveChangesAsync only once.
EF will create a batched SQL statement - group many INSERT statements together - and send them to the database together.\nThis reduces the number of round trips to the database, giving us improved performance.
using var context = new ApplicationDbContext();\n\nforeach (var user in GetUsers())\n{\n context.Users.Add(user);\n}\n\nawait context.SaveChangesAsync();\nHere are the benchmark results of this implementation:
\nEF Core - Add all and save, for 100 users: 2 ms\nEF Core - Add all and save, for 1,000 users: 18 ms\nEF Core - Add all and save, for 10,000 users: 203 ms\nEF Core - Add all and save, for 100,000 users: 2,129 ms\nEF Core - Add all and save, for 1,000,000 users: 21,557 ms\nRemember, it took Dapper 109 seconds to insert 1,000,000 records.\nWe can achieve the same with EF Core batched queries in ~21 seconds.
This is an alternative to the previous example.\nInstead of calling Add for all objects, we can call AddRange and pass in a collection.
I wanted to show this implementation because I prefer it over the previous one.
\nusing var context = new ApplicationDbContext();\n\ncontext.Users.AddRange(GetUsers());\n\nawait context.SaveChangesAsync();\nThe results are very similar to the previous example:
\nEF Core - Add range and save, for 100 users: 2 ms\nEF Core - Add range and save, for 1,000 users: 18 ms\nEF Core - Add range and save, for 10,000 users: 204 ms\nEF Core - Add range and save, for 100,000 users: 2,111 ms\nEF Core - Add range and save, for 1,000,000 users: 21,605 ms\nThere's an awesome library called EF Core Bulk Extensions that we can use to squeeze out more performance.\nYou can do a lot more than bulk inserts with this library, so it's worth exploring.\nThis library is open source, and has a community license if you meet the free usage criteria.\nCheck the licensing section for more details.
\nFor our use case, the BulkInsertAsync method is an excellent choice.\nWe can pass the collection of objects, and it will perform an SQL bulk insert.
using var context = new ApplicationDbContext();\n\nawait context.BulkInsertAsync(GetUsers());\nThe performance is equally amazing:
\nEF Core - Bulk Extensions, for 100 users: 1.9 ms\nEF Core - Bulk Extensions, for 1,000 users: 8 ms\nEF Core - Bulk Extensions, for 10,000 users: 76 ms\nEF Core - Bulk Extensions, for 100,000 users: 742 ms\nEF Core - Bulk Extensions, for 1,000,000 users: 8,333 ms\nFor comparison, we needed ~21 seconds to insert 1,000,000 records with EF Core batched queries.\nWe can do the same with the Bulk Extensions library in just 8 seconds.
If we can't get the desired performance from EF Core, we can try using SqlBulkCopy.\nSQL Server supports bulk copy operations natively, so let's use this.
This implementation is slightly more complex than the EF Core examples.\nWe need to configure the SqlBulkCopy instance and create a DataTable containing the objects we want to insert.
using var bulkCopy = new SqlBulkCopy(ConnectionString);\n\nbulkCopy.DestinationTableName = "dbo.Users";\n\nbulkCopy.ColumnMappings.Add(nameof(User.Email), "Email");\nbulkCopy.ColumnMappings.Add(nameof(User.FirstName), "FirstName");\nbulkCopy.ColumnMappings.Add(nameof(User.LastName), "LastName");\nbulkCopy.ColumnMappings.Add(nameof(User.PhoneNumber), "PhoneNumber");\n\nawait bulkCopy.WriteToServerAsync(GetUsersDataTable());\nHowever, the performance is blazing fast:
\nSQL Bulk Copy, for 100 users: 1.7 ms\nSQL Bulk Copy, for 1,000 users: 7 ms\nSQL Bulk Copy, for 10,000 users: 68 ms\nSQL Bulk Copy, for 100,000 users: 646 ms\nSQL Bulk Copy, for 1,000,000 users: 7,339 ms\nHere's how you can create a DataTable and populate it with a list of objects:
DataTable GetUsersDataTable()\n{\n var dataTable = new DataTable();\n\n dataTable.Columns.Add(nameof(User.Email), typeof(string));\n dataTable.Columns.Add(nameof(User.FirstName), typeof(string));\n dataTable.Columns.Add(nameof(User.LastName), typeof(string));\n dataTable.Columns.Add(nameof(User.PhoneNumber), typeof(string));\n\n foreach (var user in GetUsers())\n {\n dataTable.Rows.Add(\n user.Email, user.FirstName, user.LastName, user.PhoneNumber);\n }\n\n return dataTable;\n}\nCan we do better than SqlBulkCopy?
Maybe, at least my benchmark results suggest that we can.
\nThere's another awesome library called Entity Framework Extensions.\nIt's much more than just a bulk insert library - so I highly recommend checking it out.\nHowever, we'll use it for bulk inserts today.
\nFor our use case, the BulkInsertOptimizedAsync method is an excellent choice.\nWe can pass the collection of objects, and it will perform an SQL bulk insert.\nIt'll also do some optimizations under the hood to improve performance.
using var context = new ApplicationDbContext();\n\nawait context.BulkInsertOptimizedAsync(GetUsers());\nThe performance is nothing short of amazing:
\nEF Core - Entity Framework Extensions, for 100 users: 1.86 ms\nEF Core - Entity Framework Extensions, for 1,000 users: 6.9 ms\nEF Core - Entity Framework Extensions, for 10,000 users: 66 ms\nEF Core - Entity Framework Extensions, for 100,000 users: 636 ms\nEF Core - Entity Framework Extensions, for 1,000,000 users: 7,106 ms\nNot all bulk insert options are equal. Here's a comparison to help you choose the right approach:
\n| Method | Relative Speed | EF Core Integration | Database Support | License |\n| ------------------------------------------------------ | -------------- | --------------------------- | ------------------ | ---------------- |\n| EF Core `AddRange` + `SaveChanges` | Medium | Full (change tracking) | All EF providers | Free |\n| Dapper `ExecuteAsync` | Medium | None | Any ADO.NET | Free |\n| EFCore.BulkExtensions `BulkInsertAsync` | Fast | Partial (bypasses tracking) | Multiple providers | Free (community) |\n| `SqlBulkCopy` | Fastest | None | SQL Server only | Free |\n| Entity Framework Extensions `BulkInsertOptimizedAsync` | Fastest | Partial (bypasses tracking) | Multiple providers | Commercial |\nEF Core AddRange is the simplest option and works out of the box, but it goes through the change tracker, making it slower for large datasets.
Dapper is a good fit if you're already using it in your stack, but it doesn't integrate with your EF Core context.
\nEFCore.BulkExtensions hits a sweet spot: near-SqlBulkCopy speed, works with your existing DbContext, and is open source.
SqlBulkCopy is the raw speed champion for SQL Server but requires boilerplate DataTable setup and is SQL Server-only.
Entity Framework Extensions matches SqlBulkCopy performance with EF Core integration, but requires a commercial license.
Choose the right method based on your scenario:
\n| Scenario | Recommended Method |\n| --------------------------------------------------------------------- | ---------------------------------- |\n| Small datasets (under 1,000 rows) | EF Core `AddRange` + `SaveChanges` |\n| Medium datasets with existing Dapper infrastructure | Dapper `ExecuteAsync` |\n| Large datasets, open-source required, EF Core codebase | `EFCore.BulkExtensions` |\n| Maximum speed, SQL Server only | `SqlBulkCopy` |\n| Maximum speed with EF Core integration, commercial license acceptable | Entity Framework Extensions |\n| PostgreSQL, MySQL, or other non-SQL Server databases | `EFCore.BulkExtensions` |\nHere are the results for all the bulk insert implementations:
\n| Method | Size | Speed\n|------------------- |----------- |----------------:\n| EF_OneByOne | 100 | 19.800 ms |\n| EF_OneByOne | 1000 | 259.870 ms |\n| EF_OneByOne | 10000 | 8,860.790 ms |\n| EF_OneByOne | 100000 | N/A |\n| EF_OneByOne | 1000000 | N/A |\n\n| Dapper_Insert | 100 | 10.650 ms |\n| Dapper_Insert | 1000 | 113.137 ms |\n| Dapper_Insert | 10000 | 1,027.979 ms |\n| Dapper_Insert | 100000 | 10,916.628 ms |\n| Dapper_Insert | 1000000 | 109,064.815 ms |\n\n| EF_AddAll | 100 | 2.064 ms |\n| EF_AddAll | 1000 | 17.906 ms |\n| EF_AddAll | 10000 | 202.975 ms |\n| EF_AddAll | 100000 | 2,129.370 ms |\n| EF_AddAll | 1000000 | 21,557.136 ms |\n\n| EF_AddRange | 100 | 2.035 ms |\n| EF_AddRange | 1000 | 17.857 ms |\n| EF_AddRange | 10000 | 204.029 ms |\n| EF_AddRange | 100000 | 2,111.106 ms |\n| EF_AddRange | 1000000 | 21,605.668 ms |\n\n| BulkExtensions | 100 | 1.922 ms |\n| BulkExtensions | 1000 | 7.943 ms |\n| BulkExtensions | 10000 | 76.406 ms |\n| BulkExtensions | 100000 | 742.325 ms |\n| BulkExtensions | 1000000 | 8,333.950 ms |\n\n| BulkCopy | 100 | 1.721 ms |\n| BulkCopy | 1000 | 7.380 ms |\n| BulkCopy | 10000 | 68.364 ms |\n| BulkCopy | 100000 | 646.219 ms |\n| BulkCopy | 1000000 | 7,339.298 ms |\n\n| EF Extensions | 100 | 1.860 ms |\n| EF Extensions | 1000 | 6.923 ms |\n| EF Extensions | 10000 | 68.106 ms |\n| EF Extensions | 100000 | 636.231 ms |\n| EF Extensions | 1000000 | 7,106.891 ms |\nSqlBulkCopy holds the crown for maximum raw speed and simplicity.\nHowever, Entity Framework Extensions\ndeliver fantastic performance while maintaining the ease of use that EF Core is known for.
The best choice hinges on your project's specific demands:
\nSqlBulkCopy is your solution.I leave it up to you to decide which option is best for your use case.
\nHope this was helpful.
\nSee you next week.
\nA soft delete marks a record as deleted with a flag like IsDeleted instead of removing it, so the row stays in the database and can be restored later.\nIn EF Core you implement it with a SaveChangesInterceptor that turns deletes into updates, plus a global query filter that hides the flagged rows from every query.
To delete or not to delete, that is the question (pun intended).
\nThe traditional way to remove information in a database is through a "hard delete."\nA hard delete permanently erases a record from the database table.\nWhile this seems straightforward, it presents a significant risk: once that data is gone, it's gone for good.
\nInstead of physically removing a record, a soft delete marks it as deleted, usually by setting a flag like IsDeleted to true.\nThe record remains in the database, but it's effectively hidden from regular application queries.
Today, we'll dive into the details of how to implement soft deletes using EF Core.\nWe'll discuss global query filters, explore efficient ways to handle soft-deleted data, and weigh the trade-offs.
\nA soft delete is a data persistence strategy that prevents the permanent deletion of records from your database.\nInstead of removing data from the database, a flag is set on the record, indicating it as "deleted."
\nThis approach allows the application to ignore these records during normal queries.\nHowever, you can restore these records if necessary.\nSoft delete is also practical if you want to keep foreign key constraints in place.\nSoft delete is a "non-destructive" operation in contrast with hard delete, where data is completely removed from the database.
\nA hard delete uses the SQL DELETE statement:
DELETE FROM bookings.Reviews\nWHERE Id = @BookingId;\nA soft delete, on the other hand, uses an UPDATE statement:
UPDATE bookings.Reviews\nSET IsDeleted = 1, DeletedOnUtc = @UtcNow\nWHERE Id = @BookingId;\nThe data is still present in the database, and the operation can be undone.
\nBut you need to remember to filter out soft-deleted data when querying the database:
\nSELECT *\nFROM bookings.Reviews\nWHERE IsDeleted = 0;\nLet's see how we can implement soft delete with EF Core.
\nEF Core interceptors\nprovide a powerful mechanism for intercepting and modifying database operations.\nFor example, you can intercept the saving changes operation to implement soft delete functionality.
\nLet's create an ISoftDeletable marker interface to represent soft-deletable entities:
public interface ISoftDeletable\n{\n bool IsDeleted { get; set; }\n\n DateTime? DeletedOnUtc { get; set; }\n}\nThe entities that should support soft delete will implement this interface.\nYou will need to apply the respective database migration to create these columns.
\nThe next component we need is a SaveChangesInterceptor, which allows us to hook into the SavingChangesAsync (or SavingChanges) method.\nWe can access the ChangeTracker and look for entries that implement ISoftDeletable and are flagged for deletion.\nWe can figure this out by checking if the entity state is EntityState.Deleted.
When we find the entities flagged for deletion, we loop through them and update their state to EntityState.Modified.\nYou should also set the respective values for the IsDeleted and DeletedOnUtc properties.\nThis will cause EF to generate an UPDATE operation instead of a DELETE operation.
public sealed class SoftDeleteInterceptor : SaveChangesInterceptor\n{\n public override ValueTask<InterceptionResult<int>> SavingChangesAsync(\n DbContextEventData eventData,\n InterceptionResult<int> result,\n CancellationToken cancellationToken = default)\n {\n if (eventData.Context is null)\n {\n return base.SavingChangesAsync(\n eventData, result, cancellationToken);\n }\n\n IEnumerable<EntityEntry<ISoftDeletable>> entries =\n eventData\n .Context\n .ChangeTracker\n .Entries<ISoftDeletable>()\n .Where(e => e.State == EntityState.Deleted);\n\n foreach (EntityEntry<ISoftDeletable> softDeletable in entries)\n {\n softDeletable.State = EntityState.Modified;\n softDeletable.Entity.IsDeleted = true;\n softDeletable.Entity.DeletedOnUtc = DateTime.UtcNow;\n }\n\n return base.SavingChangesAsync(eventData, result, cancellationToken);\n }\n}\nThis approach ensures that all delete operations across the application respect the soft delete policy.
\nYou'll need to register the SoftDeleteInterceptor with dependency injection and configure it with the ApplicationDbContext.
services.AddSingleton<SoftDeleteInterceptor>();\n\nservices.AddDbContext<ApplicationDbContext>(\n (sp, options) => options\n .UseSqlServer(connectionString)\n .AddInterceptors(\n sp.GetRequiredService<SoftDeleteInterceptor>()));\nIf you want to learn more, here's an article with a few practical use cases for EF Core interceptors.
\nTo ensure that soft-deleted records are automatically excluded from queries, we can use EF Core global query filters.\nWe can apply query filters to entities using the OnModelCreating method to automatically exclude records marked as deleted.\nThis feature dramatically simplifies writing queries.
Here's how to configure the soft delete query filter:
\npublic sealed class ApplicationDbContext(\n DbContextOptions<UsersDbContext> options) : DbContext(options)\n{\n public DbSet<Review> Reviews { get; set; }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.Entity<Review>().HasQueryFilter(r => !r.IsDeleted);\n }\n}\nA limitation is you can't have more than one query filter configured per entity.
\nHowever, it's sometimes useful to explicitly include soft-deleted records.\nYou can achieve this using the IgnoreQueryFilters method.
dbContex.Reviews\n .IgnoreQueryFilters()\n .Where(r => r.ApartmentId == apartmentId)\n .ToList();\nTo enhance query performance, especially in tables with a significant number of soft-deleted records, you can use filtered indexes.\nA filtered index only includes records that meet the specified criteria.\nThis reduces the index size and improves query execution times for operations that exclude filtered records.\nMost popular databases support filtered indexes.
\nHere's how you can configure a filtered index with EF Core:
\npublic sealed class ApplicationDbContext(\n DbContextOptions<UsersDbContext> options) : DbContext(options)\n{\n public DbSet<Review> Reviews { get; set; }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.Entity<Review>().HasQueryFilter(r => !r.IsDeleted);\n\n modelBuilder.Entity<Review>()\n .HasIndex(r => r.IsDeleted)\n .HasFilter("IsDeleted = 0");\n }\n}\nThe HasFilter method accepts the SQL filter for records that will be included in the index.
You can also create a filtered index using SQL:
\nCREATE INDEX IX_Reviews_IsDeleted\nON bookings.Reviews (IsDeleted)\nWHERE IsDeleted = 0;\nYou can learn more about filtered indexes from the documentation:
\n\nIt's worthwhile to think through if you even need to soft delete records.
\nIn enterprise systems, you're typically not thinking about "deleting" data.\nThere are business concepts that don't involve deleting data.\nA few examples are canceling an order, refunding a payment, or voiding an invoice.\nThese "destructive" operations return the system to a previous state.\nBut from a business perspective, you aren't really deleting data.
\nSoft deletes are helpful if there is a risk of accidental deletion.\nThey allow you to easily restore soft-deleted records.
\nIn any case, consider if soft deletes make sense from a business perspective.
\nSoft deletes offer a valuable safety net for data recovery and can enhance historical data tracking.\nHowever, it's crucial to assess whether they truly align with your application's specific requirements.\nConsider factors like the importance of deleted data recovery, any auditing needs, and your industry's regulations.\nCreating a filtered index can improve query performance on tables with soft-deleted records.
\nIf you decide that soft deletes are a good fit, EF Core provides the tools necessary for a streamlined implementation.
\nThanks for reading, and I'll see you next week!
\nA modular monolith is a single application organized into independent modules, each grouping related functionality behind a clear boundary.\nThe modules stay loosely coupled and communicate through public APIs, while the application still deploys as a single unit.\nYou get high cohesion and data encapsulation without the operational complexity of a distributed system.
\nI've worked with many different software architectures over the years.
\nThere's one that clearly stands out for its benefits: Modular Monolith architecture.
\nModular monoliths blend the simplicity and robustness of traditional monolithic applications with the flexibility and scalability of microservices.\nI'm tempted to say they bring together the best of both worlds.
\nThe modular monolith architecture allows you to work in a unified codebase with clearly defined boundaries and independent modules.\nYou can have a high development velocity without the complexity of distributed systems.
\nToday, I'll introduce you to the modular monolith architecture and why you should know about it.
\nA modular monolith is an architectural pattern that structures the application into independent modules or components with well-defined boundaries.\nThe modules are split based on logical boundaries, grouping together related functionalities.\nThis approach significantly improves the cohesion of the system.
\nThe modules are loosely coupled, which further promotes modularity and separation of concerns.\nModules communicate through a public API, and you can learn more about this in my article on modular monolith communication patterns.
\nBut what are the benefits of a modular design?
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_080/modular_monolith.png\")
\nIf we take the example of an apartment booking system illustrated above.\nDuring the holiday season, the system is expecting a traffic spike.\nThe bookings and payments modules need to scale so they can be deployed independently.\nAt the end of the holiday season, they can be merged back into a single deployment.\nModular monoliths give you this kind of flexibility.
\nModular monoliths introduce a few important technical challenges that we will need to solve.
\nTo achieve a modular architecture, the modules:
\nIs it possible for a module to be completely independent?\nNot really.\nThat would mean it's not integrated with other modules.\nWe want loosely coupled modules and to keep the number of dependencies low.\nWe can use a few techniques to keep the modules independent, and having good data isolation is one example.
\nAnother factor you need to consider is how strong the dependency is.\nIf two modules are very "chatty", you might have incorrectly defined the boundaries.\nYou should consider merging these modules together.
\nRemember, a module is a grouping of related functionalities accessed via a well-defined interface.
\nHaving a modular architecture allows you to easily extract modules into separate services.
\nMicroservices have become the most popular architectural pattern in recent years, and for good reason.\nMicroservices offer many benefits like clearly defined service boundaries, independent deployments, independent scalability, and much more.
\nHowever, most teams would be better off starting with a monolith application.
\nA monolith is an architectural pattern where all components are deployed as a single physical deployment unit.
\nHere's an interesting quote from Martin Fowler:
\n\n\n\nYou shouldn't start a new project with microservices, even if you're sure your application will be big enough to make it worthwhile.
\n
And I wholeheartedly agree with this. Better yet, consider starting with a modular monolith.
\nEven Google is jumping on board the modular monolith trend in their recent research paper, Towards Modern Development of Cloud Applications.
\nHere are the five main challenges Google identified with microservices:
\nWhen you factor in the complexity of distributed systems, starting with a modular monolith becomes increasingly compelling.\nI also recommend reading about the fallacies of distributed computing if you're unfamiliar with them.
\nWell-defined, in-process components (modules) can be an excellent stepping stone to out-of-process components (services).
\nModular monoliths have many benefits. So, I want to highlight a few that I consider important:
\nThe biggest difference between modular monoliths and microservices is how they're deployed.\nMicroservices elevate the logical boundaries inside a modular monolith into physical boundaries.
\nMicroservices give you a clear strategy for modularity and decomposing the bounded contexts.\nBut, you can also achieve this without building a distributed system.\nThe problem is people end up using microservices to enforce code boundaries.
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_080/modular_monolith_vs_microservices.png\")
\nInstead, you can build a modular monolith to get most of the same benefits.\nModular monoliths give you high cohesion, low coupling, data encapsulation, focus on business functionalities, and more.
\nMicroservices give you all that, plus independent deployments, independent scalability, and the ability to use different technology stacks per service.
\n\n\n\nChoose microservices for the benefits, not because your monolithic codebase is a mess.
\n
Modular monoliths offer a compelling way to structure applications.\nThey balance the benefits of well-organized code, scalability potential, and a smooth path for transitioning to microservices if needed.\nIf you want to improve the maintainability and adaptability of your software, consider exploring modular monoliths.
\nWant to dive deeper into modular monoliths? Check out these resources:
\nThat's all for today. Stay awesome, and I'll see you next week.
\nAn in-memory message bus passes messages between loosely coupled components inside the same process, giving you low latency and non-blocking communication.\nYou build one with System.Threading.Channels: an unbounded channel holds the integration events, an IEventBus writes to it, and a BackgroundService reads and dispatches them to handlers.\nMessages are lost if the process goes down.
Suppose you're building a modular monolith, a type of software architecture where different components are organized into loosely coupled modules.\nOr you might need to process data asynchronously.\nYou'll need a tool or service that allows you to implement this.
\nMessaging plays a crucial role in modern software architecture, enabling communication and coordination between loosely coupled components.
\nAn in-memory message bus is particularly useful when high performance and low latency are critical requirements.
\nIn today's issue, we will:
\nLet's dive in.
\nI have to preface this by saying that an in-memory message bus is far from a silver bullet.\nThere are many caveats to using it, as you will soon learn.
\nBut first, let's start with the pros of using an in-memory message bus:
\nHowever, there are a few drawbacks to this approach:
\nA practical use case for an in-memory message bus is when building a modular monolith.\nYou can implement communication between modules using integration events.\nWhen you need to extract some modules into a separate service, you can replace the in-memory bus with a distributed one.
\nWe will need a few abstractions to build our simple messaging system.\nFrom the client's perspective, we really only need two things.\nOne abstraction is to publish messages, and another is to define a message handler.
\nThe IEventBus interface exposes the PublishAsync method.\nThis is what we will use to publish messages.\nThere's also a generic constraint defined that only allows passing in an IIntegrationEvent instance.
public interface IEventBus\n{\n Task PublishAsync<T>(\n T integrationEvent,\n CancellationToken cancellationToken = default)\n where T : class, IIntegrationEvent;\n}\nI want to be practical with the IIntegrationEvent abstraction, so I'll use MediatR for the pub-sub support.\nThe IIntegrationEvent interface will inherit from INotification.\nThis allows us to easily define IIntegrationEvent handlers using INotificationHandler<T>.\nAlso, the IIntegrationEvent has an identifier, so we can track its execution.
The abstract IntegrationEvent serves as a base class for concrete implementations.
using MediatR;\n\npublic interface IIntegrationEvent : INotification\n{\n Guid Id { get; init; }\n}\n\npublic abstract record IntegrationEvent(Guid Id) : IIntegrationEvent;\nThe System.Threading.Channels namespace provides data structures for asynchronously passing messages between producers and consumers.\nChannels implement the producer/consumer pattern.\nProducers asynchronously produce data, and consumers asynchronously consume that data.\nIt's an essential pattern for building loosely coupled systems.
One of the primary motivations behind the adoption of .NET Channels\nis their exceptional performance characteristics.\nUnlike traditional message queues, Channels operate entirely in memory.\nThis has the disadvantage of the potential for message loss if the application crashes.
\nThe InMemoryMessageQueue creates an unbounded channel using the Channel.CreateUnbounded bounded.\nThis means the channel can have any number of readers and writers.\nIt also exposes a ChannelReader and ChannelWriter, which allow consumers to publish and consume messages.
internal sealed class InMemoryMessageQueue\n{\n private readonly Channel<IIntegrationEvent> _channel =\n Channel.CreateUnbounded<IIntegrationEvent>();\n\n public ChannelReader<IIntegrationEvent> Reader => _channel.Reader;\n\n public ChannelWriter<IIntegrationEvent> Writer => _channel.Writer;\n}\nYou also need to register the InMemoryMessageQueue as a singleton with dependency injection:
builder.Services.AddSingleton<InMemoryMessageQueue>();\nThe IEventBus implementation is now straightforward with the use of channels.\nThe EventBus class uses the InMemoryMessageQueue to access the ChannelWriter and write an event to the channel.
internal sealed class EventBus(InMemoryMessageQueue queue) : IEventBus\n{\n public async Task PublishAsync<T>(\n T integrationEvent,\n CancellationToken cancellationToken = default)\n where T : class, IIntegrationEvent\n {\n await queue.Writer.WriteAsync(integrationEvent, cancellationToken);\n }\n}\nWe will register the EventBus as a singleton service with dependency injection because it's stateless:
builder.Services.AddSingleton<IEventBus, EventBus>();\nWith the EventBus implementing the producer, we need a way to consume the published IIntegrationEvent.\nWe can implement a simple background service using the built-in IHostedService abstraction.
The IntegrationEventProcessorJob depends on the InMemoryMessageQueue, but this time for reading (consuming) messages.\nWe'll use the ChannelReader.ReadAllAsync method to get back an IAsyncEnumerable.\nThis allows us to consume all the messages in the Channel asynchronously.
The IPublisher from MediatR helps us connect the IIntegrationEvent with the respective handlers.\nIt's important to resolve it from a custom scope if you want to inject scoped services into the event handlers.
internal sealed class IntegrationEventProcessorJob(\n InMemoryMessageQueue queue,\n IServiceScopeFactory serviceScopeFactory,\n ILogger<IntegrationEventProcessorJob> logger)\n : BackgroundService\n{\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n await foreach (IIntegrationEvent integrationEvent in\n queue.Reader.ReadAllAsync(stoppingToken))\n {\n try\n {\n using IServiceScope scope = serviceScopeFactory.CreateScope();\n\n IPublisher publisher = scope.ServiceProvider\n .GetRequiredService<IPublisher>();\n\n await publisher.Publish(integrationEvent, stoppingToken);\n }\n catch (Exception ex)\n {\n logger.LogError(\n ex,\n "Something went wrong! {IntegrationEventId}",\n integrationEvent.Id);\n }\n }\n }\n}\nDon't forget to register the hosted service:
\nbuilder.Services.AddHostedService<IntegrationEventProcessorJob>();\nWith all of the necessary abstractions in place, we can finally use the in-memory message bus.
\nThe IEventBus service will write the message to the Channel and immediately return.\nThis allows you to publish messages in a non-blocking way, which can improve performance.
internal sealed class RegisterUserCommandHandler(\n IUserRepository userRepository,\n IEventBus eventBus)\n : ICommandHandler<RegisterUserCommand>\n{\n public async Task<User> Handle(\n RegisterUserCommand command,\n CancellationToken cancellationToken)\n {\n // First, register the user.\n User user = CreateFromCommand(command);\n\n userRepository.Insert(user);\n\n // Now we can publish the event.\n await eventBus.PublishAsync(\n new UserRegisteredIntegrationEvent(user.Id),\n cancellationToken);\n\n return user;\n }\n}\nThis solves the producer side, but we also need to create a consumer for the UserRegisteredIntegrationEvent message.\nThis part is greatly simplified because I'm using MediatR in this implementation.
We need to define an INotificationHandler implementation handling the integration event UserRegisteredIntegrationEvent.\nThis will be the UserRegisteredIntegrationEventHandler.
When the background job reads the UserRegisteredIntegrationEvent from the Channel, it will publish the message and execute the handler.
internal sealed class UserRegisteredIntegrationEventHandler\n : INotificationHandler<UserRegisteredIntegrationEvent>\n{\n public async Task Handle(\n UserRegisteredIntegrationEvent event,\n CancellationToken cancellationToken)\n {\n // Asynchronously handle the event.\n }\n}\nWhile our basic in-memory message bus is functional, there are several areas we can improve:
\nWe've covered the key aspects of building an in-memory message bus using .NET Channels.\nYou can extend this further by implementing the improvements for a more robust solution.
\nRemember that this implementation only works inside of one process.\nConsider using a real message broker if you need a more reliable solution.
\nThat's all for today. I'll see you next week.
\nDefine an IEndpoint interface with a single MapEndpoint method and implement it once per endpoint.\nScan the assembly with reflection, register every implementation with dependency injection, then call MapEndpoints at startup to map them all.\nYou can pass in a RouteGroupBuilder to apply a route prefix or API versioning to every endpoint.
In ASP.NET Core applications using Minimal APIs,\nregistering each API endpoint with app.MapGet, app.MapPost, etc., can introduce repetitive code.\nAs projects grow, this manual process becomes increasingly time-consuming and prone to maintenance headaches.
You can try grouping the Minimal API endpoints using extension methods so as not to clutter the Program file.\nThis approach scales well as the project grows.\nHowever, it feels like reinventing controllers.
I like to view each Minimal API endpoint as a standalone component.
\nThe vision I have in my mind aligns nicely with the concept of vertical slices.
\nToday, I'll show you how to register your Minimal APIs automatically with a simple abstraction.
\nAutomatically registering Minimal APIs significantly reduces boilerplate, streamlining development.\nIt makes your codebase more concise and improves maintainability by establishing a centralized registration mechanism.
\nLet's create a simple IEndpoint abstraction to represent a single endpoint.
The MapEndpoint accepts an IEndpointRouteBuilder, which we can use to call MapGet, MapPost, etc.
public interface IEndpoint\n{\n void MapEndpoint(IEndpointRouteBuilder app);\n}\nEach IEndpoint implementation should contain exactly one Minimal API endpoint definition.
Nothing prevents you from registering multiple endpoints in the MapEndpoint method.\nBut you (really) shouldn't.
Additionally, you could implement a code analyzer or architecture test to enforce this rule.
\npublic class GetFollowerStats : IEndpoint\n{\n public void MapEndpoint(IEndpointRouteBuilder app)\n {\n app.MapGet("users/{userId}/followers/stats", async (\n Guid userId,\n ISender sender) =>\n {\n var query = new GetFollowerStatsQuery(userId);\n\n Result<FollowerStatsResponse> result = await sender.Send(query);\n\n return result.Match(Results.Ok, CustomResults.Problem);\n })\n .WithTags(Tags.Users);\n }\n}\nReflection allows us to dynamically examine code at runtime.\nFor Minimal API registration, we'll use reflection to scan our .NET assemblies and find classes that implement IEndpoint.\nThen, we will configure them as services with dependency injection.
The Assembly parameter should be the assembly that contains the IEndpoint implementations.\nIf you want to have endpoints in multiple assemblies (projects), you can easily extend this method to accept a collection.
public static IServiceCollection AddEndpoints(\n this IServiceCollection services,\n Assembly assembly)\n{\n ServiceDescriptor[] serviceDescriptors = assembly\n .DefinedTypes\n .Where(type => type is { IsAbstract: false, IsInterface: false } &&\n type.IsAssignableTo(typeof(IEndpoint)))\n .Select(type => ServiceDescriptor.Transient(typeof(IEndpoint), type))\n .ToArray();\n\n services.TryAddEnumerable(serviceDescriptors);\n\n return services;\n}\nWe only need to call this method once from the Program file:
builder.Services.AddEndpoints(typeof(Program).Assembly);\nThe final step in our implementation is to register the endpoints automatically.\nWe can create an extension method on the WebApplication, which lets us resolve services using the IServiceProvider.
We're looking for all registrations of the IEndpoint service.\nThese will be the endpoint classes we can now register with the application by calling MapEndpoint.
I'm also adding an option to pass in a RouteGroupBuilder if you want to apply conventions to all endpoints.\nA great example is adding a route prefix, authentication, or API versioning.
public static IApplicationBuilder MapEndpoints(\n this WebApplication app,\n RouteGroupBuilder? routeGroupBuilder = null)\n{\n IEnumerable<IEndpoint> endpoints = app.Services\n .GetRequiredService<IEnumerable<IEndpoint>>();\n\n IEndpointRouteBuilder builder =\n routeGroupBuilder is null ? app : routeGroupBuilder;\n\n foreach (IEndpoint endpoint in endpoints)\n {\n endpoint.MapEndpoint(builder);\n }\n\n return app;\n}\nHere's what the Program file could look like when we put it all together.
We're calling AddEndpoints to register the IEndpoint implementations.
Then, we're calling MapEndpoints to automatically register the Minimal APIs.
I'm also configuring a route prefix and API Versioning for each endpoint using a RouteGroupBuilder.
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen();\n\nbuilder.Services.AddEndpoints(typeof(Program).Assembly);\n\nWebApplication app = builder.Build();\n\nApiVersionSet apiVersionSet = app.NewApiVersionSet()\n .HasApiVersion(new ApiVersion(1))\n .ReportApiVersions()\n .Build();\n\nRouteGroupBuilder versionedGroup = app\n .MapGroup("api/v{version:apiVersion}")\n .WithApiVersionSet(apiVersionSet);\n\napp.MapEndpoints(versionedGroup);\n\napp.Run();\nAutomatic Minimal API registration with techniques like reflection can significantly improve developer efficiency and project maintainability.
\nWhile highly beneficial, it's important to acknowledge the potential performance impact of reflection on application startup.
\nSo, an improvement point could be using source generators for pre-compiled registration logic.
\nA few alternatives worth exploring:
\n\nHope this was helpful.
\nSee you next week.
\nP.S. Here's the complete source code for this article.
\nASP.NET Core refuses to inject a scoped service into a singleton, so you inject IServiceScopeFactory instead, create a scope, and resolve the scoped service from that scope.\nThis is how you use an EF Core DbContext inside a background service.\nIn middleware, inject the scoped service as an InvokeAsync parameter so it shares the current request's scope.
Did you ever need to inject a scoped service into a singleton service?
\nI often need to resolve a scoped service, like the EF Core DbContext, in a background service.
Another example is when you need to resolve a scoped service in ASP.NET Core middleware.
\nIf you ever tried this, you were probably greeted with an exception similar to this one:
\nSystem.InvalidOperationException: Cannot consume scoped service 'Scoped' from singleton 'Singleton'.\nToday, I'll explain how you can solve this problem and safely use scoped services from within singletons in ASP.NET Core.
\nASP.NET Core has three service lifetimes:
\nTransient services are created each time they're requested from the service container.
\nScoped services are created once within the scope's lifetime.\nFor ASP.NET Core applications, a new scope is created for each request.\nThis is how you can resolve scoped services within a given request.
\nASP.NET Core applications also have a root IServiceProvider used to resolve singleton services.
So, what can we do if resolving a scoped service from a singleton throws an exception?
\nIServiceScopeFactoryWhat if you want to resolve a scoped service inside a background service?
\nYou can create a new scope (IServiceScope) with its own IServiceProvider instance.\nThe scoped IServiceProvider can be used to resolve scoped services.\nWhen the scope is disposed, all disposable services created within that scope are also disposed.
Here's an example of using the IServiceScopeFactory to create a new IServiceScope.\nWe're using the scope to resolve the ApplicationDbContext, which is a scoped service.
The BackgroundJob is registered as a singleton when calling AddHostedService<BackgroundJob>.
public class BackgroundJob(IServiceScopeFactory serviceScopeFactory)\n : BackgroundService\n{\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n using IServiceScope scope = serviceScopeFactory.CreateScope();\n\n var dbContext = scope\n .ServiceProvider\n .GetRequiredService<ApplicationDbContext>();\n\n // Do some background processing with the EF database context.\n await DoWorkAsync(dbContext);\n }\n}\nWhat if you want to use a scoped service in ASP.NET Core middleware?
\nMiddleware is constructed once per application lifetime.
\nIf you try injecting a scoped service, you'll get an exception:
\nSystem.InvalidOperationException: Cannot resolve scoped service 'Scoped' from root provider.\nThere are two ways to get around this.
\nFirst, you could use the previous approach with creating a new scope using IServiceScopeFactory.\nYou'll be able to resolve scoped services.\nBut, they won't share the same lifetime as the other scoped service in the same request.\nThis could even be a problem depending on your requirements.
Is there a better way?
\nMiddleware allows you to inject scoped services in the InvokeAsync method.\nThe injected services will use the current request's scope, so they'll have the same lifetime as any other scoped service.
public class ConventionalMiddleware(RequestDelegate next)\n{\n public async Task InvokeAsync(\n HttpContext httpContext,\n IMyScopedService scoped)\n {\n scoped.DoSomething();\n\n await _next(httpContext);\n }\n}\nIServiceScopeFactory vs. IServiceProviderYou might see examples using the IServiceProvider to create a scope instead of the IServiceScopeFactory.
What's the difference between these two approaches?
\nThe CreateScope method from IServiceProvider\nresolves an IServiceScopeFactory instance and calls CreateScope() on it:
public static IServiceScope CreateScope(this IServiceProvider provider)\n{\n return provider.GetRequiredService<IServiceScopeFactory>().CreateScope();\n}\nSo, if you want to use the IServiceProvider directly to create a scope, that's fine.
However, the IServiceScopeFactory is a more direct way to achieve the desired result.
Understanding the difference between Transient, Scoped, and Singleton lifetimes is crucial for managing dependencies in ASP.NET Core applications.
\nThe IServiceScopeFactory provides a solution when you need to resolve scoped services from singletons.\nIt allows you to create a new scope, which you can use to resolve scoped services.
In middleware, we can inject scoped services into the InvokeAsync method.\nThis also ensures the services use the current request's scope and lifecycle.
Thanks for reading, and I'll see you next week!
\nDefine an IUserContext abstraction in the Application layer that exposes what your use cases need, such as the current UserId.\nImplement it in the Infrastructure layer with IHttpContextAccessor and the claims on the ClaimsPrincipal.\nYour use cases stay decoupled from identity, so the Clean Architecture dependency rule holds.
The applications you build serve your users (customers) to help them solve some problems.\nIt's a common requirement that you will need to know who the current application user is.
\nHow do you get the current user's information in a Clean Architecture use case?
\nUse cases live in the Application layer, where you can't introduce external concerns.\nOtherwise, you will be breaking the dependency rule.
\nLet's say you want to know who the current user is to determine if they can access some resource.\nThis is your typical resource-based authorization check.\nBut you have to interact with the identity provider to get this information.\nThis breaks the dependency rule in Clean Architecture.
\nI've seen this problem confuse developers who are new to Clean Architecture.
\nIn today's issue, I'll show you how to access the current user's information in a clean way.
\nThe inner layers in Clean Architecture define abstractions for external concerns.\nFrom the Application layer's perspective, authentication and user identity are external concerns.
\nThe Infrastructure layer deals with external concerns, including authentication and identity management.\nThis is where you would implement the abstraction.
\nMy preferred approach is creating an IUserContext abstraction.\nThe main information I need is the UserId of the current user.\nBut you can expand the IUserContext with any other data you think is necessary.
public interface IUserContext\n{\n bool IsAuthenticated { get; }\n\n Guid UserId { get; }\n}\nLet's see how to implement the IUserContext.
The UserContext class is the IUserContext implementation in the Infrastructure layer.\nWe need to inject the IHttpContextAccessor, which allows us to access the ClaimsPrincipal\nthrough the User property.\nThe ClaimsPrincipal gives you access to the current user's claims, containing the required information.
In this example, I'm throwing an exception if any of the properties evaluate to null.\nYou can decide if throwing an exception makes sense for you.
I also want to share an important remark here about IHttpContextAccessor.\nWe're using it to access the HttpContext instance — which only exists during an API request.\nOutside an API request, the HttpContext will be null, and the UserContext will throw an exception when accessing its properties.
internal sealed class UserContext(IHttpContextAccessor httpContextAccessor)\n : IUserContext\n{\n public Guid UserId =>\n httpContextAccessor\n .HttpContext?\n .User\n .GetUserId() ??\n throw new ApplicationException("User context is unavailable");\n\n public bool IsAuthenticated =>\n httpContextAccessor\n .HttpContext?\n .User\n .Identity?\n .IsAuthenticated ??\n throw new ApplicationException("User context is unavailable");\n}\nHere's the GetUserId extension method that's used in the UserContext.UserId property.\nIt's looking for a claim with the ClaimTypes.NameIdentifier name, and parsing that value into a Guid.\nYou can replace this with a different type to match the user identity in your system.
internal static class ClaimsPrincipalExtensions\n{\n public static Guid GetUserId(this ClaimsPrincipal? principal)\n {\n string? userId = principal?.FindFirstValue(ClaimTypes.NameIdentifier);\n\n return Guid.TryParse(userId, out Guid parsedUserId) ?\n parsedUserId :\n throw new ApplicationException("User id is unavailable");\n }\n}\nNow that you have the IUserContext, you can use it from the Application layer.
A common requirement is checking if the current user can access some resources.
\nHere's an example using the GetInvoiceQueryHandler, which queries the database for an invoice.\nAfter projecting the result to an InvoiceResponse object, we check if the current user is the one to whom the invoice was issued.\nYou can also apply this check as part of the database query.\nBut performing it in memory lets you return a different response to the user when they aren't authorized.\nFor example, a 403 Forbidden might be appropriate.
class GetInvoiceQueryHandler(IAppDbContext dbContext, IUserContext userContext)\n : IQueryHandler<GetInvoiceQuery, InvoiceResponse>\n{\n public async Task<Result<InvoiceResponse>> Handle(\n GetInvoiceQuery request,\n CancellationToken cancellationToken)\n {\n InvoiceResponse? invoiceResponse = await dbContext\n .Invoices\n .ProjectTo<InvoiceResponse>()\n .FirstOrDefaultAsync(\n invoice => invoice.Id == request.InvoiceId,\n cancellationToken);\n\n if (invoiceResponse is null ||\n invoiceResponse.IssuedToUserId != userContext.UserId)\n {\n return Result.Failure<InvoiceResponse>(InvoiceErrors.NotFound);\n }\n\n return invoiceResponse;\n }\n}\nIncorporating user identity and authentication into Clean Architecture\ndoesn't have to compromise the integrity of your design.\nThe Application layer should remain decoupled from external concerns such as identity management.
\nWe respect the Clean Architecture dependency rule by\nabstracting user-related information through the IUserContext interface and implementing it within the Infrastructure layer.
With this strategy, you can effectively manage user information, support authorization checks, and ensure your application remains robust and adaptable to future changes.
\nRemember, the key is in defining clear abstractions and respecting the architecture's boundaries.
\nHope this was helpful.
\nSee you next week.
\nQuerying the database inside a foreach loop costs one round trip per item.\nBatching removes that: collect the ids up front, fetch every related row in a single query, and build a dictionary for in-memory lookup.\nIn this issue's benchmark, that took the endpoint from 1913.3 us to 558.6 us, 3.42x faster against a local SQL database.
EF Core is a fantastic ORM if you're building .NET applications.
\nBut it's a tool like any other. And you can end up using it in a suboptimal way.
\nToday, I'll show you a simple idea I used to get an almost 4x performance improvement.
\nI'm not saying you'll see the same result, but understanding the idea will make your queries faster.
\nHere's the example I want to use to explain this powerful idea.\nIt's taken from a production app I was working on, but I simplified it for this example.
\nWe're using an InvoiceService to get a collection of invoices for a given company.\nThe invoices could come from a third-party API or some other persistence store.\nWe're lacking detailed line item information, so we're querying the database to fill in the missing data.
The highlighted LINQ query below isn't bad by itself.\nIt returns all the line items in one database query (round trip).
\nBut it's missing one important realization that can unlock further performance gains.
\nBecause we're iterating over the invoices, we're querying the database many times.
\napp.MapGet("invoices/{companyId}", (\n long companyId,\n InvoiceService invoiceService,\n AppDbContext dbContext) =>\n{\n IEnumerable<Invoice> invoices = invoiceService.GetForCompanyId(\n companyId,\n take: 10);\n\n var invoiceDtos = new List<InvoiceDto>();\n foreach (var invoice in invoices)\n {\n var invoiceDto = new InvoiceDto\n {\n Id = invoice.Id,\n CompanyId = invoice.CompanyId,\n IssuedDate = invoice.IssuedDate,\n DueDate = invoice.DueDate,\n Number = invoice.Number\n };\n\n var lineItemDtos = await dbContext\n .LineItems\n .Where(li => invoice.LineItemIds.Contains(li.Id))\n .Select(li => new LineItemDto\n {\n Id = li.Id,\n Name = li.Name,\n Price = li.Price,\n Quantity = li.Quantity\n })\n .ToArrayAsync();\n\n invoiceDto.LineItems = lineItemDtos;\n\n invoiceDtos.Add(invoiceDto);\n }\n\n return invoiceDtos;\n});\nOnce you figure this out, the solution comes down to applying a simple idea.
\nInstead of fetching the line items for each invoice, we can query all the line items ahead of time.
\nHere's the same query, but refactored to only query the line items once.\nThis means there's just a single round trip to the database.
\nThere are three components to the final design:
\nLineItems in a single database round-tripLineItemDto dictionary for fast lookupOnce we have the dictionary, we can loop through the invoices and assign the line items.\nPopulating a line item becomes a dictionary lookup (cheap) instead of a database query (expensive).
\nBefore deciding if this solution makes sense, you should consider a few more things.
\nHow many records can you load from the database at once?
\nEach invoice contains ~20 line items on average, and we're only fetching ten invoices.\nSo, we're loading ~200 line items from the database.\nMost applications can handle this load.\nBut things could be different if you're fetching thousands of rows.
\napp.MapGet("invoices/{companyId}", (\n long companyId,\n InvoiceService invoiceService,\n AppDbContext dbContext) =>\n{\n IEnumerable<Invoice> invoices = invoiceService.GetForCompanyId(\n companyId,\n take: 10);\n\n long[] lineItemIds = invoices\n .SelectMany(invoice => invoice.LineItemIds)\n .ToArray();\n\n var lineItemDtos = await dbContext\n .LineItems\n .Where(li => lineItemIds.Contains(li.Id))\n .Select(li => new LineItemDto\n {\n Id = li.Id,\n Name = li.Name,\n Price = li.Price,\n Quantity = li.Quantity\n })\n .ToListAsync();\n\n Dictionary<long, LineItemDto> lineItemsDictionary =\n lineItemDtos.ToDictionary(keySelector: li => li.Id);\n\n var invoiceDtos = new List<InvoiceDto>();\n foreach (var invoice in invoices)\n {\n var invoiceDto = new InvoiceDto\n {\n Id = invoice.Id,\n CompanyId = invoice.CompanyId,\n IssuedDate = invoice.IssuedDate,\n DueDate = invoice.DueDate,\n Number = invoice.Number,\n LineItems = invoice\n .LineItemIds\n .Select(li => lineItemsDictionary[li])\n .ToArray()\n };\n\n invoiceDtos.Add(invoiceDto);\n }\n\n return invoiceDtos;\n})\nIt seems plausible that the batch variant would be faster. Right?
\nWe have N queries (one per invoice) in the first version and a single query in the batched version.
\nHere are the benchmark results I got using BenchmarkDotNet:
\n![\"Benchmark](\"https://milanjovanovic.tech/blogs/mnw_075/benchmark.png\")
\nThe foreach version takes 1913.3 us (microseconds) on average.
\nThe batched version takes 558.6 us on average.
That's 3.42x faster with the batched version. This is with a local SQL database.
\nThe batched version should be even faster if you're querying a remote database because of the impact of network round-trip time.\nIt quickly adds up when you have N queries (foreach version).
\nThe power of this approach lies in its simplicity and efficiency.\nBy batching database queries, we significantly reduce the number of round trips to the database.\nThis is often one of the biggest performance bottlenecks.
\nBut it's crucial to understand that this approach is not a one-size-fits-all solution.
\nEF Core offers many features and optimizations, but it's up to the developer to use them effectively.
\nFinally, always remember to measure and benchmark.\nThe improvements we saw in this case were quantified through benchmarks.\nWithout proper measurement, it's easy to make changes that inadvertently degrade performance.
\nThanks for reading, and stay awesome!
\nTo build a URL shortener in .NET, expose two Minimal API endpoints.\nOne generates a unique code for a long URL and stores the mapping, and the other looks up the code and redirects to the original URL.\nStore the mappings in a database like PostgreSQL, and add a distributed cache like Redis to improve read performance.
\nA URL shortener is a simple yet powerful tool that converts long URLs into more manageable, shorter versions.\nThis is particularly useful for sharing links on platforms with character limits or improving user experience by reducing clutter.\nTwo popular URL shorteners are Bitly and TinyURL.\nDesigning a URL shortener is an interesting challenge with fun problems to solve.
\nBut how would you build a URL shortener in .NET?
\nURL shorteners have two core functionalities:
\nToday, I'll guide you through the design, implementation, and considerations for creating your URL shortener.
\nHere's the high-level system design for our URL shortener.\nWe want to expose two endpoints.\nOne to shorten a long URL and the other to redirect users based on a shortened URL.\nThe shortened URLs are stored in a PostgreSQL database in this example.\nWe can introduce a distributed cache like Redis to the system to improve read performance.
\n![\"URL](\"https://milanjovanovic.tech/blogs/mnw_074/url_shortener.png\")
\nWe first need to ensure a large number of short URLs.\nWe're going to assign a unique code to each long URL, and use it to generate the shortened URL.\nThe unique code length and set of characters determine how many short URLs the system can generate.\nWe will discuss this in more detail when we implement unique code generation.
\nWe're going to use the random code generation strategy.\nIt's straightforward to implement and has an acceptably low rate of collisions.\nThe trade-off we're making is increased latency, but we will also explore other options.
\nLet's start by figuring out what we will store in the database.\nOur data model is straightforward.\nWe have a ShortenedUrl class representing the URLs stored in our system:
public class ShortenedUrl\n{\n public Guid Id { get; set; }\n\n public string LongUrl { get; set; } = string.Empty;\n\n public string ShortUrl { get; set; } = string.Empty;\n\n public string Code { get; set; } = string.Empty;\n\n public DateTime CreatedOnUtc { get; set; }\n}\nThis class includes properties for the original URL (LongUrl), the shortened URL (ShortUrl), and a unique code (Code) that represents the shortened URL.\nThe Id and CreatedOnUtc fields are used for database and tracking purposes.\nThe users will send the unique Code to our system, which will try to find a matching LongUrl and redirect them.
In addition, we will also define an EF ApplicationDbContext class, which is responsible for configuring our entity and setting up our database context.\nI'm doing two things here to improve performance:
Code maximum length with HasMaxLengthCode columnA unique index shields us from concurrency conflicts, so we will never have duplicate Code values persisted in the database.\nSetting the maximum length for this column saves storage space, and it's a requirement for indexing string columns in some databases.
Note that some databases treat strings in a case-insensitive way.\nThis severely reduces the number of available short URLs.\nYou want to configure the database to treat the unique code in a case-sensitive way.
\npublic class ApplicationDbContext : DbContext\n{\n public ApplicationDbContext(DbContextOptions options)\n : base(options)\n {\n }\n\n public DbSet<ShortenedUrl> ShortenedUrls { get; set; }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.Entity<ShortenedUrl>(builder =>\n {\n builder\n .Property(shortenedUrl => shortenedUrl.Code)\n .HasMaxLength(ShortLinkSettings.Length);\n\n builder\n .HasIndex(shortenedUrl => shortenedUrl.Code)\n .IsUnique();\n });\n }\n}\nThe most crucial part of our URL shortener is generating a unique code for each URL.\nThere are a few different algorithms you can choose to implement this.\nWe want an even distribution of unique codes across all possible values.\nThis helps to reduce potential collisions.
\nI will implement a random, unique code generator with a predefined alphabet.\nIt's simple to implement, and the chance of collision is relatively low.\nStill, there are more performant solutions than this, but more on this later.
\nLet's define a ShortLinkSettings class that contains two constants.\nOne is for defining the length of the unqualified code we will generate.\nThe other constant is the alphabet we will use to generate the random code.
public static class ShortLinkSettings\n{\n public const int Length = 7;\n public const string Alphabet =\n "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";\n}\nThe alphabet has 62 characters, which gives us 62^7 possible unique code combinations.
If you're wondering, this is 3,521,614,606,208 combinations.
Spelled out: three trillion, five hundred twenty-one billion, six hundred fourteen million, six hundred six thousand, two hundred eight.
\nThose are quite a few unique codes, which will be enough for our URL shortener.
\nNow, let's implement our UrlShorteningService, which handles generating unique codes.\nThis service generates a random string of the specified length using our predefined alphabet.\nIt checks against the database to ensure uniqueness.
public class UrlShorteningService(ApplicationDbContext dbContext)\n{\n private readonly Random _random = new();\n\n public async Task<string> GenerateUniqueCode()\n {\n var codeChars = new char[ShortLinkSettings.Length];\n const int maxValue = ShortLinkSettings.Alphabet.Length;\n\n while (true)\n {\n for (var i = 0; i < ShortLinkSettings.Length; i++)\n {\n var randomIndex = _random.Next(maxValue);\n\n codeChars[i] = ShortLinkSettings.Alphabet[randomIndex];\n }\n\n var code = new string(codeChars);\n\n if (!await dbContext.ShortenedUrls.AnyAsync(s => s.Code == code))\n {\n return code;\n }\n }\n }\n}\nDownsides and Improvement Points
\nThe downside of this implementation is increased latency because we're checking each code we generate against the database.\nAn improvement point could be generating the unique codes in the database ahead of time.
\nAnother improvement point could be using a fixed number of iterations instead of an infinite loop.\nIn case of multiple collisions in a row, the current implementation would continue until a unique value is found.\nConsider throwing an exception instead after a few collisions in a row.
\nNow that our core business logic is ready, we can expose an endpoint to shorten URLs.\nWe can use a simple Minimal API endpoint.
\nThis endpoint accepts a URL, validates it, and then uses the UrlShorteningService to create a shortened URL, which is then saved to the database.\nWe return the full shortened URL to the client.
public record ShortenUrlRequest(string Url);\n\napp.MapPost("shorten", async (\n ShortenUrlRequest request,\n UrlShorteningService urlShorteningService,\n ApplicationDbContext dbContext,\n HttpContext httpContext) =>\n{\n if (!Uri.TryCreate(request.Url, UriKind.Absolute, out _))\n {\n return Results.BadRequest("The specified URL is invalid.");\n }\n\n var code = await urlShorteningService.GenerateUniqueCode();\n\n var request = httpContext.Request;\n\n var shortenedUrl = new ShortenedUrl\n {\n Id = Guid.NewGuid(),\n LongUrl = request.Url,\n Code = code,\n ShortUrl = $"{request.Scheme}://{request.Host}/{code}",\n CreatedOnUtc = DateTime.UtcNow\n };\n\n dbContext.ShortenedUrls.Add(shortenedUrl);\n\n await dbContext.SaveChangesAsync();\n\n return Results.Ok(shortenedUrl.ShortUrl);\n});\nThere is a minor race condition here, as we generate a unique code first and then insert it into the database.\nA concurrent request could generate the same unique code and insert it into the database before we complete our transaction.\nHowever, the chances of this happening are low, so I decided not to handle that case.
\nRemember that the unique index in the database is still guarding us against duplicate values.
\nThe second use case for a URL shortener is redirection when accessing a shortened URL.
\nWe will expose another Minimal API endpoint for this feature.\nThe endpoint will accept a unique code, find the respective shortened URL, and redirect the user to the original long URL.\nYou can implement additional validation for the specified code before checking if there's a shortened URL in the database.
\napp.MapGet("{code}", async (string code, ApplicationDbContext dbContext) =>\n{\n var shortenedUrl = await dbContext\n .ShortenedUrls\n .SingleOrDefaultAsync(s => s.Code == code);\n\n if (shortenedUrl is null)\n {\n return Results.NotFound();\n }\n\n return Results.Redirect(shortenedUrl.LongUrl);\n});\nThis endpoint looks up the code in the database and, if found, redirects the user to the original long URL.\nThe response will have a 302 (Found) status code per the HTTP standards.
\nWhile our basic URL shortener is functional, there are several areas we can improve:
\nWe've covered the key components of building a URL shortener using .NET.\nYou can take this further and implement the improvements points for a more robust solution.
\nIf you want to see me build this from scratch, here's a video tutorial on YouTube.
\nThat's all for today.
\nSee you next week.
\nCross-cutting concerns are application-level functionalities that affect the entire application and span several layers.\nIn Clean Architecture, they belong in the Infrastructure layer, implemented with ASP.NET Core middleware, decorators, or MediatR pipeline behaviors.\nCentralizing them in one location prevents code duplication and tight coupling between components.
\nCross-cutting concerns are software aspects that affect the entire application.\nThese are your common application-level functionalities that span several layers and tiers.\nCross-cutting concerns should be centralized in one location.\nThis prevents code duplication and tight coupling between components.
\nA few examples of cross-cutting concerns are:
\nIn today's newsletter, I'll show you how to integrate cross-cutting concerns in Clean Architecture.
\nIn Clean Architecture, cross-cutting concerns\nplay an essential role in ensuring the maintainability and scalability of your system.\nIdeally, these concerns should be handled separately from the core business logic.\nThis aligns with Clean Architecture's principles, emphasizing the decoupling of concerns and modularity.\nYour core business rules remain uncluttered, and the architecture stays clean and adaptable.
\nIdeally, you want to implement cross-cutting concerns in the Infrastructure layer.\nYou can use ASP.NET Core middleware, decorators, or MediatR pipeline behaviors.\nWhichever approach you decide to use, the guiding idea remains the same.
\n![\"Cross-cutting](\"https://milanjovanovic.tech/blogs/mnw_073/clean_architecture_cross_cutting_concerns.png\")
\nLet's see how to implement logging, validation, and caching as cross-cutting concerns.
\nLogging is a fundamental aspect of software development, allowing you to look into an application's behavior.\nIt's vital for debugging, monitoring application health, and tracking user activities and system anomalies.\nIn the context of Clean Architecture, logging must be implemented in a way that maintains the separation of concerns.
\nAn elegant way to achieve this is with MediatR's IPipelineBehavior.\nBy encapsulating the logging logic inside a pipeline behavior, we ensure that logging is treated as a distinct concern, separate from business logic.\nThis approach enables us to capture detailed information about requests flowing through the application.
Effective logging should be consistent, context-rich, and non-intrusive.\nUsing Serilog's structured logging\ncapabilities, we can create logs that are not only informative but also easily queryable.\nThis is essential for understanding the state of the application at any given moment.
\nWhen done correctly, structured logging\nprovides invaluable insights into your application without cluttering the core logic.\nIt's a balance of granularity and clarity, ensuring that your logs are a helpful tool rather than a source of noise.
\nusing Serilog.Context;\n\ninternal sealed class RequestLoggingPipelineBehavior<TRequest, TResponse>(\n ILogger<RequestLoggingPipelineBehavior<TRequest, TResponse>> logger)\n : IPipelineBehavior<TRequest, TResponse>\n where TRequest : class\n where TResponse : Result\n{\n public async Task<TResponse> Handle(\n TRequest request,\n RequestHandlerDelegate<TResponse> next,\n CancellationToken cancellationToken)\n {\n string requestName = typeof(TRequest).Name;\n\n logger.LogInformation(\n "Processing request {RequestName}",\n requestName);\n\n TResponse result = await next();\n\n if (result.IsSuccess)\n {\n logger.LogInformation(\n "Completed request {RequestName}",\n requestName);\n }\n else\n {\n using (LogContext.PushProperty("Error", result.Error, true))\n {\n logger.LogError(\n "Completed request {RequestName} with error",\n requestName);\n }\n }\n\n return result;\n }\n}\nValidation is a critical cross-cutting concern in software engineering.\nIt serves as the first line of defense against incorrect data entering your system.\nValidation guards the application against inconsistent data states and potential security vulnerabilities.
\nIn the example below, I'm creating a validation pipeline behavior.\nThis setup allows for a clean separation of validation logic from business logic.\nThe pipeline behavior ensures that each request is validated before it reaches the core processing logic.
\nIn approaching validation, it's crucial to distinguish between two types:
\nInput validation checks for the correctness and format of the data (like string length, number ranges, and date formats), ensuring it meets the basic criteria before processing.
\nOn the other hand, business rule validation is more about ensuring that the data adheres to your domain's specific rules and logic.
\nEffective validation practices significantly contribute to the resilience and reliability of an application.\nBy enforcing validation rules, you can maintain a high data quality standard and ensure a better user experience.
\ninternal sealed class ValidationPipelineBehavior<TRequest, TResponse>(\n IEnumerable<IValidator<TRequest>> validators)\n : IPipelineBehavior<TRequest, TResponse>\n where TRequest : class\n{\n public async Task<TResponse> Handle(\n TRequest request,\n RequestHandlerDelegate<TResponse> next,\n CancellationToken cancellationToken)\n {\n ValidationFailure[] validationFailures = await ValidateAsync(request);\n\n if (validationFailures.Length != 0)\n {\n throw new ValidationException(validationFailures);\n }\n\n return await next();\n }\n\n private async Task<ValidationFailure[]> ValidateAsync(TRequest request)\n {\n if (!validators.Any())\n {\n return [];\n }\n\n var context = new ValidationContext<TRequest>(request);\n\n ValidationResult[] validationResults = await Task.WhenAll(\n validators.Select(validator => validator.ValidateAsync(context)));\n\n ValidationFailure[] validationFailures = validationResults\n .Where(validationResult => !validationResult.IsValid)\n .SelectMany(validationResult => validationResult.Errors)\n .ToArray();\n\n return validationFailures;\n }\n}\nCaching is an essential cross-cutting concern in software development.\nIt's primarily aimed at enhancing performance and scalability.\nCaching involves temporarily storing data in a fast-access layer.\nThis reduces the need to fetch or calculate the same information repeatedly.
\nThe caching pipeline behavior, which you see below, implements the Cache Aside pattern.\nThis pattern involves checking the cache before processing the request and updating the cache with new data as needed.\nIt's a popular caching strategy due to its simplicity and effectiveness.\nHere's a video tutorial if you want to see how I implemented this.
\nWhen implementing caching, it's crucial to consider:
\nEffective caching improves response times and reduces the load on your system, making it a critical strategy for building scalable .NET applications.
\ninternal sealed class QueryCachingPipelineBehavior<TRequest, TResponse>(\n ICacheService cacheService,\n ILogger<QueryCachingPipelineBehavior<TRequest, TResponse>> logger)\n : IPipelineBehavior<TRequest, TResponse>\n where TRequest : ICachedQuery\n where TResponse : Result\n{\n public async Task<TResponse> Handle(\n TRequest request,\n RequestHandlerDelegate<TResponse> next,\n CancellationToken cancellationToken)\n {\n TResponse? cachedResult = await cacheService.GetAsync<TResponse>(\n request.CacheKey,\n cancellationToken);\n\n string requestName = typeof(TRequest).Name;\n if (cachedResult is not null)\n {\n logger.LogInformation("Cache hit for {RequestName}", requestName);\n\n return cachedResult;\n }\n\n logger.LogInformation("Cache miss for {RequestName}", requestName);\n\n TResponse result = await next();\n\n if (result.IsSuccess)\n {\n await cacheService.SetAsync(\n request.CacheKey,\n result,\n request.Expiration,\n cancellationToken);\n }\n\n return result;\n }\n}\nManaging cross-cutting concerns such as logging, caching, validation, and exception handling is not just about technical implementation.\nIt's about aligning these aspects with the core principles of Clean Architecture.\nBy adopting the decoupling techniques we discussed, you can ensure that your .NET projects are robust and maintainable.
\nEach step you take towards refining your handling of cross-cutting concerns is a step towards a better software architecture.\nI encourage you to experiment with these strategies in your own .NET projects.\nIf you want a structured guide covering these aspects in-depth, take a look at Pragmatic Clean Architecture.
\nRemember, the beauty of software development lies in the continuous evolution and relentless pursuit of improvement.
\nHope this was helpful.
\nSee you next week.
\nDelegating handlers are like ASP.NET Core middleware for outgoing HTTP requests.\nYou inherit from the DelegatingHandler base class and override SendAsync to add behavior before or after an HttpClient sends a request.\nThis is useful for cross-cutting concerns like logging, resiliency, and authentication.
Delegating handlers are like ASP.NET Core middleware.\nExcept they work with the HttpClient.\nThe ASP.NET Core request pipeline allows you to introduce custom behavior with middleware.\nYou can solve many cross-cutting concerns using middleware — logging, tracing, validation, authentication, authorization, etc.
But, an important aspect here is that middleware works with incoming HTTP requests to your API.\nDelegating handlers work with outgoing requests.
\nHttpClient is my preferred way of sending HTTP requests in ASP.NET Core.\nIt's straightforward to use and solves most of my use cases.\nYou can use delegating handlers to extend the HttpClient with behavior before or after sending an HTTP request.
Today, I want to show you how to use a DelegatingHandler to introduce:
Here's a very simple application that:
\nGitHubService class as a typed HTTP clientHttpClient.BaseAddress to point to the GitHub APIWe're going to extend the GitHubService behavior using delegating handlers.
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddHttpClient<GitHubService>(httpClient =>\n{\n httpClient.BaseAddress = new Uri("https://api.github.com");\n});\n\nvar app = builder.Build();\n\napp.MapGet("api/users/{username}", async (\n string username,\n GitHubService gitHubService) =>\n{\n var content = await gitHubService.GetByUsernameAsync(username);\n\n return Results.Ok(content);\n});\n\napp.Run();\nThe GitHubService class is a typed client implementation.\nTyped clients allow you to expose a strongly typed API and hide the HttpClient.\nThe runtime takes care of providing a configured HttpClient instance through dependency injection.\nYou also don't have to think about disposing of the HttpClient.\nIt's resolved from an underlying IHttpClientFactory that manages the HttpClient lifetime.
public class GitHubService(HttpClient client)\n{\n public async Task<GitHubUser?> GetByUsernameAsync(string username)\n {\n var url = $"users/{username}";\n\n return await client.GetFromJsonAsync<GitHubUser>(url);\n }\n}\nLet's start with a simple example.\nWe will add logging before and after sending an HTTP request.\nFor this, we will to create a custom delegating handler - LoggingDelegatingHandler.
The custom delegating handler implements the DelegatingHandler base class.\nThen, you can override the SendAsync method to introduce additional behavior.
public class LoggingDelegatingHandler(ILogger<LoggingDelegatingHandler> logger)\n : DelegatingHandler\n{\n protected override async Task<HttpResponseMessage> SendAsync(\n HttpRequestMessage request,\n CancellationToken cancellationToken)\n {\n try\n {\n logger.LogInformation("Before HTTP request");\n\n var result = await base.SendAsync(request, cancellationToken);\n\n result.EnsureSuccessStatusCode();\n\n logger.LogInformation("After HTTP request");\n\n return result;\n }\n catch (Exception e)\n {\n logger.LogError(e, "HTTP request failed");\n\n throw;\n }\n }\n}\nYou also need to register the LoggingDelegatingHandler with dependency injection.\nDelegating handlers must be registered as transient services.
The AddHttpMessageHandler method adds the LoggingDelegatingHandler as a delegating handler for the GitHubService.\nAny HTTP request sent using the GitHubService will first go through the LoggingDelegatingHandler.
builder.Services.AddTransient<LoggingDelegatingHandler>();\n\nbuilder.Services.AddHttpClient<GitHubService>(httpClient =>\n{\n httpClient.BaseAddress = new Uri("https://api.github.com");\n})\n.AddHttpMessageHandler<LoggingDelegatingHandler>();\nLet's see what else we can do.
\nBuilding resilient applications is an important requirement for cloud development.
\nThe RetryDelegatingHandler class uses Polly to create an AsyncRetryPolicy.\nThe retry policy wraps the HTTP request and retries it in case of a transient failure.
public class RetryDelegatingHandler : DelegatingHandler\n{\n private readonly AsyncRetryPolicy<HttpResponseMessage> _retryPolicy =\n Policy<HttpResponseMessage>\n .Handle<HttpRequestException>()\n .RetryAsync(2);\n\n protected override async Task<HttpResponseMessage> SendAsync(\n HttpRequestMessage request,\n CancellationToken cancellationToken)\n {\n var policyResult = await _retryPolicy.ExecuteAndCaptureAsync(\n () => base.SendAsync(request, cancellationToken));\n\n if (policyResult.Outcome == OutcomeType.Failure)\n {\n throw new HttpRequestException(\n "Something went wrong",\n policyResult.FinalException);\n }\n\n return policyResult.Result;\n }\n}\nYou also need to register the RetryDelegatingHandler with dependency injection.\nAlso, remember to configure it as a message handler.\nIn this example, I'm chaining two delegating handlers together, and they will run one after another.
builder.Services.AddTransient<RetryDelegatingHandler>();\n\nbuilder.Services.AddHttpClient<GitHubService>(httpClient =>\n{\n httpClient.BaseAddress = new Uri("https://api.github.com");\n})\n.AddHttpMessageHandler<LoggingDelegatingHandler>()\n.AddHttpMessageHandler<RetryDelegatingHandler>();\nAuthentication is a cross-cutting concern you will have to solve in any microservices application.\nA common use case for delegating handlers is adding the Authorization header before sending an HTTP request.
For example, the GitHub API requires an access token to be present for authenticating incoming requests.\nThe AuthenticationDelegatingHandler class adds the Authorization header value from the GitHubOptions.\nAnother requirement is specifying the User-Agent header, which is set from the app configuration.
public class AuthenticationDelegatingHandler(IOptions<GitHubOptions> options)\n : DelegatingHandler\n{\n protected override Task<HttpResponseMessage> SendAsync(\n HttpRequestMessage request,\n CancellationToken cancellationToken)\n {\n request.Headers.Add("Authorization", options.Value.AccessToken);\n request.Headers.Add("User-Agent", options.Value.UserAgent);\n\n return base.SendAsync(request, cancellationToken);\n }\n}\nDon't forget to configure the AuthenticationDelegatingHandler with the GitHubService:
builder.Services.AddTransient<AuthenticationDelegatingHandler>();\n\nbuilder.Services.AddHttpClient<GitHubService>(httpClient =>\n{\n httpClient.BaseAddress = new Uri("https://api.github.com");\n})\n.AddHttpMessageHandler<LoggingDelegatingHandler>()\n.AddHttpMessageHandler<RetryDelegatingHandler>()\n.AddHttpMessageHandler<AuthenticationDelegatingHandler>();\nHere's a more involved authentication example using the KeyCloakAuthorizationDelegatingHandler.\nThis is a delegating handler that acquires the access token from Keycloak.\nKeycloak is an open-source identity and access management service.
I used Keycloak as the identity provider in my Pragmatic Clean Architecture course.
\nThe delegating handler in this example uses an OAuth 2.0 client credentials grant flow to obtain an access token.\nThis grant is used when applications request an access token to access their own resources, not on behalf of a user.
\npublic class KeyCloakAuthorizationDelegatingHandler(\n IOptions<KeycloakOptions> keycloakOptions)\n : DelegatingHandler\n{\n protected override async Task<HttpResponseMessage> SendAsync(\n HttpRequestMessage request,\n CancellationToken cancellationToken)\n {\n var authToken = await GetAccessTokenAsync();\n\n request.Headers.Authorization = new AuthenticationHeaderValue(\n JwtBearerDefaults.AuthenticationScheme,\n authToken.AccessToken);\n\n var httpResponseMessage = await base.SendAsync(\n request,\n cancellationToken);\n\n httpResponseMessage.EnsureSuccessStatusCode();\n\n return httpResponseMessage;\n }\n\n private async Task<AuthToken> GetAccessTokenAsync()\n {\n var params = new KeyValuePair<string, string>[]\n {\n new("client_id", _keycloakOptions.Value.AdminClientId),\n new("client_secret", _keycloakOptions.Value.AdminClientSecret),\n new("scope", "openid email"),\n new("grant_type", "client_credentials")\n };\n\n var content = new FormUrlEncodedContent(params);\n\n var authRequest = new HttpRequestMessage(\n HttpMethod.Post,\n new Uri(_keycloakOptions.TokenUrl))\n {\n Content = content\n };\n\n var response = await base.SendAsync(authRequest, cancellationToken);\n\n response.EnsureSuccessStatusCode();\n\n return await response.Content.ReadFromJsonAsync<AuthToken>() ??\n throw new ApplicationException();\n }\n}\nDelegating handlers give you a powerful mechanism to extend the behavior when sending requests with an HttpClient.\nYou can use delegating handlers to solve cross-cutting concerns, similar to how you would use middleware.
Here are a few ideas on how you could use delegating handlers:
\nI'm sure you can come up with a few use cases yourself.
\nI made a video showing how to implement delegating handlers, and you can watch it here.
\nThanks for reading, and stay awesome!
\nMassTransit gives you one messaging abstraction over several transports, so the same publish and consume code runs on RabbitMQ or Azure Service Bus.\nYou install the matching transport package, call AddMassTransit, and select the transport with UsingRabbitMq or UsingAzureServiceBus.\nMassTransit configures the broker topology for you.
MassTransit is an open-source distributed application framework for .NET.\nIt provides a messaging abstraction on top of the supported message transports.\nMassTransit lets you focus on adding business value instead of worrying about messaging complexity.
\nMassTransit supports many message transport technologies.\nHere are a few that are popular:
\nIn today's newsletter, I'll show you how to install and configure MassTransit in .NET.\nWe'll connect MassTransit to a few message brokers - RabbitMQ and Azure Service Bus.\nAnd we will also cover how to publish and consume messages with MassTransit.
\nMassTransit solves many challenges of building distributed applications.\nYou (almost) don't have to think about the underlying message transport.\nThis allows you to focus on providing business value.
\nHere are a few things MassTransit does for you:
\nLet's see how to start using MassTransit.
\nYou need to install the MassTransit library.\nIf you already have a message transport, you can install the respective transport library.\nLet's add the MassTransit.RabbitMQ library to configure RabbitMQ as the transport mechanism.
Install-Package MassTransit\n\nInstall-Package MassTransit.RabbitMQ\nThen, you can configure the required services for MassTransit.\nThe AddMassTransit method accepts a delegate where you can configure many settings.\nFor example, you can set the messaging endpoints to use kebab case naming by calling SetKebabCaseEndpointNameFormatter.\nThis is also where you configure the transport mechanism.\nCalling UsingRabbitMq allows you to connect RabbitMQ as the transport mechanism.
builder.Services.AddMassTransit(busConfigurator =>\n{\n busConfigurator.SetKebabCaseEndpointNameFormatter();\n\n busConfigurator.UsingRabbitMq((context, configurator) =>\n {\n configurator.Host("localhost", "/", h =>\n {\n h.Username("guest");\n h.Password("guest");\n });\n\n configurator.ConfigureEndpoints(context);\n });\n});\nMassTransit takes care of setting up the required broker topology.\nRabbitMQ supports exchanges and queues, so messages are sent or published to exchanges.\nRabbitMQ routes those messages through exchanges to the appropriate queues.
\nYou can start RabbitMQ locally inside a Docker container:
\ndocker run -d --name rabbitmq -p 5672:5672\nAzure Service Bus\nis a cloud-based message broker with support for queues and topics.\nMassTransit fully supports Azure Service Bus, including many advanced features and capabilities.\nHowever, you must be on the Standard or Premium tier of the Microsoft Azure Service Bus service.
\nTo configure MassTransit to work with Azure Service Bus, you need to install the required transport library:
\nInstall-Package MassTransit.Azure.ServiceBus.Core\nThen, you can connect to Azure Service Bus by calling UsingAzureServiceBus and providing the connection string.\nEverything else remains the same.\nMassTransit takes care of configuring the broker topology.\nMassTransit sends messages to topics, and Azure Service Bus routes those messages to the appropriate queues.
builder.Services.AddMassTransit(busConfigurator =>\n{\n busConfigurator.SetKebabCaseEndpointNameFormatter();\n\n busConfigurator.UsingAzureServiceBus((context, configurator) =>\n {\n configurator.Host("<CONNECTION_STRING>");\n\n configurator.ConfigureEndpoints(context);\n });\n});\nYou can also configure MassTransit to use an in-memory transport.\nIt's useful for testing, because it doesn't require a message broker to be running.\nAnother advantage is that it's fast.
\nHowever, there's a big problem with the in-memory transport - it's not durable.
\nIf the message bus is stopped, all messages are lost.\nDon't use the in-memory transport for production systems.
\nIt will only work on a single machine.\nSo, it doesn't make sense for distributed applications.
\nbuilder.Services.AddMassTransit(busConfigurator =>\n{\n busConfigurator.SetKebabCaseEndpointNameFormatter();\n\n busConfigurator.UsingInMemory((context, configurator) =>\n {\n configurator.ConfigureEndpoints(context);\n });\n});\nMassTransit requires message types to be reference types.\nSo, you can use a class, record or interface to define a message.
You'll often create two types of messages: commands and events.
\nA command is an instruction to perform some action.\nCommands are intended to have exactly one consumer.\nCommands are expressed using verbs first: CreateArticle, PublishArticle, ShareArticle.
An event represents that something of significance happened.\nEvents can have one or many consumers.\nEvents should have a name in the past tense: ArticleCreated, ArticlePublished, ArticleShared.
Here's an example ArticleCreated message containing information about an article:
public record ArticleCreated\n{\n public Guid Id { get; init; }\n public string Title { get; init; }\n public string Content { get; init; }\n public DateTime CreatedOnUtc { get; init; }\n}\nUsing public set or public init properties is recommended to avoid serialization problems with System.Text.Json.
You can use the IPublishEndpoint service to publish messages with MassTransit.\nThe framework routes the message to the appropriate queue or topic based on the message type.
app.MapPost("article", async (\n CreateArticleRequest request,\n IPublishEndpoint publishEndpoint) =>\n{\n await publishEndpoint.Publish(new ArticleCreated\n {\n Id = Guid.NewGuid(),\n Title = request.Title,\n Content = request.Content,\n CreatedOnUtc = DateTime.UtcNow\n });\n\n return Results.Accepted();\n});\nTo consume an ArticleCreated message, you need to implement the IConsumer interface.\nThe IConsumer has one Consume method where you place your business logic.\nThe consumer also gives you access to the ConsumeContext, which you can use to send further messages.
public class ArticleCreatedConsumer(ApplicationDbContext dbContext)\n : IConsumer<ArticleCreatedEvent>\n{\n public async Task Consume(ConsumeContext<ArticleCreatedEvent> context)\n {\n ArticleCreated message = context.Message;\n\n var article = new Article\n {\n Id = message.Id,\n Title = message.Title,\n Content = message.Content,\n CreatedOnUtc = message.CreatedOnUtc\n };\n\n dbContext.Add(article);\n\n await dbContext.SaveChangesAsync();\n }\n}\nMassTransit doesn't automatically know that the ArticleCreatedConsumer exists.\nYou have to configure the consumer when calling AddMassTransit.\nThe AddConsumer method registers the consumer type with the bus.
builder.Services.AddMassTransit(busConfigurator =>\n{\n busConfigurator.SetKebabCaseEndpointNameFormatter();\n\n busConfigurator.AddConsumer<ArticleCreatedConsumer>();\n\n // ...\n});\nMassTransit is an excellent messaging library I often use when building distributed applications.\nThe setup is straightforward, and there are only a few important abstractions.\nYou need to know abstraction for publishing messages (IPublishEndpoint) and consuming messages (IConsumer).\nMassTransit takes care of doing the heavy lifting for you.
If you aren't already using it, I highly recommend adding MassTransit to your toolbox.
\nHere are some more practical MassTransit learning resources:
\nThat's all for today.
\nSee you next week.
\nAPI versioning lets your API evolve without breaking the clients already integrated with it.\nInstead of shipping a breaking change, you publish a new version and let clients migrate on their own schedule.\nIn ASP.NET Core you add it with the Asp.Versioning packages, then read the version from the URL segment, a header, or the query string.
In the past year, I built and maintained a large public API.\nThe API has dozens of integrations, serving mainly mobile applications.
\nWhen your API is serving so many clients, breaking changes are expensive.
\nSo, everything I implemented on the public API had to be planned.
\nAdding a new field? Forget about it.
\nRenaming existing fields? Forget about it.
\nIf I wanted to introduce breaking changes, I had to version the API.
\nToday, I'll show you how to implement API versioning in ASP.NET Core.
\nAPI versioning is the practice of assigning distinct identifiers to different iterations of an API,\nso that clients can target a specific version and continue working even as the API evolves.
\nWithout versioning, every change you make to your API is potentially a breaking change for clients already integrated with it.\nWith .NET API versioning, you can introduce a new v2 endpoint with the updated behavior while v1 continues to work exactly as before.\nClients upgrade on their own schedule, and you maintain full control over which old versions to deprecate and remove.
This is what makes API versioning essential for any public-facing or long-lived .NET API.\nThe same principles apply whether you're building with ASP.NET Core MVC controllers or Minimal APIs.
\nAPI versioning allows your API to evolve independently from the clients using it.
\nIntroducing breaking changes to your API is a bad user experience.\nAPI versioning gives you a mechanism to avoid exposing breaking changes to clients.\nInstead of making a breaking change, you introduce a new API version.
\nWhat's the definition of a breaking change?
\nThis isn't an exhaustive list, but a few examples of breaking changes are:
\nYou can decide what a breaking change means for your API.\nFor example, adding a new field to the response doesn't have to be a breaking change.
\nLet's see how to implement API versioning.
\nLet's start by installing three NuGet packages that we'll need to implement API versioning:
\nAsp.Versioning.HttpAsp.Versioning.MvcAsp.Versioning.Mvc.ApiExplorerInstall-Package Asp.Versioning.Http # This is needed for Minimal APIs\nInstall-Package Asp.Versioning.Mvc # This is needed for Controllers\nInstall-Package Asp.Versioning.Mvc.ApiExplorer\nThis allows us to call AddApiVersioning and provide a delegate to configure the ApiVersioningOptions.
builder.Services.AddApiVersioning(options =>\n{\n options.DefaultApiVersion = new ApiVersion(1);\n options.ReportApiVersions = true;\n options.AssumeDefaultVersionWhenUnspecified = true;\n options.ApiVersionReader = ApiVersionReader.Combine(\n new UrlSegmentApiVersionReader(),\n new HeaderApiVersionReader("X-Api-Version"));\n})\n.AddMvc() // This is needed for controllers\n.AddApiExplorer(options =>\n{\n options.GroupNameFormat = "'v'V";\n options.SubstituteApiVersionInUrl = true;\n});\nHere's the explanation for the ApiVersioningOptions properties:
DefaultApiVersion - Sets the default API version. Typically, this will be v1.0.ReportApiVersions - Reports the supported API versions in the api-supported-versions response header.AssumeDefaultVersionWhenUnspecified - Uses the DefaultApiVersion when the client didn't provide an explicit version.ApiVersionReader - Configures how to read the API version specified by the client. The default value is QueryStringApiVersionReader.The AddApiExplorer method is helpful if you are using Swagger.\nIt will fix the endpoint routes and substitute the API version route parameter.
There are several strategies for .NET API versioning, each with different tradeoffs.
\nURL versioning embeds the version directly in the request path:
\nGET https://localhost:5001/api/v1/workouts
This is the most explicit approach. The version is visible at a glance, trivial to test in a browser or with curl,\nand is the most widely-used strategy for public .NET APIs.\nThe UrlSegmentApiVersionReader in Asp.Versioning.Http handles this automatically.
Header versioning passes the API version via a custom request header:
\nGET https://localhost:5001/api/workouts with header X-Api-Version: 1
This keeps your URLs clean, but the version is invisible unless clients inspect outgoing headers.\nThe HeaderApiVersionReader supports this strategy.
Query string versioning appends the version as a query parameter:
\nGET https://localhost:5001/api/workouts?api-version=1
This is the default behavior in Asp.Versioning.Http using QueryStringApiVersionReader.\nIt's easy to use during development and testing without any special tooling.
There are a few other ways to implement API versioning, such as using the accept or content-type headers, but they aren't used often.
The Asp.Versioning.Http library provides several IApiVersionReader implementations to support these strategies:
UrlSegmentApiVersionReaderHeaderApiVersionReaderQueryStringApiVersionReaderMediaTypeApiVersionReaderMicrosoft's API versioning guidelines\nsuggest using URL or query string parameter versioning.
\nI use URL versioning almost exclusively in the applications I'm developing.
\nTo implement API versioning in ASP.NET controllers, you have to decorate the controller with the ApiVersion attribute.
The ApiVersion attribute allows you to specify which API versions that WorkoutsController supports.\nIn this case, the controller supports both v1 and v2.\nYou use the MapToApiVersion attribute on the endpoints to specify the concrete API version.
The route parameter v{v:apiVersion} lets you specify the API version using v1 or v2 in the URL.
[ApiVersion(1)]\n[ApiVersion(2)]\n[ApiController]\n[Route("api/v{v:apiVersion}/workouts")]\npublic class WorkoutsController : ControllerBase\n{\n [MapToApiVersion(1)]\n [HttpGet("{workoutId}")]\n public IActionResult GetWorkoutV1(Guid workoutId)\n {\n return Ok(new GetWorkoutByIdQuery(workoutId).Handle());\n }\n\n [MapToApiVersion(2)]\n [HttpGet("{workoutId}")]\n public IActionResult GetWorkoutV2(Guid workoutId)\n {\n return Ok(new GetWorkoutByIdQuery(workoutId).Handle());\n }\n}\nIf you want to deprecate an old API version, you can set the Deprecated property on the ApiVersion attribute.\nThe deprecated API versions will be reported using the api-deprecated-versions response header.
[ApiVersion(1, Deprecated = true)]\n[ApiVersion(2)]\n[ApiController]\n[Route("api/v{v:apiVersion}/workouts")]\npublic class WorkoutsController : ControllerBase\n{\n}\nVersioning Minimal APIs requires you to define an ApiVersionSet, which you'll pass to the endpoints.
NewApiVersionSet - Creates a new ApiVersionSetBuilder that you can use to configure the ApiVersionSet.HasApiVersion - Indicates that the ApiVersionSet supports the specified ApiVersion.ReportApiVersions- Indicates that all APIs in the ApiVersionSet will report their versions.After creating the ApiVersionSet, you must pass it to a Minimal API endpoint by calling WithApiVersionSet.\nYou can map to an explicit API version by calling MapToApiVersion.
ApiVersionSet apiVersionSet = app.NewApiVersionSet()\n .HasApiVersion(new ApiVersion(1))\n .HasApiVersion(new ApiVersion(2))\n .ReportApiVersions()\n .Build();\n\napp.MapGet("api/v{version:apiVersion}/workouts/{workoutId}", async (\n Guid workoutId,\n ISender sender,\n CancellationToken ct) =>\n{\n var query = new GetWorkoutByIdQuery(workoutId);\n\n Result<WorkoutResponse> result = await sender.Send(query, ct);\n\n return result.Match(Results.Ok, CustomResults.Problem);\n})\n.WithApiVersionSet(apiVersionSet)\n.MapToApiVersion(1);\nSpecifying the ApiVersionSet for each Minimal API endpoint can be cumbersome.\nSo you can define a route group and set the ApiVersionSet only once.\nRoute groups are also practical because they allow you to specify the route prefix.
ApiVersionSet apiVersionSet = app.NewApiVersionSet()\n .HasApiVersion(new ApiVersion(1))\n .ReportApiVersions()\n .Build();\n\nRouteGroupBuilder group = app\n .MapGroup("api/v{version:apiVersion}")\n .WithApiVersionSet(apiVersionSet);\n\ngroup.MapGet("workouts", ...);\ngroup.MapGet("workouts/{workoutId}", ...);\nHere are key practices to keep in mind when implementing API versioning in .NET Core:
\nv1) gives you room to introduce v2 later without painful migrations.[ApiVersion(1, Deprecated = true)]. Give clients time to migrate before removing it entirely.ReportApiVersions = true so that clients can discover available versions via the api-supported-versions response header.API versioning is one of the best practices for designing modern APIs.\nConsider implementing API versioning from the first release.\nThis makes it easier for clients to support future API versions.\nAnd it gets your team used to managing breaking changes and versioning the API.
\nYou can use the Asp.Versioning.Http library to add API versioning in ASP.NET Core.\nDefine the supported API versions, and start using them in your endpoints.
Remember to agree as a team what represents a breaking change.\nThis should be well documented in the team's API design guidelines.
\nMy preferred way to implement API versioning is using URL versioning. It's simple and explicit.
\nAnd since this is the last issue for the year, I wish you a happy and prosperous new year.
\nThanks for reading, and stay awesome!
\nA value object is an immutable domain type with no identity: it wraps a set of primitive values, enforces their invariants, and compares by value.\nIn .NET you can implement one with a record or a ValueObject base class, then persist it with EF Core owned types or complex types.
Value Objects are one of the building blocks of Domain-Driven Design.\nDDD is a software development approach for solving problems in complex domains.
\nValue objects encapsulate a set of primitive values and related invariants.\nA few examples of value objects are money and date range objects.\nMoney consists of an amount and currency.\nA date range consists of start and end dates.
\nToday, I'll show you some best practices for implementing Value Objects.
\nLet's start with the definition from the Domain-Driven Design book:
\n\n\n\nAn object that represents a descriptive aspect of the domain with no conceptual identity is called a Value Object.\nValue Objects are instantiated to represent elements of the design that we care about only for what they are, not who or which they are.
\n
Value objects are different from entities - they don't have a concept of identity.\nThey encapsulate primitive types in the domain and solve primitive obsession.
\nThere are two main qualities of Value Objects:
\nAnother quality of value objects is structural equality.\nTwo value objects are equal if their values are the same.\nThis quality is the least important in practice.\nHowever, there are cases where you want only some values to determine equality.
\nThe most important quality of value objects is immutability.\nThe values of a value object can't change once an object is created.\nIf you want to change an individual value, you need to replace the entire value object.
\nHere's a Booking entity with primitive values representing an address and the start and end dates of the booking.
public class Booking\n{\n public string Street { get; init; }\n public string City { get; init; }\n public string State { get; init; }\n public string Country { get; init; }\n public string ZipCode { get; init; }\n\n public DateOnly StartDate { get; init; }\n public DateOnly EndDate { get; init; }\n}\nYou can replace these primitive values with Address and DateRange value objects.
public class Booking\n{\n public Address Address { get; init; }\n\n public DateRange Period { get; init; }\n}\nBut how do you implement value objects?
\nYou can use C# records to represent value objects.\nRecords are immutable by design, and they have structural equality.\nWe want both of these qualities for our value objects.
\nFor example, you can represent an Address value object using a record with a primary constructor.\nThe advantage of this approach is conciseness.
public record Address(\n string Street,\n string City,\n string State,\n string Country,\n string ZipCode);\nHowever, you lose this advantage when defining a private constructor.\nThis will happen when you want to enforce invariants while creating the value object.\nAnother issue with using records is avoiding value object invariants using the with expression.
public record Address\n{\n private Address(\n string street,\n string city,\n string state,\n string country,\n string zipCode)\n {\n Street = street;\n City = city;\n State = state;\n Country = country;\n ZipCode = zipCode;\n }\n\n public string Street { get; init; }\n public string City { get; init; }\n public string State { get; init; }\n public string Country { get; init; }\n public string ZipCode { get; init; }\n\n public static Result<Address> Create(\n string street,\n string city,\n string state,\n string country,\n string zipCode)\n {\n // Check if the address is valid\n\n return new Address(street, city, state, country, zipCode);\n }\n}\nThe alternative way to implement value objects is with a ValueObject base class.\nThe base class handles structural equality with the GetAtomicValues abstract method.\nValueObject implementations have to implement this method and define the equality components.
The advantage of using a ValueObject base class is that it's explicit.\nIt's clear which classes in your domain represent value objects.\nAnother advantage is being able to control the equality components.
Here's a ValueObject base class I use in my projects:
public abstract class ValueObject : IEquatable<ValueObject>\n{\n public static bool operator ==(ValueObject? a, ValueObject? b)\n {\n if (a is null && b is null)\n {\n return true;\n }\n\n if (a is null || b is null)\n {\n return false;\n }\n\n return a.Equals(b);\n }\n\n public static bool operator !=(ValueObject? a, ValueObject? b) =>\n !(a == b);\n\n public virtual bool Equals(ValueObject? other) =>\n other is not null && ValuesAreEqual(other);\n\n public override bool Equals(object? obj) =>\n obj is ValueObject valueObject && ValuesAreEqual(valueObject);\n\n public override int GetHashCode() =>\n GetAtomicValues().Aggregate(\n default(int),\n (hashcode, value) =>\n HashCode.Combine(hashcode, value.GetHashCode()));\n\n protected abstract IEnumerable<object> GetAtomicValues();\n\n private bool ValuesAreEqual(ValueObject valueObject) =>\n GetAtomicValues().SequenceEqual(valueObject.GetAtomicValues());\n}\nThe Address value object implementation would look like this:
public sealed class Address : ValueObject\n{\n public string Street { get; init; }\n public string City { get; init; }\n public string State { get; init; }\n public string Country { get; init; }\n public string ZipCode { get; init; }\n\n protected override IEnumerable<object> GetAtomicValues()\n {\n yield return Street;\n yield return City;\n yield return State;\n yield return Country;\n yield return ZipCode;\n }\n}\nI use value objects to solve primitive obsession and encapsulate domain invariants.\nEncapsulation is an important aspect of any domain model.\nYou shouldn't be able to create a value object in an invalid state.
\nValue objects also give you type safety.\nTake a look at this method signature:
\npublic interface IPricingService\n{\n decimal Calculate(Apartment apartment, DateOnly start, DateOnly end);\n}\nThen, compare it to this method signature, where we added value objects.\nYou can see how the IPricingService with value objects is much more explicit.\nYou also get the benefit of type safety.\nWhen compiling the code, value objects reduce the chance of errors creeping in.
public interface IPricingService\n{\n PricingDetails Calculate(Apartment apartment, DateRange period);\n}\nHere are a few more things you should consider to decide if you need value objects:
\nValue objects are part of domain entities, and you need to save them in the database.
\nI'll show you how to use EF Owned Types\nand Complex Types\nto persist value objects.
\nOwned Types can be configured by calling the OwnsOne method when configuring the entity.\nThis tells EF to persist the Address and Price value objects to the same table as the Apartment entity.\nThe value objects are represented with additional columns in the apartments table.
public void Configure(EntityTypeBuilder<Apartment> builder)\n{\n builder.ToTable("apartments");\n\n builder.OwnsOne(property => property.Address);\n\n builder.OwnsOne(property => property.Price, priceBuilder =>\n {\n priceBuilder.Property(money => money.Currency)\n .HasConversion(\n currency => currency.Code,\n code => Currency.FromCode(code));\n });\n}\nA few more remarks about owned types:
\nOwnsManyComplex Types are a new EF feature available in .NET 8.\nThey aren't identified or tracked by a key value.\nComplex types have to be part of an entity type.
\nComplex types are more appropriate for representing value objects with EF.
\nHere's how you can configure an Address value object as a complex type:
public void Configure(EntityTypeBuilder<Apartment> builder)\n{\n builder.ToTable("apartments");\n\n builder.ComplexProperty(property => property.Address);\n}\nA few limitations for complex types:
\nValue objects help design a rich domain model.\nYou can use them to solve primitive obsession and encapsulate domain invariants.\nValue objects can reduce errors by preventing the instantiation of invalid domain objects.
\nYou can use a record or ValueObject base class to represent value objects.\nThis should depend on your specific requirements and the complexity of your domain.\nI use records by default unless I need some qualities of a ValueObject base class.\nFor example, a base class is practical when you want to control equality components.
More learning material about value objects:
\n\nHope this was helpful.
\nSee you next week.
\nThese five Serilog practices make .NET logs easier to search: configure Serilog through the ASP.NET Core configuration system, enable request logging, enrich logs with a CorrelationId, log important application events, and run Seq for local development.\nStructured logs are machine-readable, so you can filter them by properties like CorrelationId instead of scanning text.
Serilog is a structured logging library for .NET.
\nIt's also my preferred logging library in the projects I'm developing.
\nSerilog supports many logging destinations called Sinks.\nThe log destinations range from console and file sinks to managed logging services such as Application Insights.
\nToday, I want to share 5 practical tips for better structured logging with Serilog.
\nThere are two ways you can configure Serilog in ASP.NET Core:
\nThe Fluent API allows you to write code and easily configure Serilog.\nThe downside is you are hardcoding your configuration.\nAny configuration changes require deploying a new version.
\nI prefer using the ASP.NET configuration system to set up Serilog.\nThe benefit is you can change the logging configuration without redeploying your application.
\nYou'll need to install the Serilog.Settings.Configuration library.
This allows you to configure Serilog using the configuration system:
\nbuilder.Host.UseSerilog((context, loggerConfig) =>\n loggerConfig.ReadFrom.Configuration(context.Configuration));\nHere's a Serilog configuration with Console and Seq sinks.\nWe also configure a few Serilog enrichers to enrich application logs with extra information.
\n{\n "Serilog": {\n "Using": ["Serilog.Sinks.Console", "Serilog.Sinks.Seq"],\n "MinimumLevel": {\n "Default": "Information",\n "Override": {\n "Microsoft": "Information"\n }\n },\n "WriteTo": [\n { "Name": "Console" },\n {\n "Name": "Seq",\n "Args": { "serverUrl": "http://localhost:5341" }\n }\n ],\n "Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]\n }\n}\nYou can install the Serilog.AspNetCore library to add Serilog logging for the ASP.NET Core request pipeline.\nIt adds ASP.NET's internal operations to the same Serilog sinks as your application events.
All you need to do is call the UseSerilogRequestLogging method:
app.UseSerilogRequestLogging();\nThe SourceContext for these structured logs is Serilog.AspNetCore.RequestLoggingMiddleware.
Here's an example structured log produced by this middleware:
\n{\n "@t": "2023-12-16T00:00:00.0000000Z",\n "@mt": "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms",\n "@m": "HTTP POST /api/users responded 409 in 24.7928 ms",\n "@i": "37aa1435",\n "@r": ["24.7928"],\n "@tr": "61a449a8606fdb64e88d6c64b7b7354e",\n "@sp": "163ed90674cb12f6",\n "ConnectionId": "0HMVSP0L8FVEN",\n "CorrelationId": "0HMVSP0L8FVEN:0000000B",\n "Elapsed": 24.792778,\n "RequestId": "0HMVSP0L8FVEN:0000000B",\n "RequestMethod": "POST",\n "RequestPath": "/api/users",\n "SourceContext": "Serilog.AspNetCore.RequestLoggingMiddleware",\n "StatusCode": 409\n}\nHow can you track all the logs belonging to the same request?
\nYou can add a CorrelationId property to your structured logs.
This also works across multiple applications.\nYou need to pass the CorrelationId using an HTTP header.\nFor example, you could use a custom X-Correlation-Id header.
In the RequestContextLoggingMiddleware, I'm adding the CorrelationId to the Serilog LogContext.\nThis will make it available to all logs created during this application request.
public class RequestContextLoggingMiddleware\n{\n private const string CorrelationIdHeaderName = "X-Correlation-Id";\n private readonly RequestDelegate _next;\n\n public RequestContextLoggingMiddleware(RequestDelegate next)\n {\n _next = next;\n }\n\n public Task Invoke(HttpContext context)\n {\n string correlationId = GetCorrelationId(context);\n\n using (LogContext.PushProperty("CorrelationId", correlationId))\n {\n return _next.Invoke(context);\n }\n }\n\n private static string GetCorrelationId(HttpContext context)\n {\n context.Request.Headers.TryGetValue(\n CorrelationIdHeaderName, out StringValues correlationId);\n\n return correlationId.FirstOrDefault() ?? context.TraceIdentifier;\n }\n}\nI like to create an extension method for adding the middleware.\nThe UseRequestContextLogging method will add the RequestContextLoggingMiddleware to the request pipeline.\nNote that the order of registering middleware is important.\nIf you want the CorrelationId in all your logs, you want to place this middleware at the start.
public static IApplicationBuilder UseRequestContextLogging(\n this IApplicationBuilder app)\n{\n app.UseMiddleware<RequestContextLoggingMiddleware>();\n\n return app;\n}\nIn general, I try to log important events in my application.\nThis includes current request information, errors, failures, unexpected values, branching points, etc.
\nI'm a proponent of using the Result pattern to express application failures.\nSo, having a custom middleware to log request processing results is important.
\nSome developers prefer using exceptions to achieve the same functionality.\nI disagree with this.\nUsing exceptions for flow control is a bad practice.\nBut still, don't forget to add a global exception handler for unhandled exceptions.
\nIf you're using the CQRS pattern with MediatR, you can easily add logging for all application requests.
\nIn the RequestLoggingPipelineBehavior I'm pushing the Error property to the LogContext.\nThe error object is deconstructed into a JSON value in the structured log.\nThis lets me filter my logs based on the error details.
internal sealed class RequestLoggingPipelineBehavior<TRequest, TResponse>\n : IPipelineBehavior<TRequest, TResponse>\n where TRequest : class\n where TResponse : Result\n{\n private readonly ILogger _logger;\n\n public RequestLoggingPipelineBehavior(ILogger logger)\n {\n _logger = logger;\n }\n\n public async Task<TResponse> Handle(\n TRequest request,\n RequestHandlerDelegate<TResponse> next,\n CancellationToken cancellationToken)\n {\n string requestName = typeof(TRequest).Name;\n\n _logger.LogInformation(\n "Processing request {RequestName}", requestName);\n\n TResponse result = await next();\n\n if (result.IsSuccess)\n {\n _logger.LogInformation(\n "Completed request {RequestName}", requestName);\n }\n else\n {\n using (LogContext.PushProperty("Error", result.Error, true))\n {\n _logger.LogError(\n "Completed request {RequestName} with error", requestName);\n }\n }\n\n return result;\n }\n}\nSeq is a self-hosted search, analysis, and alerting server built for structured log data.\nIt's free to use for local development.\nIt offers advanced search and filtering capabilities on the structured log data.
\nYou can spin up a Seq instance in a Docker container:
\nversion: '3.4'\n\nservices:\n seq:\n image: datalust/seq:latest\n container_name: seq\n environment:\n - ACCEPT_EULA=Y\n ports:\n - 5341:5341\n - 8081:80\nYou can start filtering data when you configure Serilog to write application logs to the Seq instance.
\n![\"Seq](\"https://milanjovanovic.tech/blogs/mnw_068/seq.png\")
\nStructured logs follow follow the same structure.\nAnd since structured logs are machine-readable, you can search them for specific information.\nStructured logs provide more context and details about application errors.\nThey make it easier to identify and fix problems.
\nYou can use Serilog's powerful LogContext to enrich your logs with a CorrelationId.\nThis lets you easily track all logs related to a single application request.
When you have structured logging set up, you'll want to search and analyze your logs.\nSeq is an excellent tool for this that you can use for local development.
\nIf you want to get started with Seq, check out my beginner Seq tutorial.
\nThanks for reading, and stay awesome!
\nData isolation means each module in a modular monolith reads and writes only its own tables, and other modules reach that data through the module's public API.\nThere are four levels: separate tables, a separate schema per module, a separate database per module, and different persistence.\nStart with schemas and introduce separate databases later if the requirements demand it.
\nModular monoliths are an architectural approach that's becoming very popular.\nThey combine the benefits of modularity and monolithic design.
\nModular monoliths try to solve the shortcomings of monolithic and microservice architectures.
\nOne problem I often see with monolithic architectures is tight coupling between components.
\nThis leads to dependencies between different parts of the system.
\nModular monoliths enforce better architectural practices with well-defined module boundaries and communication patterns.
\nBut one aspect you can't overlook is data isolation between modules.
\nData isolation ensures that modules are independent and loosely coupled.
\nToday, I will show you four data isolation approaches for modular monoliths:
\nLet's first understand why data isolation is important in a modular monolith architecture.
\nA modular monolith has strict rules for data integrity:
\nModules inside a modular monolith should be self-contained.\nEach module handles its own data.\nOther modules can access that data using the module's public API.
\nWhat are the benefits of this design?
\nKeeping modules isolated from each other promotes modularity and loose coupling.\nIt makes it easier to introduce new changes to the system.\nThere are fewer unintended side effects when components are loosely coupled.
\nIf you are using a relational database, you can still maintain referential integrity.\nRemoving the foreign keys when extracting tables is not a problem.
\n![\"Tightly](\"https://milanjovanovic.tech/blogs/mnw_067/monolith_components.png\")
\nThe simplest solution is to have no isolation at the database level.\nTables for all modules live inside one database.\nIt's not easy to determine which tables belong to which module.
\nI'm only mentioning this approach for the sake of completeness.
\nBut this approach works fine up to a particular application size.
\nHowever, the more tables you have, the harder it becomes to keep them isolated between modules.
\nYou can improve this by adding logical isolation between tables.
\n![\"Level](\"https://milanjovanovic.tech/blogs/mnw_067/separate_table.png\")
\nGrouping related tables in the database is a way to introduce logical isolation.\nYou can implement this using database schemas.\nEach module has a unique schema containing the module's tables.
\nNow, it becomes easy to distinguish which module contains which tables.
\nAn easy way to implement this is using multiple EF Core database contexts.
\nYou can also introduce rules to prevent querying data from other modules.\nFor example, you could implement this using architecture tests.
\nI always start with logical data isolation when building a modular monolith.
\nBut what if this isn't enough?
\n![\"Level](\"https://milanjovanovic.tech/blogs/mnw_067/separate_schema.png\")
\nThe next data isolation level is moving each module's data into separate databases.\nThis approach has more constraints than data isolation using schemas.
\nThis is the way to go if you need strict data isolation rules between modules.\nBut, the downside is more operational complexity.\nYou have to manage infrastructure for multiple databases.
\nHowever, this is an excellent step toward extracting modules.
\nFirst, you move the tables of the module you want to extract into a separate database.\nThis also forces you to solve any database coupling problems between your modules.\nYou're ready to extract the module once you move the tables into a separate database.
\nCan we take the module data isolation further?
\n![\"Level](\"https://milanjovanovic.tech/blogs/mnw_067/separate_db.png\")
\nWho says you have to use the same database type for all modules?
\nI work with relational (SQL) databases most of the time.\nRelational databases are amazing and solve a wide range of problems.\nBut sometimes, a document or graph database is a much better solution.
\nThe idea here is similar: you're doing data isolation using separate databases.
\nHowever, you can introduce a different database type to solve specific problems.\nFor example, you can use a relational database for one module.\nAnd a graph or column-store database for another module.\nYou also have to maintain different persistence models in your application.
\nThis could be a worthwhile tradeoff for your use case.\nBut it takes careful planning.
\n![\"Level](\"https://milanjovanovic.tech/blogs/mnw_067/separate_db_type.png\")
\nModular monoliths are excellent if you don't need microservices right away.\nYou develop your application as a monolith with distinct boundaries inside the system.\nYou still have the flexibility to extract modules and move to microservices.\nBut you have faster development speed with a modular monolith.
\nModules have to comply with a few rules.\nThey can only access their own tables.\nThey can't share tables with other modules.\nAnd they can't directly query tables of other modules.\nThese rules help to enforce data isolation between modules.
\nBut you still have to implement data isolation at the database level.
\nThere are four options you can choose from:
\nI always go for logical isolation using schemas.\nIt's easy to implement and helps me understand my boundaries better.\nDepending on the requirements, I can introduce separate databases later.
\nHope this was helpful.
\nSee you next week.
\nASP.NET Core 8 gives you two ways to handle exceptions globally.\nThe old way is custom middleware that wraps the request in a try-catch and returns a ProblemDetails response.\nThe new way is the IExceptionHandler abstraction, registered with AddExceptionHandler and plugged into the pipeline with UseExceptionHandler.
Exceptions are for exceptional situations.\nI even wrote about avoiding exceptions entirely.
\nBut they will inevitably happen in your applications, and you need to handle them.
\nYou can implement a global exception handling mechanism or handle only specific exceptions.
\nASP.NET Core gives you a few options on how to implement this. So which one should you choose?
\nToday, I want to show you an old and new way to handle exceptions in ASP.NET Core 8.
\nThe standard to implement exception handling in ASP.NET Core is using middleware.\nMiddleware allows you to introduce logic before or after executing HTTP requests.\nYou can easily extend this to implement exception handling.\nAdd a try-catch statement in the middleware and return an error HTTP response.
There are 3 ways to create middleware in ASP.NET Core:
\nIMiddlewareThe convention-based approach requires you to define an InvokeAsync method.
Here's an ExceptionHandlingMiddleware defined by convention:
public class ExceptionHandlingMiddleware\n{\n private readonly RequestDelegate _next;\n private readonly ILogger<ExceptionHandlingMiddleware> _logger;\n\n public ExceptionHandlingMiddleware(\n RequestDelegate next,\n ILogger<ExceptionHandlingMiddleware> logger)\n {\n _next = next;\n _logger = logger;\n }\n\n public async Task InvokeAsync(HttpContext context)\n {\n try\n {\n await _next(context);\n }\n catch (Exception exception)\n {\n _logger.LogError(\n exception, "Exception occurred: {Message}", exception.Message);\n\n var problemDetails = new ProblemDetails\n {\n Status = StatusCodes.Status500InternalServerError,\n Title = "Server Error"\n };\n\n context.Response.StatusCode =\n StatusCodes.Status500InternalServerError;\n\n await context.Response.WriteAsJsonAsync(problemDetails);\n }\n }\n}\nThe ExceptionHandlingMiddleware will catch any unhandled exception and return a Problem Details response.\nYou can decide how much information you want to return to the caller.\nIn this example, I'm hiding the exception details.
You also need to add this middleware to the ASP.NET Core request pipeline:
\napp.UseMiddleware<ExceptionHandlingMiddleware>();\nASP.NET Core 8\nintroduces a new IExceptionHandler\nabstraction for managing exceptions.\nThe built-in exception handler middleware uses IExceptionHandler implementations to handle exceptions.
This interface has only one TryHandleAsync method.
TryHandleAsync attempts to handle the specified exception within the ASP.NET Core pipeline.\nIf the exception can be handled, it should return true.\nIf the exception can't be handled, it should return false.\nThis allows you to implement custom exception-handling logic for different scenarios.
Here's a GlobalExceptionHandler implementation:
internal sealed class GlobalExceptionHandler : IExceptionHandler\n{\n private readonly ILogger<GlobalExceptionHandler> _logger;\n\n public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)\n {\n _logger = logger;\n }\n\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n _logger.LogError(\n exception, "Exception occurred: {Message}", exception.Message);\n\n var problemDetails = new ProblemDetails\n {\n Status = StatusCodes.Status500InternalServerError,\n Title = "Server error"\n };\n\n httpContext.Response.StatusCode = problemDetails.Status.Value;\n\n await httpContext.Response\n .WriteAsJsonAsync(problemDetails, cancellationToken);\n\n return true;\n }\n}\nYou need two things to add an IExceptionHandler implementation to the ASP.NET Core request pipeline:
IExceptionHandler service with dependency injectionExceptionHandlerMiddleware\nwith the request pipelineYou call the AddExceptionHandler method to register the GlobalExceptionHandler as a service.\nIt's registered with a singleton lifetime.\nSo be careful about injecting services with a different lifetime.
I'm also calling AddProblemDetails to generate a Problem Details response for common exceptions.
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();\nbuilder.Services.AddProblemDetails();\nYou also need to call UseExceptionHandler to add the ExceptionHandlerMiddleware to the request pipeline:
app.UseExceptionHandler();\nYou can add multiple IExceptionHandler implementations, and they're called in the order they are registered.\nA possible use case for this is using exceptions for flow control.
You can define custom exceptions like BadRequestException and NotFoundException.\nThey correspond with the HTTP status code you would return from the API.
Here's a BadRequestExceptionHandler implementation:
internal sealed class BadRequestExceptionHandler : IExceptionHandler\n{\n private readonly ILogger<BadRequestExceptionHandler> _logger;\n\n public BadRequestExceptionHandler(ILogger<BadRequestExceptionHandler> logger)\n {\n _logger = logger;\n }\n\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n if (exception is not BadRequestException badRequestException)\n {\n return false;\n }\n\n _logger.LogError(\n badRequestException,\n "Exception occurred: {Message}",\n badRequestException.Message);\n\n var problemDetails = new ProblemDetails\n {\n Status = StatusCodes.Status400BadRequest,\n Title = "Bad Request",\n Detail = badRequestException.Message\n };\n\n httpContext.Response.StatusCode = problemDetails.Status.Value;\n\n await httpContext.Response\n .WriteAsJsonAsync(problemDetails, cancellationToken);\n\n return true;\n }\n}\nAnd here's a NotFoundExceptionHandler implementation:
internal sealed class NotFoundExceptionHandler : IExceptionHandler\n{\n private readonly ILogger<NotFoundExceptionHandler> _logger;\n\n public NotFoundExceptionHandler(ILogger<NotFoundExceptionHandler> logger)\n {\n _logger = logger;\n }\n\n public async ValueTask<bool> TryHandleAsync(\n HttpContext httpContext,\n Exception exception,\n CancellationToken cancellationToken)\n {\n if (exception is not NotFoundException notFoundException)\n {\n return false;\n }\n\n _logger.LogError(\n notFoundException,\n "Exception occurred: {Message}",\n notFoundException.Message);\n\n var problemDetails = new ProblemDetails\n {\n Status = StatusCodes.Status404NotFound,\n Title = "Not Found",\n Detail = notFoundException.Message\n };\n\n httpContext.Response.StatusCode = problemDetails.Status.Value;\n\n await httpContext.Response\n .WriteAsJsonAsync(problemDetails, cancellationToken);\n\n return true;\n }\n}\nYou also need to register both exception handlers by calling AddExceptionHandler:
builder.Services.AddExceptionHandler<BadRequestExceptionHandler>();\nbuilder.Services.AddExceptionHandler<NotFoundExceptionHandler>();\nThe BadRequestExceptionHandler will execute first and try to handle the exception.\nIf the exception isn't handled, NotFoundExceptionHandler will execute next and attempt to handle the exception.
Using middleware for exception handling is an excellent solution in ASP.NET Core.\nHowever, it's great that we have new options using the IExceptionHandler interface.\nI will use the new approach in ASP.NET Core 8 projects.
I'm very much against using exceptions for flow control.\nExceptions are a last resort when you can't continue normal application execution.\nThe Result pattern is a better alternative.
\nExceptions are also extremely expensive,\nas David Fowler noted:
\n![\"David](\"https://milanjovanovic.tech/blogs/mnw_066/fowler_comment.png\")
\nIf you want to get rid of exceptions in your code, check out this video.
\nThanks for reading, and stay awesome!
\nRefactoring restructures existing code without changing its behavior, one small transformation at a time.\nI take a nearly 100-line AddCustomer method and apply five techniques to it: extract method, extract interface, extract class, refactoring toward functional code, and pushing logic down into the domain.
Refactoring is a technique for restructuring existing code without changing its behavior.\nYou can think of refactoring as a series of small code transformations.
\nOne change (refactoring) does little.\nBut a sequence of refactors produces a significant transformation.
\nThere's no better way to learn refactoring than practicing.
\nSo I prepared a refactoring exercise for you.
\nToday I'm going to refactor some poorly written code.
\nAnd I'll show you 5 awesome refactoring techniques along the way:
\nWe will refactor the CustomerService below to try to improve the code.
I want to achieve three goals with this refactor.
\nOr rather, I want to improve three qualities of the CustomerService:
To improve these qualities, we need to figure out what's preventing us from attaining them.
\nSo, let's first understand what the CustomerService is doing on a high level:
Company and creating a new CustomerCustomer has a credit limit and the amountCustomer to the database if they meet a specific conditionYou can see quite a few things are happening inside the AddCustomer method.
It's almost 100 lines of code, which reduces readability.
\nIt's difficult to test because we can't control any external dependencies.
\nIt's impossible to extend the behavior of the CustomerService without changing the code.
But we can fix all these problems.\nLet me show you how.
\npublic class CustomerService\n{\n public bool AddCustomer(\n string firstName,\n string lastName,\n string email,\n DateTime dateOfBirth,\n int companyId)\n {\n if (string.IsNullOrEmpty(firstName) || string.IsNullOrEmpty(lastName))\n {\n return false;\n }\n\n if (!email.Contains('@') && !email.Contains('.'))\n {\n return false;\n }\n\n var now = DateTime.Now;\n var age = now.Year - dateOfBirth.Year;\n if (dateOfBirth.Date > now.AddYears(-age))\n {\n age -= 1;\n }\n\n if (age < 21)\n {\n return false;\n }\n\n var companyRepository = new CompanyRepository();\n var company = companyRepository.GetById(companyId);\n\n var customer = new Customer\n {\n Company = company,\n DateOfBirth = dateOfBirth,\n EmailAddress = email,\n Firstname = firstName,\n Surname = lastName\n };\n\n if (company.Type == "VeryImportantClient")\n {\n // Skip credit check\n customer.HasCreditLimit = false;\n }\n else if (company.Type == "ImportantClient")\n {\n // Do credit check and double credit limit\n customer.HasCreditLimit = true;\n using var creditService = new CustomerCreditServiceClient();\n\n var creditLimit = creditService.GetCreditLimit(\n customer.Firstname,\n customer.Surname,\n customer.DateOfBirth);\n\n creditLimit *= 2;\n customer.CreditLimit = creditLimit;\n }\n else\n {\n // Do credit check\n customer.HasCreditLimit = true;\n using var creditService = new CustomerCreditServiceClient();\n\n var creditLimit = creditService.GetCreditLimit(\n customer.Firstname,\n customer.Surname,\n customer.DateOfBirth);\n\n customer.CreditLimit = creditLimit;\n }\n\n if (customer.HasCreditLimit && customer.CreditLimit < 500)\n {\n return false;\n }\n\n var customerRepository = new CustomerRepository();\n customerRepository.AddCustomer(customer);\n\n return true;\n }\n}\nThe first part of the code validating input parameters is pretty concise.\nIt also follows the early return principle.
\nThe validation consists of simple input validation and a calculation for the customer's age.
\nI would start with an extract method refactor to move the validation into one place.
\nif (string.IsNullOrEmpty(firstName) || string.IsNullOrEmpty(lastName))\n{\n return false;\n}\n\nif (!email.Contains('@') && !email.Contains('.'))\n{\n return false;\n}\n\nvar now = DateTime.Now;\nvar age = now.Year - dateOfBirth.Year;\nif (dateOfBirth.Date > now.AddYears(-age))\n{\n age -= 1;\n}\n\nif (age < 21)\n{\n return false;\n}\nCalculating the age isn't part of the validation flow, so I'll extract that into the CalculateAge method.
int CalculateAge(DateTime dateOfBirth, DateTime now)\n{\n var age = now.Year - dateOfBirth.Year;\n if (dateOfBirth.Date > now.AddYears(-age))\n {\n age -= 1;\n }\n\n return age;\n}\nThen, I'll create the IsValid method to encapsulate all the validation rules.\nInstead of writing many if-else statements, I can write a single bool expression.
I also introduced a minimumAge constant to improve readability.
You can see how the CalculateAge method helps simplify the validation check.
bool IsValid(\n string firstName,\n string lastName,\n string email,\n DateTime dateOfBirth)\n{\n const int minimumAge = 21;\n\n return !string.IsNullOrEmpty(firstName) &&\n !string.IsNullOrEmpty(lastName) &&\n (email.Contains('@') || email.Contains('.')) &&\n CalculateAge(dateOfBirth, DateTime.Now) >= minimumAge;\n}\nThis simplifies the validation code in AddCustomer to:
if (!IsValid(firstName, lastName, email, dateOfBirth))\n{\n return false;\n}\nThe next problem I want to solve is introducing dependency injection to the CustomerService.
Dependency injection allows us to achieve Inversion of Control (IoC).\nWe depend only on interfaces at compile time and on implementations at run time.
\nThe dependency injection pattern has a few important benefits.
\nYou don't have to know how to initialize or dispose of external dependencies.
\nIt also improves testability since you now depend on interfaces.\nInterfaces can be mocked to make unit testing easier.
\nSo let's update the CustomerService not to initialize the dependencies directly:
var companyRepository = new CompanyRepository();\n\nusing var creditService = new CustomerCreditServiceClient();\n\nvar customerRepository = new CustomerRepository();\nInstead, we will inject them as constructor arguments.\nYou can even use the C# 12 primary constructor feature.
\npublic class CustomerService(\n CompanyRepository companyRepository,\n CustomerRepository customerRepository,\n CustomerCreditServiceClient creditService)\n{\n // ...\n}\nThe next step would be introducing interfaces for these dependencies.\nThis comes down to an extract interface refactor.
\nThe credit limit calculation is the most complicated part of the code.\nThere are different business rules based on the company type.
\nI try to notice patterns in the code before refactoring.\nSo here are a few of my observations.
\nMultiple if-else statements based on the Type property make me wonder if I'll need to extend this in the future.\nAdding a new rule would mean another if-else check.\nThe strategy pattern could be an alternative, but a switch statement will also work fine.
Another thing that stands out is the code duplication in the last two blocks.\nThis usually means I can do an extract method refactoring to reduce code duplication.
\nif (company.Type == "VeryImportantClient")\n{\n // Skip credit check\n customer.HasCreditLimit = false;\n}\nelse if (company.Type == "ImportantClient")\n{\n // Do credit check and double credit limit\n customer.HasCreditLimit = true;\n using var creditService = new CustomerCreditServiceClient();\n\n var creditLimit = creditService.GetCreditLimit(\n customer.Firstname,\n customer.Surname,\n customer.DateOfBirth);\n\n creditLimit *= 2;\n customer.CreditLimit = creditLimit;\n}\nelse\n{\n // Do credit check\n customer.HasCreditLimit = true;\n using var creditService = new CustomerCreditServiceClient();\n\n var creditLimit = creditService.GetCreditLimit(\n customer.Firstname,\n customer.Surname,\n customer.DateOfBirth);\n\n customer.CreditLimit = creditLimit;\n}\nThe first thing I want to do is introduce an enum for the CompanyType.
This is a clean coding principle I often use.\nIt improves the readability and extensibility of the code.
\npublic enum CompanyType\n{\n Regular = 0,\n ImportantClient = 1,\n VeryImportantClient = 2\n}\nThe next thing that bothers me is that the credit limit calculation doesn't belong to the CustomerService.\nIt violates the single responsibility principle.
So I want to introduce a dedicated CreditLimitCalculator using an extract class refactoring.\nI replaced the if-else statements with a switch expression that I can easily extend in the future.
public class CreditLimitCalculator(\n CustomerCreditServiceClient customerCreditServiceClient)\n{\n public (bool HasCreditLimit, decimal? CreditLimit) Calculate(\n Customer customer,\n Company company)\n {\n return company.Type switch\n {\n CompanyType.VeryImportantClient => (false, null),\n CompanyType.ImportantClient => (true, GetCreditLimit(customer) * 2),\n _ => (true, GetCreditLimit(customer))\n };\n }\n\n private decimal GetCreditLimit(Customer customer)\n {\n return customerCreditServiceClient.GetCreditLimit(\n customer.FirstName,\n customer.LastName,\n customer.DateOfBirth);\n }\n}\nLet's pause momentarily and review the refactored version of the CustomerService.\nI'm confident you will find it more readable and easier to understand.\nWe can easily test this class and verify that the behavior is correct.
I would usually stop the refactoring at this point, since I'm happy with the results.
\nBut can we take this further?
\npublic class CustomerService(\n CompanyRepository companyRepository,\n CustomerRepository customerRepository,\n CreditLimitCalculator creditLimitCalculator)\n{\n public bool AddCustomer(\n string firstName,\n string lastName,\n string email,\n DateTime dateOfBirth,\n int companyId)\n {\n if (!IsValid(firstName, lastName, email, dateOfBirth))\n {\n return false;\n }\n\n var company = companyRepository.GetById(companyId);\n\n var customer = new Customer\n {\n Company = company,\n DateOfBirth = dateOfBirth,\n EmailAddress = email,\n FirstName = firstName,\n LastName = lastName\n };\n\n (customer.HasCreditLimit, customer.CreditLimit) =\n creditLimitCalculator.Calculate(customer, company);\n\n if (customer is { HasCreditLimit: true, CreditLimit: < 500 })\n {\n return false;\n }\n\n customerRepository.AddCustomer(customer);\n\n return true;\n }\n}\nThis part is optional, but I want to show you how to simplify the CustomerService by pushing logic into the domain.
What if we moved the responsibility of creating a Customer into the class?
I often use the static factory pattern to implement this.\nThe caveat is I have to take a dependency on CreditLimitCalculator.\nI'm trading off domain model purity to get business rules completeness.
I also added the IsUnderCreditLimit method to wrap the credit limit check.
public class Customer\n{\n // Properties omited\n\n public static Customer Create(\n Company company,\n string firstName,\n string lastName,\n string email,\n DateTime dateOfBirth,\n CreditLimitCalculator creditLimitCalculator)\n {\n var customer = new Customer\n {\n Company = company,\n DateOfBirth = dateOfBirth,\n EmailAddress = email,\n FirstName = firstName,\n LastName = lastName\n };\n\n (customer.HasCreditLimit, customer.CreditLimit) =\n creditLimitCalculator.Calculate(customer, company);\n\n return customer;\n }\n\n public bool IsUnderCreditLimit() => HasCreditLimit && CreditLimit < 500;\n}\nThis is what the CustomerService looks like now:
public class CustomerService(\n CompanyRepository companyRepository,\n CustomerRepository customerRepository,\n CreditLimitCalculator creditLimitCalculator)\n{\n public bool AddCustomer(\n string firstName,\n string lastName,\n string email,\n DateTime dateOfBirth,\n int companyId)\n {\n if (!IsValid(firstName, lastName, email, dateOfBirth))\n {\n return false;\n }\n\n var company = companyRepository.GetById(companyId);\n\n var customer = Customer.Create(\n company,\n firstName,\n lastName,\n email,\n dateOfBirth,\n creditLimitCalculator);\n\n if (customer.IsUnderCreditLimit())\n {\n return false;\n }\n\n customerRepository.AddCustomer(customer);\n\n return true;\n }\n}\nWhat do you think about this implementation?
\nFirst of all, congrats on making it to the end.\nThis was a much longer newsletter issue than usual.\nWhat do you think of this format?
\nWriting unit tests before starting the refactoring would be a great idea.\nUnit tests will help detect any changes in behavior.
\nRemember, refactoring is transforming the existing code without changing the behavior.
\nHere are a few ideas on how you could further refactor the code:
\nIf you want to try this refactoring exercise, you can find the complete source code here.
\nHope this was helpful.
\nSee you next week.
\nEF Core interceptors let you intercept, change, or suppress EF Core operations.\nEvery interceptor implements the IInterceptor interface.\nThe most popular one is the SaveChangesInterceptor, which adds behavior before or after saving changes to the database.
EF Core is my favorite ORM for .NET applications.\nYet, its many fantastic features sometimes go unnoticed.\nFor example, query splitting,\nquery filters,\nand interceptors.
\nEF interceptors are interesting because you can do powerful things with them.\nFor example, you can hook into materialization, handle optimistic concurrency errors, or add query hints.
\nThe most practical use case is adding behavior when saving changes to the database.
\nToday I want to show you three unique use cases for EF Core interceptors:
\nEF Core interceptors\nallow you to intercept, change, or suppress EF Core operations.\nEvery interceptor implements the IInterceptor interface.\nA few common derived interfaces include IDbCommandInterceptor, IDbConnectionInterceptor, and IDbTransactionInterceptor.
The most popular one is the ISaveChangesInterceptor. It allows you to add behavior before or after saving changes.
Interceptors are registered for each DbContext instance when configuring the context.
public interface IInterceptor\n{\n}\nYou don't have to implement these interfaces directly.\nIt's better to use concrete implementations and override the needed methods.
\nFor example, I'll show you how to use the SaveChangesInterceptor.
An audit log of entity changes is a valuable feature in some applications.\nYou write additional audit information every time an entity is created or modified.\nThe audit log could also contain the complete before/after values, depending on your requirements.
\nHowever, let's use a simple example to make it easy to understand.
\nI have an IAuditable interface with two properties representing when an entity was created or modified.
public interface IAuditable\n{\n DateTime CreatedOnUtc { get; }\n\n DateTime? ModifiedOnUtc { get; }\n}\nNext, I'll implement an UpdateAuditableInterceptor interceptor to write the audit values.\nIt uses the ChangeTracker to find all IAuditable instances and sets the respective property value.
I want to highlight that I'm overriding the SavingChangesAsync method here.\nSavingChangesAsync runs before the changes are saved in the database and any updates applied inside the UpdateAuditableInterceptor\nare also part of the current database transaction.
This implementation can be easily extended to include the information about the current user.
\ninternal sealed class UpdateAuditableInterceptor : SaveChangesInterceptor\n{\n public override ValueTask<InterceptionResult<int>> SavingChangesAsync(\n DbContextEventData eventData,\n InterceptionResult<int> result,\n CancellationToken cancellationToken = default)\n {\n if (eventData.Context is not null)\n {\n UpdateAuditableEntities(eventData.Context);\n }\n\n return base.SavingChangesAsync(eventData, result, cancellationToken);\n }\n\n private static void UpdateAuditableEntities(DbContext context)\n {\n DateTime utcNow = DateTime.UtcNow;\n var entities = context.ChangeTracker.Entries<IAuditable>().ToList();\n\n foreach (EntityEntry<IAuditable> entry in entities)\n {\n if (entry.State == EntityState.Added)\n {\n SetCurrentPropertyValue(\n entry, nameof(IAuditable.CreatedOnUtc), utcNow);\n }\n\n if (entry.State == EntityState.Modified)\n {\n SetCurrentPropertyValue(\n entry, nameof(IAuditable.ModifiedOnUtc), utcNow);\n }\n }\n\n static void SetCurrentPropertyValue(\n EntityEntry entry,\n string propertyName,\n DateTime utcNow) =>\n entry.Property(propertyName).CurrentValue = utcNow;\n }\n}\nAnother use case for EF interceptors is publishing domain events.\nDomain events are a DDD tactical pattern to create loosely coupled systems.
\nDomain events allow you to express side effects explicitly and provide a better separation of concerns in the domain.
\nYou can create an IDomainEvent interface, which derives from MediatR.INotification.\nThis allows you to use the IPublisher to publish domain events and handle them asynchronously.
using MediatR;\n\npublic interface IDomainEvent : INotification\n{\n}\nThen, I'll create a PublishDomainEventsInterceptor that also inherits from SaveChangesInterceptor.\nHowever, this time, we're using the SavedChangesAsync to publish the domain events after saving changes in the database.
This has two important implications:
\nYou can make this process more reliable by using an Outbox.
\ninternal sealed class PublishDomainEventsInterceptor : SaveChangesInterceptor\n{\n private readonly IPublisher _publisher;\n\n public PublishDomainEventsInterceptor(IPublisher publisher)\n {\n _publisher = publisher;\n }\n\n public override async ValueTask<int> SavedChangesAsync(\n SaveChangesCompletedEventData eventData,\n int result,\n CancellationToken cancellationToken = default)\n {\n if (eventData.Context is not null)\n {\n await PublishDomainEventsAsync(eventData.Context);\n }\n\n return result;\n }\n\n private async Task PublishDomainEventsAsync(DbContext context)\n {\n var domainEvents = context\n .ChangeTracker\n .Entries<Entity>()\n .Select(entry => entry.Entity)\n .SelectMany(entity =>\n {\n List<IDomainEvent> domainEvents = entity.DomainEvents;\n\n entity.ClearDomainEvents();\n\n return domainEvents;\n })\n .ToList();\n\n foreach (IDomainEvent domainEvent in domainEvents)\n {\n await _publisher.Publish(domainEvent);\n }\n }\n}\nInstead of publishing domain events as part of the EF transaction, you can convert them to Outbox messages.
\nHere's an InsertOutboxMessagesInterceptor that does precisely this.
It overrides the SavingChangesAsync method.\nWhich means it runs inside the current EF transaction before saving changes.
The InsertOutboxMessagesInterceptor converts any domain events into an OutboxMessage and adds it to the respective DbSet<OutboxMessage>.\nThis means they will be saved to the database with any existing changes inside the same transaction.
This is an atomic operation.
\nEither everything succeeds or everything fails.
\nThere's no in-between state like in the PublishDomainEventsInterceptor.
You can then create a background worker that will process the Outbox messages.
\nAnd this is how you implement the Outbox pattern with EF Core.
\nusing Newtonsoft.Json;\n\npublic sealed class InsertOutboxMessagesInterceptor : SaveChangesInterceptor\n{\n private static readonly JsonSerializerSettings Serializer = new()\n {\n TypeNameHandling = TypeNameHandling.All\n };\n\n public override ValueTask<InterceptionResult<int>> SavingChangesAsync(\n DbContextEventData eventData,\n InterceptionResult<int> result,\n CancellationToken cancellationToken = default)\n {\n if (eventData.Context is not null)\n {\n InsertOutboxMessages(eventData.Context);\n }\n\n return base.SavingChangesAsync(eventData, result, cancellationToken);\n }\n\n private static void InsertOutboxMessages(DbContext context)\n {\n context\n .ChangeTracker\n .Entries<Entity>()\n .Select(entry => entry.Entity)\n .SelectMany(entity =>\n {\n List<IDomainEvent> domainEvents = entity.DomainEvents;\n\n entity.ClearDomainEvents();\n\n return domainEvents;\n })\n .Select(domainEvent => new OutboxMessage\n {\n Id = domainEvent.Id,\n OccurredOnUtc = domainEvent.OccurredOnUtc,\n Type = domainEvent.GetType().Name,\n Content = JsonConvert.SerializeObject(domainEvent, Serializer)\n })\n .ToList();\n\n context.Set<OutboxMessage>().AddRange(outboxMessages);\n }\n}\nEF interceptors should be lightweight and stateless.\nYou can add them to the DbContext by calling AddInterceptors and passing in the interceptor instances.
I like to configure the interceptors with Dependency Injection for two reasons:
\nDbContext using AddDbContextHere's how you can configure the UpdateAuditableInterceptor and InsertOutboxMessagesInterceptor with the ApplicationDbContext:
services.AddSingleton<UpdateAuditableInterceptor>();\nservices.AddSingleton<InsertOutboxMessagesInterceptor>();\n\nservices.AddDbContext<IApplicationDbContext, ApplicationDbContext>(\n (sp, options) => options\n .UseSqlServer(connectionString)\n .AddInterceptors(\n sp.GetRequiredService<UpdateAuditableInterceptor>(),\n sp.GetRequiredService<InsertOutboxMessagesInterceptor>()));\nInterceptors allow you to do almost anything with an EF Core operation.\nBut with great power comes great responsibility.\nYou should be mindful that interceptors have an impact on performance.\nCalls to external services or handling events will slow down the operation.
\nRemember, you don't necessarily have to use EF interceptors.\nYou can achieve the same behavior by overriding the SaveChangesAsync method on the DbContext and adding your custom logic there.
I showed you a few practical use cases for EF interceptors in this week's issue.
\nBut, if you want to see more examples, I have a few videos about:
\n\nThanks for reading, and stay awesome!
\nThere are two common ways to generate PDF documents in .NET.\nYou can compose the document in code with a library like QuestPDF and its fluent API.\nOr you can build an HTML template, for example an ASP.NET Core Razor view, and convert it to PDF with a library like IronPDF.
\nReporting is essential for business applications like e-commerce, shipping, fintech, etc.
\nOne of the most popular document formats for reporting purposes is PDF.
\nPDF stands for Portable Document Format.\nIt's a file format to present documents (including text formatting and images) independently of application software, hardware, and operating systems.
\nSome common problems .NET developers will face when working with PDF files:
\nToday I want to show you a few interesting ways to generate PDF files in .NET.
\nQuestPDF is an open-source .NET library for generating PDF documents.\nIt exposes a fluent API you can use to compose together many simple elements to create complex documents.\nUnlike other libraries, it does not rely on HTML-to-PDF conversion.
\nLet's install the QuestPDF NuGet package:
\nInstall-Package QuestPDF\nHere's how you can generate a simplified invoice with QuestPDF:
\nusing QuestPDF.Fluent;\nusing QuestPDF.Helpers;\nusing QuestPDF.Infrastructure;\n\nDocument.Create(container =>\n{\n container.Page(page =>\n {\n page.Margin(50);\n page.Size(PageSizes.A4);\n page.PageColor(Colors.White);\n page.DefaultTextStyle(x => x.FontSize(16));\n\n page.Header()\n .AlignCenter()\n .Text("Invoice #: 2023-77")\n .SemiBold().FontSize(24).FontColor(Colors.Grey.Darken4);\n\n page.Content()\n .Table(table =>\n {\n table.ColumnsDefinition(columns =>\n {\n columns.ConstantColumn(20);\n columns.RelativeColumn();\n columns.RelativeColumn();\n });\n\n table.Header(header =>\n {\n header.Cell().Text("#");\n header.Cell().Text("Product");\n header.Cell().AlignRight().Text("Price");\n });\n\n foreach (var lineItem in lineItems)\n {\n table.Cell().Text(lineItem.Index.ToString());\n table.Cell().Text(lineItem.Name);\n table.Cell().Text($"${lineItem.Price}");\n }\n });\n });\n})\n.GeneratePdf("invoice.pdf");;\nWhat I like about QuestPDF:
\nWhat I don't like about QuestPDF:
\nLicensing
\nQuestPDF is free for small companies and development use.\nThere's also a commercial license for larger companies.\nYou can check out the licensing details here.
\nThe more common approach for generating PDF files is using an HTML template.
\nMy favorite library that supports this is IronPDF.
\nIronPDF is a C# PDF library that allows for fast and efficient manipulation of PDF files.\nIt also has many valuable features, like exporting to PDF/A format\nand digitally signing PDF documents.
\nBut what's the idea behind using an HTML template?
\nFirst of all, you have more control over formatting the document.\nYou can use CSS to style the HTML markup, which will be applied when exporting to a PDF document.
\nAn interesting implementation approach is using ASP.NET Core MVC views\nand the Razor syntax.\nYou can pass an object to the view at runtime to render dynamic HTML content.
\nI've used this approach with MVC views on a few projects with excellent results.
\nLet's start by installing the IronPDF NuGet package:
\nInstall-Package IronPdf\nI'm using a strongly typed Razor view to define my markup.\nThe InoviceViewModel class is the model, and it's used to create dynamic content.
@model ViewModels.InoviceViewModel\n\n<div>Invoice number: @Model.InvoiceNumber</div>\n<div>Invoice date: @Model.InvoiceDate</div>\n<br/>\n<span>Line items:</span>\n<ul>\n @foreach(var lineItem in Model.LineItems)\n {\n <li>@lineItem.Name | @lineItem.Price</li>\n }\n</ul>\nNow, you need to use the IronPDF ChromePdfRenderer to convert the HTML to a PDF document.
var html = ConvertRazorViewToHtml(invoice);\n\nvar renderer = new ChromePdfRenderer();\n\nvar pdf = renderer.RenderHtmlAsPdf(html);\n\npdf.SaveAs($"invoice-{invoice.InvoiceNumber}.pdf");\nIt really is that simple.
\nLicensing
\nIronPDF is free for development use and has multiple pricing tiers for commercial use that you can check out here.
\nAnother common requirement I've seen is merging multiple PDF files.\nFor example, you could implement a feature to merge the monthly receipts for the accounting department.
\nYou can use the PdfDocument.Merge method to implement this.\nIt accepts a PdfDocument collection as the argument.\nYou'll first have to load the PDF documents into memory before merging them.
Here's an example:
\nvar pdfs = new List<PdfDocument>();\n\npdfs.Add(PdfDocument.FromFile("google-invoice.pdf"));\npdfs.Add(PdfDocument.FromFile("google-ads-invoice.pdf"));\npdfs.Add(PdfDocument.FromFile("converkit-invoice.pdf"));\n\nPdfDocument mergedPdfDocument = PdfDocument.Merge(pdfs);\n\nmergedPdfDocument.SaveAs("merged-invoices.pdf");\nIt's pretty straightforward to return a PDF file from an API endpoint in ASP.NET Core.
\nMinimal APIs have the Results.File method accepting either a file path, stream, or byte array.\nYou also need to specify the content type and an optional file name.\nThe MIME type\nfor PDF files is application/pdf.
Here's how you can return a PDF file from a byte array:
\napp.MapGet("newsletter/download", () =>\n{\n var renderer = new ChromePdfRenderer();\n\n var pdf = renderer.RenderHtmlAsPdf("<h1>The .NET Weekly</h1>");\n\n return Results.File(pdf.BinaryData, "application/pdf", "newsletter.pdf");\n});\nChoosing which PDF library you will use in .NET is an important consideration to make.\nAnd while pricing is a significant factor, the features you want to use will also dictate your choice.
\nQuestPDF is an excellent choice if you're looking for a (mostly) free option with rich features.\nThe library is constantly improved, and new features are being added.\nHowever, it doesn't support HTML-to-PDF conversion and modifying existing documents.
\nIronPDF is the library I've used most often on commercial projects.\nIt has fantastic features for working with PDF files, with many customization options.\nThe HTML-to-PDF conversion works like a charm.
\nThe hardest part is picking the right tool for the job.
\nSo I hope this is helpful.
\nSee you next week.
\nVertical Slice Architecture organizes a system around features instead of technical layers.\nAll the files for a single use case live in one folder.\nThis minimizes coupling between unrelated features and maximizes coupling inside a single feature.
\nLayered architectures are the foundation of many software systems.\nHowever, layered architectures organize the system around technical layers.\nAnd the cohesion between layers is low.
\nWhat if you wanted to organize the system around features instead?
\nMinimize coupling between unrelated features and maximize coupling in a single feature.
\nToday I want to talk about Vertical Slice Architecture, which does precisely that.
\nLayered architectures organize the software system into layers or tiers.\nEach of the layers is typically one project in your solution.\nSome of the popular implementations are N-tier architecture or Clean architecture.
\nLayered architectures focus on separating the concerns of the various components.\nThis makes it easier to understand and maintain the software system.\nAnd there are many benefits of structured software design,\nsuch as maintainability, flexibility, and loose coupling.
\n![\"Clean](\"https://milanjovanovic.tech/blogs/mnw_062/clean_architecture.png\")
\nHowever, layered architectures also impose constraints or rigid rules on your system.\nThe direction of dependencies between layers is pre-determined.
\nFor example, in Clean Architecture:
\nYou end up having high coupling inside a layer and low coupling between layers.\nThis doesn't mean layered architectures are bad.\nBut it does mean you will have many abstractions between individual layers.\nAnd more abstractions mean increased complexity because there are more components to maintain.
\nI first heard about Vertical Slice Architecture from Jimmy Bogard.\nHe's also the creator of some popular open-source libraries like MediatR and Automapper.
\nVertical Slice Architecture was born from the pain of working with layered architectures.\nThey force you to make changes in many different layers to implement a feature.
\nLet's imagine what adding a new feature looks like in a layered architecture:
\nThe cohesion is low because you are creating many files in different layers.
\nVertical slices take a different approach:
\n\n\nMinimize coupling between slices, and maximize coupling in a slice.
\n
Here's how you can visualize vertical slices:
\n![\"Vertical](\"https://milanjovanovic.tech/blogs/mnw_062/vertical_slice_architecture.png\")
\nAll the files for a single use case are grouped inside one folder.\nSo, the cohesion for a single use case is very high.\nThis simplifies the development experience.\nIt's easy to find all the relevant components for each feature since they are close together.
\nIf you're building an API, the system already breaks down into commands (POST/PUT/DELETE) and queries (GET).\nBy splitting the requests into commands and queries, you're getting the benefits of the CQRS pattern.
\nVertical slices narrowly focus on a single feature.\nThis allows you to treat each use case separately and tailor the implementation to the specific requirements.\nOne vertical slice can use EF Core to implement a GET request.\nAnother vertical slice can use Dapper with raw SQL queries.
\n![\"Four](\"https://milanjovanovic.tech/blogs/mnw_062/vertical_slices.png\")
\nAnother benefit of implementing vertical slices like this is:
\n\n\nNew features only add code, you're not changing shared code and worrying about side effects.
\n
However, vertical slices have their own set of challenges.\nBecause you are implementing much of the business logic inside a single use case, you need to be able to spot code smells.\nAs the use case grows, it can end up doing too much.\nYou will have to refactor the code by pushing logic to the domain.
\nLayered architectures, such as Clean architecture, organize the solution across layers.\nThis results in a folder structure grouped by technical concerns.
\nVertical slice architecture, on the other hand, organizes the code around features or use cases.
\nAn interesting approach to structuring APIs around features is using the REPR pattern.\nIt stands for Request-EndPoint-Response.\nThis aligns perfectly with the idea of vertical slices.\nYou can achieve this with the MediatR library, for example.
\nThe REPR pattern defines that web API endpoints should have three components:
\nHere's an example solution structure in .NET.\nYou'll notice the Features folder, which contains the vertical slices.\nEach vertical slice implements one API request (or use case).
🔗 RunTracker.API\n|__ 📁 Database\n|__ 📁 Entities\n |__ #️⃣ Activity.cs\n |__ #️⃣ Workout.cs\n |__ #️⃣ ...\n|__ 📁 Features\n |__ 📁 Activities\n |__ 📁 GetActivity\n |__ #️⃣ ActivityResponse.cs\n |__ #️⃣ GetActivityEndpoint.cs\n |__ #️⃣ GetActivityQuery.cs\n |__ #️⃣ GetActivityQueryHandler.cs\n |__ 📁 CreateActivity\n |__ #️⃣ CreateActivity.cs\n |__ #️⃣ CreateActivity.Command.cs\n |__ #️⃣ CreateActivity.Endpoint.cs\n |__ #️⃣ CreateActivity.Handler.cs\n |__ #️⃣ CreateActivity.Validator.cs\n |__ 📁 Workouts\n |__ 📁 ...\n|__ 📁 Middleware\n|__ 📄 appsettings.json\n|__ 📄 appsettings.Development.json\n|__ #️⃣ Program.cs\nA few more libraries for implementing the REPR pattern:
\n\nSome of you may not like the idea of grouping all the files related to a feature in a single folder.
\nHowever, there's a lot of value in grouping by features in general.\nYou don't have to implement vertical slices.\nBut you can apply this concept to your domain by grouping files around aggregates, for example.\nThis is the approach I show in Pragmatic Clean Architecture.
\nI made a video about Vertical Slice Architecture,\nshowing how to implement the concepts discussed in today's issue. Check it out here.
\nThanks for reading, and stay awesome!
\nThe Result pattern is a functional approach to error handling in .NET.\nInstead of throwing exceptions, a method returns a Result object that exposes IsSuccess, IsFailure, and an Error describing what went wrong.\nThe return type makes it explicit that the method can fail.
How should you handle errors in your code?
\nThis has been a topic of many discussions, and I want to share my opinion.
\nOne school of thought suggests using exceptions for flow control.\nThis is not a good approach because it makes the code harder to reason about.\nThe caller must know the implementation details and which exceptions to handle.
\nExceptions are for exceptional situations.
\nToday, I want to show you how to implement error handling using the Result pattern.
\nIt's a functional approach to error handling, making your code more expressive.
\nUsing exceptions for flow control is an approach to implement the fail-fast principle.
\nAs soon as you encounter an error in the code, you throw an exception —\neffectively terminating the method, and making the caller responsible for handling the exception.
\nThe problem is the caller must know which exceptions to handle.\nAnd this isn't obvious from the method signature alone.
\nAnother common use case is throwing exceptions for validation errors.
\nHere's an example in the FollowerService:
public sealed class FollowerService\n{\n private readonly IFollowerRepository _followerRepository;\n\n public FollowerService(IFollowerRepository followerRepository)\n {\n _followerRepository = followerRepository;\n }\n\n public async Task StartFollowingAsync(\n User user,\n User followed,\n DateTime createdOnUtc,\n CancellationToken cancellationToken = default)\n {\n if (user.Id == followed.Id)\n {\n throw new DomainException("Can't follow yourself");\n }\n\n if (!followed.HasPublicProfile)\n {\n throw new DomainException("Can't follow non-public profile");\n }\n\n if (await _followerRepository.IsAlreadyFollowingAsync(\n user.Id,\n followed.Id,\n cancellationToken))\n {\n throw new DomainException("Already following");\n }\n\n var follower = Follower.Create(user.Id, followed.Id, createdOnUtc);\n\n _followerRepository.Insert(follower);\n }\n}\nA rule of thumb I follow is to use exceptions for exceptional situations.\nSince you already expect potential errors, why not make it explicit?
\nYou can group all application errors into two groups:
\nExceptions are an excellent solution for the errors you don't know how to handle.\nAnd you should catch and handle them at the lowest level possible.
\nWhat about the errors you know how to handle?
\nYou can handle them in a functional way with the Result pattern.\nIt's explicit and clearly expresses the intent that the method can fail.\nThe drawback is the caller has to manually check if the operation failed.
\nThe first thing you will need is an Error class to represent application errors.
Code - unique name for the error in the applicationDescription - contains developer-friendly details about the errorpublic sealed record Error(string Code, string Description)\n{\n public static readonly Error None = new(string.Empty, string.Empty);\n}\nThen, you can implement the Result class using the Error to describe the failure.\nThis implementation is very bare-bones, and you could add many more features.\nIn most cases, you also need a generic Result<T> class, which will wrap a value inside.
Here's what the Result class looks like:
public class Result\n{\n private Result(bool isSuccess, Error error)\n {\n if (isSuccess && error != Error.None ||\n !isSuccess && error == Error.None)\n {\n throw new ArgumentException("Invalid error", nameof(error));\n }\n\n IsSuccess = isSuccess;\n Error = error;\n }\n\n public bool IsSuccess { get; }\n\n public bool IsFailure => !IsSuccess;\n\n public Error Error { get; }\n\n public static Result Success() => new(true, Error.None);\n\n public static Result Failure(Error error) => new(false, error);\n}\nThe only way to create a Result instance is by using static methods:
Success - creates a success resultFailure - creates a failure result with the specified ErrorIf you want to avoid building your own Result class, take a look at the FluentResults library.
Now that we have the Result class let's see how to apply it in practice.
Here's a refactored version of the FollowerService.\nNotice a few things:
Result return type is explicitAnother benefit of error handling using the Result pattern is that it's easier to test.
\npublic sealed class FollowerService\n{\n private readonly IFollowerRepository _followerRepository;\n\n public FollowerService(IFollowerRepository followerRepository)\n {\n _followerRepository = followerRepository;\n }\n\n public async Task<Result> StartFollowingAsync(\n User user,\n User followed,\n DateTime utcNow,\n CancellationToken cancellationToken = default)\n {\n if (user.Id == followed.Id)\n {\n return Result.Failure(FollowerErrors.SameUser);\n }\n\n if (!followed.HasPublicProfile)\n {\n return Result.Failure(FollowerErrors.NonPublicProfile);\n }\n\n if (await _followerRepository.IsAlreadyFollowingAsync(\n user.Id,\n followed.Id,\n cancellationToken))\n {\n return Result.Failure(FollowerErrors.AlreadyFollowing);\n }\n\n var follower = Follower.Create(user.Id, followed.Id, utcNow);\n\n _followerRepository.Insert(follower);\n\n return Result.Success();\n }\n}\nYou can use the Error class to document all possible errors in your application.
One approach is to create a static class called Errors.\nIt will have nested classes inside containing the specific errors.\nThe usage would look like Errors.Followers.NonPublicProfile.
However, the approach I like to use is to create a specific class containing the errors.
\nHere's the FollowerErrors class documenting the possible errors for the Follower entity:
public static class FollowerErrors\n{\n public static readonly Error SameUser = new Error(\n "Followers.SameUser", "Can't follow yourself");\n\n public static readonly Error NonPublicProfile = new Error(\n "Followers.NonPublicProfile", "Can't follow non-public profiles");\n\n public static readonly Error AlreadyFollowing = new Error(\n "Followers.AlreadyFollowing", "Already following");\n}\nInstead of static fields, you can also use static methods returning an error.\nYou would call this method with a concrete argument to get an Error instance.
public static class FollowerErrors\n{\n public static Error NotFound(Guid id) => new Error(\n "Followers.NotFound", $"The follower with Id '{id}' was not found");\n}\nThe Result object will eventually reach the Minimal API (or controller) endpoint in ASP.NET Core.\nMinimal APIs return an IResult response, and controllers return an IActionResult response.\nRegardless, you must convert the Result instance into a valid API response.
The straightforward approach is checking the Result state and returning an HTTP response.\nHere's an example where we check the Result.IsFailure flag:
app.MapPost(\n "users/{userId}/follow/{followedId}",\n (Guid userId, Guid followedId, FollowerService followerService) =>\n {\n var result = await followerService.StartFollowingAsync(\n userId,\n followedId,\n DateTime.UtcNow);\n\n if (result.IsFailure)\n {\n return Results.BadRequest(result.Error);\n }\n\n return Results.NoContent();\n });\nHowever, this is an excellent opportunity for a more functional approach.\nYou can implement the Match extension method to provide a callback for each Result state.\nThe Match method will execute the respective callback and return the result.
Here's the implementation of Match:
public static class ResultExtensions\n{\n public static T Match<T>(\n this Result result,\n Func<T> onSuccess,\n Func<Error, T> onFailure)\n {\n return result.IsSuccess ? onSuccess() : onFailure(result.Error);\n }\n}\nAnd this is how you would use the Match method in a Minimal API endpoint:
app.MapPost(\n "users/{userId}/follow/{followedId}",\n (Guid userId, Guid followedId, FollowerService followerService) =>\n {\n var result = await followerService.StartFollowingAsync(\n userId,\n followedId,\n DateTime.UtcNow);\n\n return result.Match(\n onSuccess: () => Results.NoContent(),\n onFailure: error => Results.BadRequest(error));\n });\nMuch more concise. Don't you think so?
\nIf you take one thing with you from this week's issue, it should be this: exceptions are for exceptional situations.\nMoreover, you should only use exceptions for errors you don't know how to handle.\nIn all other cases, expressing the error clearly with the Result pattern is more valuable.
\nUsing the Result class allows you to:
Additionally, you can document all application errors with the Error class.\nThis is helpful for developers to know which errors they need to handle.
You can even convert this to actual documentation.\nFor example, I wrote a simple program that scans the project for all Error fields.\nIt then converts this into a table format and uploads it to a Confluence page.
So I encourage you to try the Result pattern and see how it can improve your code.
\nSee you next week.
\nCommand Query Responsibility Segregation (CQRS) gives commands and queries their own models, so you can optimize writes and reads independently.\nThe separation can be logical inside one database or physical across two.\nWith MediatR you extend IRequest into custom ICommand and IQuery abstractions, and ISender routes each one to its handler.
Today I want to show you how to use the CQRS pattern to build fast and scalable applications.
\nThe CQRS pattern separates the writes and reads in the application.
\nThis separation can be logical or physical and has many benefits:
\nI'm also going to show you how to implement CQRS in your application using MediatR.
\nBut first, we have to understand what CQRS is.
\nCQRS stands for Command Query Responsibility Segregation.\nThe CQRS pattern uses separate models for reading and updating data.\nThe benefits of using CQRS are complexity management, improved performance, scalability, and security.
\nThe standard approach for working with a database is using the same model to query and update data.\nThis is simple and works great for most CRUD operations.\nHowever, in more complex applications, it becomes difficult to maintain.\nOn the write side, you could have complex business logic and validation in the model.\nOn the read side, you may need to perform many different queries.
\nAlso, consider how we create the data model.\nApplying SQL data modeling best practices will give you a normalized database.\nThis is generally fine, but it's optimized for writing.
\nHaving separate models for commands and queries allows you to scale them independently.\nThe separation could be logical while using the same database.\nYou could split the subsystems for commands and queries into separate services.\nAnd you can even have multiple databases optimized for writing or reading data.
\nCQS stands for Command Query Separation.\nIt's a term coined by Bertrand Meyer in his book Object-Oriented Software Construction.
\nThe basic premise of CQS is splitting an object's methods into Commands and Queries.
\nThis doesn't mean a command can never return a value.\nA typical example is popping a value from a stack.\nIt returns a value and changes the state of the system.\nBut the intent is what matters here.
\nCQS is a principle.\nYou can follow this principle if it makes sense, but be pragmatic.
\nCQRS is the evolution of CQS.\nCQRS works on the architectural level.\nAt the same time, CQS works on the method (or class) level.
\nHere's a high-level overview of a CQRS system using multiple databases.\nCommands update the write database.\nThen, you need to synchronize the updates with the read database.\nThis introduces eventual consistency to CQRS systems.
\nEventual consistency significantly increases the complexity of your application.\nYou must consider what happens if the synchronization process fails, and have a fault tolerance strategy.
\n![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_060/cqrs.png\")
\nThere are many flavors of this approach:
\nSeparating the models for updating and reading data allows you to choose the best database for your requirements.
\nHow do you apply the CQRS pattern to your system?\nI prefer using MediatR.
\nMediatR implements the mediator pattern to solve a simple problem - decoupling the in-process sending of messages from handling messages.
\nYou can extend MediatR's IRequest interface with a custom ICommand and IQuery abstraction.\nThis allows you to define commands and queries in your system explicitly.
On the write side, I typically use EF Core and a rich domain model to encapsulate business logic.\nThe command flow uses EF to load an entity into memory, execute the domain logic, and save the changes to the database.
\nOn the read side, I want as little indirection as possible.\nUsing Dapper with raw SQL queries is an excellent choice.\nYou can also create views in the database and query them.\nAlternatively, you could use EF Core to execute queries with projections.
\n![\"Diagram](\"https://milanjovanovic.tech/blogs/mnw_060/cqrs_application.png\")
\nImplementing CQRS with MediatR has two components:
\nI made an in-depth video explaining this process, and you can watch it here.
\nYou use the ISender interface to Send the command or query.\nMediatR takes care of routing the command or query to the respective handler.
The request will pass through the request pipeline.\nIt's a wrapper around each request, and you can use it to solve cross-cutting concerns with IPipelineBehavior.\nFor example, you can implement validation for commands with FluentValidation.
[ApiController]\n[Route("api/bookings")]\npublic class BookingsController : ControllerBase\n{\n private readonly ISender _sender;\n\n public BookingsController(ISender sender)\n {\n _sender = sender;\n }\n\n [HttpPut("{id}/confirm")]\n public async Task<IActionResult> ConfirmBooking(\n Guid id,\n CancellationToken cancellationToken)\n {\n var command = new ConfirmBookingCommand(id);\n\n var result = await _sender.Send(command, cancellationToken);\n\n if (result.IsFailure)\n {\n return BadRequest(result.Error);\n }\n\n return NoContent();\n }\n}\n\nHere's an example of a command handler with repositories and a rich domain model:
\ninternal sealed class ConfirmBookingCommandHandler\n : ICommandHandler<ConfirmBookingCommand>\n{\n private readonly IDateTimeProvider _dateTimeProvider;\n private readonly IBookingRepository _bookingRepository;\n private readonly IUnitOfWork _unitOfWork;\n\n public ConfirmBookingCommandHandler(\n IDateTimeProvider dateTimeProvider,\n IBookingRepository bookingRepository,\n IUnitOfWork unitOfWork)\n {\n _dateTimeProvider = dateTimeProvider;\n _bookingRepository = bookingRepository;\n _unitOfWork = unitOfWork;\n }\n\n public async Task<Result> Handle(\n ConfirmBookingCommand request,\n CancellationToken cancellationToken)\n {\n var booking = await _bookingRepository.GetByIdAsync(\n request.BookingId,\n cancellationToken);\n\n if (booking is null)\n {\n return Result.Failure(BookingErrors.NotFound);\n }\n\n var result = booking.Confirm(_dateTimeProvider.UtcNow);\n\n if (result.IsFailure)\n {\n return result;\n }\n\n await _unitOfWork.SaveChangesAsync(cancellationToken);\n\n return Result.Success();\n }\n}\nHere's an example of a query handler that uses Dapper and raw SQL:
\ninternal sealed class SearchApartmentsQueryHandler\n : IQueryHandler<SearchApartmentsQuery, IReadOnlyList<ApartmentResponse>>\n{\n private static readonly int[] ActiveBookingStatuses =\n {\n (int)BookingStatus.Reserved,\n (int)BookingStatus.Confirmed,\n (int)BookingStatus.Completed\n };\n\n private readonly ISqlConnectionFactory _sqlConnectionFactory;\n\n public SearchApartmentsQueryHandler(\n ISqlConnectionFactory sqlConnectionFactory)\n {\n _sqlConnectionFactory = sqlConnectionFactory;\n }\n\n public async Task<Result<IReadOnlyList<ApartmentResponse>>> Handle(\n SearchApartmentsQuery request,\n CancellationToken cancellationToken)\n {\n if (request.StartDate > request.EndDate)\n {\n return new List<ApartmentResponse>();\n }\n\n using var connection = _sqlConnectionFactory.CreateConnection();\n\n const string sql = """\n SELECT\n a.id AS Id,\n a.name AS Name,\n a.description AS Description,\n a.price_amount AS Price,\n a.price_currency AS Currency,\n a.address_country AS Country,\n a.address_state AS State,\n a.address_zip_code AS ZipCode,\n a.address_city AS City,\n a.address_street AS Street\n FROM apartments AS a\n WHERE NOT EXISTS\n (\n SELECT 1\n FROM bookings AS b\n WHERE\n b.apartment_id = a.id AND\n b.duration_start <= @EndDate AND\n b.duration_end >= @StartDate AND\n b.status = ANY(@ActiveBookingStatuses)\n )\n """;\n\n var apartments = await connection\n .QueryAsync<ApartmentResponse, AddressResponse, ApartmentResponse>(\n sql,\n (apartment, address) =>\n {\n apartment.Address = address;\n\n return apartment;\n },\n new\n {\n request.StartDate,\n request.EndDate,\n ActiveBookingStatuses\n },\n splitOn: "Country");\n\n return apartments.ToList();\n }\n}\nSeparating commands and queries can improve performance and scalability in the long run.\nYou can optimize commands and queries differently based on your requirements.
\nCommands encapsulate complex business logic and validation.\nUsing EF Core and a rich domain model is an excellent solution.
\nQueries are all about performance, so you want to use what's fastest.\nThis could be raw SQL queries with Dapper, EF Core projections, or Redis.
\nIf you want the system I use to build scalable applications with CQRS and MediatR, check out Pragmatic Clean Architecture.
\nStay awesome!
\nScrutor extends the built-in ASP.NET Core dependency injection container with two things the framework doesn't ship: assembly scanning and service decoration.\nAssembly scanning registers services by convention instead of one line per service.\nDecoration wraps an existing registration, which is how you add caching or permission checks without touching the original class.
\nDependency injection (DI) is one of the most exciting features of ASP.NET Core.\nIt helps us build more testable and maintainable applications.\nHowever, ASP.NET Core's built-in DI system sometimes needs a little help to achieve more advanced scenarios.
\nSo I want to introduce you to a powerful library for enhancing your ASP.NET Core DI - Scrutor.
\nIf you're an ASP.NET Core developer, you're already familiar with Dependency Injection.\nIt's a fundamental part of building modular and maintainable applications.
\nLet's explore how Scrutor can simplify and enhance your DI setup.
\nDependency Injection\nis a software design pattern used in ASP.NET Core to achieve the Inversion of Control (IOC)\nprinciple.\nThis promotes loose coupling and makes your code more testable, maintainable, and extensible.
\nDI allows you to inject dependencies into your classes rather than create them within the class.\nThe framework takes care of providing the required instances at runtime.\nIt also manages the disposal of these dependencies based on the service lifetime.
\nHere's an example of combining constructor and method injection in a controller:
\n[ApiController]\n[Route("api/activities")]\npublic class ActivitiesController : ControllerBase\n{\n private readonly ILogger<ActivitiesController> _logger;\n\n // Constructor injection\n public ActivitiesController(ILogger<ActivitiesController> logger)\n {\n _logger = logger;\n }\n\n [HttpGet]\n public async Task<IActionResult> Get(ISender sender) // Method injection\n {\n var activities = await sender.Send(new GetActivitiesQuery());\n\n return Ok(activities);\n }\n}\nBefore we dive into Scrutor, let's briefly discuss service lifetimes in ASP.NET Core.\nWhen you register a service in the DI container, you specify its lifetime.\nThe service lifetime defines how long the DI container should maintain the service.
\nASP.NET Core provides three main lifetimes:
\nUnderstanding service lifetimes is crucial when designing your application's architecture.
\nThe Scrutor library improves your dependency injection code by extending the existing features from Microsoft.Extensions.DependencyInjection.
These extensions add support for advanced assembly scanning and service decoration.
\nTo get started using Scrutor, you need to install the NuGet package:
\nInstall-Package Scrutor\nOne of the most powerful features of Scrutor is its ability to perform assembly scanning.\nRather than manually registering each service, Scrutor allows you to scan your assemblies for types that should be registered with the DI container.\nThis can significantly reduce the boilerplate code required for service registration, making your code cleaner and more maintainable.
\nThe entry point for assembly scanning is the Scan method, which accepts a delegate to define the DI setup.
Here's an example of scanning two assemblies and registering the classes inside as scoped services:
\nbuilder.Services.Scan(selector => selector\n .FromAssemblies(\n typeof(PersistenceAssembly).Assembly,\n typeof(InfrastructureAssembly).Assembly)\n .AddClasses(publicOnly: false)\n .UsingRegistrationStrategy(RegistrationStrategy.Skip)\n .AsMatchingInterface()\n .WithScopedLifetime());\nLet's unpack what's happening here:
\nFromAssemblies - allows you to specify which assemblies to scanAddClasses - adds the classes from the selected assembliesUsingRegistrationStrategy - defines which RegistrationStrategy to useAsMatchingInterface - registers the types as matching interfaces (ClassName → IClassName)WithScopedLifetime - registers the types with a scoped service lifetimeThere are three values for RegistrationStrategy you can use:
RegistrationStrategy.Skip - skips registrations if service already existsRegistrationStrategy.Append- appends a new registration for existing servicesRegistrationStrategy.Throw- throws when trying to register an existing serviceYou can also specify a filter to AddClasses to select specific types you want to configure.\nHere's an example of registering repository implementations:
services.Scan(scan => scan\n .FromAssemblies(typeof(PersistenceAssembly).Assembly)\n .AddClasses(\n filter => filter.Where(x => x.Name.EndsWith("Repository")),\n publicOnly: false)\n .UsingRegistrationStrategy(RegistrationStrategy.Throw)\n .AsMatchingInterface()\n .WithScopedLifetime());\nService decoration is another valuable feature offered by Scrutor.\nIt enables you to modify or extend services during registration without changing the original implementation.
\nThis is incredibly useful when adding cross-cutting concerns or other modifications to services without altering their core functionality.\nFor example, you can implement a caching decorator for repositories.
\nHere's how you can configure a decorator with Scrutor's Decorate method:
services.AddScoped<IActivitiesRepository, ActivitiesRepository>();\n\nservices.Decorate<IActivitiesRepository, PermissionActivitiesRepository>();\nIt will decorate the ActivitiesRepository service using the PermissionActivitiesRepository.\nThis also means that PermissionActivitiesRepository can inject an IActivitiesRepository instance, and at runtime, this is resolved as ActivitiesRepository.
Here's how you can implement the PermissionActivitiesRepository:
public class PermissionActivitiesRepository : IActivitiesRepository\n{\n private readonly IActivitiesRepository _decorated;\n private readonly IPermissionChecker _permissionChecker;\n\n public PermissionActivitiesRepository(\n IActivitiesRepository decorated,\n IPermissionChecker permissionChecker)\n {\n _decorated = decorated;\n _permissionChecker = permissionChecker;\n }\n\n public List<Activity> Get()\n {\n if (!_permissionChecker.HasPermission(Permissions.FetchActivities))\n {\n return new();\n }\n\n return _decorated.Get();\n }\n}\nScrutor can improve your ASP.NET Core DI by simplifying service registration through assembly scanning and enabling service decoration.\nYou can use Scrutor's capabilities to write cleaner, more maintainable, and flexible DI code while reducing the complexity of your startup configuration.
\nAssembly scanning can reduce the boilerplate code required for service registration.\nIt also allows you to create custom conventions for registering services.
\nService decoration has been a real game-changer for me.\nIt's the simplest way to introduce cross-cutting concerns in your application.\nFor example, I used to add an idempotency check before handling events.
\nHope this was valuable.
\nStay awesome!
\nTo get started with NServiceBus, install the NServiceBus.Extensions.Hosting package, call UseNServiceBus on the host, and configure a transport such as Azure Service Bus.\nThen define messages as ICommand, IEvent, or IMessage classes, publish them through IMessageSession, and handle them by implementing IHandleMessages<T>.
NServiceBus is a feature-rich messaging framework supporting many different message transports.\nIt's developed and maintained by Particular Software.\nAnd it simplifies the process of building complex distributed systems across various cloud-based queueing technologies.
\nThe basic building blocks of NServiceBus are messages and endpoints.\nA message contains the required information to execute a business operation.\nEndpoints are logical entities that send and receive messages.
\nAnd now let's see how to get started with NServiceBus, from installation and setup to building your first NServiceBus endpoint.
\nIn this week's newsletter, you will learn how to:
\nIMessageSessionLet's dive in!
\nNServiceBus is a messaging framework and platform that simplifies building reliable, scalable, and maintainable distributed systems.\nIt's designed to address the challenges that arise when building applications that are distributed across multiple servers.
\nOne of NServiceBus's foundational principles is its embrace of a message-driven architecture.\nIn this model, components communicate by sending and receiving messages.\nMessages are the fundamental units of communication, representing commands, events, or data that services exchange.
\nWhy is this significant?
\nMessage-driven architectures offer several advantages:
\nNServiceBus supports the powerful publish/subscribe (pub/sub) messaging pattern.\nThis pattern allows services to publish events and subscribe to events of interest.\nWhen a service publishes an event, all interested subscribers receive a copy of the event.\nThis is a key feature for building event-driven architectures, where services react to and process events in response to various actions or changes in the system.
\nNServiceBus uses the concept of an endpoint to send and receive messages.\nIt's a logical component that communicates with other components.\nYou define your message handlers and sagas inside of an endpoint.
\nLet's start by installing the NServiceBus NuGet package:
Install-Package NServiceBus.Extensions.Hosting\nNow you can configure an endpoint to use Azure Service Bus\nto send messages:
\nvar builder = WebApplication.CreateBuilder();\n\nbuilder.Host.UseNServiceBus(context =>\n{\n var endpointConfiguration = new EndpointConfiguration("Training");\n\n var transport = endpointConfiguration\n .UseTransport<AzureServiceBusTransport>();\n\n var connectionString = builder.Configuration\n .GetConnectionString("AzureServiceBusConnectionString");\n transport.ConnectionString(connectionString);\n\n endpointConfiguration.EnableInstallers();\n\n return endpointConfiguration;\n});\n\nvar app = builder.Build();\n\napp.Run();\nThe call to UseNServiceBus tells the host to use NServiceBus.\nInside the callback, you can configure the endpoint that will start when the host runs.
One more important aspect is calling EnableInstallers to set up the Azure Service Bus topology.\nThis will tell NServiceBus to create the required queues, so you don't have to do it manually.
The next building block you need in any messaging system is the messages.\nMessages are C# classes or interfaces that contain meaningful data for the business process.
\nNServiceBus supports three types of messages:
\nICommand - sends a request to perform an actionIEvent - communicates that something significant occurredIMessage - for messages that aren't commands or events (typically for replies in request-response)Events can have more than one handler, while a command should have only one handler.
\nLet's create our first message contract:
\nusing NServiceBus;\n\npublic class WorkoutCreated : IEvent\n{\n public Guid Id [ get; set; ]\n}\nThe WorkoutCreated message is an event that we will publish after creating a new Workout.
You can use the IMessageSession service to send messages from your controllers or Minimal API endpoints.
app.MapPost("api/workouts", async (\n Workout workout,\n AppDbContext context,\n IMessageSession messageSession) =>\n{\n context.Add(workout);\n\n await context.SaveChangesAsync();\n\n await messageSession.Publish(new WorkoutCreated { Id = workout.Id });\n\n return Results.Ok(workout);\n});\nNServiceBus has some built-in validation when sending messages.\nYou have to specify an ICommand when calling the Send method, or you will get an exception.\nSimilarly, you have to specify an IEvent when calling the Publish method.
Once you send a message, you need a way to handle it and run some business logic.\nTo handle a message, you need to implement the IHandleMessages interface and specify which message you are handling.
Here's an implementation of the WorkoutCreatedHandler:
public class WorkoutCreatedHandler : IHandleMessages<WorkoutCreated>\n{\n private readonly ILogger<WorkoutCreated> _logger;\n\n public WorkoutCreatedHandler(ILogger<WorkoutCreated> logger)\n {\n _logger = logger;\n }\n\n public async Task Handle(\n WorkoutCreated message,\n IMessageHandlerContext context)\n {\n logger.LogInformation("Processing workout - {Id}", message.Id);\n\n // Continue to process the message.\n }\n}\nImplementing IHandleMessages<WorkoutCreated> tells NServiceBus how to process the WorkoutCreated message when an endpoint receives it.\nThis interface defines only one method: Handle.
The Handle method has an IMessageHandlerContext parameter, which allows you to send more messages.\nThis can be helpful when implementing a choreographed saga.\nProcessing one message triggers the next step in the chain until the entire process is completed.
In this week's issue, we discussed NServiceBus, a robust messaging framework for building distributed systems in .NET.\nYou learned how to configure NServiceBus with the Azure Service Bus transport.\nWe discussed the different message types in NServiceBus and how to publish and handle a message.
\nBuilding distributed systems is a complex endeavor, but NServiceBus simplifies many challenges.\nBy embracing a message-driven architecture and leveraging NServiceBus's features,\nyou'll be well-equipped to create resilient, scalable, and maintainable applications in the .NET ecosystem.
\nFurther reading:
\nHope this was helpful.
\nI'll see you next week!
\nYou validate CQRS commands with a MediatR IPipelineBehavior that runs FluentValidation validators before the handler executes.\nInput validation only checks that the command is processable, while business validation reads the system state to check business rules.\nA middleware turns the resulting ValidationException into a ProblemDetails response with status 400.
Validation is an essential cross-cutting concern that you need to solve in your application.\nYou want to ensure the request is valid before you consider processing it.
\nAnother important question you need to answer is how you approach different types of validation.\nFor example, I consider input and business validation differently, and each deserves a specific solution.
\nI want to show you an elegant solution for validation using MediatR\nand FluentValidation.
\nIf you aren't using CQRS with MediatR, don't worry.\nEverything I explain about validation can easily be adapted to other paradigms.
\nHere's what I'm going to talk about in this week's newsletter:
\nValidationBehaviorLet's dive in.
\nThe standard way of implementing validation is right before processing the command.\nThe validation is tightly coupled to the command handler, which could be problematic.
\nI find this approach difficult to maintain as the complexity of the validation increases.\nEach change to the validation logic also touches the handler, and the handler itself can grow out of control.
\nIt also makes it harder to differentiate between input and business validation.
\nHere's an example ShipOrderCommandHandler that checks if the ShippingAddress.Country is one of the supported countries:
internal sealed class ShipOrderCommandHandler\n : IRequestHandler<ShipOrderCommand>\n{\n private readonly IOrderRepository _orderRepository;\n private readonly IShippingService _shippingService;\n private readonly ShipmentSettings _shipmentSettings;\n\n public async Task Handle(\n ShipOrderCommand command,\n CancellationToken cancellationToken)\n {\n if (!_shipmentSettings\n .SupportedCountries\n .Contains(command.ShippingAddress.Country))\n {\n throw new ArgumentException(nameof(ShipOrderCommand.Address));\n }\n\n var order = _orderRepository.Get(command.OrderId);\n\n _shippingService.ShipTo(\n command.ShippingAddress,\n command.ShippingMethod);\n }\n}\nWhat if we can separate command validation and command handling?
\nI mentioned input and business validation in the previous section.
\nHere's how I consider them to be different:
\nnull values, empty strings, etc.Another way to compare them is cheap vs. expensive.\nInput validation is usually cheap to execute and can be done in memory.\nWhile business validation involves reading state and is slower.
\nSo, input validation sits at the entry point of the use case before handling the request.\nAfter it completes, we have a valid command.\nAnd this is a rule I always follow - an invalid command should never reach the handler.
\nFluentValidation is an excellent validation library for .NET,\nwhich uses a fluent interface and lambda expressions for building strongly typed validation rules.
\nHere's the ShipOrderCommand that we want to validate:
public sealed record ShipOrderCommand : IRequest\n{\n public Guid OrderId { get; set; }\n\n public string ShippingMethod { get; set; }\n\n public Address ShippingAddress { get; set; }\n}\nTo implement a validator with FluentValidation,\nyou create a class that inherits from the AbstractValidator<T> base class.\nThen, you can add the validation rules from the constructor using RuleFor:
public sealed class ShipOrderCommandValidator\n : AbstractValidator<ShipOrderCommand>\n{\n public ShipOrderCommandValidator(ShipmentSettings settings)\n {\n RuleFor(command => command.OrderId)\n .NotEmpty()\n .WithMessage("The order identifier can't be empty.");\n\n RuleFor(command => command.ShippingMethod)\n .NotEmpty()\n .WithMessage("The shipping method can't be empty.");\n\n RuleFor(command => command.ShippingAddress)\n .NotNull()\n .WithMessage("The shipping address can't be empty.");\n\n RuleFor(command => command.ShippingAddress.Country)\n .Must(country => settings.SupportedCountries.Contains(country))\n .WithMessage("The shipping country isn't supported.");\n }\n}\nThe naming convention I like to use is the name of the command and append Validator.\nYou can also enforce this by writing architecture tests.
\nTo automatically register all validators from an assembly, you need to call the AddValidatorsFromAssembly method:
services.AddValidatorsFromAssembly(ApplicationAssembly.Assembly);\nTo run the ShipOrderCommandValidator, you can use the IValidator<T> service and inject it from the constructor.
The validator exposes a few methods you can call, like Validate, ValidateAsync, or ValidateAndThrow.
The Validate method returns a ValidationResult object which contains two properties:
IsValid - a boolean flag saying whether the validation succeededErrors - a collection of ValidationFailure objects containing any validation failuresAlternatively, calling the ValidateAndThrow method throws a ValidationException if validation fails.
internal sealed class ShipOrderCommandHandler\n : IRequestHandler<ShipOrderCommand>\n{\n private readonly IOrderRepository _orderRepository;\n private readonly IShippingService _shippingService;\n private readonly IValidator<ShipOrderCommand> _validator;\n\n public async Task Handle(\n ShipOrderCommand command,\n CancellationToken cancellationToken)\n {\n _validator.ValidateAndThrow(command);\n\n var order = _orderRepository.Get(command.OrderId);\n\n _shippingService.ShipTo(\n command.ShippingAddress,\n command.ShippingMethod);\n }\n}\nThis approach forces you to define an explicit dependency on IValidator in every command handler.
What if we can implement this cross-cutting concern in a more generic way?
\nHere's a complete implementation of a ValidationBehavior using FluentValidation and MediatR's IPipelineBehavior.
The ValidationBehavior acts as a middleware for the request pipeline and performs validation.\nIf the validation fails, it will throw a custom ValidationException with a collection of ValidationError objects.
I also want to highlight the use of ValidateAsync, which allows you to define asynchronous validation rules.\nYou must call the ValidateAsync method if you have asynchronous rules.\nOtherwise, the validator will throw an exception.
public sealed class ValidationBehavior<TRequest, TResponse>\n : IPipelineBehavior<TRequest, TResponse>\n where TRequest : ICommandBase\n{\n private readonly IEnumerable<IValidator<TRequest>> _validators;\n\n public ValidationBehavior(IEnumerable<IValidator<TRequest>> validators)\n {\n _validators = validators;\n }\n\n public async Task<TResponse> Handle(\n TRequest request,\n RequestHandlerDelegate<TResponse> next,\n CancellationToken cancellationToken)\n {\n var context = new ValidationContext<TRequest>(request);\n\n var validationFailures = await Task.WhenAll(\n _validators.Select(validator => validator.ValidateAsync(context)));\n\n var errors = validationFailures\n .Where(validationResult => !validationResult.IsValid)\n .SelectMany(validationResult => validationResult.Errors)\n .Select(validationFailure => new ValidationError(\n validationFailure.PropertyName,\n validationFailure.ErrorMessage))\n .ToList();\n\n if (errors.Any())\n {\n throw new Exceptions.ValidationException(errors);\n }\n\n var response = await next();\n\n return response;\n }\n}\nDon't forget to register the ValidationBehavior with MediatR by calling AddOpenBehavior:
services.AddMediatR(config =>\n{\n config.RegisterServicesFromAssemblyContaining<ApplicationAssembly>();\n\n config.AddOpenBehavior(typeof(ValidationBehavior<,>));\n});\nHere's a custom ValidationExceptionHandlingMiddleware middleware that only handles the custom ValidationException.\nIt converts the exception to a ProblemDetails response and includes any validation errors.
You can easily expand this to be a generic global exception handler.
\npublic sealed class ValidationExceptionHandlingMiddleware\n{\n private readonly RequestDelegate _next;\n\n public ValidationExceptionHandlingMiddleware(RequestDelegate next)\n {\n _next = next;\n }\n\n public async Task InvokeAsync(HttpContext context)\n {\n try\n {\n await _next(context);\n }\n catch (Exceptions.ValidationException exception)\n {\n var problemDetails = new ProblemDetails\n {\n Status = StatusCodes.Status400BadRequest,\n Type = "ValidationFailure",\n Title = "Validation error",\n Detail = "One or more validation errors has occurred"\n };\n\n if (exception.Errors is not null)\n {\n problemDetails.Extensions["errors"] = exception.Errors;\n }\n\n context.Response.StatusCode = StatusCodes.Status400BadRequest;\n\n await context.Response.WriteAsJsonAsync(problemDetails);\n }\n }\n}\nYou also need to include the middleware in the request pipeline by calling UseMiddleware:
app.UseMiddleware<ExceptionHandlingMiddleware>();\nThis implementation of ValidationBehavior is something I use in real projects, and it works incredibly well.\nIf I don't want to throw an exception, I can update the ValidationBehavior to return a result object instead.
How do you apply this if you're not using MediatR?
\nI'm using an IPipelineBehavior, which allows me to implement a middleware wrapping each request.
So, all you need is a way to implement middleware and place your validation inside.\nAnd I like having options, so here are three ways to create middleware in ASP.NET Core.
\nHope this was valuable.
\nStay awesome!
\nA modular monolith makes the move to microservices easier because it forces you to solve coupling first.\nYou identify bounded contexts, keep each module's tables private, and have modules communicate through a public API or messaging.\nExtracting a module then means moving it into its own process behind a reverse proxy.
\nYou start building a beautiful monolith system.\nMaybe a modular monolith.
\nThe system grows over time, and requirements are ever-changing. Slowly, cracks begin to appear in the system.
\nThis could be for organizational reasons and distributing the work across a team.\nOr it could be because of scaling issues and performance bottlenecks.
\nYou begin evaluating the possible solutions, and the benefits and tradeoffs of each one.\nAt last, you come to a decision.
\nIt's time to migrate parts of the system to individual (micro)services.
\nSo, how do we approach this migration from monolith to microservices?
\nThat is the topic of this week's newsletter.
\nLet's dive in!
\nThe first step in moving from a monolith to microservices is identifying the bounded contexts.\nBecause they represent cohesive parts of the domain that are candidates for extraction.
\nOne solution is to identify bounded contexts\nusing the domain-driven design strategic modeling.
\nBounded contexts define the explicit boundaries between modules and separate the responsibilities.\nThis is one of the biggest challenges when migrating to microservices.\nIdentifying good boundaries\nbetween modules ensures microservices are narrowly focused on one problem domain.
\nDefining boundaries is also easier in a monolith because you aren't working with a distributed system.\nRefactoring bad boundaries\nis less risky, and you have more freedom to "get it right".
\n![\"Bounded](\"https://milanjovanovic.tech/blogs/mnw_056/bounded_contexts.png\")
\nAnd the size of the bounded context shouldn't worry you.\nInstead, focus on service boundaries.
\nThe next problem you need to solve is coupling.\nCoupling is manifested in two ways:
\nYou can solve these problems from the start by building a modular monolith.\nBut I'll also explain the guiding principles you can use to solve coupling.
\nA modular monolith is a catchy name for a monolith system built from a few\nbounded contexts (modules) and following a set of principles to control coupling.\nEach module contains a cohesive set of functionalities and is isolated from other modules in the system.\nThe isolation refers to database dependencies and inter-module communication.
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_056/modular_monolith.png\")
\nYou can think of a module as a distinct application within the system.\nA module has its own domain, entities, use cases, database tables.\nThe modules are deployed together as a single executable application.\nBut they are otherwise independent.
\nYou can apply different architectural approaches to each module, like Clean Architecture.
\nSo I mentioned that you need to reduce the coupling between modules.
\nHere are two principles to solve database coupling:
\nSharing database tables leads to a high degree of coupling, and this is exactly what you are trying to avoid.\nYou can isolate the data for each module on a logical level using schemas or physically with different databases.
\nA module should expose a public API that other modules can call.\nThis public API is the entry point into the module.\nAnd this is the only way for modules to communicate.
\nCommunication between modules can be synchronous\nusing method calls, or asynchronous\nusing a message bus.
\nMy preferred approach is asynchronous communication using messaging.\nIt's loosely coupled and makes the transition to microservices easier.
\nTo implement asynchronous communication between modules, you can introduce a message broker.\nBut you don't need to introduce a full-blown message broker from the start.
\nYou can implement messaging between modules using an abstraction like MassTransit while abstracting away the transport mechanism.
\nMassTransit has an in-memory transport that works well inside a single process.\nIt's very fast.\nBut it isn't durable, and you can lose messages if the bus is stopped.
\nYou only need to configure a different transport mechanism when introducing a real message broker.\nBut you don't need to change your messaging code.
\n![\"Modular](\"https://milanjovanovic.tech/blogs/mnw_056/modular_monolith_queue.png\")
\nWhat is the purpose of messaging inside a modular monolith?
\nDesigning your system like this makes the modules loosely coupled and independent.\nThe price you pay in increased complexity at the start is justified as the project matures.
\nWe decided to move from a monolith system to microservices.\nSince we built our system in a modular way, the migration comes down to extracting a module into a new process.
\nYou should introduce a reverse proxy in front of your services to route incoming traffic.\nThis will hide the implementation details of the microservices system from client applications.
\nThe new microservice needs to connect to the message bus, but we don't need to change anything in our code.\nUsing messaging for communication between modules simplifies the migration process.\nThis might remind you of event-driven architecture.
\nIf you implement inter-module communication using method calls, you must replace that implementation with HTTP calls over the network.\nBecause you're now building a distributed system, and the previous implementation using method calls will not work.\nYou also need to consider authentication, fault tolerance...
\n![\"Microservices](\"https://milanjovanovic.tech/blogs/mnw_056/extracting_modules.png\")
\nExtracting modules from the monolith system leads to replacing all the functionalities of the old system with new microservices.\nThis process of migrating to microservices follows the strangler fig pattern.
\nThe biggest blocker for moving from a monolith to microservices is coupling.\nCoupling is a change preventer.\nSo, this is the first thing you need to tackle.
\nYou need to solve coupling at the database level and between components in the code.\nBuilding the system in a modular way can prevent these problems from the start.
\nWhich is why a Modular monolith is an excellent approach.
\nYou can identify bounded contexts in the system and use them as the boundaries in the monolith.\nAnd getting the boundaries right is easier in a monolith.
\nMigrating to microservices comes down to extracting the modules into individual services.
\nOf course, you still need to think about security and fault tolerance because you now have a distributed system.
\nTalking about architecture in abstract terms can be difficult to grasp, but it's important when discussing conceptual solutions.
\nI'll show you a practical Modular monolith implementation soon to complete the circle.
\nUntil then, I hope this was valuable.
\nSee you next week!
\nFeature flags let you turn application features on or off at runtime without redeploying the code.\nIn .NET you get them from the Microsoft.FeatureManagement library, which builds on the configuration system and exposes flag state through IFeatureManager.\nPercentage and targeting filters turn that switch into phased rollouts and A/B tests.
The ability to conditionally turn features on or off in your application without redeploying the code is a powerful tool.
\nIt lets you quickly iterate on new features and frequently integrate your changes with the main branch.
\nYou can use feature flags to achieve this.
\nFeature flags are a software development technique that allows you to wrap application features in a conditional statement.\nYou can then toggle the feature on or off in runtime to control which features are enabled.
\nWe have a lot to cover in this week's newsletter:
\nLet's dive in!
\nFeature flags provide a way for .NET and ASP.NET Core applications to turn features on or off dynamically.
\nTo get started, you need to install the Microsoft.FeatureManagement library in your project:
Install-Package Microsoft.FeatureManagement\nThis library will allow you to develop and expose application functionality based on features.\nIt's useful when you have special requirements when a new feature should be enabled and under what conditions.
\nThe next step is to register the required services with dependency injection by calling AddFeatureManagement:
builder.Services.AddFeatureManagement();\nAnd you are ready to create your first feature flag.\nFeature flags are built on top of the .NET configuration system.\nAny .NET configuration provider can act as the backbone for exposing feature flags.
\nLet's create a feature flag called ClipArticleContent in our appsettings.json file:
"FeatureManagement": {\n "ClipArticleContent": false\n}\nBy convention, feature flags have to be defined in the FeatureManagement configuration section.\nBut you can change this by providing a different configuration section when calling AddFeatureManagement.
Microsoft recommends exposing feature flags using enums and then consuming them with the nameof operator.\nFor example, you would write nameof(FeatureFlags.ClipArticleContent).
However, I prefer defining feature flags as constants in a static class because it simplifies the usage.
\n// Using enums\npublic enum FeatureFlags\n{\n ClipArticleContent = 1\n}\n\n// Using constants\npublic static class FeatureFlags\n{\n public const string ClipArticleContent = "ClipArticleContent";\n}\nTo check the feature flag state, you can use the IFeatureManager service.\nIn this example, if the ClipArticleContent feature flag is turned on, we will return only the first thirty characters of the article's content.
app.MapGet("articles/{id}", async (\n Guid id,\n IGetArticle query,\n IFeatureManager featureManager) =>\n{\n var article = query.Execute(id);\n\n if (await featureManager.IsEnabledAsync(FeatureFlags.ClipArticleContent))\n {\n article.Content = article.Content.Substring(0, 50);\n }\n\n return Results.Ok(article);\n});\nYou can also apply feature flags on a controller or endpoint level using the FeatureGate attribute:
[FeatureGate(FeatureFlags.EnableArticlesApi)]\npublic class ArticlesController : Controller\n{\n // ...\n}\nThis covers the fundamentals of using feature flags, and now, let's tackle more advanced topics.
\nThe feature flags I showed you in the previous section were like a simple on-off switch.\nAlthough practical, you might want more flexibility from your feature flags.
\nThe Microsoft.FeatureManagement package comes with a few built-in feature filters that allow you to create dynamic rules for enabling feature flags.
The available feature filters are\nMicrosoft.Percentage,\nMicrosoft.TimeWindow\nand Microsoft.Targeting.
Here's an example of defining a ShowArticlePreview feature flag that uses a percentage filter:
"FeatureFlags": {\n "ClipArticleContent": false,\n "ShowArticlePreview": {\n "EnabledFor": [\n {\n "Name": "Percentage",\n "Parameters": {\n "Value": 50\n }\n }\n ]\n }\n}\nThis means the feature flag will be randomly turned on 50% of the time.\nThe downside is the same user might see different behavior on subsequent requests.\nA more realistic scenario is to have the feature flag state be cached for the duration of the user's session.
\nTo use the PercentageFilter, you need to enable it by calling AddFeatureFilter:
builder.Services.AddFeatureManagement().AddFeatureFilter<PercentageFilter>();\nAnother interesting feature filter is the TargetingFilter, which allows you to target specific users.\nTargeting is used in phased rollouts, where you want to introduce a new feature to your users gradually.\nYou start by enabling the feature for a small percentage of users and slowly increase the rollout percentage while monitoring how the system responds.
Trunk-based development is a Git branching strategy where all developers work in short-lived branches or directly in the trunk, the main codebase.\nThe "trunk" is the main branch of your repository.\nIf you're using Git, it will be either the main or master branch.\nTrunk-based development avoids the "merge hell" problem caused by long-lived branches.
So, how do feature flags fit into trunk-based development?
\nThe only way to ensure the trunk is always releasable is to hide incomplete features behind feature flags.\nYou continue pushing changes to the trunk as you work on the feature while the feature flag remains turned off on the main branch.\nWhen the feature is complete, you turn on the feature flag and release it to production.
\n![\"Trunk](\"https://milanjovanovic.tech/blogs/mnw_055/trunk_based_development.png\")
\nA/B testing (split testing) is an experiment where two or more variants of a page (or feature) are shown randomly to users.\nStatistical analysis is performed in the background to determine which variation performs better for a given conversion goal.
\nHere's an example A/B test I performed on my website:
\n![\"Split](\"https://milanjovanovic.tech/blogs/mnw_055/split_test.png\")
\nThe hypothesis was that removing the image and focusing on the benefits would make more people want to subscribe.\nI measure this using the conversion rate, which is the number of people visiting the page divided by the number of people subscribing.
\nI'm using a platform called Posthog to run experiments, which automatically calculates the results.
\nYou can see that the test variant has a significantly higher conversion rate, so it becomes the winner of the A/B test.
\n![\"Split](\"https://milanjovanovic.tech/blogs/mnw_055/experiment_results.png\")
\nThe ability to dynamically turn features on or off without deploying the code is like a superpower.\nFeature flags give you this ability with very little work.
\nYou can work with feature flags in .NET by installing the Microsoft.FeatureManagement library.\nFeature flags build on top of the .NET configuration system, and you can check the feature flag state using the IFeatureManager service.
Another use case for feature flags is A/B testing.\nI run weekly experiments on my website, testing changes that will improve my conversion rate.\nFeature flags help me decide which version of the website to show to the user.\nAnd then, I can measure results based on the user's actions.
\nI also made a video about feature flagging in .NET, and you can watch it here if you want to learn more.
\nHope this was valuable.
\nStay awesome!
\nEF Core solves race conditions with optimistic concurrency, which takes no locks on the data.\nYou configure a property as a concurrency token, usually a SQL Server rowversion column, and EF Core adds it to the WHERE clause of the UPDATE.\nIf the value changed since you queried it, the save throws a DbUpdateConcurrencyException.
How often do you think about concurrency conflicts when writing code?
\nYou write the code for a new feature, confirm that it works, and call it a day.
\nBut one week later, you find out you introduced a nasty bug because you didn't think about concurrency.
\nThe most common issue is race conditions with two competing threads executing the same function.\nIf you don't consider this during development, you introduce the risk of leaving the system in a corrupted state.
\nIn this week's newsletter, I'll challenge you to spot the race condition in a method for reserving a booking.\nThe business requirement is you can't have two overlapping reservations for the same dates.
\nAnd then, I'll show you how to solve this race condition using EF Core optimistic concurrency.
\nLet's dive in!
\nThere's a race condition hiding somewhere in this code snippet.
\nCan you see it?
\npublic Result<Guid> Handle(\n ReserveBooking command,\n AppDbContext dbContext)\n{\n var user = dbContext.Users.GetById(command.UserId);\n var apartment = dbContext.Apartments.GetById(command.ApartmentId);\n var (startDate, endDate) = command;\n\n if (dbContext.Bookings.IsOverlapping(apartment, startDate, endDate))\n {\n return Result.Failure<Guid>(BookingErrors.Overlap);\n }\n\n var booking = Booking.Reserve(apartment, user, startDate, endDate);\n\n dbContext.Add(booking);\n\n dbContext.SaveChanges();\n\n return booking.Id;\n}\nThe call to IsOverlapping is an optimistic check to see if there's an existing booking for the specified dates.
if (dbContext.Bookings.IsOverlapping(apartment, startDate, endDate)) { }\nIf it returns true, we're trying to double-book the apartment.\nSo we return a failure, and the method completes.
But if it returns false, we reserve a booking and call SaveChanges to persist the changes in the database.
And there lies the problem.
\nThere's a chance for a concurrent request to pass the IsOverlapping check and attempt to reserve the booking.\nWithout any concurrency control, both requests will succeed, and we will end up with an inconsistent state in the database.
So how can we solve this?
\nThe pessimistic concurrency approach acquires a lock for the data before modifying it.\nIt's slower and causes competing transactions to be blocked until the lock is released.\nEF Core doesn't support this approach out of the box.
\nYou can also solve this problem using optimistic concurrency with EF Core.\nIt doesn't take any locks, but any data modifications will fail to save if the data has changed since it was queried.
\nTo implement optimistic concurrency in EF Core, you need to configure a property as a concurrency token.\nIt's loaded and tracked with the entity.\nWhen you call SaveChanges, EF Core will compare the value of the concurrency token to the value in the database.
Let's assume we're using SQL Server, which has a native rowversion column.\nThe rowversion automatically changes when the row is updated, so it's a great option for a concurrency token.
To configure a byte[] property as a concurrency token you can decorate it with the Timestamp attribute.\nIt will be mapped to a rowversion column in SQL Server.
public class Apartment\n{\n public Guid Id { get; set; }\n\n [Timestamp]\n public byte[] Version { get; set; }\n}\nI prefer a different approach because attributes pollute the entity.
\nYou can do the same with the Fluent API.\nI will even use a shadow property to hide the concurrency token from the entity class.
\nprotected override void OnModelCreating(ModelBuilder modelBuilder)\n{\n modelBuilder.Entity<Apartment>()\n .Property<byte[]>("Version")\n .IsRowVersion();\n}\nThe exact configuration will differ based on the database you are using, so check the documentation.
\nSo here's what changes when we configure the concurrency token.
\nWhen loading the Apartment entity, EF will also load the concurrency token.
SELECT a.Id, a.Version\nFROM Apartments a\nWHERE a.Id = @p0\nAnd when we call SaveChanges, the update statement will compare the concurrency token value with the one in the database:
UPDATE Apartments a\nSET a.LastBookedOnUtc = @p0\nWHERE a.Id = @p1 AND a.Version = @p2;\nIf the rowversion in the database changes, the number of updated rows will be 0.
EF Core expects to update 1 row, so it will throw a DbUpdateConcurrencyException, which you need to handle.
Now that you know how to use optimistic concurrency with EF Core, you can fix the previous code snippet.
\nIf two concurrent requests pass the IsOverlapping check, only one can complete the SaveChanges call.\nThe other concurrent request will run into a Version mismatch in the database and throw a DbUpdateConcurrencyException.
In case of a concurrency conflict, we need to add a try-catch statement to catch the DbUpdateConcurrencyException.\nHow you handle the actual exception depends on your business requirements.\nAnd sometimes, race conditions might not even exist.
public Result<Guid> Handle(\n ReserveBooking command,\n AppDbContext dbContext)\n{\n var user = dbContext.Users.GetById(command.UserId);\n var apartment = dbContext.Apartments.GetById(command.ApartmentId);\n var (startDate, endDate) = command;\n\n if (dbContext.Bookings.IsOverlapping(apartment, startDate, endDate))\n {\n return Result.Failure<Guid>(BookingErrors.Overlap);\n }\n\n try\n {\n var booking = Booking.Reserve(apartment, user, startDate, endDate);\n\n dbContext.Add(booking);\n\n dbContext.SaveChanges();\n\n return booking.Id;\n }\n catch (DbUpdateConcurrencyException)\n {\n return Result.Failure<Guid>(BookingErrors.Overlap);\n }\n}\nIf you're wondering how will this even work, here's the missing piece.\nThe Booking.Reserve method will update the LastBookedOnUtc property of the Apartment entity.
public static Booking Reserve(Apartment apartment, User user, DateTime startDate, DateTime endDate)\n{\n apartment.LastBookedOnUtc = DateTime.UtcNow;\n\n return new Booking\n {\n Id = Guid.NewGuid(),\n Apartment = apartment,\n User = user,\n StartDate = startDate,\n EndDate = endDate\n };\n}\nWhen we call SaveChanges, this will cause an update to the Apartment entity, which will include the concurrency token check.\nThis ensures that if two requests try to update the same entity simultaneously, one will succeed while the other will fail with a DbUpdateConcurrencyException.
Optimistic concurrency considers the best scenario is also the most probable one.\nIt assumes conflicts between transactions will be infrequent and doesn't acquire locks on the data.\nThis means your system can scale better because there is no blocking slowing down performance.
\nHowever, you must still expect concurrency conflicts and implement custom logic to handle them.
\nOptimistic concurrency is a good choice if your application doesn't expect many conflicts.
\nAnother reason to use optimistic concurrency is when you can't hold an open connection to the database for the length of the transaction.\nThis is required for pessimistic locking.
\nHope this was helpful.
\nI'll see you next week!
\nTestcontainers is a .NET library that spins up throwaway Docker containers for integration tests.\nInstead of mocks or in-memory databases, you run the real SQL Server image, point EF Core at its connection string, and dispose the container when the tests finish.\nIt works in any CI pipeline that supports Docker.
\nModern software applications rarely work in isolation.\nOn the contrary, a typical application will talk to several external systems like databases, messaging systems, cache providers, and many 3rd party services.\nAnd it's up to you to ensure everything functions correctly.
\nHopefully, I don't have to convince you about the value of writing tests.
\nYou should be writing tests.\nPeriod.
\nHowever, I do want to discuss the value of integration testing.
\nUnit tests are helpful to test business logic in isolation, without any external services.\nThey are easy to write and provide almost instant feedback.
\nBut you can't be fully confident in your application without integration tests.
\nSo, in this week's newsletter, I'll show you how to use Docker for integration testing.
\nHere's what we will use to write integration tests:
\nLet's dive in!
\nTestcontainers is a library for writing tests with throwaway Docker containers.
\nWhy should you use it?
\nIntegration testing is considered "difficult" because you have to maintain testing infrastructure.\nBefore running tests, you need to make sure the database is up and running.\nYou also have to seed any data required for the tests.\nIf you have tests running in parallel on the same database, they could interfere with each other.
\nA possible solution could be using in-memory variations of the required services.\nBut this isn't much different from using mocks.\nIn-memory services might not have all the features of the production service.
\nTestcontainers solves this by using Docker to spin up real services for integration testing.
\nHere's an example of creating a SQL Server container:
\nMsSqlContainer dbContainer = new MsSqlBuilder()\n .WithImage("mcr.microsoft.com/mssql/server:2022-latest")\n .WithPassword("Strong_password_123!")\n .Build();\nYou can then use the MsSqlContainer instance to get a connection string for the database running inside the container.
Do you see how this is valuable for writing integration tests?
\nNo more need for mocks or fake in-memory databases.\nInstead, you can use the real deal.
\nI won't do a deep dive into this library here, so refer to the documentation for more information.
\nASP.NET Core provides an in-memory test server that we can use to spin up an application instance for running tests.\nThe Microsoft.AspNetCore.Mvc.Testing package provides the WebApplicationFactory class that we will use as the base for our implementation.
WebApplicationFactory<TEntryPoint> is used to create a TestServer for the integration tests.
The custom IntegrationTestWebAppFactory will do a few things:
MsSqlContainer instanceConfigureTestServices to set up EF Core with the container databaseIAsyncLifetimeMsSqlContainer has a GetConnectionString method to grab the connection string for the current container.\nNote that this can change between tests, as each test class will create a separate container instance.\nTest cases inside the same test class will use the same container instance.\nSo keep that in mind if you need to do a cleanup between tests.
Another thing to keep in mind is database migrations.\nYou will have to run them manually before every test to create the required database structure.
\nStarting the container instance is done asynchronously using IAsyncLifetime.\nThe container is started inside StartAsync before any of the tests run.\nAnd it's stopped inside StopAsync.
Here's the complete code for IntegrationTestWebAppFactory:
public class IntegrationTestWebAppFactory\n : WebApplicationFactory<Program>,\n IAsyncLifetime\n{\n private readonly MsSqlContainer _dbContainer = new MsSqlBuilder()\n .WithImage("mcr.microsoft.com/mssql/server:2022-latest")\n .WithPassword("Strong_password_123!")\n .Build();\n\n protected override void ConfigureWebHost(IWebHostBuilder builder)\n {\n builder.ConfigureTestServices(services =>\n {\n var descriptorType =\n typeof(DbContextOptions<ApplicationDbContext>);\n\n var descriptor = services\n .SingleOrDefault(s => s.ServiceType == descriptorType);\n\n if (descriptor is not null)\n {\n services.Remove(descriptor);\n }\n\n services.AddDbContext<ApplicationDbContext>(options =>\n options.UseSqlServer(_dbContainer.GetConnectionString()));\n });\n }\n\n public Task InitializeAsync()\n {\n return _dbContainer.StartAsync();\n }\n\n public new Task DisposeAsync()\n {\n return _dbContainer.StopAsync();\n }\n}\nThe base test class will implement a class fixture interface IClassFixture.\nIt indicates the class contains tests and provides shared object instances across the test cases inside.\nThis is a good place to instantiate any services that are required for most tests.
For example, I'm creating an IServiceScope for resolving scoped services inside the tests.
ISender for sending commands and queriesApplicationDbContext for database setup or verifying resultspublic abstract class BaseIntegrationTest\n : IClassFixture<IntegrationTestWebAppFactory>,\n IDisposable\n{\n private readonly IServiceScope _scope;\n protected readonly ISender Sender;\n protected readonly ApplicationDbContext DbContext;\n\n protected BaseIntegrationTest(IntegrationTestWebAppFactory factory)\n {\n _scope = factory.Services.CreateScope();\n\n Sender = _scope.ServiceProvider.GetRequiredService<ISender>();\n\n DbContext = _scope.ServiceProvider\n .GetRequiredService<ApplicationDbContext>();\n }\n\n public void Dispose()\n {\n _scope?.Dispose();\n DbContext?.Dispose();\n }\n}\nWith all the infrastructure in place, we're finally ready to write the tests.
\nHere's a ProductTests class with an integration test inside.
I use the Arrange-Act-Assert pattern to structure tests:
\nCreateProduct.Command instanceISender and store the resultThe value of writing integration tests like this is that you can use the complete MediatR request pipeline.\nIf you have any IPipelineBehavior wrapping the request, it will also be executed.
The same applies if you write your business logic inside service classes.\nInstead of resolving the ISender, you would resolve the specific services you want to test.
Most importantly, this test uses a real database instance running inside a Docker container.
\npublic class ProductTests : BaseIntegrationTest\n{\n public ProductTests(IntegrationTestWebAppFactory factory)\n : base(factory)\n {\n }\n\n [Fact]\n public async Task Create_ShouldCreateProduct()\n {\n // Arrange\n var command = new CreateProduct.Command\n {\n Name = "AMD Ryzen 7 7700X",\n Category = "CPU",\n Price = 223.99m\n };\n\n // Act\n var productId = await Sender.Send(command);\n\n // Assert\n var product = DbContext\n .Products\n .FirstOrDefault(p => p.Id == productId);\n\n Assert.NotNull(product);\n }\n}\nYou can also run integration tests with Testcontainers inside CI/CD pipelines.\nThe only requirement is that it supports Docker.
\nGitHub Actions does support Docker.\nIf you are hosting your project there, integration tests will work out of the box.
\nYou can learn more about building a CI/CD pipeline with GitHub Actions here.
\nAnd if you want a plug-in solution, here's a GitHub Actions workflow you can use:
\nname: Run Tests 🚀\n\non:\n workflow_dispatch:\n push:\n branches:\n - main\n\njobs:\n run-tests:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Setup .NET\n uses: actions/setup-dotnet@v3\n with:\n dotnet-version: '7.0.x'\n\n - name: Restore\n run: dotnet restore ./Products.Api.sln\n\n - name: Build\n run: dotnet build ./Products.Api.sln --no-restore\n\n - name: Test\n run: dotnet test ./Products.Api.sln --no-build\nTestcontainers is an excellent solution for writing integration tests with Docker.\nYou can spin up and configure any Docker image and use it from your application.\nThis is far better than using mocks or in-memory variations because they lack many features.
\nIf you have a CI/CD pipeline that supports Docker, Testcontainers will work out of the box.
\nOnly a few integration tests will drastically improve your confidence in the system.
\nYou can grab the source code for this newsletter on my GitHub.
\nIt's completely free, so what are you waiting for?
And if you prefer video, here's a quick tutorial on integration testing with Testcontainers.
\nHope this was valuable.
\nStay awesome!
\nOrchestration is centralized and command-driven: one service acts as the orchestrator and tells the other services what to do.\nChoreography is decentralized and event-driven: each service publishes events, and other services react to the ones they care about.\nOrchestration is easier to monitor and troubleshoot, while choreography gives you looser coupling.
\nMore than 63%+ of organizations said in a Dzone survey\nthat they are adopting Microservices for some or all of their applications.
\nAs more businesses adopt the use of Microservice architectures, we as developers have to become more skilled with Microservices communication.
\nWorking with distributed systems is both fun and challenging at the same time.\nOne of those challenges is designing effective communication between services.
\nMore centralization or less centralization?\nMore coupling or less coupling?\nMore control or less control?
\nThese are only a few questions you need to answer.
\nIn this week's newsletter, we will:
\nLet's dive in!
\nMicroservices are a software architecture style where an application is built from small, autonomous services.\nEach microservice serves a distinct purpose and can be independently deployed.
\nYou probably already know this, so this is a quick refresher.
\n![\"Complex](\"https://milanjovanovic.tech/blogs/mnw_052/microservices_hell.png\")
\nHere are the key tenets of Microservices:
\nA significant challenge is designing effective inter-service communication within this distributed environment.
\nInside a Monolith system, communication happens through direct method calls.\nThis is a straightforward approach that works well when all components live within a single process.\nHowever, this doesn't work with microservices.
\nOrchestration is a centralized approach to Microservices communication.\nOne of the services takes on the role of the orchestrator and coordinates the communication between services.
\nOrchestration uses command-driven communication.\nThe command communicates the intent of the action.\nThe sender wants something to happen, and the recipient doesn't need to know who sent the command.
\nAn example of orchestration can be a Saga implemented with RabbitMQ.
\n![\"Orchestration](\"https://milanjovanovic.tech/blogs/mnw_052/orchestration.png\")
\nIt has some nice benefits:
\nOrchestration is typically simpler to implement and maintain than choreography.\nBecause there is a central coordinator, you can manage and monitor service interactions.\nThis, in turn, improves troubleshooting, as you know where to look when something goes wrong.
\nThe drawbacks of orchestration are:
\nChoreography is a decentralized communication approach.\nChoreography uses event-driven communication - as opposed to orchestration, which uses commands.
\nAn event is something that has happened in the past and is a fact.\nThe sender does not know who will handle the event or what will happen after processing it.
\nI talked about events in-depth in the newsletter about publishing domain events.
\n![\"Choreography](\"https://milanjovanovic.tech/blogs/mnw_052/choreography.png\")
\nThe most important benefits of choreography are:
\nChoreography allows microservices to be loosely coupled, which means they can operate independently and asynchronously.\nThis makes the system more scalable and resilient.\nA failure of one microservice won't necessarily affect microservices.
\nOf course, there are downsides to choreography:
\nIt's more complex to implement and maintain than orchestration.
\nEffective monitoring is the biggest challenge from my experience.
\nSo, how do you know which one to pick for your system?
\nI always start with the requirements of the system I'm building.\nAnd then, I look at the pros and cons of orchestration vs. choreography.\nHere's a small framework to help you decide.
\nOrchestration excels when:
\nThis also means you will need a central database managed by the orchestrator to handle all workflow-related state.
\nChoreography works best when:
\nYou can benefit from increased flexibility (such as modifying individual steps in isolation)\nUnfortunately, choreography can make it difficult to trace, debug, or monitor the processes triggered by an event.\nAnd the larger the event stream is, the more challenging it becomes.
\nSo, think carefully before opting for orchestration or choreography.
\nBoth approaches bring their advantages but also downsides.
\nOrchestration defines a sequence of steps that each microservice must follow.\nThis is great for identifying and addressing complex service interdependencies.\nAnother benefit is that business logic can be managed and monitored in one place.
\nChoreography, on the other hand, is a decentralized technique for microservices communication.\nEach service can operate independently while still being part of the larger architecture.
\nTo decide which approach to use, you should observe your system and identify what you stand to gain or lose.\nEverything is a tradeoff.
\nThere's also an alternative approach I want to mention.
\nYou could go for a hybrid approach that integrates orchestration and choreography.
\nIn a hybrid approach, you decide which communication technique to use for a specific workflow.\nSome workflows can benefit from orchestration, and others can benefit more from choreography.
\nHope this was helpful.
\nI'll see you next week!
\nThe built-in .NET rate limiter goes beyond a single global policy once you partition it.\nA RateLimitPartition lets you key the limit on the client's IP address for anonymous users, or on the user identity for authenticated ones.\nIf you run behind a reverse proxy, you partition on the X-Forwarded-For header instead of the connection IP, or apply rate limiting at the proxy itself.
Rate limiting is about restricting the number of requests to your application.\nIt's usually applied within a specific time window or based on other criteria.
\nIt's helpful for a few reasons:
\n.NET 7 shipped with a built-in rate limiter, but you need to know how to implement it correctly.\nOr you could grind your system to a halt - and we don't want that.
\nIn this week's newsletter, I'll teach you:
\nSo let's dive in!
\nStarting with .NET 7, we have access to built-in rate limiting middleware in the Microsoft.AspNetCore.RateLimiting namespace.\nThe API is straightforward, and you can create a rate limit policy with a few lines of code.
We can use one of the four rate limiting algorithms:
\nHere's how to define a rate limit policy by calling the AddTokenBucketLimiter method:
builder.Services.AddRateLimiter(rateLimiterOptions =>\n{\n options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;\n\n rateLimiterOptions.AddTokenBucketLimiter("token", options =>\n {\n options.TokenLimit = 1000;\n options.ReplenishmentPeriod = TimeSpan.FromHours(1);\n options.TokensPerPeriod = 700;\n options.AutoReplenishment = true;\n });\n});\nNow you can reference the token rate limit policy on your endpoint or controller.
You also have to add the RateLimitingMiddleware to the request pipeline:
app.UseRateLimiter();\nYou can learn more about rate limiting in .NET 7 here, so I won't go deeper into the fundamentals.
\nThe approach I just showed you has a problem - the rate limit policy is global and applies to all users.
\nMost of the time, you don't want to do this.\nRate limiting should be granular and apply to individual users.
\nLuckily, you can achieve this by creating a RateLimitPartition.
The RateLimitPartition has two components:
Here's how to define a rate limiter with a fixed window policy, and the partition key is the user's IP address.
\nbuilder.Services.AddRateLimiter(options =>\n{\n options.AddPolicy("fixed-by-ip", httpContext =>\n RateLimitPartition.GetFixedWindowLimiter(\n partitionKey: httpContext.Connection.RemoteIpAddress?.ToString(),\n factory: _ => new FixedWindowRateLimiterOptions\n {\n PermitLimit = 10,\n Window = TimeSpan.FromMinutes(1)\n }));\n});\nRate limiting by IP address can be a good layer of security for unauthenticated users.\nYou don't know who is accessing your system and can't apply more granular rate limiting.\nThis can help protect your system from malicious users trying to perform a DDoS attack.
\nYou can also create chained limiters using the CreateChained API.\nIt allows you to pass in multiple PartitionedRateLimiter, which are combined into one PartitionedRateLimiter.\nThe chained limiter runs all the input limiters in sequence (one by one).
If your application is running behind a reverse proxy, you need to make sure not to rate limit the proxy IP address.\nReverse proxies usually forward the original IP address with the X-Forwarded-For header.\nSo you can use it as the partition key:
builder.Services.AddRateLimiter(options =>\n{\n options.AddPolicy("fixed-by-ip", httpContext =>\n RateLimitPartition.GetFixedWindowLimiter(\n httpContext.Request.Headers["X-Forwarded-For"].ToString(),\n factory: _ => new FixedWindowRateLimiterOptions\n {\n PermitLimit = 10,\n Window = TimeSpan.FromMinutes(1)\n }));\n});\nIf you require users to authenticate with your API, you can determine who the current is.\nThen you can use the user's identity as the partition key for a RateLimitPartition.
Here's how you would create such a rate limit policy:
\nbuilder.Services.AddRateLimiter(options =>\n{\n options.AddPolicy("fixed-by-user", httpContext =>\n RateLimitPartition.GetFixedWindowLimiter(\n partitionKey: httpContext.User.Identity?.Name?.ToString(),\n factory: _ => new FixedWindowRateLimiterOptions\n {\n PermitLimit = 10,\n Window = TimeSpan.FromMinutes(1)\n }));\n});\nI'm using the User.Identity value on the HttpContext to get the current user's Name claim.\nThis usually corresponds to the sub claim inside a JWT - which is the user identifier.
In a robust implementation, you want to rate limit on the reverse proxy level before the request hits your API.\nAnd if you have a distributed system, this is a requirement.\nOtherwise, your system wouldn't function correctly.
\nThere are many reverse proxy implementations to choose from.
\nYARP is a reverse proxy with excellent .NET integration.\nNot surprising since it was written in C#.\nYou can learn more about building an API Gateway with YARP here.
\nTo implement rate limiting on the reverse proxy with YARP you need to:
\nRateLimiterPolicy for the route in YARP settings"products-route": {\n "ClusterId": "products-cluster",\n "RateLimiterPolicy": "sixty-per-minute-fixed",\n "Match": {\n "Path": "/products/{**catch-all}"\n },\n "Transforms": [\n { "PathPattern": "{**catch-all}" }\n ]\n}\nThe built-in rate limiter middleware uses an in-memory store to track the number of requests.\nIf you want to run your reverse proxy in a high-availability setup, you will need to use a distributed cache.\nA nice option to look into is using a Redis backplane for rate limiting.
\nWith the PartitionedRateLimiter you can easily create granular rate limit policies.
The two common approaches are:
\nI was really excited to see the .NET team ship rate limiting.\nBut, the current implementation has its shortcomings.\nThe main issue is that it only works in memory.\nFor a distributed solution, you need to implement something yourself or use an external library.
\nYou can use the YARP reverse proxy to build robust and scalable distributed systems.\nAnd it only takes a few lines of code to add rate limiting on the reverse proxy level.\nI'm using it extensively in my systems.
\nThanks for reading.
\nAnd stay awesome!
\nDapper maps a flat result set straight into an object, but relationships need multi-mapping.\nFor a one-to-one relationship, pass both types to QueryAsync, supply a mapping function, and set splitOn to the first column of the nested object.\nFor one-to-many, keep a dictionary so the joined rows reuse the same parent, and many-to-many needs one dictionary per side.
Dapper is a lightweight object-relational mapper in .NET.\nIt's popular because it's easy to use and fast at the same time.
\nDapper extends the IDbConnection interface with methods for sending SQL queries to the database.
But, because of the nature of SQL, mapping the result into an object model can be tricky.
\nSo in this week's newsletter, I'll teach you how to map:
\nLet's dive in!
\nLet's first see how to do a simple mapping using Dapper.
\nWriting a query with Dapper has three parts:
\nIDbConnection instanceWe will write a SQL query to load a set of LineItem objects for a specific Order.
public class LineItem\n{\n public long LineItemId { get; init; }\n\n public long OrderId { get; init; }\n\n public decimal Price { get; init; }\n\n public string Currency { get; init; }\n\n public decimal Quantity { get; init; }\n}\nHere's the SQL query returning the result we need:
\nSELECT Id AS LineItemId, OrderId, Price, Currency, Quantity\nFROM LineItems\nWHERE OrderId = @OrderId\nI'm parameterizing the Order identifier using the @OrderId syntax.\nThis is a Dapper convention.\nIt's important that you use parameterized queries to avoid SQL injection attacks.
The mapping is straightforward in this case because we are only returning one type from the database.
\nWe call the QueryAsync method and specify LineItem as the return type.\nMake sure to pass in the arguments for this method, the SQL query, and the OrderId parameter.\nI prefer creating anonymous objects for Dapper parameters.
using var connection = new SqlConnection();\n\nvar lineItems = await connection.QueryAsync<LineItem>(\n sql,\n new { OrderId = orderId });\nThat's everything you need for a simple mapping.
\nWhat if the object we want to return from the SQL query contains a nested object?
\nHere's an updated LineItem type that also contains a Product inside.
public class LineItem\n{\n public long LineItemId { get; init; }\n\n public long OrderId { get; init; }\n\n public decimal Price { get; init; }\n\n public string Currency { get; init; }\n\n public decimal Quantity { get; init; }\n\n public Product Product { get; init; }\n}\n\npublic class Product\n{\n public long ProductId { get; init; }\n\n public string Name { get; init; }\n}\nNow you need to return two types in the same query.
\nHere's the updated SQL query with a join on the Products table:
SELECT li.Id AS LineItemId, li.OrderId, li.Price, li.Currency, li.Quantity,\n p.Id AS ProductId, p.Name\nFROM LineItems li\nJOIN Products p ON p.Id = li.ProductId\nWHERE li.OrderId = @OrderId\nThis query is more complicated because we need to use Dapper's multi-mapping feature.
\nIn the QueryAsync method, we specify both LineItem and Product as return types and LineItem as the final return type for the method.
We must also tell Dapper how to map the LineItem and Product from the result set into a single LineItem object.
And we need to specify the splitOn argument, which tells Dapper where one object ends and the next begins.
using var connection = new SqlConnection();\n\nvar lineItems = await connection.QueryAsync<LineItem, Product, LineItem>(\n sql,\n (lineItem, product) =>\n {\n lineItem.Product = product;\n\n return lineItem;\n },\n new { OrderId = orderId },\n splitOn: "ProductId");\nWe write more code to make this work, but it should be easy to wrap your head around it.
\nAnother frequent situation is mapping a one-to-many relationship from SQL into an object model.
\nBecause you are joining two tables, the result set will contain duplicate data on the "one" side of the relationship.
\nFor this example, let's use an Order with a list of LineItem objects.
public class Order\n{\n public long OrderId { get; init; }\n\n public List<LineItem> LineItems { get; init; } = new();\n}\n\npublic class LineItem\n{\n public long LineItemId { get; init; }\n\n public long OrderId { get; init; }\n\n public decimal Price { get; init; }\n\n public string Currency { get; init; }\n\n public decimal Quantity { get; init; }\n}\nHere's the SQL query returning the data we need from the database:
\nSELECT o.Id AS OrderId,\n li.Id AS LineItemId, li.OrderId, li.Price, li.Currency, li.Quantity\nFROM Orders o\nJOIN LineItems li ON li.OrderId = o.Id\nWHERE o.Id = @OrderId\nWe're going to get back duplicate Order data because of the JOIN.\nBut we only want to return one Order with all the line items.
The Dapper mapping function only gives us the Order and LineItem for the current row in the result set.
One way to solve this is to use a Dictionary to store the Order and reuse it inside the mapping.
Order in the dictionary if it's not thereLineItem to the existing Order instanceusing var connection = new SqlConnection();\n\nvar ordersDictionary = new Dictionary<long, Order>();\n\nawait connection.QueryAsync<Order, LineItem, Order>(\n sql,\n (order, lineItem) =>\n {\n if (ordersDictionary.TryGetValue(order.OrderId, out var existingOrder))\n {\n order = existingOrder;\n }\n else\n {\n ordersDictionary.Add(order.OrderId, order);\n }\n\n order.LineItems.Add(lineItem);\n\n return order;\n },\n new { OrderId = orderId },\n splitOn: "LineItemId");\n\nvar mappedOrder = ordersDictionary[orderId];\nA many-to-many relationship would use the same idea, except you'll need two dictionaries for each side of the relationship.
\nDapper is a fantastic library for writing fast database queries using SQL.
\nBecause of how SQL works, mapping into an object model is sometimes complicated.
\nThere are four common scenarios:
\nNow you have a cheat sheet for mapping relationships with Dapper.
\nHope this was helpful.
\nI'll see you next week!
\nModules in a modular monolith communicate in two ways.\nSynchronous method calls on a module's public API are fast and easy to implement, but they couple the modules together.\nAsynchronous messaging through a message broker gives you loose coupling and availability, at the cost of another piece of infrastructure to manage.
\nModular monoliths are becoming more popular in the software engineering community.
\nThe allure of Microservices is becoming less compelling.\nWe also have seasoned veterans of our industry saying you should reconsider:
\n\n\n\nYou shouldn't start a new project with microservices, even if you're sure your application will be big enough to make it worthwhile.
\n
Modular monoliths give you the logical architecture of Microservices without the operational complexity.\nYou can safely determine the boundaries between modules.\nAnd refactoring is straightforward and less risky.\nThey can also be easily migrated into Microservices if you decide to do so.
\nI've built and maintained several large Modular monolith systems in the past years.
\nIn this week's newsletter, I want to focus on the communication patterns in the Modular monolith architecture.
\nBut first, let me explain what is a Modular monolith.
\nHere's one definition of what a Modular monolith is:
\n\n\nA Modular Monolith is a software design approach in which a monolith is designed with an emphasis on interchangeable (and potentially reusable) modules.
\n
The problem with most monolith systems is that they become tightly coupled over time.\nComponents are deeply intertwined.\nMaking a change in one component impacts many others.\nIntroducing new features is difficult and error-prone.
\nModular monoliths aim to solve these problems.
\n![\"Comparison](\"https://milanjovanovic.tech/blogs/mnw_049/modular_monolith_diagram.png\")
\nA Modular monolith consists of many loosely coupled modules.\nModules represent cohesive sets of functionalities.\nModules are also independent of each other.
\nHere are a few examples:
\nIf this concept reminds you of Microservices, that's because it should.
\nMicroservices represent self-contained services encapsulating a set of functionalities of the larger system, much like modules in a Modular monolith.
\nFor a Modular monolith to be loosely coupled, you need to solve how modules will communicate.
\nModules cannot reference each other directly except through their public APIs.
\nThere are two widely used communication patterns.\nBoth have pros and cons and a set of tradeoffs that you need to understand.
\nThe first and easiest communication pattern is simple method calls between modules.\nMethod calls are synchronous and very fast because they're in memory.
\nModule A calls a method declared on the public API of Module B and waits until it receives a result.
\nEach module exposes a public API, which can be an interface in .NET.
The module will implement this interface internally and hide any implementation details.\nYou can use the internal keyword to make the implementation inaccessible outside the module.
Modules depend on the interfaces at compile-time.\nAt runtime, dependency injection will provide the respective implementation.
\n![\"Module](\"https://milanjovanovic.tech/blogs/mnw_049/modular_monolith_sync_communication.png\")
\nThe benefits of this approach are:
\nBut, the drawback of this approach is strong coupling.
\nSynchronous communication means that the modules will be tightly coupled.\nIf one of the modules is unavailable, it will affect any dependent modules.\nYou can introduce a retry mechanism, but this only goes so far.
\nThe second communication pattern is asynchronous messaging between modules.
\nModule A sends a message to the message broker in a fire-and-forget fashion.\nModule B subscribes to relevant messages and handles them accordingly.
\nModules don't need to know about each other, but they do need to know about the message contracts.
\nMessage contracts are the public API of a module in this scenario.
\n![\"Modules](\"https://milanjovanovic.tech/blogs/mnw_049/modular_monolith_async_communication.png\")
\nThe benefits of this approach are:
\nAsynchronous communication gives us loose coupling because modules communicate using messages.\nModule B doesn't need to be available for Module A to send a message.
\nThe obvious drawback of this approach is increased complexity.
\nWe're introducing a message broker to the system.\nThis is another infrastructure component we have to manage.\nIt's also a single point of failure.\nIf the message broker fails, so does communication between the modules.
\nYou can prevent message loss by storing messages in an Outbox before publishing them.\nWe can always send the messages again from the database in case of a message broker failure.
\nSynchronous communication between modules is easy to implement, and it's performant. But it comes at the cost of tight coupling between modules.
\nAsynchronous communication using a message broker is loosely coupled. But it's more complex to implement.
\nSo which communication pattern should you be using?
\nIt depends.
\nAsynchronous communication can help you build loosely coupled and independent modules.\nMigrating a Modular monolith using messaging into a distributed system is much easier.
\nYou extract a module into its own deployment unit.\nAnd the communication between modules remains the same.\nBecause you are using messaging, you don't need to reimplement anything.
\nSynchronous method calls are an excellent choice to increase development velocity and reduce operational complexity.
\nI'll let the software architect in you decide.
\nThanks for reading.
\nAnd stay awesome!
\nClean Architecture is a domain-centric way to organize a system into four layers: Domain, Application, Infrastructure, and Presentation.\nAll dependencies point inwards, so the core domain stays independent of the UI, databases, and external services.\nIt pays off when the business logic is complex, and it can be over-engineering on a small project.
\nI've been using Clean Architecture for 6+ years on large-scale applications serving thousands of customers and millions of requests.\nToday I want to talk about why it's a great approach for structuring your applications.
\nI'm aware that Clean Architecture isn't a silver bullet, so I will discuss what types of systems can benefit from this architecture.
\nClean architecture isn't revolutionary.
\nBut it's prescriptive about how you should structure the code.
\nIt's an evolution of layered architecture, focusing on the core domain and the direction of dependencies.\nAll dependencies should point inwards, applying dependency inversion.
\nHere are some of the promises of Clean Architecture:
\nIt's independent of UI, databases, or external services - but you also need to be pragmatic (more on this later).
\nLet's dive in!
\nClean Architecture was created by Robert C. Martin, aka Uncle Bob.
\nClean Architecture is an approach to organizing a software system to separate the concerns of the various components.\nMaking the system easier to understand and maintain.
\nYou can think about Clean Architecture as a domain-centric approach to organizing dependencies.
\nThere are similar architectures that follow the same domain-centric idea.\nYou may know them as the Hexagonal and Onion architectures.\nThey are more or less interchangeable with each other.\nAnd they all place the core domain at the center of the architecture.
\nThis is my high-level interpretation of Clean Architecture:
\n![\"Clean](\"https://milanjovanovic.tech/blogs/mnw_048/clean_architecture.png\")
\nThere are four layers inside:
\nLet's see what should live inside each layer.
\nHere's a breakdown of what should live inside each layer of the Clean Architecture.
\nDomain
\nApplication
\nInfrastructure
\nPresentation
\nHere's an example of how to structure the Clean Architecture on a solution level.\nYou can also group related components together by feature.\nIt leads to better cohesion and is an excellent option if your project is more complex.
\nI also made a few videos covering the Clean Architecture project setup:
\nClean Architecture is very versatile and applies to various domains and systems.
\nBut, you should play to its strengths and use it only when there's a tangible benefit.
\nI use the Clean Architecture when I want to:
\nIf the above is true for your project, then Clean Architecture is an excellent option.
\nYou should also consider the benefits of Clean Architecture.
\nI try to be pragmatic when using Clean Architecture.
\nApplying what I like and having the freedom of "breaking" Clean Architecture if it will simplify things.
\nCan this be called Clean Architecture, then?\nNo, not in the purest sense.
\nBut, I still get most of the benefits of Clean Architecture.
\nHere's an example, when I'm applying CQRS in Clean Architecture to implement the use cases.
\nOn the command (write) side, it's valuable to be independent of external concerns, so I will use repositories behind an interface.\nI can control the repository contract, and unit testing is straightforward.
\nBut, on the query (read) side, I want to return the response as fast as possible.\nCreating an abstraction only adds indirection and reduces performance.
\nA better approach is to use the EF or Dapper in the handler and query the database.\nIt's simple, fast, and you can use all the features offered by the ORM.\nYou don't need a lot of complexity or abstractions on the query side.
\nI should call this approach Pragmatic Clean Architecture.
\nClean Architecture gives you a standard for organizing your solution.
\nYou don't have to reinvent the wheel every time at the start of the project.
\nBut, the layered structure and architectural constraints can increase the complexity of smaller projects.
\nSo make sure your project is complex enough to apply Clean Architecture.
Another caveat of Clean Architecture is the danger of over-engineering.
\nDon't follow the principles religiously without considering the specific project requirements.
\nThe overhead of maintaining so many layers and abstractions may not be justified.
Be pragmatic and try to make the best decision possible.
\nSometimes that means straying from the paradigm.
\nHope this was helpful.
\nI'll see you next week!
\nA domain event is a Domain-Driven Design pattern that records a fact which already happened in the domain.\nOther components subscribe to that event and react to it, so the code raising the event stays decoupled from the side effects.\nIn .NET you can implement domain events as MediatR notifications and publish them from EF Core's SaveChangesAsync.
In software engineering, "coupling" means how much different parts of a software system depend on each other.\nIf they are tightly coupled, changes to one part can affect many others.\nBut if they are loosely coupled, changes to one part won't cause big problems in the rest of the system.
\nDomain events are a Domain-Driven Design (DDD) tactical pattern that we can use to build loosely coupled systems.
\nYou can raise a domain event from the domain, which represents a fact that has occurred.\nAnd other components in the system can subscribe to this event and handle it accordingly.
\nHere's what you will learn in this week's newsletter:
\nWe have a lot to cover, so let's dive in!
\nAn event is something that has happened in the past.
\nIt is a fact.
\nUnchangeable.
\nA domain event is something that happened in the domain, and other parts of the domain should be aware of it.
\nDomain events allow you to express side effects explicitly, and provide a better separation of concerns in the domain.\nThey're an ideal way to trigger side effects across multiple aggregates inside the domain.
\nIt's your responsibility to ensure that publishing a domain event is transactional.\nYou'll see why this is easier said than done.
\n![\"CourseCompleted](\"https://milanjovanovic.tech/blogs/mnw_047/domain_events.png\")
\nYou may have heard of integration events, and you're now wondering what's the difference between them and domain events.
\nSemantically, they're the same thing: a representation of something that occurred in the past.
\nHowever, their intent is different and this is important to understand.
\nDomain events:
\nIntegration events:
\nSo if you're wondering what type of event you should publish, think about the intent and who should be handling the event.
\nDomain events can also be used to generate integration events, which leave the domain boundary.
\nMy preferred approach to implement domain events is creating an IDomainEvent abstraction and implementing MediatR INotification.
The benefit is you can use MediatR's publish-subscribe support to publish a notification to one or multiple handlers.
\nusing MediatR;\n\npublic interface IDomainEvent : INotification\n{\n}\nNow you can implement a concrete domain event.
\nHere are a few constraints to consider when designing domain events:
\npublic class CourseCompletedDomainEvent : IDomainEvent\n{\n public Guid CourseId { get; init; }\n}\nAfter you create your domain events, you want to raise them from the domain.
\nMy approach is creating an Entity base class, because only entities are allowed to raise domain events.\nYou can further encapsulate raising domain events by making the RaiseDomainEvent method protected.
We're storing domain events in an internal collection, to prevent anyone else from accessing it.\nThe GetDomainEvents method is there to get a snapshot of the collection, and the ClearDomainEvents method to clear the internal collection.
public abstract class Entity : IEntity\n{\n private readonly List<IDomainEvent> _domainEvents = new();\n\n public IReadOnlyList<IDomainEvent> GetDomainEvents()\n {\n return _domainEvents.ToList();\n }\n\n public void ClearDomainEvents()\n {\n _domainEvents.Clear();\n }\n\n protected void RaiseDomainEvent(IDomainEvent domainEvent)\n {\n _domainEvents.Add(domainEvent);\n }\n}\nNow you're entities can inherit from the Entity base class and raise domain events:
public class Course : Entity\n{\n public Guid Id { get; private set; }\n\n public CourseStatus Status { get; private set; }\n\n public DateTime? CompletedOnUtc { get; private set; }\n\n public void Complete()\n {\n Status = CourseStatus.Completed;\n CompletedOnUtc = DateTime.UtcNow;\n\n RaiseDomainEvent(new CourseCompletedDomainEvent { CourseId = this.Id });\n }\n}\nAnd all that's left to do is publish the domain events.
\nAn elegant solution for publishing domain events is using EF Core.
\nSince EF Core acts as a Unit of Work, you can use it to gather all domain events in the current transaction and publish them.
\nI don't like to complicate things, and simply override the SaveChangesAsync method to publish the domain events after persisting the changes in the database.\nBut you could also use an interceptor.
public class ApplicationDbContext : DbContext\n{\n public override async Task<int> SaveChangesAsync(\n CancellationToken cancellationToken = default)\n {\n // When should you publish domain events?\n //\n // 1. BEFORE calling SaveChangesAsync\n // - domain events are part of the same transaction\n // - immediate consistency\n // 2. AFTER calling SaveChangesAsync\n // - domain events are a separate transaction\n // - eventual consistency\n // - handlers can fail\n\n var result = await base.SaveChangesAsync(cancellationToken);\n\n await PublishDomainEventsAsync();\n\n return result;\n }\n}\nThe most important decision you will have to make here is when to publish the domain events.
\nI think it makes the most sense to publish after calling SaveChangesAsync.\nIn other words, after saving changes to the database.
This comes with a few tradeoffs:
\nEventual consistency is something I can live with, so I choose to make this tradeoff.
\nHowever, introducing a risk of database inconsistency is a big concern.
\nYou can solve this with the Outbox pattern,\nwhere you persist your changes to the database and the domain events (as outbox messages) in a single transaction.\nNow you have a guaranteed atomic transaction, and the domain events are processed asynchronously using a background job.
\nIf you're wondering what's inside the PublishDomainEventsAsync method:
private async Task PublishDomainEventsAsync()\n{\n var domainEvents = ChangeTracker\n .Entries<Entity>()\n .Select(entry => entry.Entity)\n .SelectMany(entity =>\n {\n var domainEvents = entity.GetDomainEvents();\n\n entity.ClearDomainEvents();\n\n return domainEvents;\n })\n .ToList();\n\n foreach (var domainEvent in domainEvents)\n {\n await _publisher.Publish(domainEvent);\n }\n}\nWith all of the plumbing we created so far, we're ready to implement a handler for the domain events.\nLuckily, this is the simplest step in the process.
\nAll you have to do is define a class implementing INotificationHandler<T> and specify your domain event type as the generic argument.
Here's a handler for the CourseCompletedDomainEvent, which takes the domain event and publishes a CourseCompletedIntegrationEvent to notify other systems.
public class CourseCompletedDomainEventHandler\n : INotificationHandler<CourseCompletedDomainEvent>\n{\n private readonly IBus _bus;\n\n public CourseCompletedDomainEventHandler(IBus bus)\n {\n _bus = bus;\n }\n\n public async Task Handle(\n CourseCompletedDomainEvent domainEvent,\n CancellationToken cancellationToken)\n {\n await _bus.Publish(\n new CourseCompletedIntegrationEvent(domainEvent.CourseId),\n cancellationToken);\n }\n}\nDomain events can help you build a loosely coupled system.\nYou can use them to separate the core domain logic from the side effects, which can be handled asynchronously.
\nThere's no need to reinvent the wheel for implementing domain events, and you can use the EF Core and MediatR libraries to build this.
\nYou will have to make the decision when you want to publish domain events.\nPublishing before or after saving changes to the database both have their set of tradeoffs.
\nI prefer publishing domain events after saving changes to the database, and I use the Outbox pattern\nto add transactional guarantees.\nThis approach introduces eventual consistency, but it's also more reliable.
\nHope this was helpful.
\nSee you next week!
\nToday's action step:\nTake a look at this video, where I explain how to implement domain events to build a decoupled system that scales.
\nClean code is easy to read and maintain, and refactoring exercises are how you practice writing it.\nThis issue takes one badly written Process method through eight steps: early returns, merged conditions, LINQ, a descriptive method name, custom exceptions, constants for magic numbers, enums for magic strings, and the result object pattern.
Clean code is code that's easy to read, maintain, and understand.
\nI consider writing clean code a skill.
\nAnd it's a skill that you can learn and improve with deliberate practice.
\nMy favorite approach for practicing clean coding is doing refactoring exercises.
\nSo I prepared one for you today, and we're going to improve it one step at a time by applying clean code principles.
\nLet's dive in!
\nI like starting with a problem when trying to learn new concepts.
\nAnd the more illustrative the problem, the better.
\nSo we'll use some poorly written code as the starting point for our refactoring.
\nAnd in each step, I will highlight what the current issue is and how we will fix it.
\nHere's what I see when I look at the Process method:
How can we turn this into clean code?
\npublic void Process(Order? order)\n{\n if (order != null)\n {\n if (order.IsVerified)\n {\n if (order.Items.Count > 0)\n {\n if (order.Items.Count > 15)\n {\n throw new Exception(\n "The order " + order.Id + " has too many items");\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new Exception(\n "The order " + order.Id + " isn't ready to process");\n }\n\n order.IsProcessed = true;\n }\n }\n }\n}\nIt should be painfully obvious by now that the initial version is deeply nested because of the if statements applying precondition checks.
We'll solve this using the early return principle, which states that we should return from a method as soon as the conditions for that have been met.
\nIn the case of the Process method, this means moving from a deeply nested structure to a set of guard clauses.
public void Process(Order? order)\n{\n if (order is null)\n {\n return;\n }\n\n if (!order.IsVerified)\n {\n return;\n }\n\n if (order.Items.Count == 0)\n {\n return;\n }\n\n if (order.Items.Count > 15)\n {\n throw new Exception(\n "The order " + order.Id + " has too many items");\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new Exception(\n "The order " + order.Id + " isn't ready to process");\n }\n\n order.IsProcessed = true;\n}\nThe early return principle makes the Process method more readable.
But there's no need to have one guard clause after another.
\nSo we can merge all of them into one if statement.
The behavior of the Process method remains unchanged, but we remove a lot of excess code.
public void Process(Order? order)\n{\n if (order is null ||\n !order.IsVerified ||\n order.Items.Count == 0)\n {\n return;\n }\n\n if (order.Items.Count > 15)\n {\n throw new Exception(\n "The order " + order.Id + " has too many items");\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new Exception(\n "The order " + order.Id + " isn't ready to process");\n }\n\n order.IsProcessed = true;\n}\nA quick improvement can be using LINQ to make the code more concise and expressive.
\nInstead of checking for Items.Count == 0, I prefer using the LINQ Any method.
You could argue that LINQ has worse performance, but I always optimize for readability.
\nThere are far more expensive operations in an application than a simple method call.
\npublic void Process(Order? order)\n{\n if (order is null ||\n !order.IsVerified ||\n !order.Items.Any())\n {\n return;\n }\n\n if (order.Items.Count > 15)\n {\n throw new Exception(\n "The order " + order.Id + " has too many items");\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new Exception(\n "The order " + order.Id + " isn't ready to process");\n }\n\n order.IsProcessed = true;\n}\nMerging multiple conditions into one if statement means writing less code, but it can decrease readability with complex conditions.
However, you can fix this and improve readability by using a variable or method with a descriptive name.
\nI prefer using methods, so I will introduce the IsProcessable method to represent the precondition check.
public void Process(Order? order)\n{\n if (!IsProcessable(order))\n {\n return;\n }\n\n if (order.Items.Count > 15)\n {\n throw new Exception(\n "The order " + order.Id + " has too many items");\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new Exception(\n "The order " + order.Id + " isn't ready to process");\n }\n\n order.IsProcessed = true;\n}\n\nstatic bool IsProcessable(Order? order)\n{\n return order is not null &&\n order.IsVerified &&\n order.Items.Any();\n}\nNow let's talk about throwing exceptions.\nI like to use exceptions for "exceptional" situations only, and I don't use them for flow control in my code.
\nHaving said that, if you do want to use exceptions for flow control, it's better to use custom exceptions.
\nYou can introduce valuable contextual information and better describe the reason for throwing the exception.
\nAnd if you want to handle these exceptions globally, you can create a base class to be able to catch specific exceptions.
\npublic void Process(Order? order)\n{\n if (!IsProcessable(order))\n {\n return;\n }\n\n if (order.Items.Count > 15)\n {\n throw new TooManyLineItemsException(order.Id);\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new NotReadyForProcessingException(order.Id);\n }\n\n order.IsProcessed = true;\n}\n\nstatic bool IsProcessable(Order? order)\n{\n return order is not null &&\n order.IsVerified &&\n order.Items.Any();\n}\nA common code smell I see is the use of magic numbers.
\nThey are usually easy to spot because they're used to check if numeric some condition applies.
\nThe problem with magic numbers is that they carry no meaning.
\nThe code is harder to reason about, and more error-prone.
\nFixing magic numbers should be straightforward, and one solution is introducing a constant.
\nconst int MaxNumberOfLineItems = 15;\n\npublic void Process(Order? order)\n{\n if (!IsProcessable(order))\n {\n return;\n }\n\n if (order.Items.Count > MaxNumberOfLineItems)\n {\n throw new TooManyLineItemsException(order.Id);\n }\n\n if (order.Status != "ReadyToProcess")\n {\n throw new NotReadyForProcessingException(order.Id);\n }\n\n order.IsProcessed = true;\n}\n\nstatic bool IsProcessable(Order? order)\n{\n return order is not null &&\n order.IsVerified &&\n order.Items.Any();\n}\nSimilar to magic numbers, we have the magic strings code smell.
\nA typical use case for magic strings is to represent some sort of state.
\nYou'll notice that we're comparing the Order.Status value to a magic string to check if the order is ready to process.
A few problems with magic strings:
\nLet's create an OrderStatus enum to represent the possible states:
enum OrderStatus\n{\n Pending = 0,\n ReadyToProcess = 1,\n Processed = 2\n}\nAnd now we have to use the appropriate OrderStatus in the check:
const int MaxNumberOfLineItems = 15;\n\npublic void Process(Order? order)\n{\n if (!IsProcessable(order))\n {\n return;\n }\n\n if (order.Items.Count > MaxNumberOfLineItems)\n {\n throw new TooManyLineItemsException(order.Id);\n }\n\n if (order.Status != OrderStatus.ReadyToProcess)\n {\n throw new NotReadyForProcessingException(order.Id);\n }\n\n order.IsProcessed = true;\n order.Status = OrderStatus.Processed;\n}\n\nstatic bool IsProcessable(Order? order)\n{\n return order is not null &&\n order.IsVerified &&\n order.Items.Any();\n}\nI said I don't prefer using exceptions for flow control. But how can we fix this?
\nOne solution is using the result object pattern.
\nYou can use a generic Result class to represent all types of results or a specific one like ProcessOrderResult.
To make your result objects encapsulated, expose a set of factory methods to create the concrete result type.
\npublic class ProcessOrderResult\n{\n private ProcessOrderResult(\n ProcessOrderResultType type,\n long orderId,\n string message)\n {\n Type = type;\n OrderId = orderId;\n Message = message;\n }\n\n public ProcessOrderResultType Type { get; }\n\n public long OrderId { get; }\n\n public string? Message { get; }\n\n public static ProcessOrderResult NotProcessable() =>\n new(ProcessOrderResultType.NotProcessable, default, "Not processable");\n\n public static ProcessOrderResult TooManyLineItems(long oderId) =>\n new(ProcessOrderResultType.TooManyLineItems, orderId, "Too many items");\n\n public static ProcessOrderResult NotReadyForProcessing(long oderId) =>\n new(ProcessOrderResultType.NotReadyForProcessing, oderId, "Not ready");\n\n public static ProcessOrderResult Success(long oderId) =>\n new(ProcessOrderResultType.Success, oderId, "Success");\n}\nUsing an enum like ProcessOrderResultType will make consuming the result object easier with switch expressions.\nHere's the enum to represent the ProcessOrderResult.Type:
public enum ProcessOrderResultType\n{\n NotProcessable = 0,\n TooManyLineItems = 1,\n NotReadyForProcessing = 2,\n Success = 3\n}\nAnd now the Process method becomes:
const int MaxNumberOfLineItems = 15;\n\npublic ProcessOrderResult Process(Order? order)\n{\n if (!IsProcessable(order))\n {\n return ProcessOrderResult.NotProcessable();\n }\n\n if (order.Items.Count > MaxNumberOfLineItems)\n {\n return ProcessOrderResult.TooManyLineItems(order);\n }\n\n if (order.Status != OrderStatus.ReadyToProcess)\n {\n return ProcessOrderResult.NotReadyForProcessing(order);\n }\n\n order.IsProcessed = true;\n order.Status = OrderStatus.Processed;\n\n return ProcessOrderResult.Success(order);\n}\n\nstatic bool IsProcessable(Order? order)\n{\n return order is not null &&\n order.IsVerified &&\n order.Items.Any();\n}\nHere's how using an enum for the ProcessOrderResult.Type allows you to write a switch expression:
var result = Process(order);\n\nresult.Type switch\n{\n ProcessOrderResultType.TooManyLineItems =>\n Console.WriteLine($"Too many line items: {result.OrderId}"),\n\n ProcessOrderResultType.NotReadyForProcessing =>\n Console.WriteLine($"Not ready for processing {result.OrderId}"),\n\n ProcessOrderResultType.Success =>\n Console.WriteLine($"Processed successfully {result.OrderId}"),\n\n _ => Console.WriteLine("Failed to process: {OrderId}", result.OrderId),\n};\nThat's it, 8 tips to write clean code:
\nWriting clean code is a matter of deliberate practice and experience.
\nMost people will read about clean coding principles, but few will strive to apply them daily.
\nThis is where you can set yourself apart.
\nI also made a video about these clean code tips, you can watch it here.
\nHope this was helpful.
\nSee you next week!
\nToday's action step:\nTake a look at your project and see if you're making some of the mistakes I highlighted here.\nAnd then fix them using the clean code tips I shared with you.
\nAn API gateway is a single entry point that accepts client calls and forwards them to the right microservice.\nYARP is Microsoft's open source reverse proxy library, and you configure its routes and clusters from application settings.\nBecause the gateway is an ASP.NET Core application, you can also apply authentication and rate limiting there.
\nLarge Microservice-based systems can consist of tens or even hundreds of individual services.\nA client application needs to have all of this information to be able to make requests to the relevant microservice directly.
\nHowever, this has numerous issues, such as security concerns, increased complexity, and coupling.
\nWe can solve this by introducing an API gateway that acts as a reverse proxy to accept API calls from the client application and forward them to the appropriate service.
\nThe API gateway also enforces security and ensures scalability and high availability.
\nIn this week's newsletter, I'll show you how to implement an API gateway for your microservices system using the YARP reverse proxy.
\nHere's what we will cover:
\nLet's dive in.
\nA reverse proxy and an API gateway are similar concepts, but they serve different purposes.
\nA reverse proxy acts as an intermediary between clients and servers.\nThe clients can only call the backend servers through the reverse proxy, which forwards the request to the appropriate server.\nIt hides the implementation details of individual servers inside the internal network.
\nA reverse proxy is commonly used for:
\n![\"Reverse](\"https://milanjovanovic.tech/blogs/mnw_045/reverse_proxy.png\")
\nAn API gateway is a specific type of reverse proxy designed for managing APIs.\nIt acts as a single entry point for API consumers to the various backend services.
\nThe key characteristics of an API gateway are:
\nAlso, note that an API gateway can perform load balancing and other functionalities mentioned for reverse proxies.
\nNow let's see how to use a reverse proxy to implement an API gateway.
\nYARP (Yet Another Reverse Proxy) is a library developed by Microsoft to address the needs of various teams needing to build a reverse proxy.\nIt's open source and built with .NET, so it integrates nicely with the existing ecosystem.
\nLet's install Yarp.ReverseProxy NuGet package to get started:
Install-Package Yarp.ReverseProxy\nNext, we're going to call:
\nAddReverseProxy to add the required services for YARPLoadFromConfig to load the reverse proxy configuration from application settingsMapReverseProxy to introduce the reverse proxy middlewarevar builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddReverseProxy()\n .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));\n\nvar app = builder.Build();\n\napp.MapReverseProxy();\n\napp.Run();\nWe need to tell the YARP reverse proxy how to route the incoming requests to the individual microservices.
\nYARP uses the concept of Routes to represent request patterns for the proxy and Clusters to represent the services to forward those requests.
{\n "ReverseProxy": {\n "Routes": {\n ...\n },\n "Clusters": {\n ...\n }\n }\n}\nHere's an example YARP configuration with a {**catch-all} pattern that will route all incoming requests to the one destination server.
{\n "ReverseProxy": {\n "Routes": {\n "ROUTE_NAME": {\n "ClusterId": "CLUSTER_NAME",\n "Match": {\n "Path": "{**catch-all}"\n }\n }\n },\n "Clusters": {\n "CLUSTER_NAME": {\n "Destinations": {\n "destination1": {\n "Address": "https://www.milanjovanovic.tech/"\n }\n }\n }\n }\n }\n}\nWe can use YARP to build an API gateway by providing the configuration for the services we want to route traffic to.
\nI created a sample API gateway implementation with YARP on GitHub, so you can give it a try.\nThe system has two services, the Users.Api and Products.Api, which are .NET 7 applications.
If a request comes in matching the /users-service/{**catch-all}, for example /users-service/users, it will be routed to the users-cluster.\nThe same logic applies for the products-cluster. We can apply more advanced transformations through the Transforms section.
{\n "ReverseProxy": {\n "Routes": {\n "users-route": {\n "ClusterId": "users-cluster",\n "Match": {\n "Path": "/users-service/{**catch-all}"\n },\n "Transforms": [{ "PathPattern": "{**catch-all}" }]\n },\n "products-route": {\n "ClusterId": "products-cluster",\n "Match": {\n "Path": "/products-service/{**catch-all}"\n },\n "Transforms": [{ "PathPattern": "{**catch-all}" }]\n }\n },\n "Clusters": {\n "users-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "https://localhost:5201/"\n }\n }\n },\n "products-cluster": {\n "Destinations": {\n "destination1": {\n "Address": "https://localhost:5101/"\n }\n }\n }\n }\n }\n}\nWe now have a functioning API gateway built with YARP, routing requests to two individual services.
\nBut what else can we do with YARP?
\nThe API gateway can enforce authentication and authorization at the entry point to the system before letting authenticated requests proceed.
\nAnd YARP supports integrating with the existing authentication & authorization middleware.
\nYou first need to define an authorization policy:
\nbuilder.Services.AddAuthorization(options =>\n{\n options.AddPolicy("authenticated", policy =>\n policy.RequireAuthenticatedUser());\n});\nAnd call UseAuthentication and UseAuthorization to add the respective middleware to the request pipeline.\nIt's important to add them before calling MapReverseProxy.
app.UseAuthentication();\n\napp.UseAuthorization();\n\napp.MapReverseProxy();\nNow all you have to do is add the AuthorizationPolicy section to the reverse proxy configuration:
"users-route": {\n "ClusterId": "users-cluster",\n "AuthorizationPolicy": "authenticated",\n "Match": {\n "Path": "/users-service/{**catch-all}"\n },\n "Transforms": [\n { "PathPattern": "{**catch-all}" }\n ]\n}\nYARP will forward most credentials to the proxied services, such as cookies or bearer tokens because it might be important to identify the user in the individual microservices.
\nYou can also use an API gateway to introduce rate limiting to your system.\nIt's a technique to limit the number of requests to your API to improve security and reduce the load on the servers.
\nYou can learn more about how to use rate limiting in .NET here.
\nAs you can already guess, YARP supports the native rate limiting mechanism added in .NET 7.
\nAll you need to do is define a rate limit policy:
\nbuilder.Services.AddRateLimiter(rateLimiterOptions =>\n{\n rateLimiterOptions.AddFixedWindowLimiter("fixed", options =>\n {\n options.Window = TimeSpan.FromSeconds(10);\n options.PermitLimit = 5;\n });\n});\nThen you need to call UseRateLimiter to add the rate limiter middleware to the request pipeline.\nIt's important to do it before calling MapReverseProxy.
app.UseRateLimiter();\n\napp.MapReverseProxy();\nAnd then, you can apply rate limiting to the desired route using the RateLimiterPolicy section in the reverse proxy configuration:
"products-route": {\n "ClusterId": "products-cluster",\n "RateLimiterPolicy": "fixed",\n "Match": {\n "Path": "/products-service/{**catch-all}"\n },\n "Transforms": [\n { "PathPattern": "{**catch-all}" }\n ]\n}\nAn API gateway is a critical component for a robust microservices system implementation.
\nAnd YARP is an excellent option if you want to build an API gateway with .NET.
\nI created a sample API gateway implementation with YARP, which you can find here.\nThe system consists of two APIs, and the API gateway is configured to route requests between them.\nIt also implements:
\n\nIn this newsletter, we only scratched the surface of what's possible with YARP.
\nHere are some useful resources if you want to learn more:
\n\nThat's all for today.
\nHope it was helpful.
\nToday's action step:\nDownload the source code for the sample application implementing an API gateway with YARP, and take it for a spin.\nYou can challenge yourself by creating multiple instances of a single service and configuring load balancing with the various load balancing algorithms.
\nResponse compression in ASP.NET Core takes two method calls: AddResponseCompression to register the services and UseResponseCompression to add the middleware.\nBrotli and Gzip providers are registered by default, and compression is not turned on for HTTPS unless you set EnableForHttps to true.\nIn a test, Brotli reduced a 4.5kB JSON response by roughly 93.5%.
Reducing the size of your API responses can noticeably improve the performance of your application.
\nAnd since network bandwidth is a limited resource, you should at least consider the benefits of response compression.
\nHere's what you'll learn in this week's newsletter:
\nLet's get started!
\nUsing response compression in an .NET applications is remarkably easy.
\nYou only have to call these two methods:
\nAddResponseCompression - to configure the default services for response compressionUseResponseCompression - to add the response compression middleware to the request pipelineThe UseResponseCompression method should be called before any middleware that compresses responses.
Response compression isn't turned on by default for HTTPS, so you have to enable it by setting EnableForHttps to true.
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddResponseCompression(options =>\n{\n options.EnableForHttps = true;\n});\n\nvar app = builder.Build();\n\napp.UseResponseCompression();\n\napp.MapGet("/", () => "This response will be compressed 📦");\n\napp.Run();\nIt really is that simple.
\nBut...
\nIdeally, you want to be using server-based response compression if your application server supports it.
\nBecause the middleware performs response compression at the application level, it will typically have worse performance.
\nIf you are hosting your application and you can't use server-based compression, then using the response compression middleware is justified.
\nOne more concern should be security, because using response compression over HTTPS can expose you to CRIME and BREACH attacks
\nHere's what you can do to improve security:
\nThere are two compression providers added by default when you call AddResponseCompression:
BrotliCompressionProviderGzipCompressionProviderYou can further customize the available providers by adding custom compression providers if you want to.
\nCompression will default to Brotli compression when it's supported by the client.\nOtherwise, it will default to Gzip if that is the supported compression format.
\nbuilder.Services.AddResponseCompression(options =>\n{\n options.EnableForHttps = true;\n options.Providers.Add<BrotliCompressionProvider>();\n options.Providers.Add<GzipCompressionProvider>();\n options.MimeTypes = ResponseCompressionDefaults.MimeTypes;\n});\nThe interesting thing is you can configure the CompressionLevel for the Brotli and Gzip compression providers.
There are four possible values:
\nOptimal - tries to balance response size and compression speedFastest - sacrifices optimal compression for improved speedNoCompression - self explanatorySmallestSize - sacrifices compression speed to make the output as small as possibleThe default value is CompressionLevel.Fastest.
builder.Services.Configure<BrotliCompressionProviderOptions>(options =>\n{\n options.Level = CompressionLevel.Optimal;\n});\n\nbuilder.Services.Configure<GzipCompressionProviderOptions>(options =>\n{\n options.Level = CompressionLevel.SmallestSize;\n});\nLet's find out how much network bandwidth we can save by using response compression.
\nHere's a minimal API endpoint returning a list of Message objects:
app.MapGet("/", () => Results.Ok(\n Enumerable\n .Range(1, 100)\n .Select(num => new Message\n {\n Id = num,\n Content = $"This is the message #{num}"\n })));\nAnd here are the results with different providers and compression levels:
\nCompressionLevel.Fastest - 569BCompressionLevel.SmallestSize - 539BCompressionLevel.Optimal - 554BCompressionLevel.Fastest - 400BCompressionLevel.SmallestSize - 296BCompressionLevel.Optimal - 319BBrotli is the clear winner, which is why it's the default compression provider.
\nIn the best case scenario, you can reduce the response size by ~93.5%.\nMultiply this by the number of requests you're serving daily, and then you can begin to estimate the possible network savings.
\nOne more thing I noticed is that using CompressionLevel.SmallestSize has a noticeable negative impact on response time.\nI can't say this was surprising, so I suggest to simply keep using the default compression level.
Response compression\nis an interesting technique to improve API performance and reduce network costs.
\nIdeally, you'd want to be using server-based response compression if it's supported by your application server.\nIf that's not the case, application-based compression is available in .NET with the response compression middleware.
\nWhat's the cost of response compression?
\nIt will increase the CPU load, and can expose some security risks over HTTPS, but there are ways to mitigate this.
\nIn my experience, the default configuration values for the compression provider and compression level give excellent results.
\nThat's all for this week.
\nSee you next Saturday.
\nToday's action step:\nTo see the value of response compression, I suggest enabling it in your application and examining the changes in response size.\nYou can try the different compression providers by varying the Accept-Encoding header, and also configure different compression levels in your application.
SignalR is the library you will most likely reach for when you need real-time functionality in .NET.\nIt lets you push content from server-side code to any connected clients as changes happen, and it abstracts away the message transport mechanism.\nThe one concept you need to grasp is the Hub class, which manages clients and sends messages.
Today's modern applications must deliver the latest information without refreshing the user interface.
\nIf you need to introduce real-time functionality to your application in .NET, there's one library you will most likely reach for - SignalR.
\nSignalR allows you to push content from your server-side code to any connected clients as changes happen in real-time.
\nHere's what I'll teach you in this week's newsletter:
\nHubLet's see why SignalR is so powerful and how easy it is to build real-time applications with it.
\nTo start using SignalR you'll need to:
\nHub classLet's start by installing the Microsoft.AspNetCore.SignalR.Client NuGet package:
Install-Package Microsoft.AspNetCore.SignalR.Client\nThen you need a SignalR Hub, which is the central component in your application responsible for managing clients and sending messages.
Let's create a NotificationsHub by inheriting from the base Hub class:
public sealed class NotificationsHub : Hub\n{\n public async Task SendNotification(string content)\n {\n await Clients.All.SendAsync("ReceiveNotification", content);\n }\n}\nThe SignalR Hub exposes a few useful properties:
Clients - used to invoke methods on the clients connected to this hubGroups - an abstraction for adding and removing connections from groupsContext - used for accessing information about the hub caller connectionYou can learn more about the Hub class here.
Lastly, you need to register the SignalR services by calling the AddSignalR method.\nYou also need to call the MapHub<T> method, where you specify the NotificationsHub class and the path clients will use to connect to the hub.
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddSignalR();\n\nvar app = builder.Build();\n\napp.MapHub<NotificationsHub>("notifications-hub");\n\napp.Run();\nNow let's see how we can test the NotificationsHub.
To test SignalR, you need a client that will connect to the Hub instance.\nYou could create a simple application with Blazor or JavaScript, but I will show you a different approach.
We will use Postman's WebSocket Request to connect to the NotificationsHub.
![\"Postman](\"https://milanjovanovic.tech/blogs/mnw_043/postman_websocket_request.png\")
\nHere's what we need to do:
\nNotificationsHubNotificationsHub methodsAll messages need to end with a null termination character, which is just the ASCII character 0x1E.
Let's start off by sending this message to set the communication protocol to JSON:
\n{\n "protocol": "json",\n "version": 1\n}?\nYou'll receive this response from the hub.
\n![\"Postman](\"https://milanjovanovic.tech/blogs/mnw_043/postman_set_protocol_request.png\")
\nWe need a slightly different message format to call a message on the Hub.\nThe key is specifying the arguments and target, which is the actual hub method we want to call.
Let's say we want to call the SendNotification method on the NotificationsHub:
{\n "arguments": ["This is the notification message."],\n "target": "SendNotification",\n "type": 1\n}?\nThis will be the response we get back from the NotificationsHub:
![\"Postman](\"https://milanjovanovic.tech/blogs/mnw_043/postman_send_notification_request.png\")
\nThe base Hub class uses the SendAsync method to send messages to connected clients.\nUnfortunately, we have to use strings to specify client-side methods to invoke, and it's easy to make a mistake.\nThere's also nothing enforcing which parameters are used.
SignalR supports strongly typed hubs that aim to solve this.
\nFirst, you need to define a client interface, so let's create a simple INotificationsClient abstraction:
public interface INotificationsClient\n{\n Task ReceiveNotification(string content);\n}\nThe arguments don't have to be primitive types and can also be objects. SignalR will take care of serialization on the client side.
\nAfter that, you need to update the NotificationsHub class to inherit from the Hub<T> class to make it strongly typed:
public sealed class NotificationsHub : Hub<INotificationsClient>\n{\n public async Task SendNotification(string content)\n {\n await Clients.All.ReceiveNotification(content);\n }\n}\nYou will lose access to the SendAsync method, and only the methods defined in your client interface will be available.
HubContextWhat good is a NotificationsHub if we can't send notifications from the backend to connected clients?
\nNot much.
You can use the IHubContext<THub> interface access to the Hub instance in your backend code.
And you can use IHubContext<THub, TClient> for a strongly typed hub.
Here's a simple Minimal API endpoint that injects an IHubContext<NotificationsHub, INotificationsClient> for our strongly typed hub and uses it\nto send a notification to all connected clients:
app.MapPost("notifications/all", async (\n string content,\n IHubContext<NotificationsHub, INotificationsClient> context) =>\n{\n await context.Clients.All.ReceiveNotification(content);\n\n return Results.NoContent();\n});\nThe real value of SignalR is being able to send messages, or notifications in this example, to a specific user.
\nI've seen some complicated implementations that manage a dictionary with a user identifier and a map of active connections.\nWhy would you do that when SignalR already supports this functionality?
\nYou can call the User method and pass it the userId to scope the ReceiveNotification message to that specific user.
app.MapPost("notifications/user", async (\n string userId,\n string content,\n IHubContext<NotificationsHub, INotificationsClient> context) =>\n{\n await context.Clients.User(userId).ReceiveNotification(content);\n\n return Results.NoContent();\n});\nHow does SignalR know which user to send the message to?
\nIt uses the DefaultUserIdProvider internally to extract the user identifier from the claims.\nTo be specific, it's using the ClaimTypes.NameIdentifier claim.\nThis also implies that you should be authenticated when connecting to the Hub, for example, by passing a JWT.
public class DefaultUserIdProvider : IUserIdProvider\n{\n public virtual string? GetUserId(HubConnectionContext connection)\n {\n return connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;\n }\n}\nBy default, all the methods in a hub can be called by unauthenticated users.\nSo you need to decorate it with an Authorize attribute to only allow authenticated clients to access the hub.
[Authorize]\npublic sealed class NotificationsHub : Hub<INotificationsClient>\n{\n public async Task SendNotification(string content)\n {\n await Clients.All.ReceiveNotification(content);\n }\n}\nAdding real-time functionality to your application creates room for innovation and adds value to your users.
\nWith SignalR, you can start building real-time apps in .NET in minutes.
\nYou need to grasp one concept - the Hub class.\nSignalR abstracts away the message transport mechanism, so you don't have to worry about it.
Make sure to send authenticated requests to SignalR hubs and turn on authentication on the Hub.\nSignalR will internally track the users connecting to your hubs, allowing you to send them messages based on the user identifier.
That's all for today.
\nThanks for reading, and have an awesome Saturday.
\nToday's action step:\nLook at your project and try to find an opportunity to add real-time functionality.\nCommit 30 min. to build a simple proof of concept with SignalR and see if it can improve your project.
\nAn anemic domain model has only data properties and no behavior, so business logic ends up scattered across the application.\nA rich domain model fixes that by encapsulating the business logic inside the domain entities themselves.\nThe refactoring is gradual: hide constructors, encapsulate collections, move validation into entity methods, and raise domain events for side effects.
\nIs the anemic domain model an antipattern?
\nIt's a domain model without any behavior and only data properties.
\nAnemic domain models work great in simple applications, but they are difficult to maintain and evolve if you have rich business logic.
\nThe important parts of your business logic and rules end up being scattered all over the application.\nIt reduces cohesiveness and reusability, and makes adding new features more difficult.
\nRich domain model attempts to solve this by encapsulating as much of the business logic as possible.
\nBut how can you design a rich domain model?
\nThis is a never-ending process of moving business logic into the domain and refining your domain model.
\nLet's see how to refactor from an anemic domain model to a rich domain model.
\nTo understand what working with an anemic domain model looks like, I'll use an example of handling a SendInvitationCommand.
I omitted the class and its dependencies so that we can focus on the Handle method.\nIt loads some entities from the database, performs validation, executes the business logic, and finally persists the changes in the database and sends an email.
It already implements some good practices like using repositories and returning result objects.
\nHowever, it's working with an anemic domain model.
\nA few things indicating this:
\nIn other words - the classes representing domain entities contain only data properties and no behavior.
\nThe problems of an anemic domain model are:
\nWe'll apply a few techniques to push logic down into the domain, and try to make the model more domain-driven.\nI hope you'll be able to see the value and benefits this will bring.
\npublic async Task<Result> Handle(SendInvitationCommand command)\n{\n var member = await _memberRepository.GetByIdAsync(command.MemberId);\n\n var gathering = await _gatheringRepository.GetByIdAsync(command.GatheringId);\n\n if (member is null || gathering is null)\n {\n return Result.Failure(Error.NullValue);\n }\n\n if (gathering.Creator.Id == member.Id)\n {\n throw new Exception("Can't send invitation to the creator.");\n }\n\n if (gathering.ScheduledAtUtc < DateTime.UtcNow)\n {\n throw new Exception("Can't send invitation for the past.");\n }\n\n var invitation = new Invitation\n {\n Id = Guid.NewGuid(),\n Member = member,\n Gathering = gathering,\n Status = InvitationStatus.Pending,\n CreatedOnUtc = DateTime.UtcNow\n };\n\n gathering.Invitations.Add(invitation);\n\n _invitationRepository.Add(invitation);\n\n await _unitOfWork.SaveChangesAsync();\n\n await _emailService.SendInvitationSentEmailAsync(member, gathering);\n\n return Result.Success();\n}\nThe goal is to move as much of the business logic as possible into the domain.
\nLet's start with the Invitation entity and defining a constructor for it.\nI can simplify the design by setting the Status and CreatedOnUtc properties inside the constructor.\nI'm also going to make it internal so that an Invitation instance can only be created within the domain.
public sealed class Invitation\n{\n internal Invitation(Guid id, Gathering gathering, Member member)\n {\n Id = id;\n Member = member;\n Gathering = gathering;\n Status = InvitationStatus.Pending;\n CreatedOnUtc = DateTime.Now;\n }\n\n // Data properties omitted for brevity.\n}\nThe reason I made the Invitation constructor internal is so that I can introduce a new method on the Gathering entity.\nLet's call it SendInvitation and it will be responsible for instantiating a new Invitation instance and adding it to the internal collection.
Currently, the Gathering.Invitations collection is public, which means anyone can obtain a reference and modify the collection.
We don't want to allow this, so what we can do is encapsulate this collection behind a private field.\nThis moves the responsibility for managing the _invitations collection to the Gathering class.
Here's how the Gathering class looks like now:
public sealed class Gathering\n{\n private readonly List<Invitation> _invitations;\n\n // Other members omitted for brevity.\n\n public void SendInvitation(Member member)\n {\n var invitation = new Invitation(Guid.NewGuid(), gathering, member);\n\n _invitations.Add(invitation);\n }\n}\nThe next thing we can do is move the validation rules into the SendInvitation method, further enriching the domain model.
Unfortunately, this is still a bad practice because of throwing "expected" exceptions when a validation fails.\nIf you want to use exceptions to enforce your validation rules you should at least do it right, and use specific exceptions instead of generic ones.
\nBut it would be even better to use a result object to express validation errors.
\npublic sealed class Gathering\n{\n // Other members omitted for brevity.\n\n public void SendInvitation(Member member)\n {\n if (gathering.Creator.Id == member.Id)\n {\n throw new Exception("Can't send invitation to the creator.");\n }\n\n if (gathering.ScheduledAtUtc < DateTime.UtcNow)\n {\n throw new Exception("Can't send invitation for the past.");\n }\n\n var invitation = new Invitation(Guid.NewGuid(), gathering, member);\n\n _invitations.Add(invitation);\n }\n}\nHere's how using result objects would look like:
\npublic sealed class Gathering\n{\n // Other members omitted for brevity.\n\n public Result SendInvitation(Member member)\n {\n if (gathering.Creator.Id == member.Id)\n {\n return Result.Failure(DomainErrors.Gathering.InvitingCreator);\n }\n\n if (gathering.ScheduledAtUtc < DateTime.UtcNow)\n {\n return Result.Failure(DomainErrors.Gathering.AlreadyPassed);\n }\n\n var invitation = new Invitation(Guid.NewGuid(), gathering, member);\n\n _invitations.Add(invitation);\n\n return Result.Success();\n }\n}\nThe benefit of this approach is we can introduce constants for possible domain errors.\nThe catalog of domain errors will act as documentation for your domain, and make it more expressive.
\nFinally, here's how the Handle method looks like with all the changes so far:
public async Task<Result> Handle(SendInvitationCommand command)\n{\n var member = await _memberRepository.GetByIdAsync(command.MemberId);\n\n var gathering = await _gatheringRepository.GetByIdAsync(command.GatheringId);\n\n if (member is null || gathering is null)\n {\n return Result.Failure(Error.NullValue);\n }\n\n var result = gathering.SendInvitation(member);\n\n if (result.IsFailure)\n {\n return Result.Failure(result.Errors);\n }\n\n await _unitOfWork.SaveChangesAsync();\n\n await _emailService.SendInvitationSentEmailAsync(member, gathering);\n\n return Result.Success();\n}\nIf you take a closer look at the Handle method you'll notice it's doing two things:
This means it's not atomic.
\nThere's a potential for the database transaction to complete, and the email sending to fail.\nAlso, sending the email will slow down the method which could affect performance.
\nHow can make this method atomic?
\nBy sending the email in the background. It's not important for our business logic, so this is safe to do.
\nYou can use domain events to express that something occurred in your domain that might be interesting to other components in your system.
\nI often use domain events to trigger actions in the background, like sending a notification or email.
\nLet's introduce an InvitationSentDomainEvent:
public record InvitationSentDomainEvent(Invitation Invitation) : IDomainEvent;\nWe're going to raise this domain event inside the SendInvitation method:
public sealed class Gathering\n{\n private readonly List<Invitation> _invitations;\n\n // Other members omitted for brevity.\n\n public Result SendInvitation(Member member)\n {\n if (gathering.Creator.Id == member.Id)\n {\n return Result.Failure(DomainErrors.Gathering.InvitingCreator);\n }\n\n if (gathering.ScheduledAtUtc < DateTime.UtcNow)\n {\n return Result.Failure(DomainErrors.Gathering.AlreadyPassed);\n }\n\n var invitation = new Invitation(Guid.NewGuid(), gathering, member);\n\n _invitations.Add(invitation);\n\n Raise(new InvitationSentDomainEvent(invitation));\n\n return Result.Success();\n }\n}\nThe goal is to remove the code responsible for sending the email from the Handle method:
public async Task<Result> Handle(SendInvitationCommand command)\n{\n var member = await _memberRepository.GetByIdAsync(command.MemberId);\n\n var gathering = await _gatheringRepository.GetByIdAsync(command.GatheringId);\n\n if (member is null || gathering is null)\n {\n return Result.Failure(Error.NullValue);\n }\n\n var result = gathering.SendInvitation(member);\n\n if (result.IsFailure)\n {\n return Result.Failure(result.Errors);\n }\n\n await _unitOfWork.SaveChangesAsync();\n\n return Result.Success();\n}\nWe only want to worry about executing the business logic and persisting any changes to the database.\nPart of those changes will also be the domain event, which the system will publish in the background.
\nOf course, we need a respective handler for the domain event:
\npublic sealed class InvitationSentDomainEventHandler\n : IDomainEventHandler<InvitationSentDomainEvent>\n{\n private readonly IEmailService _emailService;\n\n public InvitationSentDomainEventHandler(IEmailService emailService)\n {\n _emailService = emailService;\n }\n\n public async Task Handle(InvitationSentDomainEvent domainEvent)\n {\n await _emailService.SendInvitationSentEmailAsync(\n domainEvent.Invitation.Member,\n domainEvent.Invitation.Gathering);\n }\n}\nWe achieved two things:
\nSendInvitationCommand is now atomicDesigning a rich domain model is a gradual process, and you can slowly evolve the domain model over time.
\nThe first step could be making your domain model more defensive:
\ninternal keywordThe benefit is your domain models will have a fine-grained public API (methods) which act as an entry point for executing the business logic.
\nIt's easy to test behavior when it's encapsulated in a class without having to mock external dependencies.
\nYou can raise domain events to notify the system that something of important occurred, and any interested components can subscribe to that domain event.\nDomain events allow you to develop a decoupled system, where you focus on the core domain logic, and don't have to worry about the side effects.
\nHowever, this doesn't mean that every system needs a rich domain model.
\nYou should be pragmatic and decide when the complexity is worth it.
\nThat's all for this week.
\nSee you next Saturday.
\nThe right way to use HttpClient in .NET is to avoid creating an instance per request (port exhaustion) and to avoid a naive singleton (stale DNS).\nLet IHttpClientFactory manage the lifetime for you, or reuse a single instance with a configured PooledConnectionLifetime.\nThis issue covers named clients, typed clients, and when to use each option.
If you're building a .NET application, chances are high that you'll need to call an external API over HTTP.
\nThe easy way to make HTTP requests in .NET is to use the HttpClient to send those requests.\nAnd it's a great abstraction to work with, especially with the methods supporting JSON payloads and responses.
Unfortunately, it's easy to misuse the HttpClient.
Port exhaustion and DNS behavior are some of the most common problems.
\nSo here's what you need to know about working with HttpClient:
HttpClientIHttpClientFactoryLet's dive in!
\nHttpClient is the primary class in .NET for sending HTTP requests and receiving HTTP responses from a URI.\nIt lives in the System.Net.Http namespace and is included in the .NET runtime (you don't need extra packages).
You can use it to call REST APIs, download files, or communicate with any HTTP-based service.\nIt supports all standard HTTP methods (GET, POST, PUT, DELETE, PATCH) and has built-in support for JSON\nthrough extension methods like GetFromJsonAsync and PostAsJsonAsync.
While HttpClient is easy to get started with, it's also easy to misuse.\nThe most common mistakes are creating too many instances (causing port exhaustion) and holding on to instances for too long (causing stale DNS responses).\nThe rest of this article covers the right patterns for working with HttpClient in .NET.
The simplest way to work with the HttpClient is to just create a new instance, set the required properties and use it to send requests.
What could possibly go wrong?
\nHttpClient instances are meant to be long-lived, and reused throughout the lifetime of the application.
Each instance uses its own connection pool for isolation purposes, but also to prevent port exhaustion.\nIf a server is under high load, and your application is constantly creating new connections, it could lead to exhausting the available ports.\nThis will cause an exception at runtime, when trying to send a request.
\nSo how can you avoid this?
\npublic class GitHubService\n{\n private readonly GitHubSettings _settings;\n\n public GitHubService(IOptions<GitHubSettings> settings)\n {\n _settings = settings.Value;\n }\n\n public async Task<GitHubUser?> GetUserAsync(string username)\n {\n using var client = new HttpClient();\n\n client.DefaultRequestHeaders.Add("Authorization", _settings.GitHubToken);\n client.DefaultRequestHeaders.Add("User-Agent", _settings.UserAgent);\n client.BaseAddress = new Uri("https://api.github.com");\n\n GitHubUser? user = await client\n .GetFromJsonAsync<GitHubUser>($"users/{username}");\n\n return user;\n }\n}\nInstead of managing the HttpClient lifetime yourself, you can use an IHttpClientFactory to create the HttpClient instance.
Simply call the CreateClient method and use the returned HttpClient instance to send your HTTP requests.
Why is this a better approach?
\nThe expensive part of the HttpClient is the actual message handler - HttpMessageHandler.\nEach HttpMessageHandler has an internal HTTP connection pool that can be reused.
The IHttpClientFactory will cache the HttpMessageHandler and reuse it when creating a new HttpClient instance.
An important note here is that HttpClient instances created by IHttpClientFactory are meant to be short-lived.
public class GitHubService\n{\n private readonly GitHubSettings _settings;\n private readonly IHttpClientFactory _factory;\n\n public GitHubService(\n IOptions<GitHubSettings> settings,\n IHttpClientFactory factory)\n {\n _settings = settings.Value;\n _factory = factory;\n }\n\n public async Task<GitHubUser?> GetUserAsync(string username)\n {\n using var client = _factory.CreateClient();\n\n client.DefaultRequestHeaders.Add("Authorization", _settings.GitHubToken);\n client.DefaultRequestHeaders.Add("User-Agent", _settings.UserAgent);\n client.BaseAddress = new Uri("https://api.github.com");\n\n GitHubUser? user = await client\n .GetFromJsonAsync<GitHubUser>($"users/{username}");\n\n return user;\n }\n}\nUsing IHttpClientFactory will solve most of the issues of manually creating an HttpClient.\nHowever, we still need to configure the default request parameters every time we obtain a new HttpClient from the CreateClient method.
You can configure a named client by calling the AddHttpClient method and passing in the desired name.\nThe AddHttpClient accepts a delegate that you can use to configure the default parameters on the HttpClient instance.
services.AddHttpClient("github", (serviceProvider, client) =>\n{\n var settings = serviceProvider\n .GetRequiredService<IOptions<GitHubSettings>>().Value;\n\n client.DefaultRequestHeaders.Add("Authorization", settings.GitHubToken);\n client.DefaultRequestHeaders.Add("User-Agent", settings.UserAgent);\n\n client.BaseAddress = new Uri("https://api.github.com");\n});\nThe main difference is you now have to obtain the client by passing the name of the client to CreateClient.
But the use of the HttpClient looks a lot simpler:
public class GitHubService\n{\n private readonly IHttpClientFactory _factory;\n\n public GitHubService(IHttpClientFactory factory)\n {\n _factory = factory;\n }\n\n public async Task<GitHubUser?> GetUserAsync(string username)\n {\n using var client = _factory.CreateClient("github");\n\n GitHubUser? user = await client\n .GetFromJsonAsync<GitHubUser>($"users/{username}");\n\n return user;\n }\n}\nThe downside of using named clients is having to resolve an HttpClient by passing in a name every time.
There's a better way to achieve the same behavior by configuring a typed client.\nYou can do this by calling the AddClient<TClient> method and configuring the service that will consume the HttpClient.
Under the hood, this is still using a named client, where the name is the same as the type name.
\nAnd this will also register GitHubService with a transient lifetime.
services.AddHttpClient<GitHubService>((serviceProvider, client) =>\n{\n var settings = serviceProvider\n .GetRequiredService<IOptions<GitHubSettings>>().Value;\n\n client.DefaultRequestHeaders.Add("Authorization", settings.GitHubToken);\n client.DefaultRequestHeaders.Add("User-Agent", settings.UserAgent);\n\n client.BaseAddress = new Uri("https://api.github.com");\n});\nInside of GitHubService, you inject and use the typed HttpClient instance which will have all of the configuration applied.
No more dealing with IHttpClientFactory and creating HttpClient instances manually.
public class GitHubService\n{\n private readonly HttpClient client;\n\n public GitHubService(HttpClient client)\n {\n _client = client;\n }\n\n public async Task<GitHubUser?> GetUserAsync(string username)\n {\n GitHubUser? user = await client\n .GetFromJsonAsync<GitHubUser>($"users/{username}");\n\n return user;\n }\n}\nYou could run into a problem if you inject a typed client into a singleton service.\nSince the typed client is transient, injecting it in a singleton service will cause it to be cached for the lifetime of the singleton service.
\nThis will prevent the typed client from reacting to DNS changes.
\nIf you want to use a typed client in a singleton service, the recommened approach is using SocketsHttpHandler as the primary handler,\nand configuring the PooledConnectionLifetime.
Since the SocketsHttpHandler will handle connection pooling, you can disable recycling at the IHttpClientFactory level by setting HandlerLifetime to Timeout.InfiniteTimeSpan.
services.AddHttpClient<GitHubService>((serviceProvider, client) =>\n{\n var settings = serviceProvider\n .GetRequiredService<IOptions<GitHubSettings>>().Value;\n\n client.DefaultRequestHeaders.Add("Authorization", settings.GitHubToken);\n client.DefaultRequestHeaders.Add("User-Agent", settings.UserAgent);\n\n client.BaseAddress = new Uri("https://api.github.com");\n})\n.ConfigurePrimaryHttpMessageHandler(() =>\n{\n return new SocketsHttpHandler()\n {\n PooledConnectionLifetime = TimeSpan.FromMinutes(15)\n };\n})\n.SetHandlerLifetime(Timeout.InfiniteTimeSpan);\nUnder the hood, every HttpClient uses an HttpMessageHandler to manage TCP connections.\n.NET has two primary handler implementations worth knowing.
HttpClientHandler is the traditional handler, available since .NET Framework.\nOn modern .NET runtimes it internally delegates to SocketsHttpHandler.\nIt exposes familiar properties for cookies, automatic decompression, and proxy configuration.
SocketsHttpHandler is the fully managed, cross-platform handler that debuted in .NET Core 2.1 and is now the default on all current .NET runtimes.\nUnlike HttpClientHandler, it exposes PooledConnectionLifetime and PooledConnectionIdleTimeout,\ngiving you direct control over how long connections stay in the pool before being recycled.\nThis is exactly what makes SocketsHttpHandler valuable when using a typed HttpClient in a singleton service, as\nyou can ensure DNS changes are picked up without relying on IHttpClientFactory handler recycling.
For most applications using IHttpClientFactory, you don't need to choose explicitly.\nConfigure SocketsHttpHandler directly only when you need fine-grained control over connection-pool behavior.\nYou wire it up with ConfigurePrimaryHttpMessageHandler when registering the client:
builder.Services\n .AddHttpClient<MyService>()\n .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler\n {\n PooledConnectionLifetime = TimeSpan.FromMinutes(2)\n });\nI showed you a few possible options for working with HttpClient.
But which one should you use and when?
\nMicrosoft was kind enough to provide us with a set of best practices and recommended use\nfor HttpClient.
static or singleton HttpClient instance with a PooledConnectionLifetime configured, since this solves both port exhaustion and tracking DNS changesIHttpClientFactory if you want to move the configuration to one place, but remember that clients are meant to be short-livedIHttpClientFactory configurabilityI prefer working with a typed client, and I'm mindful of the fact that it's configured as a transient service.
\nThanks for reading, and have an awesome Saturday.
\nQuartz.NET is an open source job scheduling system for .NET that runs recurring background work.\nIt has three concepts: the job you want to run, the trigger controlling when it runs, and the scheduler coordinating them.\nYou install Quartz.Extensions.Hosting, implement IJob, and register a trigger with a simple schedule or a cron expression.
If you're building a scalable application, it's a common requirement to offload some work in your application to a background job.
\nHere are a few examples of that:
\nHow can you create a recurring background job in .NET?
\nQuartz.NET is a full-featured, open source job scheduling system that can be used from smallest apps to large scale enterprise systems.
\nThere are three concepts you need to understand in Quartz.NET:
\nLet's see how we can use Quartz.NET to create and schedule background jobs.
\nThe first thing we need to do is install the Quartz.NET NuGet package.\nThere are a few to pick from, but we're going to install the Quartz.Extensions.Hosting library:
Install-Package Quartz.Extensions.Hosting\nThe reason we're using this library is because it integrates nicely with .NET using an IHostedService instance.
To get the Quartz.NET hosted service up and running, we need two things:
\nservices.AddQuartz(configure =>\n{\n configure.UseMicrosoftDependencyInjectionJobFactory();\n});\n\nservices.AddQuartzHostedService(options =>\n{\n options.WaitForJobsToComplete = true;\n});\nQuartz.NET will create jobs by fetching them from the DI container.\nThis also means you can use scoped services in your jobs, not just singleton or transient services.
\nSetting the WaitForJobsToComplete option to true will ensure that Quartz.NET waits for the jobs to complete gracefully before exiting.
IJobTo crate a background job with Quartz.NET you need to implement the IJob interface.
It only exposes a single method - Execute - where you can place the code for your background job.
A few things worth noting here:
\nApplicationDbContext and IPublisher servicesDisallowConcurrentExecution to prevent running the same job concurrently[DisallowConcurrentExecution]\npublic class ProcessOutboxMessagesJob : IJob\n{\n private readonly ApplicationDbContext _dbContext;\n private readonly IPublisher _publisher;\n\n public ProcessOutboxMessagesJob(\n ApplicationDbContext dbContext,\n IPublisher publisher)\n {\n _dbContext = dbContext;\n _publisher = publisher;\n }\n\n public async Task Execute(IJobExecutionContext context)\n {\n List<OutboxMessage> messages = await _dbContext\n .Set<OutboxMessage>()\n .Where(m => m.ProcessedOnUtc == null)\n .Take(20)\n .ToListAsync(context.CancellationToken);\n\n foreach (OutboxMessage outboxMessage in messages)\n {\n IDomainEvent? domainEvent = JsonConvert\n .DeserializeObject<IDomainEvent>(\n outboxMessage.Content,\n new JsonSerializerSettings\n {\n TypeNameHandling = TypeNameHandling.All\n });\n\n if (domainEvent is null)\n {\n continue;\n }\n\n await _publisher.Publish(domainEvent, context.CancellationToken);\n\n outboxMessage.ProcessedOnUtc = DateTime.UtcNow;\n\n await _dbContext.SaveChangesAsync();\n }\n }\n}\nNow that the background job is ready, we need to register it with the DI container and add a trigger that will run the job.
\nI mentioned at the start that there are three key concepts in Quartz.NET:
\nWe already implemented the ProcessOutboxMessagesJob background job in the previous section.
The Quartz.NET library will take care of the scheduler.
\nAnd this leaves us with configuring the trigger for our ProcessOutboxMessagesJob.
services.AddQuartz(configure =>\n{\n var jobKey = new JobKey(nameof(ProcessOutboxMessagesJob));\n\n configure\n .AddJob<ProcessOutboxMessagesJob>(jobKey)\n .AddTrigger(\n trigger => trigger.ForJob(jobKey).WithSimpleSchedule(\n schedule => schedule.WithIntervalInSeconds(10).RepeatForever()));\n\n configure.UseMicrosoftDependencyInjectionJobFactory();\n});\nWe need to uniquely identify our background job with a JobKey.\nI like to keep it simple and use the job name.
Calling AddJob will register the ProcessOutboxMessagesJob with DI and also with Quartz.
After that we configure a trigger for this job by calling AddTrigger.\nYou need to associate the job with the trigger by calling ForJob, and then you configure the schedule for the background job.\nIn this example, I'm scheduling the job to run every ten seconds and repeat forever while the hosted service is running.
Quartz also has support for configuring triggers using cron expressions.
\nBy default, Quartz configures all jobs using the RAMJobStore which is the most performant because it keeps all of its data in RAM.\nHowever, this also means it's volatile and you can lose all scheduling information when your application stops or crashes.
It could be useful to have a persistent job store in some scenarios and there's a built in AdoJobStore which works with SQL databases.\nYou need to create a set of database tables for Quartz.NET to use.
You can learn more about this in the job stores documentation.
\nQuartz.NET makes running background jobs in .NET easy, and you can use all the power of DI in your background jobs.\nIt's also flexible for various scheduling requirements with configuration via code or using cron expressions.
\nThere's some room for improvement to make scheduling jobs easier and reduce boilerplate:
\nIf you want to see a tutorial on using Quartz.NET, I made an in-depth video about using Quartz for processing Outbox messages.
\nThat's all for this week.
\nSee you next Saturday.
\nA GitHub Actions workflow builds, tests, and deploys a .NET application on every push to main.\nThe build job checks out the code, sets up the .NET SDK, then runs dotnet restore, dotnet build, and dotnet test.\nThe deployment job adds a dotnet publish step and the azure/webapps-deploy action to ship the output to Azure App Service.
Do you want to streamline your software development process and accelerate your release cycles?
\nImagine being able to automatically build, test, and deploy your .NET applications with every code change.
\nWith CI/CD, you can significantly reduce manual effort and focus more on creating software, ensuring faster and more reliable releases.
\nAnd it's never been easier to get started with CI/CD.
\nGitHub Actions are completely free and simple to use.
\nSo here's what we'll cover:
\nLet's dive in.
\nI'll try to briefly explain what CI/CD is, before we take a look at GitHub Actions.
\nCI/CD is a method to increase the frequency of delivering new features by adding automation to your software development workflow.
\nContinuous Integration ("CI") refers to the automation process of syncing new code to a repository.\nAny new changes to the application code are immediately built, tested and merged.
\nContinuous Delivery, or Deployment, ("CD") refers to the process of automating the deployment part of the workflow.\nWhen you make a change which gets merged to the repository, this step takes care of deploying those changes to the production environment (or any other environment).
\nIf you're using GitHub, getting started with Continuous Integration has never been easier.
\nYou can use GitHub Actions to automate your build, test, and deployment pipeline.\nYou can create workflows that build and test every commit to your repository, or deploy to production when a new tag is created.
\nTo create a GitHub Action, you write a workflow to be triggered when some event occurs in your repository.\nAn example event is a commit to the main branch, creation of a tag, or you can manually run the workflow.
\nHere's a GitHub Actions workflow to build and test a .NET project:
\nname: Build & Test 🧪\n\non:\n push:\n branches:\n - main\n\nenv:\n DOTNET_VERSION: '7.0.x'\n\njobs:\n build:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Setup .NET 📦\n uses: actions/setup-dotnet@v3\n with:\n dotnet-version: ${{ env.DOTNET_VERSION }}\n\n - name: Install dependencies 📂\n run: dotnet restore WebApi\n\n - name: Build 🧱\n run: dotnet build WebApi --configuration Release --no-restore\n\n - name: Test 🧪\n run: dotnet test WebApi --configuration Release --no-build\nLet's unwrap what is happening here:
\nenv.DOTNET_VERSIONdotnet CLI toolYou can add this to your GitHub repository today, and start getting instant feedback when you commit code to the repository.
\nWhen a workflow run fails due to a build error or a failed test, you'll get an email notification.
\nContinuous Integration is a great way to start out with CI/CD, but the real value lies in automating your deployment process.
\nImagine this:
\nUsually it's a little more nuanced, because we need to think about configuration, database migrations, etc.\nBut try to see the big picture here.
\nIf you're running your application in the cloud, for example on Azure, chances are there's an existing GitHub Action you can use.
\nHere's a deployment pipeline I use to publish my application to an Azure App Service instance:
\nname: Publish 🚀\n\non:\n push:\n branches:\n - main\n\nenv:\n AZURE_WEBAPP_NAME: web-api\n AZURE_WEBAPP_PACKAGE_PATH: './publish'\n DOTNET_VERSION: '7.0.x'\n\njobs:\n build:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v3\n\n - name: Setup .NET 📦\n uses: actions/setup-dotnet@v3\n with:\n dotnet-version: ${{ env.DOTNET_VERSION }}\n\n - name: Build and Publish 📂\n run: |\n dotnet restore WebApi\n dotnet build WebApi -c Release --no-restore\n dotnet publish WebApi -c Release --no-build\n --output '${{ env.AZURE_WEBAPP_PACKAGE_PATH }}'\n\n - name: Deploy to Azure 🌌\n uses: azure/webapps-deploy@v2\n with:\n app-name: ${{ env.AZURE_WEBAPP_NAME }}\n publish-profile: ${{ secrets.AZURE_PUBLISH_PROFILE }}\n package: '${{ env.AZURE_WEBAPP_PACKAGE_PATH }}'\nThis workflow is pretty similar to the previous one, with the differences being:
\nazure/webapps-deploy@v2 action to deploy to AzureIf you need to safely and securely expose secret values in your workflows, you can use GitHub secrets.\nYou can define the secrets on GitHub, and use them in actions without having to add them to source control.
\nIn the deployment workflow I'm using secrets.AZURE_PUBLISH_PROFILE to access my publish profile for the App Service instance.
Continuous Integration and Delivery can transform your development process by increasing the speed at which you release changes.
\nTry adding up how much time you spend on deployments.\nI'm pretty sure you'll be surprised by the time savings potential of automating them.
\nAnd the good part is you will typically set up your build and deployment pipelines once, and then continue benefiting from them for the lifetime of your project.
\nIf you want a step by step guide, I made a video showing how to implement a CI/CD pipeline from scratch.\nAnd the source code is also public, so you can add the GitHub Actions workflow file to your project.
\nThanks for reading.
\nHope that was helpful!
\nA multi-tenant application serves many customers from one deployment while keeping each tenant's data isolated.\nYou get there with a single database and logical isolation, or a database per tenant and physical isolation.\nIn EF Core, a global query filter on a TenantId column applies the tenant filter to every query for you.
Most software applications today are built around the concept of multi-tenancy.
\nOne application serves multiple customers, while keeping their data isolated.
\nYou can approach multi-tenancy in two ways:
\nWhich option you decide to use will depend mostly on your requirements.\nSome industries like healthcare require a high degree of data isolation, and using a database per tenant is a must.
\nSo how are we going to implement multi-tenancy support with EF Core?
\nWe can use Query Filters to apply a tenant filter to all database queries.
\nImplement it once and you can almost forget about it.
\nLet's see what are some of the problems we need to solve.
\nIf you want an in-depth dive into Query filters, take a look at the newsletter issue where I talked about\nusing query filters with EF Core.
\nHere's a quick refresher on Query filters:
\nHasQueryFilter for your entityIgnoreQueryFiltersAnd here's a simple example:
\nmodelBuilder\n .Entity<Order>()\n .HasQueryFilter(order => !order.IsDeleted);\nAll queries to the Order table will include an IsDeleted = FALSE condition.
You will need two things to implement multi-tenancy on a single database:
\nThe typical approach for multi-tenancy on a single database is having a TenantId column in your tables.\nAnd then filtering on that column when querying the database.
You can use the Query filters feature in EF Core to apply a global filter for some entity.
\nInside of the OnModelCreating method we configure the query filter on the Order entity:
public class OrdersDbContext : DbContext\n{\n private readonly string _tenantId;\n\n public OrdersDbContext(\n DbContextOptions<OrdersDbContext> options,\n TenantProvider tenantProvider)\n : base(options)\n {\n _tenantId = tenantProvider.TenantId;\n }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder\n .Entity<Order>\n .HasQueryFilter(o => o.TenantId == _tenantId);\n }\n}\nWe're using the TenantProvider class to get the current tenant value.
Here's what the TenantProvider implementation looks like:
public sealed class TenantProvider\n{\n private const string TenantIdHeaderName = "X-TenantId";\n\n private readonly IHttpContextAccessor _httpContextAccessor;\n\n public TenantProvider(IHttpContextAccessor httpContextAccessor)\n {\n _httpContextAccessor = httpContextAccessor;\n }\n\n public string TenantId => _httpContextAccessor\n .HttpContext\n .Request\n .Headers[TenantIdHeaderName];\n}\nThe TenantId is coming from the HTTP request header in this example.
A few other options to get the TenantId are:
api/orders?tenantId=example-tenant-idIf you want a more secure implementation you should go with JWT Claims or API Keys to provide the TenantId value.
What if we want to isolate each tenant to a separate database?
\nHere are the changes we need to make:
\nYou can't use Query filters here, since we are working with different databases.
\nSo you will need to store the tenant information and connection strings somewhere.
\nA simple example would be store them in the application settings:
\n"Tenants": {\n { "Id": "tenant-1", "ConnectionString": "Host=tenant1.db;Database=tenant1" },\n { "Id": "tenant-2", "ConnectionString": "Host=tenant2.db;Database=tenant2" }\n}\nYou can then register an IOptions instance with a list of Tenant objects.
And we need to slightly modify the TenantProvider class to return a connection string for the current tenant:
public sealed class TenantProvider\n{\n private const string TenantIdHeaderName = "X-TenantId";\n\n private readonly IHttpContextAccessor _httpContextAccessor;\n private readonly TenantSettings _tenantSettings;\n\n public TenantProvider(\n IHttpContextAccessor httpContextAccessor,\n IOptions<TenantSettings> tenantsOptions)\n {\n _httpContextAccessor = httpContextAccessor;\n _tenants = tenantsOptions.Value;\n }\n\n public string TenantId => _httpContextAccessor\n .HttpContext\n .Request\n .Headers[TenantIdHeaderName];\n\n public string GetConnectionString()\n {\n return _tenantSettings.Tenants.Single(t => t.Id == TenantId);\n }\n}\nAnd the last part is registering your DbContext to dynamically resolve the connection string for the current tenant.
builder.Services.AddDbContext<OrdersDbContext>((sp, o) =>\n{\n var tenantProvider = sp.GetRequiredService<TenantProvider>();\n\n var connectionString = tenantProvider.GetConnectionString();\n\n o.UseSqlServer(connectionString);\n});\nOn every request, we create a new OrdersDbContext and connect to the appropriate database for that tenant.
You should definitely consider storing the tenant connection strings in a secure place like Azure Key Vault.
\nI hope you now have a better understanding of how to build a multi-tenant system with EF Core.
\nI showed you the bare bones implementation, which you can improve to make it more robust and secure.
\nBuilding multi-tenant systems isn't easy, but when you understand the basic principles it shouldn't be too difficult either.
\nThat's all for this week.
\nSee you next Saturday.
\nThe C4 model is a lightweight way to describe software architecture, and C4 stands for context, containers, components, and code.\nIt gives you four abstractions (person, software system, container, component) and four diagram types that zoom in from the system as a whole down to the code.
\nSoftware architecture diagrams are a great way to communicate how you are planning to build a software system or how an existing software system works.
\nHowever, the majority of software architecture diagrams I've seen are a total mess.
\nIf only there was a standard way to visualize your software architecture...
\nEnter the C4 model, which stands for context, containers, components, and code.
\nThe C4 model is a lightweight approach to describing your software architecture.
\nAnd it's essentially just two things, a predefined set of common abstractions and four diagram types:
\nLet's see how we can use the C4 model to visualize our software architecture.
\nBefore we dive into the C4 diagrams, we first need to understand the ubiquitous language of the C4 model.
\n\n\nA software system is made up of one or more containers (applications and data stores),\neach of which contains one or more components, which in turn are implemented by one or more code elements (classes, interfaces, objects, functions, etc).\nAnd people may use the software systems that we build.
\n
The C4 model defines a set of abstractions that you can use to describe your software systems:
\nWith these high-level concepts in place, let's take a look at how to use them in our C4 diagrams.
\nThe System Context diagram is a high-level view of your software system.
\nIt shows your software system as the central part, and any external systems and users that your system interacts with.
\nIt should be technology agnostic, and the focus on the people and software systems instead of low-level details.
\n![\"C4](\"https://milanjovanovic.tech/blogs/mnw_037/system_context_diagram.jpg\")
\nThe intended audience for the System Context Diagram is everybody.
\nIf you can show it to non-technical people and they are able to understand it, then you know you're on the right track.
\nWhen you zoom into one software system, you get to the Container diagram.
\nYour software system is comprised of multiple running parts - containers.
\nA container can be a:
\nYou can look at a container as a deployment unit that executes code or stores data.
\nThe Container diagram shows the high-level view of the software architecture and the major technology choices.
\n![\"C4](\"https://milanjovanovic.tech/blogs/mnw_037/container_diagram.jpg\")
\nThe Container diagram is intended for technical people inside and outside of the software development team:
\nNext you can zoom into an individual container to decompose it into its building blocks.
\nThe Component diagram show the individual components that make up a container:
\n![\"C4](\"https://milanjovanovic.tech/blogs/mnw_037/component_diagram.jpg\")
\nThe Component diagram is intended for software architects and developers.
\nFinally, you can zoom into each component to show how it is implemented with code, typically using a UML class diagram or an ER diagram.
\nThis level is rarely used as it goes into too much technical detail for most use cases.
\nHowever, there are supplementary diagrams that can be useful to fill in missing information by showcasing:
\nIt's only recommended for the most important or complex components.
\nOf course, the target audience are software architects and developers.
\nThe C4 model is a tool for visual and verbal communication, enabling your team to talk in the same language and have a common understanding of the design.
\nIt's valuable for many reasons, to name a few:
\nNow that you understand what the C4 model is, there's one question left to answer.
\nShould you use the C4 model to express your software architecture?
\nI can't give you a definitive answer.
\nI used it with a lot of success.
\nBut I think you should at least give it a try.
\nYou can learn more about the C4 model here.
\nThank you for reading, and have an awesome Saturday.
\nYou enforce software architecture by asserting its rules in an automated test.\nWith the NetArchTest.Rules library you load a set of types from an assembly, filter them, then apply a condition with Should or ShouldNot.\nThat catches a broken dependency direction or a naming convention violation without a manual code review.
Software architecture is a blueprint for how you should structure your system.\nYou can follow this blueprint strictly, or you can give yourself varying levels of freedom.
\nBut when deadlines are tight, and you start cutting corners, that beautiful software architecture you built crumbles like a house of cards.
\nHow can you enforce your software architecture?
\nBy writing architecture tests.
\nArchitecture tests are automated tests that verify the structure and design of your code.
\nYou can use them to enforce your software architecture and the direction of dependencies of your projects.
\nIn this week's issue I'll explain how to:
\nLet's dive in!
\nYou write architecture tests the same as any unit test in your application.\nThere's an excellent library for writing architecture tests that already implements the boilerplate code we need to start writing tests.
\nWe're going to use the NetArchTest.Rules library for writing architecture tests.
First, you have to install the NuGet package:
\nInstall-Package NetArchTest.Rules\nAnd now you can use it to write rules in your test project.
\nThe starting point for writing architecture tests is the static Types class, which you can use to load a set of types.
Once you have loaded your types you can further filter them to find a more specific set of types.
\nSome of the available filtering methods:
\nResideInNamespaceAreClassesAreInterfacesHaveNameStartingWithHaveNameEndingWithFinally, when you are satisfied with your selection, you can write the rule you want to enforce by calling Should or ShouldNot\nand applying the condition you want to check.
Here's an example checking that all classes in the domain assembly are sealed:
\nvar result = Types\n .InAssembly(DomainAssembly)\n .That()\n .AreClasses()\n .Should()\n .BeSealed()\n .GetResult();\n\nAssert.True(result.IsSuccessful);\nArchitecture tests are particularly useful to enforce software architecture rules in a layered architecture or Modular Monolith.
\nLet's take the example of the Clean architecture:
\nHere's how you can write tests for enforcing architecture rules.
\nDomain should not have any dependencies
\nvar result = Types\n .InAssembly(DomainAssembly)\n .ShouldNot()\n .HaveDependencyOnAny("Application", "Infrastructure")\n .GetResult();\n\nAssert.True(result.IsSuccessful);\nApplication should not depend on Infrastructure
\nvar result = Types\n .InAssembly(AplicationAssembly)\n .Should()\n .NotHaveDependencyOn("Infrastructure")\n .GetResult();\n\nAssert.True(result.IsSuccessful);\nInfrastructure should depend on Application and Domain
\nHow the NetArchTest.Rules library works is by scanning the imported namespaces of your types.
Because of this, writing negative conditions like in the previous two examples is straightforward.
\nBut writing positive conditions has to be scoped to a more specific set of types.
\nFor example, we can validate this dependency by checking that all repositories must have a dependency on the Domain namespace.
var result = Types\n .InAssembly(InfrastructureAssembly)\n .HaveNameEndingWith("Repository")\n .Should()\n .HaveDependencyOn("Domain")\n .GetResult();\n\nAssert.True(result.IsSuccessful);\nAnother valuable use case for architecture tests is enforcing design rules in your application.
\nDesign rules are more specific than project references, and focus on the implementation details of your classes.
\nHere are some design rules that you can enforce:
\nThe possibilities are endless, and it's up to you how many design rules you want to enforce.
\nHere's how you can write tests for enforcing design rules.
\nCommand handlers must end with CommandHandler
var result = Types\n .InAssembly(ApplicationAssembly)\n .That()\n .ImplementInterface(typeof(ICommandHandler))\n .Should()\n .HaveNameEndingWith("CommandHandler")\n .GetResult();\n\nAssert.True(result.IsSuccessful);\nControllers can't directly reference repositories
\nvar result = Types\n .InAssembly(ApiAssembly)\n .That()\n .HaveNameEndingWith("Controller")\n .ShouldNot()\n .HaveDependencyOn("Infrastructure.Repositories")\n .GetResult();\n\nAssert.True(result.IsSuccessful);\nArchitecture tests are an easy way to enforce software architecture and design rules with automated tests.
\nOne of the best investments you can make as a software engineer is writing automated tests.\nYou write the tests once, and use them to verify your system forever.\nGranted, you also have to maintain the tests over time as your system grows.
\nManually enforcing software architecture with pair programming and constant PR reviews is:
\nArchitecture tests really shine here, since you can write them quickly and reduce the cost of enforcing your software architecture rules to zero.
\nThanks for reading.
\nHope that was helpful!
\nASP.NET Core has built-in support for health checks.\nRegister the services with AddHealthChecks and expose an endpoint with MapHealthChecks("/health"), and each check reports Healthy, Degraded, or Unhealthy.\nYou can write a custom check by implementing IHealthCheck, or install a ready-made package from the AspNetCore.Diagnostics.HealthChecks repository.
We all want to build robust and reliable applications that can scale indefinitely and handle any number of requests.
\nBut with distributed systems and microservices architectures growing in complexity, it's becoming increasingly harder to monitor the health of our applications.
\nIt's vital that you have a system in place to receive quick feedback of your application health.
\nThat's where health checks come in.
\nHealth checks provide a way to monitor and verify the health of various components of an application including:
\nHere's what I'll show you in this week's newsletter:
\nLet's see how to implement health checks in ASP.NET Core.
\nHealth checks are a proactive mechanism for monitoring and verifying the health and availability of an application in ASP.NET Core.
\nASP.NET Core has built-in support for implementing health checks.
\nHere's the basic configuration, which registers the health check services and adds the HealthCheckMiddleware to respond at the specified URL.
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Services.AddHealthChecks();\n\nvar app = builder.Build();\n\napp.MapHealthChecks("/health");\n\napp.Run();\nThe health check returns a HealthStatus value indicating the health of the service.
There are three distinct HealthStatus values:
HealthStatus.HealthyHealthStatus.DegradedHealthStatus.UnhealthyYou can use the HealthStatus to indicate the different states of your application.
For example, if the application is functioning slower than expected you can return HealthStatus.Degraded.
You can create custom health checks by implementing the IHealthCheck interface.
For example, you can implement a check to see if your SQL database is available.
\nIt's important to use a query that can complete quickly in the database, like SELECT 1.
Here's a custom health check implementation example in the SqlHealthCheck class:
public class SqlHealthCheck : IHealthCheck\n{\n private readonly string _connectionString;\n\n public SqlHealthCheck(IConfiguration configuration)\n {\n _connectionString = configuration.GetConnectionString("Database");\n }\n\n public async Task<HealthCheckResult> CheckHealthAsync(\n HealthCheckContext context,\n CancellationToken cancellationToken = default)\n {\n try\n {\n using var sqlConnection = new SqlConnection(_connectionString);\n\n await sqlConnection.OpenAsync(cancellationToken);\n\n using var command = sqlConnection.CreateCommand();\n command.CommandText = "SELECT 1";\n\n await command.ExecuteScalarAsync(cancellationToken);\n\n return HealthCheckResult.Healthy();\n }\n catch(Exception ex)\n {\n return HealthCheckResult.Unhealthy(\n context.Registration.FailureStatus,\n exception: ex);\n }\n }\n}\nAfter you implement the custom health check, you need to register it.
\nThe previous call to AddHealthChecks now becomes:
builder.Services.AddHealthChecks()\n .AddCheck<SqlHealthCheck>("custom-sql", HealthStatus.Unhealthy);\nWe're giving it a custom name and setting which status to use as the failure result in HealthCheckContext.Registration.FailureStatus.
But stop and think for a moment.
\nDo you want to implement a custom health check on your own for every external service that you have?
\nOf course not! There's a better solution.
\nBefore you start implementing a custom health check for everything, you should first see if there's already an existing library.
\nIn the AspNetCore.Diagnostics.HealthChecks repository you can find\na wide collection health check packages for frequently used services and libraries.
Here are just a few examples:
\nAspNetCore.HealthChecks.SqlServerAspNetCore.HealthChecks.NpgsqlAspNetCore.HealthChecks.RedisAspNetCore.HealthChecks.RabbitMQAspNetCore.HealthChecks.Aws.S3AspNetCore.HealthChecks.SignalRHere's how to add health checks for PostgreSQL and RabbitMQ:
\nbuilder.Services.AddHealthChecks()\n .AddCheck<SqlHealthCheck>("custom-sql", HealthStatus.Unhealthy);\n .AddNpgSql(pgConnectionString)\n .AddRabbitMQ(rabbitConnectionString)\nBy default, the endpoint returning you health check status will return a string value representing a HealthStatus.
This isn't practical if you have multiple health checks configured, as you'd want to view the health status individually per service.
\nTo make matters worse, if one of the services is failing the entire response will return Unhealthy and you don't know what's causing the issue.
You can solve this by providing a ResponsWriter, and there's an existing one in the AspNetCore.HealthChecks.UI.Client library.
Let's install the NuGet package:
\nInstall-Package AspNetCore.HealthChecks.UI.Client\nAnd you need to slightly update the call to MapHealthChecks to use the ResponseWriter coming from this library:
app.MapHealthChecks(\n "/health",\n new HealthCheckOptions\n {\n ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse\n });\nAfter making these changes, here's what the response from the health check endpoint looks like:
\n{\n "status": "Unhealthy",\n "totalDuration": "00:00:00.3285211",\n "entries": {\n "npgsql": {\n "data": {},\n "duration": "00:00:00.1183517",\n "status": "Healthy",\n "tags": []\n },\n "rabbitmq": {\n "data": {},\n "duration": "00:00:00.1189561",\n "status": "Healthy",\n "tags": []\n },\n "custom-sql": {\n "data": {},\n "description": "Unable to connect to the database.",\n "duration": "00:00:00.2431813",\n "exception": "Unable to connect to the database.",\n "status": "Unhealthy",\n "tags": []\n }\n }\n}\nApplication monitoring is important to track availability, resource usage, and changes to performance in your application.
\nI've used health checks before to implement failover scenarios in a cloud deployment.\nWhen one application instance stops responding with a healthy result, a new one is created to continue serving requests.
\nIt's easy to monitor the health of your ASP.NET Core applications by exposing health checks for your services.
\nYou can decide to implement custom health checks, but first consider if there are existing solutions.
\nThank you for reading, and have an awesome Saturday.
\nThe Idempotent Consumer pattern prevents a message from being processed more than once.\nWhen a message arrives, the consumer checks if its unique identifier was already processed.\nIf it was, the duplicate is ignored; otherwise, the consumer handles the message and stores the identifier in a database table.
\nWhat happens when a message is retried in an event-driven system?
\nIt happens more often than you think.
\nThe worst case scenario is that the message is processed twice, and the side effects can also be applied more than once.
\nDo you want your bank account to be double charged?
\nI'll assume the answer is no, of course.
\nYou can use the Idempotent Consumer pattern to solve this problem.
\nIn this week's issue I will show you:
\nLet's see why the Idempotent Consumer pattern is valuable.
\nWhat's the idea behind the Idempotent Consumer pattern?
\n\n\nAn idempotent operation is one that has no additional effect if it is called more than once with the same input parameters.
\n
We want to avoid handling the same message more than once.
\nThis would require Exactly-once message delivery guarantees from our messaging system.\nAnd this is a really hard problem to solve in distributed systems.
\nA looser delivery guarantee is At-least-once, where we are aware that retries can happen and we can receive the same message more than once.
\nThe Idempotent Consumer pattern works well with At-least-once message delivery, and solves the problem of duplicate messages.
\nHere's what the algorithm looks like from the moment we receive a message:
\n![\"Idempotent](\"https://milanjovanovic.tech/blogs/mnw_034/idempotent_consumer_algorithm.png\")
\nWe need a unique identifier for every message we receive, and a table in the database to store processed messages.
\nHowever, it's interesting how we choose the implement the message handling and storing of the processed message identifier.
\nYou can implement the idempotent consumer as a decorator around a regular message handler.
\nI'll show you two implementations:
\nThe lazy idempotent consumer matches the flow shown in the algorithm above.
\nLazy refers to how we store the message identifer to mark it as processed.
\nIn the happy path, we handle the message and store the message identifier.
\nIf the message handler throws an exception, we never store the message identifier and the consumer can be executed again.
\nHere's what the implementation looks like:
\npublic class IdempotentConsumer<T> : IHandleMessages<T>\n where T : IMessage\n{\n private readonly IMessageRepository _messageRepository;\n private readonly IHandleMessages<T> _decorated;\n\n public IdempotentConsumer(\n IMessageRepository messageRepository,\n IHandleMessages<T> decorated)\n {\n _messageRepository = messageRepository;\n _decorated = decorated;\n }\n\n public async Task Handle(T message)\n {\n if (_messageRepository.IsProcessed(message.Id))\n {\n return;\n }\n\n await _decorated.Handle(message);\n\n _messageRepository.Store(message.Id);\n }\n}\nThe eager idempotent consumer is slightly different from the lazy implementation, but the end result is the same.
\nIn this version, we eagerly store the message identifier in the database and then continue to handle the message.
\nIf the handler throws an exception, we need to perform cleanup in the database and remove the eagerly stored message identifier.
\nOtherwise, we risk leaving the system in an inconsistent state since the message was never handled correctly.
\nHere's what the implementation looks like:
\npublic class IdempotentConsumer<T> : IHandleMessages<T>\n where T : IMessage\n{\n private readonly IMessageRepository _messageRepository;\n private readonly IHandleMessages<T> _decorated;\n\n public IdempotentConsumer(\n IMessageRepository messageRepository,\n IHandleMessages<T> decorated)\n {\n _messageRepository = messageRepository;\n _decorated = decorated;\n }\n\n public async Task Handle(T message)\n {\n try\n {\n if (_messageRepository.IsProcessed(message.Id))\n {\n return;\n }\n\n _messageRepository.Store(message.Id);\n\n await _decorated.Handle(message);\n }\n catch (Exception e)\n {\n _messageRepository.Remove(message.Id);\n\n throw;\n }\n }\n}\nIdempotency is an interesting problem to solve in a software system.
\nSome operations are naturally idempotent, and we don't need the overhead of the Idempotent Consumer pattern.
\nHowever, for those operations that aren't naturally idempotent, the Idempotent Consumer is a great solution.
\nThe high-level algorithm is simple, and you can take two approaches in the implementation:
\nI prefer to use the lazy approach, and only store the message identifier in the database when the handler completes successfully.
\nIt's easier to reason about and there is one less call to the database.
\nThanks for reading.
\nHope that was helpful.
\nEF Core supports raw SQL queries.\nEF7 added support for queries returning scalar types, and EF8 added the SqlQuery and SqlQueryRaw methods for querying unmapped types that are not part of the EF model.\nSqlQuery parameterizes interpolated values, which protects against SQL injection.
EF Core is getting many new and exciting features in the upcoming version.
\nEF7 introduced support for returning scalar types using SQL queries.
\nAnd now we're getting support for querying unmapped types with raw SQL queries in EF8.
\nThis is exactly what Dapper offers out of the box, and it's good to see EF Core catching up.
\nIn this week's newsletter, I'm going to cover how to use EF Core for:
\n\nLet's dive in!
\nEF7 added support for raw SQL queries returning scalar types.\nEF8 is taking this a step further with raw SQL queries that can return any mappable type, without having to include it in the EF model.
\nYou can query unmapped types with the SqlQuery and SqlQueryRaw methods.
The SqlQuery method uses string interpolation to parameterize the query, protecting against SQL injection attacks.
Here's an example query returning an OrderSummary list:
var startDate = new DateOnly(2023, 1, 1);\n\nvar ordersIn2023 = await dbContext\n .Database\n .SqlQuery<OrderSummary>(\n $"SELECT * FROM OrderSummaries AS o WHERE o.CreatedOn >= {startDate}")\n .ToListAsync();\nThis will be the SQL sent to the database:
\nSELECT * FROM OrderSummaries AS o WHERE o.CreatedOn >= @p0\nThe type used for the query result can have a parameterized constructor.\nThe property names don't need to match the column names in the database, but they do have to match the names of the values in the result set.
\nYou can also execute raw SQL queries and return results with:
\nAn interesting thing about SqlQuery is that it returns IQueryable, which can be further composed with LINQ.
You can add a Where statement after calling SqlQuery:
var startDate = new DateOnly(2023, 1, 1);\n\nvar ordersIn2023 = await dbContext\n .Database\n .SqlQuery<OrderSummary>("SELECT * FROM OrderSummaries AS o")\n .Where(o => o.CreatedOn >= startDate)\n .ToListAsync();\nHowever, the generated SQL isn't optimal:
\nSELECT s.Id, s.CustomerId, s.TotalPrice, s.CreatedOn\nFROM (\n SELECT * FROM OrderSummaries AS o\n) AS s\nWHERE s.CreatedOn >= @p0\nAnother possibility is to combine an OrderBy statement with Skip and Take:
var startDate = new DateOnly(2023, 1, 1);\n\nvar ordersIn2023 = await dbContext\n .Database\n .SqlQuery<OrderSummary>(\n $"SELECT * FROM OrderSummaries AS o WHERE o.CreatedOn >= {startDate}")\n .OrderBy(o => o.Id)\n .Skip(10)\n .Take(5)\n .ToListAsync();\nThis would be the generated SQL for the previous query:
\nSELECT s.Id, s.CustomerId, s.TotalPrice, s.CreatedOn\nFROM (\n SELECT * FROM OrderSummaries AS o WHERE o.CreatedOn >= @p0\n) AS s\nORDER BY s.Id\nOFFSET @p1 ROWS FETCH NEXT @p2 ROWS ONLY\nIn case you're wondering, the performance is similar to LINQ queries using Select projections.
I ran some benchmarks, and didn't notice any significant performance improvement.
\nThis feature will be very useful if you're more comfortable with writing SQL or you want to fetch data from views, functions, and stored procedures.
\nIf you want to modify data in the database with SQL, you will typically write a query that doesn't return a result.
\nThe SQL query can be an UPDATE or DELETE statement, or even a stored procedure call.
You can use the ExecuteSql method to execute this type of query with EF Core:
var startDate = new DateOnly(2023, 1, 1);\n\ndbContext.Database.ExecuteSql(\n $"UPDATE Orders SET Status = 5 WHERE CreatedOn >= {startDate}");\nExecuteSql also protects from SQL injection by parameterizing arguments, just like SqlQuery.
With EF7 you can write the above query with LINQ and the ExecuteUpdate method.\nThere's also the ExecuteDelete method for deleting records.
EF7 introduced support for raw SQL queries returning scalar values.
\nEF8 will add support for raw SQL queries returning unmapped types with SqlQuery and SqlQueryRaw.
I like the direction that EF is going, introducing more flexibility for querying the database.
\nThe performance isn't as good as Dapper, unfortunately.\nBut it's close enough that network costs will play the bigger factor.
\nI will probably be using only EF moving forward since it covers more use cases.
\nThank you for reading, and have an awesome Saturday.
\nASP.NET Core 7 introduced built-in rate limiting middleware in the Microsoft.AspNetCore.RateLimiting namespace.\nYou register policies with AddRateLimiter, apply the middleware with app.UseRateLimiter, and attach a policy using the EnableRateLimiting attribute on controllers or RequireRateLimiting on Minimal API endpoints.
Rate limiting is a technique to limit the number of requests to a server or an API.
\nA limit is introduced within a given time period to prevent server overload and protect against abuse.
\nIn ASP.NET Core 7, we have a built-in rate limiter middleware that's easy to integrate into your API.
\nWe're going to cover four rate limiter algorithms:
\n\nLet's see how we can work with rate limiting.
\nRate limiting is about restricting the number of requests to an API, usually within a specific time window or based on other criteria.
\nThis is practical for a few reasons:
\nIn a multi-tenant application, each unique user can have a limitation on the number of API requests.
\nASP.NET Core 7 introduced built-in rate limiting middleware in the Microsoft.AspNetCore.RateLimiting namespace.
To add rate limiting to your application, you first need to register the rate limiting services:
\nbuilder.Services.AddRateLimiter(options =>\n{\n options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;\n\n // We'll talk about adding specific rate limiting policies later.\n});\nI suggest updating the RejectionStatusCode to 429 (Too Many Requests) because it's more correct.\nThe default value is 503 (Service Unavailable).
And you also have to apply the RateLimitingMiddleware:
app.UseRateLimiter();\nThat's everything you'll need.
\nLet's see the rate limiting algorithms we can use.
\nThe AddFixedWindowLimiter method configures a fixed window limiter.
The Window value determines the time window.
When a time window expires, a new one starts, and the request limit is reset.
\nbuilder.Services.AddRateLimiter(rateLimiterOptions =>\n{\n rateLimiterOptions.AddFixedWindowLimiter("fixed", options =>\n {\n options.PermitLimit = 10;\n options.Window = TimeSpan.FromSeconds(10);\n options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;\n options.QueueLimit = 5;\n });\n});\nThe sliding window algorithm is similar to the fixed window, but it introduces segments in a window.
\nHere's how it works:
\nThe AddSlidingWindowLimiter method configures a sliding window limiter.
builder.Services.AddRateLimiter(rateLimiterOptions =>\n{\n rateLimiterOptions.AddSlidingWindowLimiter("sliding", options =>\n {\n options.PermitLimit = 10;\n options.Window = TimeSpan.FromSeconds(10);\n options.SegmentsPerWindow = 2;\n options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;\n options.QueueLimit = 5;\n });\n});\nThe token bucket algorithm is similar to the sliding window, but instead of adding back the requests from the expired segment,\na fixed number of tokens are added after each replenishment period.
\nThe total number of tokens can never exceed the token limit.
\nThe AddTokenBucketLimiter method configures a token bucket limiter.
builder.Services.AddRateLimiter(rateLimiterOptions =>\n{\n rateLimiterOptions.AddTokenBucketLimiter("token", options =>\n {\n options.TokenLimit = 100;\n options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;\n options.QueueLimit = 5;\n options.ReplenishmentPeriod = TimeSpan.FromSeconds(10);\n options.TokensPerPeriod = 20;\n options.AutoReplenishment = true;\n });\n});\nWhen AutoReplenishment is true, an internal timer will execute every ReplenishmentPeriod and replenish the tokens.
The concurrency limiter is the most straightforward algorithm, and it just limits the number of concurrent requests.
\nThe AddConcurrencyLimiter method configures a concurrency limiter.
builder.Services.AddRateLimiter(rateLimiterOptions =>\n{\n rateLimiterOptions.AddConcurrencyLimiter("concurrency", options =>\n {\n options.PermitLimit = 10;\n options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;\n options.QueueLimit = 5;\n });\n});\nThere's no time component involved in this case. The only parameter is the number of concurrent requests.
\nNow that we have configured our rate limiting policies, let's see how we can use them in our API.
\nThere are slight differences between controllers and minimal API endpoints, so I'll cover them in separate examples.
\nControllers
\nTo add rate limiting on a controller we use the EnableRateLimiting and DisableRateLimiting attributes.
EnableRateLimiting can be applied on the controller or on the individual endpoints.
[EnableRateLimiting("fixed")]\npublic class TransactionsController\n{\n private readonly ISender _sender;\n\n public TransactionsController(ISender sender)\n {\n _sender = sender;\n }\n\n [EnableRateLimiting("sliding")]\n public async Task<IActionResult> GetTransactions()\n {\n return Ok(await _sender.Send(new GetTransactionsQuery()));\n }\n\n [DisableRateLimiting]\n public async Task<IActionResult> GetTransactionById(int id)\n {\n return Ok(await _sender.Send(new GetTransactionByIdQuery(id)));\n }\n}\nIn the previous example:
\nTransactionsController will use a fixed window policyGetTransactions endpoint will use a sliding window policyGetTransactionById endpoint won't have any rate limiting appliedMinimal APIs
\nIn a Minimal API endpoint you can configure the rate limit policy by calling RequireRateLimiting and specifying the policy name.
We're using the token bucket policy in this example.
\napp.MapGet("/transactions", async (ISender sender) =>\n{\n return Results.Ok(await sender.Send(new GetTransactionsQuery()));\n})\n.RequireRateLimiting("token");\nIt's great that we can quickly introduce rate limiting in ASP.NET Core.
\nYou can choose from one of the existing rate limiter algorithms:
\nHere are some resources if you want to learn more about rate limiting:
\n\nI'm excited to try out rate limiting in my projects.
\nThat's all for today.
\nHave an awesome Saturday!
\nA Saga is a sequence of local transactions, where each local transaction updates the Saga state and publishes a message that triggers the next step.\nYou can implement an orchestrated Saga in .NET with Rebus, a free service bus: define the state with ISagaData, inherit from the Saga base class, configure correlation, and use RabbitMQ as the message transport.
Designing long-lived processes in a distributed environment is an interesting engineering challenge.
\nAnd a well known pattern for solving this problem is a Saga.
\nA Saga is a sequence of local transactions, where each local transaction updates the Saga state and publishes a message triggering the next step in the Saga.
\nSagas come in two forms:
\nWith an orchestrated Saga, there's a central component responsible for orchestrating the individual steps.
\nIn a choreographed Saga, processes work independently but coordinate with each other using events.
\nIn this week's issue, I'll show you how to create an orchestrated Saga using the Rebus library with RabbitMQ for message transport.
\nLet's dive in.
\nRebus is a free .NET "service bus", and it's practical for implementing asynchronous messaging-based\ncommunication between the components of an application.
\nLet's install the following libraries:
\nRebus.ServiceProvider for managing the Rebus instanceRebus.RabbitMq for RabbitMQ message transportRebus.SqlServer for SQL Server state persistenceInstall-Package Rebus.ServiceProvider -Version 8.4.0\nInstall-Package Rebus.RabbitMq -Version 8.0.0\nInstall-Package Rebus.SqlServer -Version 7.3.1\nInside of your ASP.NET Core application you will need the following configuration.
\nservices.AddRebus(\n rebus => rebus\n .Routing(r =>\n r.TypeBased().MapAssemblyOf<Program>("newsletter-queue"))\n .Transport(t =>\n t.UseRabbitMq(\n configuration.GetConnectionString("RabbitMq"),\n inputQueueName: "newsletter-queue"))\n .Sagas(s =>\n s.StoreInSqlServer(\n configuration.GetConnectionString("SqlServer"),\n dataTableName: "Sagas",\n indexTableName: "SagaIndexes"))\n .Timeouts(t =>\n t.StoreInSqlServer(\n builder.Configuration.GetConnectionString("SqlServer"),\n tableName: "Timeouts"))\n);\n\nservices.AutoRegisterHandlersFromAssemblyOf<Program>();\nUnpacking the individual configuration steps:
\nRouting - Configures messages to be routed by their typeTransport - Configures the message transport mechanismSagas - Configures the Saga persistence storeTimeouts - Configures the timeouts persistence storeYou also need to specify the queue name for sending and receiving messages.
\nAutoRegisterHandlersFromAssemblyOf will scan the specified assembly and automatically register the respective message handlers.
We're going to create a Saga for a newsletter onboarding process.
\nWhen a user subscribes to the newsletter we want to:
\nThe first step in creating the Saga is defining the data model by implementing ISagaData.\nWe'll keep it simple and store the Email for correlation, and add two flags for the distinct steps in our Saga.
public class NewsletterOnboardingSagaData : ISagaData\n{\n public Guid Id { get; set; }\n public int Revision { get; set; }\n\n public string Email { get; set; }\n\n public bool WelcomeEmailSent { get; set; }\n\n public bool FollowUpEmailSent { get; set; }\n}\nNow we can define the NewsletterOnboardingSaga class by inheriting from the Saga class and implementing the CorrelateMessages method.
It's a best practice to use a unique value for correlation.\nIn our case this will be the Email.
You also configure how the Saga starts with IAmInitiatedBy, and the individual messages the Saga handles with IHandleMessages.
public class NewsletterOnboardingSaga :\n Saga<NewsletterOnboardingSagaData>,\n IAmInitiatedBy<SubscribeToNewsletter>,\n IHandleMessages<WelcomeEmailSent>,\n IHandleMessages<FollowUpEmailSent>\n{\n private readonly IBus _bus;\n\n public NewsletterOnboardingSaga(IBus bus)\n {\n _bus = bus;\n }\n\n protected override void CorrelateMessages(\n ICorrelationConfig<NewsletterOnboardingSagaData> config)\n {\n config.Correlate<SubscribeToNewsletter>(m => m.Email, d => d.Email);\n\n config.Correlate<WelcomeEmailSent>(m => m.Email, d => d.Email);\n\n config.Correlate<FollowUpEmailSent>(m => m.Email, d => d.Email);\n }\n\n /* Handlers omitted for brevity */\n}\nThere are two types of messages you send in a Saga:
\nCommands instruct the receiving component what to do.
\nThink: verb, imperative.
Events notify the Saga which process was just completed.
\nThink: what happened, past tense.
The NewsletterOnboardingSaga starts by handling the SubscribeToNewsletter command, and publishes a SendWelcomeEmail command.
public async Task Handle(SubscribeToNewsletter message)\n{\n if (!IsNew)\n {\n return;\n }\n\n await _bus.Send(new SendWelcomeEmail(message.Email));\n}\nThe SendWelcomeEmail command is handled by a different component, which publishes a WelcomeEmailSent event when it completes.
In the WelcomeEmailSent handler we update the Saga state and publish a deferred message by calling Defer.\nRebus will persist the SendFollowUpEmail command, and publish it when the timeout expires.
public async Task Handle(WelcomeEmailSent message)\n{\n Data.WelcomeEmailSent = true;\n\n await _bus.Defer(TimeSpan.FromDays(3), new SendFollowUpEmail(message.Email));\n}\nFinally, the SendFollowUpEmail command is handled and we publish the FollowUpEmailSent event.
We update the Saga state again, and also call MarkAsComplete to complete the Saga.
public Task Handle(FollowUpEmailSent message)\n{\n Data.FollowUpEmailSent = true;\n\n MarkAsComplete();\n\n return Task.CompletedTask;\n}\nCompleting the Saga will delete it from the database.
Here's how the SendWelcomeEmail command handler looks like.
public class SendWelcomeEmailHandler : IHandleMessages<SendWelcomeEmail>\n{\n private readonly IEmailService _emailService;\n private readonly IBus _bus;\n\n public SendWelcomeEmailHandler(IEmailService emailService, IBus bus)\n {\n _emailService = emailService;\n _bus = bus;\n }\n\n public async Task Handle(SendWelcomeEmail message)\n {\n await _emailService.SendWelcomeEmailAsync(message.Email);\n\n await _bus.Reply(new WelcomeEmailSent(message.Email));\n }\n}\nThe important thing to highlight here is that we're using the Reply method to send a message back.\nThis will reply back to the endpoint specified as the return address on the current message.
Sagas are practical for implementing a long-lived process in a distributed system.\nEach business process is represented by a local transaction, and publishes a message to trigger the next step in the Saga.
\nAlthough Sagas are very powerful, they are also complicated to develop, maintain and debug.
\nWe didn't cover a few important topics in this newsletter:
\nI think you'll have some fun researching these on your own.
\nTake a look at the source code for the example used in this newsletter\nif you want to learn more about implementing Sagas.
\nIf you have Docker installed, you should be able to run it without a problem and try it out.
\nThank you for reading, and have an awesome Saturday.
\nMediatR v12 added the INotificationPublisher interface, which controls how notification handlers are invoked.\nThe default ForeachAwaitPublisher awaits each handler one by one.\nSwap in TaskWhenAllPublisher through AddMediatR, and the handlers run together with Task.WhenAll, but they still share one service scope.
MediatR is a popular library with a simple mediator pattern implementation in .NET.
\nHere's a definiton taken from MediatR's GitHub: "In-process messaging with no dependencies."
\nWith the rise in popularity of the CQRS pattern, MediatR became the go-to library to implement commands and queries.
\nHowever, MediatR also has support for the publish-subscribe pattern using notifications.\nYou can publish an INotification instance and have multiple subscribers handle the published message.
Until recently, the handlers subscribing to an INotification message could only execute serially, one by one.
In this week's newsletter, I'll show you how to configure MediatR to execute the handlers in parallel.
\nLet's dive in.
\nBefore I talk about notification publishing strategies, let's see how publish-subscribe works with MediatR.
\nYou need a class implementing the INotification interface:
public record OrderCreated(Guid OrderId) : INotification;\nThen you need a respective INotificationHandler implementation:
public class OrderCreatedHandler : INotificationHandler<OrderCreated>\n{\n private readonly INotificationService _notificationService;\n\n public OrderCreatedHandler(INotificationService notificationService)\n {\n _notificationService = notificationService;\n }\n\n public async Task Handle(\n OrderCreated notification,\n CancellationToken cancellationToken)\n {\n await _notificationService.SendOrderCreatedEmail(\n notification.OrderId,\n cancellationToken);\n }\n}\nAnd then you simply publish a message using either IMediator or IPublisher.\nI prefer using the IPublisher because it's more expressive:
await publisher.Publish(new OrderCreated(order.Id), cancellationToken);\nMediatR will invoke all the respective handlers.
\nBefore MediatR v12, the publishing strategy would invoke each handler individually.
\nHowever, there's a new interface INotificationPublisher controlling how the handlers are called.
The default implementation of this interface is ForeachAwaitPublisher:
public class ForeachAwaitPublisher : INotificationPublisher\n{\n public async Task Publish(\n IEnumerable<NotificationHandlerExecutor> handlerExecutors,\n INotification notification,\n CancellationToken cancellationToken)\n {\n foreach (var handler in handlerExecutors)\n {\n await handler\n .HandlerCallback(notification, cancellationToken)\n .ConfigureAwait(false);\n }\n }\n}\nBut now you can also use the TaskWhenAllPublisher:
public class TaskWhenAllPublisher : INotificationPublisher\n{\n public Task Publish(\n IEnumerable<NotificationHandlerExecutor> handlerExecutors,\n INotification notification,\n CancellationToken cancellationToken)\n {\n var tasks = handlerExecutors\n .Select(handler => handler.HandlerCallback(\n notification,\n cancellationToken))\n .ToArray();\n\n return Task.WhenAll(tasks);\n }\n}\nHere's a comparison between these two strategies.
\nForeachAwaitPublisher:
TaskWhenAllPublisher:
If you store the task returned by TaskWhenAllPublisher you can access the Task.Exception property, which will contain an AggregateException instance.\nYou can then implement more robust exception handling.
How do we configure which INotificationPublisher strategy MediatR will use?
There's a new way to apply configuration options when calling the AddMediatR method.
You supply an Action<MediatRServiceConfiguration> delegate and configure the MediatRServiceConfiguration instance.
If you want to use the TaskWhenAllPublisher strategy, you can either:
NotificationPublisher propertyNotificationPublisherType propertyservices.AddMediatR(config => {\n config.RegisterServicesFromAssemblyContaining<Program>();\n\n // Setting the publisher directly will make the instance a Singleton.\n config.NotificationPublisher = new TaskWhenAllPublisher();\n\n // Seting the publisher type will:\n // 1. Override the value set on NotificationPublisher\n // 2. Use the service lifetime from the ServiceLifetime property below\n config.NotificationPublisherType = typeof(TaskWhenAllPublisher);\n\n config.ServiceLifetime = ServiceLifetime.Transient;\n});\nYou can also implement a custom INotificationPublisher instance and use your own implementation instead.
Being able to run notification handlers in parallel provides a significant performance improvement over the default behavior.
\nHowever, note that all handlers will use the same service scope.
\nIf you have service instances that don't support concurrent access you may run into problems.
\nUnfortunately, one such service instance is the EF Core DbContext.
In any case, I think this is a great addition to the already amazing MediatR library.
\nThat's all for today.
\nSee you next week.
\nxUnit gives you four ways to feed data into a parameterized test: InlineData, MemberData, ClassData, and TheoryData.\nInlineData takes constant values in the attribute, and the other three load the data from a member or a class.\nTheoryData is the one that gives you type safety, since MemberData and ClassData both hand back untyped object[].
Data-driven testing is a testing method where test data is provided through some external source.\nHence it's also known as parameterized testing.
\nA popular testing library in .NET that supports parameterized testing is xUnit.\nIt uses attributes to define test methods.\nThe Fact attribute defines a simple test, and the Theory attribute defines a parameterized test.
In this week's newsletter, I'm going to show you four ways to write parameterized tests with xUnit:
\nInlineDataMemberDataClassDataTheoryDataAnd I'll discuss which approach I think is the best.
\nLet's dive in.
\nThe simplest way to write parameterized tests with xUnit is using the InlineData attribute.\nYou provide test data by passing in values to the InlineData constructor.
Here's how that would look like:
\n[Theory]\n[InlineData("test@test.com", "test.com")]\n[InlineData("milan@milanjovanovic.tech", "milanjovanovic.tech")]\npublic void EmailParser_Should_Return_Domain(string email, string expectedDomain)\n{\n // Arrange\n var parser = new EmailParser();\n\n // Act\n var domain = parser.ParseDomain(email);\n\n // Assert\n Assert.Equal(domain, expectedDomain);\n}\nIn this example, we provide two string values to the InlineData attribute, which represent the email and expectedDomain parameters in the test.\nWe can specify the InlineData attribute as many times as we want, to introduce more test cases.
The downside of this approach is that it becomes very verbose when we have many test cases.\nAnd we are limited to only using constant data for the parameters.
\nWith the MemberData attribute we have the ability to programmatically provide the test data.\nYou can load the test data from a static property or member of a type.
Here's an example of using the MemberData attribute to load test data from a property:
[Theory]\n[MemberData(nameof(EmailTestData))]\npublic void EmailParser_Should_Return_Domain(string email, string expectedDomain)\n{\n // Arrange\n var parser = new EmailParser();\n\n // Act\n var domain = parser.ParseDomain(email);\n\n // Assert\n Assert.Equal(domain, expectedDomain);\n}\n\npublic static IEnumerable<object[]> EmailTestData => new List<object>\n{\n new object[] { "test@test.com", "test.com" },\n new object[] { "milan@milanjovanovic.tech", "milanjovanovic.tech" }\n};\nYou specify the name of the member in the MemberData attribute, and it's a best practice to use the nameof operator\nso that you can rename the property (or method) in the future without breaking your test.
The one constraint is that the property (or method) has to return IEnumerable<object[]>, so there is no strong typing.
The ClassData attribute allows you to extract test data into its own class.\nThis is helpful for organizing your test data separately from your tests, and it allows for easier reuse.\nYou load the test from a class the inherits from IEnumerable<object[]> and implements the GetEnumerator method.
Here's an example of using the ClassData attribute to load test data from a class:
[Theory]\n[ClassData(typeof(EmailTestData))]\npublic void EmailParser_Should_Return_Domain(string email, string expectedDomain)\n{\n // Arrange\n var parser = new EmailParser();\n\n // Act\n var domain = parser.ParseDomain(email);\n\n // Assert\n Assert.Equal(domain, expectedDomain);\n}\n\npublic class EmailTestData : IEnumerable<object[]>\n{\n\n public IEnumerable<object[]> GetEnumerator()\n {\n yield return new object[] { "test@test.com", "test.com" };\n yield return new object[] { "milan@milanjovanovic.tech", "milanjovanovic.tech" };\n }\n\n IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();\n};\nUnfortunately, this approach is complicated because you have to implement the IEnumerable interface.
It almost defeats the purpose of separating test data from the actual tests.
\nAnd we still suffer from lack of type-safety.
\nIs there a better solution?
\nLet me introduce you to TheoryData, which is my preferred way of providing test data for parameterized tests.\nUsing the TheoryData class you can implement a class to provide test data while having the benefit of type-safety.
Here's an example of using TheoryData in combination with ClassData:
[Theory]\n[ClassData(typeof(EmailTestData))]\npublic void EmailParser_Should_Return_Domain(string email, string expectedDomain)\n{\n // Arrange\n var parser = new EmailParser();\n\n // Act\n var domain = parser.ParseDomain(email);\n\n // Assert\n Assert.Equal(domain, expectedDomain);\n}\n\npublic class EmailTestData : TheoryData<string, string>\n{\n public EmailTestData()\n {\n Add("test@test.com", "test.com");\n Add("milan@milanjovanovic.tech", "milanjovanovic.tech");\n }\n};\nHow does TheoryData work?
It's a generic class that allows us to specify the types for our parameterized test.
\nYou just call the Add method in the EmailTestData constructor to provide test data for a single test case.\nAnd introducing more test cases comes down to calling the Add method multiple times.
You can also use TheoryData in combination with MemberData, and return TheoryData from a property or method.
I showed you four approaches to write parameterized tests with xUnit:
\nInlineDataMemberDataClassDataTheoryDataSo which one should you use?
\nHere's my personal preference that you can follow if you want:
\nInlineData for simple test casesTheoryData using ClassData for complex test casesThank you for reading, and have a wonderful Saturday.
\nYou can register more than one DbContext in a single application by calling AddDbContext once per context.\nUse it when the app spans multiple databases, when you want a read-replica context, or to give each module of a modular monolith its own schema with HasDefaultSchema.\nJoins and shared transactions across contexts are limited.
Entity Framework Core (EF Core) is a popular ORM in .NET that allows you to work with SQL databases.\nEF Core uses a DbContext, which represents a session with the database and is responsible for tracking changes,\nperforming database operations, and managing database connections.
It's common to have only one DbContext for the entire application.
But what if you need to have multiple DbContexts?
\nIn this week's newsletter we're going to explore:
\nLet's dive in!
\nThere are a few cases where using multiple DbContexts can be useful.
\nMultiple Databases
\nDoes your application need to work with multiple SQL databases?\nThen you're forced to use multiple DbContexts, each one dedicated to a specific SQL database.
Separating Concerns
\nIf the application you're building has a complex domain model, you may see an improvement by separating concerns\nbetween a few DbContexts, where each one is responsible for a specific area of the domain model.
Modular Monolith
\nWhen you're building a Modular Monolith, using multiple DbContexts can be practical because you can configure\na different database schema per DbContext, giving you logical separation at the database level.
Read Replicas
\nYou can configure a separate DbContext instance to access the read replica of your database, and use that\nDbContext for read-only queries.\nYou can also configure QueryTrackingBehavior.NoTracking on the DbContext level to improve query performance.
Here's how you can easily configure multiple DbContexts.\nLet's say we have a CatalogDbContext and an OrderDbContext in our application.\nWe want to configure them using the following constrainsts:
public class CatalogDbContext : DbContext\n{\n public DbSet<Product> Products { get; set; }\n\n public DbSet<Category> Categories { get; set; }\n}\n\npublic class OrderDbContext : DbContext\n{\n public DbSet<Order> Orders { get; set; }\n\n public DbSet<LineItem> LineItems { get; set; }\n}\nFirst we need to configure the CatalogDbContext and OrderDbContext with the DI container.\nYou can do this by calling the AddDbContext method and specifying which DbContext is being configured,\nand then using the SQL provider specific method to pass the connection string.\nIn this case I'm connecting to SQL Server with the UseSqlServer method.
using Microsoft.EntityFrameworkCore;\n\nservices.AddDbContext<CatalogDbContext>(options =>\n options.UseSqlServer("CONNECTION_STRING"));\n\nservices.AddDbContext<OrderDbContext>(options =>\n options.UseSqlServer("CONNECTION_STRING"));\nIf you just want to use both DbContexts in the same schema, then this is all the configuration you need.\nYou can now inject the DbContext instances in your application and use them.
However, if you want to configure a different schema for each DbContext then you also need to override\nthe OnModelCreating method and specify the custom schema with HasDefaultSchema.
public class CatalogDbContext : DbContext\n{\n public DbSet<Product> Products { get; set; }\n\n public DbSet<Category> Categories { get; set; }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.HasDefaultSchema("catalog");\n }\n}\n\npublic class OrderDbContext : DbContext\n{\n public DbSet<Order> Orders { get; set; }\n\n public DbSet<LineItem> LineItems { get; set; }\n\n protected override void OnModelCreating(ModelBuilder modelBuilder)\n {\n modelBuilder.HasDefaultSchema("order");\n }\n}\nLimitations with multiple DbContexts:
\nDbContext instances, because EF Core doesn't know if they\nare using the same databaseUseTransaction methodMigrations History Table
\nIf you decide to use different schemas per DbContext, you will be unpleasantly surprised to learn\nthat the default schema doesn't apply to the migrations history table.
You need to configure this by calling the MigrationsHistoryTable method and specifying the table name\nand schema where the migrations history for that context will live.\nI used the HistoryRepository.DefaultTableName constant in this example, but you can specify a custom\ntable name if you want to.
using Microsoft.EntityFrameworkCore;\nusing Microsoft.EntityFrameworkCore.Migrations;\n\nservices.AddDbContext<CatalogDbContext>(options =>\n options.UseSqlServer(\n "CONNECTION_STRING",\n o => o.MigrationsHistoryTable(\n tableName: HistoryRepository.DefaultTableName,\n schema: "catalog")));\n\nservices.AddDbContext<OrderDbContext>(options =>\n options.UseSqlServer(\n "CONNECTION_STRING",\n o => o.MigrationsHistoryTable(\n tableName: HistoryRepository.DefaultTableName,\n schema: "order")));\nUsing multiple DbContexts can offer several benefits to your application:
\nEach DbContext can be responsible for a specific subset of the application's data, which can help organize the code\nand make it more modular.
\nWhen you separate data access into multiple DbContexts, the application can reduce the risk of contention and improve\nconcurrency, and this can improve performance.
\nAnd if you're using multiple DbContexts, you can configure more granular access control to improve application security.\nYou can also optimize performance and resource usage.
\nUsing multiple EF Core DbContexts in a single application is straightforward and has many benefits.
\nFor ready-heavy applications you can configure a separate DbContext to turn off query tracking by default\nand get improved performance.
Also, using multiple DbContexts is practical if you're building a Modular monolith.\nYou can configure the DbContexts to be in separate database schemas, giving you logical separation at the database level.
\nThat's all for today.
\nSee you next week.
\nC# is object-oriented, but recent versions added functional features like pattern matching, switch expressions, and records.\nIf you use LINQ, you are already writing functional code.\nYou apply it by capturing each step as a pure Func delegate and composing those functions, instead of writing the steps out imperatively.
Although C# is an object-oriented programming language, it received many new functional features in recent versions.
\nTo mention just a few of these features:
\nYou're probably already doing functional programming without even knowing it.
\nDo you use LINQ?\nIf you do, then you're doing functional programming.\nBecause LINQ is a functional .NET library.
\nIn today's issue, I will show you how to refactor some imperative code with functional programming.
\nLet's dive in.
\nBefore we take a look at some code, let's see what are the benefits of using functional programming:
\nFrom my experience, I think functional programming is more enjoyable once you get used to it.\nStarting out, it feels strange because your old object-oriented programming habits will kick in.\nBut after a while, functional programming feels easier to work with than imperative code.
\nImperative programming is the most basic programming approach.\nWe describe a step-by-step process to execute a program.\nIt's easier for beginners to reason with imperative code by following along with the steps in the process.
\nHere's an example of an EmailValidator class written with imperative code:
public class EmailValidator\n{\n private const int MaxLength = 255;\n\n public (bool IsValid, string? Error) Validate(string email)\n {\n if (string.IsNullOrEmpty(email))\n {\n return (false, "Email is empty");\n }\n\n if (email.Length > MaxLength)\n {\n return (false, "Email is too long");\n }\n\n if (email.Split('@').Length != 2)\n {\n return (false, "Email format is invalid");\n }\n\n if (Uri.CheckHostName(email.Split('@')[1]) == UriHostNameType.Unknown)\n {\n return (false, "Email domain is invalid");\n }\n\n return (true, null);\n }\n}\nYou can clearly see the distinct steps:
\nLet's see how we can refactor this using functional programming.
\nThe basic building block in functional programming is - a function.\nAnd programs are written by composing function calls.\nThere are a few other things you need to keep in mind, like keeping your functions pure.\nA function is pure if it always returns the same output for the same input.
\nWe can capture each step from the imperative version of EmailValidator with a Func delegate.\nTo also capture the respective error message together with the validation check, we can use a tuple.\nAnd since we know all of our validation steps, we can create an array of Func delegates to store all of the individual functions.
public class EmailValidator\n{\n const int MaxLength = 255;\n\n static readonly Func<string, (bool IsValid, string? Error)>[] _validations =\n {\n email => (!string.IsNullOrEmpty(email), "Email is empty"),\n email => (email.Length <= MaxLength, "Email is too long"),\n email => (email.Split('@').Length == 2, "Email format is invalid"),\n email => (\n Uri.CheckHostName(email.Split('@')[1]) != UriHostNameType.Unknown,\n "Email domain is invalid")\n };\n\n static readonly (bool IsValid, string? Error) _successResult = (true, null);\n\n public (bool IsValid, string? Error) Validate(string email)\n {\n var validationResult = _validations\n .Select(func => func(email))\n .FirstOrDefault(func => !func.IsValid);\n\n return validationResult is { IsValid: false, Error: { Length: >0 } } ?\n validationResult : _successResult;\n }\n}\nNotice that this allows us to do all sorts of interesting things with the _validations array.\nHow hard would it be to modify this function to return all of the errors instead of just the first one?
If you're thinking we can use LINQ's Select method somehow, you're thinking in the right direction.
We only scratched the surface of what functional programming is, and what you can do with it.\nIf you want to learn more, here are some learning materials:
\nThank you for reading, and have a wonderful Saturday.
\nThe Outbox pattern stores outgoing messages in an OutboxMessages table, in the same database transaction that saves your entities.\nA background process polls the table, publishes any unprocessed message, and retries when publishing fails.\nNothing is lost when the message bus is down, because the message is already committed with the data.
Working with Microservices, or any distributed system for that matter, is difficult.\nIn a distributed system many things can go wrong, and there are even research papers about this.\nIf you want to explore this topic further, I suggest that you read about the fallacies of distributed computing.
\nReducing the surface area for things to go wrong should be one of your goals, as an engineer.\nIn this week's newsletter, we'll try to achieve exactly that using the Outbox pattern.
\nHow can you implement reliable communication between components in a distributed system?
\nThe Outbox pattern is an elegant solution to this problem, allowing you to achieve transactional\nguarantees in a single service and at-least-once message delivery to external systems.
\nLet's see how the Outbox pattern solves this and how can we implement it.
\nTo understand what problem the Outbox pattern solves, first we need a problem, of course.
\nHere's an example of a user registration flow.\nThere are a few things going on here:
\nUser to the databaseUserUserRegisteredEvent to a message buspublic async Task RegisterUserAsync(User user, CancellationToken token)\n{\n _userRepository.Insert(user);\n\n await _unitOfWork.SaveChangesAsync(token);\n\n await _emailService.SendWelcomeEmailAsync(user, token);\n\n await _eventBus.PublishAsync(new UserRegisteredEvent(user.Id), token);\n}\nIn the happy path, all of the operations complete without any issues and all is well.
\nBut what happens if any one of these operations fail?
\nUser failsAlso, imagine a situation where you manage to save a User to the database,\nsend him a welcome email, but fail to publish the UserRegisteredEvent to notify other services.\nHow are you going to recover from this scenario?
The Outbox pattern allows you to atommically update the database and send messages to the message bus.
\nThe first step is to introduce a table in your database to represent the Outbox.\nWe can call this table OutboxMessages, and it's intended to store all messages that need to be delivered.\nNow instead of directly making requests to external services, we simply store a message as a new row in the Outbox table.\nThe messages are usually stored as JSON in the database.
The second step is to introduce a background process that will periodically poll the OutboxMessages table.\nIf the worker process finds a row with an unprocessed message, it's going to publish that message and mark it as sent.\nIf publishing the message fails for some reason, the work process can retry in the next execution.
Notice that with retries, you now have at-least-once message delivery implemented.\nThe message will be published exactly once for the happy path, and more than one time in case or retries.
\nWe can rewrite the RegisterUserAsync method from the previous example, now using an Outbox:
public async Task RegisterUserAsync(User user, CancellationToken token)\n{\n _userRepository.Insert(user);\n\n _outbox.Insert(new UserRegisteredEvent(user.Id));\n\n await _unitOfWork.SaveChangesAsync(token);\n}\nThe Outbox is part of the same transaction as our unit of work, so we can atomically save the User to the database\nand also persist the OutboxMessage.\nIf saving to the database fails, the entire transaction is rolled back and no messages are sent to the message bus.
And since we now moved the publishing of the UserRegisteredEvent to the worker process, we need to add a handler\nso that we can send the welcome email to the user.\nHere's an example of that in the SendWelcomeEmailHandler class:
public class SendWelcomeEmailHandler : IHandle<UserRegisteredEvent>\n{\n private readonly IUserRepository _userRepository;\n private readonly IEmailService _emailService;\n\n public SendWelcomeEmailHandler(\n IUserRepository userRepository,\n IEmailService emailService)\n {\n _userRepository = userRepository;\n _emailService = emailService;\n }\n\n public async Task Handle(UserRegisteredEvent message)\n {\n var user = await _userRepository.GetByIdAsync(message.UserId);\n\n await _emailService.SendWelcomeEmailAsync(user);\n }\n}\nHere's a high level overview of the system architecture with the Outbox introduced to the system.\nYou can see the Outbox table in the database.\nWhat changes now is that you store messages to the Outbox table in the same transaction along with your entities.
![\"Transactional](\"https://milanjovanovic.tech/blogs/mnw_026/outbox.png\")
\nAfter reading this newsletter you should have a pretty good understanding of what the Outbox pattern is\nand what problems it solves.\nIf you need to implement reliable messaging in a distributed system, it's a great solution for your problem.
\nWhat's missing is more details about how to implement the Outbox pattern, so here are a few videos you can watch:
\nThanks for reading, and have an amazing Saturday.
\nSerilog gives ASP.NET Core structured logging out of the box.\nInstall the Serilog.AspNetCore package, call UseSerilog on the host builder, and configure the sinks in appsettings.json.\nThen log with message templates like {@Book} so the values are stored as searchable properties, not flattened into text.
Structured logging is a practice where you apply the same message format to all of your\napplication logs.\nThe end result is that all your logs will have a similar structure, allowing them to be\neasily searched and analyzed.
\nSerilog is a popular logging library in .NET, packed with many features.\nIt provides logging to files, logging to the console, and elsewhere.
\nHowever, Serilog is unique because it comes with support for structured logging out of the box.
\nLet's see how we can install Serilog and configure it an ASP.NET Core application.
\nTo install Serilog in ASP.NET Core you can add the following NuGet package:
\nInstall-Package Serilog.AspNetCore\nThis NuGet packages comes with a simple API to integrate Serilog into your application.\nYou can call the UseSerilog method on the HostBuilder instance to provide a lambda\nmethod to configure Serilog.
I think the most flexible way to configure Serilog is through application settings,\nwhich is achieved by calling ReadFrom.Configuration().
You can also call the UseSerilogRequestLogging() method to introduce automatic HTTP request logging\nin your API.
var builder = WebApplication.CreateBuilder(args);\n\nbuilder.Host.UseSerilog((context, configuration) =>\n configuration.ReadFrom.Configuration(context.Configuration));\n\nvar app = builder.Build();\n\napp.UseSerilogRequestLogging();\n\napp.Run();\nThe next question is how do you provide the actual configuration values to Serilog?
\nappsettings.jsonYou need to add a Serilog section in your appsettings.json file.
Here you can configure, among other things:
\nIn this example, we're adding the Console and File sinks to Serilog.\nAnd we're adding some additional configuration for the File sink in the Serilog.WriteTo configuration section.\nWe can configure the output path for the log files, the naming format, which formatter to use for the logs and so on.
"Serilog": {\n "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],\n "MinimumLevel": {\n "Default": "Information",\n "Override": {\n "Microsoft": "Warning",\n "System": "Warning"\n }\n },\n "WriteTo": [\n { "Name": "Console" },\n {\n "Name": "File",\n "Args": {\n "path": "/logs/log-.txt",\n "rollingInterval": "Day",\n "rollOnFileSizeLimit": true,\n "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"\n }\n }\n ],\n "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ]\n}\nYou can get a more detailed overview of what's supported with the Serilog.Configuration library in the\ndocumentation.
We managed to successfully install and configure Serilog.\nBut how do we actually use it?
\nSerilog integrates with the ILogger interaface coming from the Microsoft.Extensions.Logging namespace.\nIf you're already using ILogger for logging, everything will continue working correctly.
Here's a simple example of logging inside of a Minimal API endpoint:
\napp.MapGet("/serilog-is-cool", (ILogger logger) =>\n{\n logger.LogInformation("This is a log inside of the Minimal API endpoint.");\n\n return Results.Ok(new { Message = "success" });\n});\nYou just inject an ILogger or ILogger<T> instance and Serilog will provide its own implementation at runtime.
The idea behind structured logging is that you can introduce additional contextual information inside\nof your logs.\nSerilog does this using a message template syntax, where you can specify named parameters and then\npass in their values separately.
\nHere's an example of what this message template would look like.\nYou specify parameters inside of curly bracers and provide a name, for example {NamedParameter}.\nThe value provided for the parameter will be serialized as a property inside of the corresponding\nstructured log.
var book = new { Author = "Domain-Driven Design", Title = "Eric Evans" };\nvar orderNumber = 1;\n\nlog.LogInformation(\n "Processing book {@Book}, order number = {@OrderNumber}",\n book,\n orderNumber);\nThere are a few things to unpack here:
\n{@Book} parameter which accepts an object{OrderNumber} parameter which accepts a scalar valueThe @ operator in front of Book tells Serilog to serialize the object passed in, instead of converting\nit using ToString().
Lastly, I want to highlight what are some of the benefits of structured logging and why you should be using it.
\nAs I said at the beginning, the main idea with structured logging is that all log message follow the same\nstructure.\nThis structure can be a JSON document for example, or a row in a relational table.\nSince structured logs are in a machine-readable format, it's much easier to search through them for\nspecific information.
\nWhen an error occurs, structured logs can provide more context and details about the error, making it easier to\nidentify the root cause and fix the problem.
\nIt's very easy to start doing structured logging with Serilog, and I hope you'll give it a try.
\nSee you next week, and have an excellent Saturday.
\nAzure Service Bus is a messaging service in Azure that lets services communicate without calling each other directly.\nIn .NET you talk to it with the Azure.Messaging.ServiceBus package: ServiceBusSender publishes a message to a queue, and ServiceBusProcessor consumes messages with ProcessMessageAsync and ProcessErrorAsync handlers.
If you're working in a distributed system, you need to be able to communicate between\nmultiple services.\nThere are a few ways that you can implement this.\nDepending on your chosen approach, you can either introduce tight coupling between your\nservices or stay loosely coupled.
\nLoose coupling is an important quality in distributed systems.\nIt allows you to evolve your services independently.\nSo how do you implement loosely coupled communication between services?
\nYou need a messaging system.
\nAnd Azure Service Bus\nis an excellent choice.
\nIn this week's newsletter, I'll show you how to create an Azure Service Bus instance,\nand how to implement messaging over a queue.
\nLet's dive in.
\nYou can create a new Azure Service Bus instance from the Azure portal.
\nI won't go into detail on that, since I find the Azure UI pretty intuitive.
\n![\"Azure](\"https://milanjovanovic.tech/blogs/mnw_024/service_bus.png\")
\nAfter creating your Azure Service Bus instance, you'll need to do two more things:
\nAfter that you can proceed with implementing the pub-sub pattern over a queue.\nAnd you'll use the connection string from the Azure portal for connecting to the Azure Service Bus instance.
\nThe first thing we need to do is to create the publishing side of our system, and then\nwe'll see how we can process messages.\nWe're going to use the Azure.Messaging.ServiceBus library to connect to the queue\nrunning in Azure Service Bus.
You can install the NuGet package by running the following command:
\nInstall-Package Azure.Messaging.ServiceBus\nAnd now, let's write the code for publishing a message to an Azure Service Bus queue.
\nTo work with the Azure Service Bus instance, you will use the ServiceBusClient\nclass.\nIt requires a connection string to be able to connect to the Azure Service Bus instance.
The ServiceBusClient is safe to cache and reuse in the application, so it can be registered\nas a service with the singleton lifetime.
With the ServiceBusClient you can create a ServiceBusSender\ninstance, which is responsible\nfor sending the actual messages.\nYou also need to specify which queue it will be sending messages to.\nThis can also be the name of a topic, if you are publishing to a topic instead.
using Azure.Messaging.ServiceBus;\n\nawait using var client = new ServiceBusClient(ConnectionString);\n\nawait using ServiceBusSender sender = client.CreateSender(QueueName);\n\n// This will be the payload for the message ✉️\nvar productCreated = new ProductCreatedEvent(\n eventId: Guid.NewGuid(),\n product.Id,\n product.Name);\n\nstring json = JsonSerializer.Serialize(productCreated);\n\nvar message = new ServiceBusMessage(json);\n\nawait sender.SendMessageAsync(message);\nAs you can see, publishing a message to the queue is relatively simple.
\nWe're creating a new instance of ProductCreatedEvent, which represents our message payload.\nThe payload itself is serialized into a JSON string, wrapped inside a ServiceBusMessage.
For publishing messages to Azure Service Bus, you simply call the SendMessageAsync method.
Publishing messages to a queue is only half of the job.\nYou also need to be able to receive messages from the queue.\nHowever, you'll see that this is very similar to the publishing side.
\nOn the receiving side, you'll also need to create a ServiceBusClient.\nAnd then use it to create an instance of ServiceBusProcessor,\nwhich is used for consuming messages.\nYou need to tell the ServiceBusProcessor which queue it will subscribe to.
The ServiceBusProcessor exposes two events, which represent callbacks for when a message is received.\nThese events are ProcessMessageAsync\nand ProcessErrorAsync.
You need to provide a handler for these two events, to properly consume messages from the queue.\nIn the example below, we're using the HandleMessageAsync and HandleErrorAsync local functions.
using Azure.Messaging.ServiceBus;\n\nawait using var client = new ServiceBusClient(ConnectionString);\n\nawait using ServiceBusProcessor processor = client.CreateProcessor(QueueName);\n\nprocessor.ProcessMessageAsync += HandleMessageAsync;\n\nprocessor.ProcessErrorAsync += HandleErrorAsync;\n\nawait processor.StartProcessingAsync();\n\nasync Task HandleMessageAsync(ProcessMessageEventArgs args)\n{\n string json = args.Message.Body.ToString();\n\n var productCreated = JsonSerializer.Deserialize<ProductCreatedEvent>(json);\n\n Console.WriteLine(productCreated);\n\n await args.CompleteMessageAsync(args.Message);\n}\n\nTask HandleErrorAsync(ProcessErrorEventArgs args)\n{\n var exception = args.Exception;\n\n Console.WriteLine(exception.ToString());\n\n return Task.CompletedTask;\n}\nThe ServiceBusProcessor begins listening to messages coming from the queue after calling the StartProcessingAsync method.
Notice that the success and error event handlers need to accept the\nProcessMessageEventArgs\nand ProcessErrorEventArgs,\nrespectively.
From the ProcessMessageEventArgs you can access the Message.Body which contains the mesage payload.
Azure Service Bus is a very feature rich service cloud.\nI showed you how to work with queues, which are great if you only have one publisher and one subscriber.\nHowever, if you need the ability to have multiple subscribers to a single message, you can't achieve\nthis with queues.
\nYou will have to use topics,\nand I invite you to research this topic further (pun intended).
\nAzure Functions have excellent support for integrating with Azure Service Bus.\nYou can define a QueueTrigger that will run your Azure Function when you receive a message to an Azure Service Bus queue.
I also released a video showing how to publish and consume messages using RabbitMQ,\nand I think you might enjoy it after reading this newsletter.
\nHave an excellent weekend, and stay awesome!
\nEF Core wraps every SaveChanges call in a transaction, so all the changes in that call are applied together or none of them are.\nWhen one operation needs several SaveChanges calls, start your own transaction with Database.BeginTransaction, then Commit or Rollback it.\nYou can also hand EF Core an existing transaction with UseTransaction.
Every software engineer working with SQL databases needs to know about transactions.\nAnd since most of the time the SQL database will be abstracted by an ORM like EF Core,\nit's important to understand how you can work with transactions using the available\nabstractions.
\nSo today, I'll show you how to work with transactions in EF Core.
\nHere's what we will cover:
\nLet's dive in.
\nWhat is the default EF Core transaction behavior?
\nBy default, all changes made in a single call to SaveChanges are applied in a\ntransaction. If any of the changes fail, the entire transaction is rolled back\nand no changes are applied to the database. Only if all changes are successfully\npersisted to the database, the call to SaveChanges can complete.
This is a wonderful feature of SQL databases and it saves us many headaches.\nWe don't have to think about the databases remaining in an inconsistent state,\nbecause database transactions can do the work for us.
\nLet's take a look at an example.
\nusing var context = new ShoppingContext();\n\ncontext.LineItems.Add(new LineItem\n{\n ProductId = productId,\n Quantity = quantity\n});\n\nvar stock = context.Stock.FirstOrDefault(s => s.ProductId == productId);\n\nstock.Quantity -= quantity;\n\ncontext.SaveChanges();\nBecause we are adding a LineItem, and in the same scope reducing the Stock\nquantity, the call to SaveChanges will apply both changes inside of a transaction.\nWe can guarantee that the database will remain in a consistent state.
What if you want to have more control over transactions when working with EF Core?
\nYou can manually create a transaction by accessing the Database facade available\non a DbContext instance and calling BeginTransaction.
Here's an example where we have multiple calls to SaveChanges. In the default\nscenario, both calls would run in their own transaction. This leaves the possibility\nof the second call to SaveChanges failing, and leaving the database in an\ninconsistent state.
using var context = new ShoppingContext();\nusing var transaction = context.Database.BeginTransaction();\n\ntry\n{\n context.LineItems.Add(new LineItem\n {\n ProductId = productId,\n Quantity = quantity\n });\n\n context.SaveChanges();\n\n var stock = context.Stock.FirstOrDefault(s => s.ProductId == productId);\n\n stock.Quantity -= quantity;\n\n context.SaveChanges();\n\n // When we commit the changes, they will be applied to the databases.\n // The transaction will auto-rollback when it is disposed,\n // if any command fails.\n transaction.Commit();\n}\ncatch (Exception)\n{\n transaction.Rollback();\n}\nWe call BeginTransaction to manually start a new database transaction.\nThis will create a new transaction and return it, so that we can Commit the\ntransaction when we want to complete the operation. You also want to add a\ntry-catch block around your code, so that you can Rollback the transaction\nif there are any exceptions.
Creating a transaction using the EF Core DbContext isn't the only option.\nYou can create a SqlTransaction instance and pass it to EF Core, so that\nthe changes applied with EF Core can be committed inside the same transaction.
Here's what I mean:
\nusing var sqlConnection = new SqlTransaction(connectionString);\nsqlConnection.Open();\n\nusing var transaction = sqlConnection.BeginTransaction();\n\ntry\n{\n using var context = new ShoppingContext();\n\n // Tell EF Core to use an existing transaction.\n context.UseTransaction(transaction);\n\n context.LineItems.Add(new LineItem\n {\n ProductId = productId,\n Quantity = quantity\n });\n\n context.SaveChanges();\n\n var stock = context.Stock.FirstOrDefault(s => s.ProductId == productId);\n\n stock.Quantity -= quantity;\n\n context.SaveChanges();\n\n transaction.Commit();\n}\ncatch (Exception)\n{\n transaction.Rollback();\n}\nEF Core has excellent support for transactions and it's very easy to work with.
\nYou have three options available:
\nMost of the time, you want to rely on the default behavior and not have to\nthink about it.
\nAs soon as you need to perform multiple SaveChanges calls, you should manually\ncreate a transaction, and manage the transaction yourself.
See you next week, and have an excellent Saturday.
\nYou implement API Key authentication in ASP.NET Core with a ServiceFilterAttribute that resolves an IAuthorizationFilter from the DI container.\nThe filter reads the key from a request header like X-API-Key, validates it, and sets an UnauthorizedResult when the key isn't valid.\nYou can place the attribute on a single endpoint or on the entire controller.
In this week's newsletter I want to show you how to implement API Key authentication\nin ASP.NET Core. This authentication approach uses an API Key to authenticate the\nclient of an API. You can pass the API Key to the API in a few ways, such as through\nthe query string or a request header.
\nI will show you how to implement API Key authentication where the API key is passed\nin a request header. But the implementation would be similar if we were to use any\nother approach.
\nWhen would you want to use API Key authentication? This kind of authentication\nmechanism is common in Server-to-Server (S2S) communication. When your API serves\nrequest for other server-side applications to consume and integrate with. It's\nless common in client-server communication scenarios.
\nLet's see how we can implement API Key authentication in ASP.NET Core!
\nWe will start off by creating an attribute that we can place on endpoints\nwhere we want to apply API Key authentication. It won't be any kind of\nattribute, because we will use a ServiceFilterAttribute.
What a ServiceFilterAttribute allows us to do is specify a type for the\nfilter that will be created for that attribute.\nThis means we can implement our authentication logic in an IAuthorizationFilter.\nWith a ServiceFilterAttribute we also have support for dependency injection\nin our IAuthorizationFilter implementation.
Let's first define the ApiKeyAttribute class:
public class ApiKeyAttribute : ServiceFilterAttribute\n{\n public ApiKeyAttribute()\n : base(typeof(ApiKeyAuthorizationFilter))\n {\n }\n}\nIn the ApiKeyAttribute we specify ApiKeyAuthorizationFilter class as the\nfilter that will be resolved from the DI container. Here's what it looks like:
public class ApiKeyAuthorizationFilter : IAuthorizationFilter\n{\n private const string ApiKeyHeaderName = "X-API-Key";\n\n private readonly IApiKeyValidator _apiKeyValidator;\n\n public ApiKeyAuthorizationFilter(IApiKeyValidator apiKeyValidator)\n {\n _apiKeyValidator = apiKeyValidator;\n }\n\n public void OnAuthorization(AuthorizationFilterContext context)\n {\n string apiKey = context.HttpContext.Request.Headers[ApiKeyHeaderName];\n\n if (!_apiKeyValidator.IsValid(apiKey))\n {\n context.Result = new UnauthorizedResult();\n }\n }\n}\nThe implementation comes down to validating the API Key obtained from\nthe header of the current request. If we determine that the API Key\nis not valid, we set the value of AuthorizationFilterContext.Result\nto a new instance of an UnauthorizedResult.
And lastly, all that's left for us to do is implement our custom\nvalidation logic for the API Key inside of ApiKeyValidator:
public class ApiKeyValidator : IApiKeyValidator\n{\n public bool IsValid(string apiKey)\n {\n // Implement logic for validating the API key.\n }\n}\n\npublic interface IApiKeyValidator\n{\n bool IsValid(string apiKey);\n}\nThe actual implementation for validating the API Key will vary based\non your use case, and where you are storing the API keys.\nFor example, if you store the API keys in the database you would check\nif the provided API Key exists in the database.\nIf it exists, then validation passes.\nIf it doesn't exist, then validation fails and we return an\nUnauthorizedResult.
We have to make sure to register our ApiKeyAuthorizationFilter and\nApiKeyValidator services with the dependency injection container.
builder.Services.AddSingleton<ApiKeyAuthorizationFilter>();\n\nbuilder.Services.AddSingleton<IApiKeyValidator, ApiKeyValidator>();\nThis will register them as singleton services in our application.\nYou can use a different service scope such as Transient or Scoped\nif you need to.
Finally, with our API Key authentication in place, we can apply the\nApiKeyAttribute attribute to our endpoints:
public class NewslettersController : ControllerBase\n{\n [ApiKey]\n [HttpGet]\n public IActionResult Get()\n {\n // ...\n }\n}\nIn this case I'm applying the ApiKeyAttribute to an endpoint, but\nyou can also apply it on the NewslettersController and it will add\nauthentication to all the endpoints for that controller.
Now that you know how to implement API Key authentication, I think you\nshould also learn how to implement JWT authentication. And while you're\nat it, why not throw authorization into the mix.
\nI made a few videos about JWT authentication and permission authorization\nthat you should take a look at next:
\nIn this week's newsletter I want to talk about the yield keyword in C#.\nI think it's a powerful C# feature and I wanted to highlight the benefits.
The yield keyword tells the compiler that the method in which it appears\nis an iterator block. An iterator block, or method, returns an IEnumerable\nas the result. And the yield keyword is used to return the values for the\nIEnumerable.
An interesting thing aboug IEnumerable is that it is lazily evaluted.\nCalling a method with an iterator block doesn't run any code. It's only\nwhen the IEnumerable is iterated over, or enumerated, that we get\nthe actual values. I'll talk about this more later.
Let's see how we can start using the yield keyword!
The yield keyword on it's own doesn't do anything, you have to combine\nit with the return or break statement:
yield return - provides the next value of the iteratoryield-break - signals the end of iterationIn every project I worked on, there's a piece of code similar to the\nfollowing. You create a list to hold the results, add elements to the\nlist, and return the list in the end.
\nvar engineers = GetSoftwareEngineers();\n\npublic IEnumerable<SoftwareEngineer> GetSoftwareEngineers()\n{\n var result = new List<SoftwareEngineer>();\n\n for(var i = 0; i < 10; i++)\n {\n result.Add(new SoftwareEngineer\n {\n Id = i\n });\n }\n\n return result;\n}\nYou can simplify the method using the yield return statement, and\ncompletely remove the intermediate list required to hold the results.
var engineers = GetSoftwareEngineers();\n\npublic IEnumerable<SoftwareEngineer> GetSoftwareEngineers()\n{\n for(var i = 0; i < 10; i++)\n {\n yield return new SoftwareEngineer\n {\n Id = i\n };\n }\n}\nHowever, it's important to note these two implementation are fundamentally\ndifferent from each other. In the first example, the entire list is\npopulated and materialized. In the second example, the IEnumerable\nreturned will not be materialized and you have to either iterate over\nit inside a foreach loop or call ToList().
You can use the yield break statement to stop iteration and exit\nthe iterator block. Typically you would do this when a certain\ncondition is met, or you only want to return a specific set of values\nfrom the iterator block.
Here's an example where this would be useful:
\nConsole.WriteLine(string.Join(", ", TakeWhilePositive(new[] { 1, 2, -3, 4 })));\n// Output: 1, 2\n\npublic IEnumerable<int> TakeWhilePositive(IEnumerable<int> numbers)\n{\n foreach(int num in numbers)\n {\n if (num > 0)\n {\n yield return num;\n }\n else\n {\n yield break;\n }\n }\n}\nIn C# 8 we got the IAsyncEnumerable type which allows us to\niterate over a collection asynchronously with the yield statement.
For example, this can be useful when you want to call a thid-party\nAPI multiple times to fetch some data. A common situation is when\nyou get a list of users from the database, and then have to call\nan external storage service to get profile picture information.
\nWithout IAsyncEnumerable you would have to do something like this:
public async Task<IEnumerable<User>> GetUsersAsync()\n{\n var users = await GetUsersFromDbAsync();\n\n foreach(var user in users)\n {\n user.ProfileImage = await GetProfileImageAsync(user.Id);\n }\n\n return users;\n}\n\n// And you would call the method like this.\nvar users = await GetUsersAsync();\n\nforeach(var user in users)\n{\n Console.WriteLine(user);\n}\nNow, consider this same example with the use of IAsyncEnumerable:
public async IAsyncEnumerable<User> GetUsersAsync()\n{\n var users = await GetUsersFromDbAsync();\n\n foreach(var user in users)\n {\n user.ProfileImage = await GetProfileImageAsync(user.Id);\n\n yield return user;\n }\n}\n\n// And you would call the method like this.\nawait foreach(var user in GetUsersAsync())\n{\n Console.WriteLine(user);\n}\nThe second implementation will iterate over the users returned from\nthe database when they are yielded by the IAsyncEnumerable.
I've found a few interesting practical applications for the yield keyword.\nOne example is when implementing Domain-Driven Design value objects.
Value objects need to support structural equality. They need to implement\na method that returns all of the equality components. Here's an example of\nthat using the yield return statement:
public class Address\n{\n public string City { get; init; }\n\n public string Street { get; init; }\n\n public string Zip { get; init; }\n\n public string Country { get; init; }\n\n public IEnumerable<object> GetEqualityComponents()\n {\n yield return City;\n yield return Street;\n yield return Zip;\n yield return Country;\n }\n}\nCompiled queries let you compile a frequently executed EF Core query once with EF.CompileQuery and reuse it for the lifetime of the application.\nIn my benchmarks on EF Core 7 and SQL Server 2022, the compiled query was consistently around 10% faster than the standard one.\nUse them sparingly, because they add a lot of complexity.
In this week's newsletter I want to introduce you to an interesting feature\nin EF Core called Compiled Queries.
\nIf you have queries that you execute frequently in your application with a\ndifferent set of parameters, it can be helpful to explicitly compile the\nquery and reuse it throughout the lifetime of your application.
\nCompiled Queries are more performant than standard EF queries, because they\ncan take advantage of some additional optimizations.
\nLet me show you how to use Compiled Queries, and how much performance\nimprovement to expect!
\nLets define a simple class that will represent out data model that we will\nuse for writing EF queries:
\npublic class Newsletter\n{\n public long Id { get; init; }\n\n public string Title { get; init; }\n\n public int ReadTimeInMinutes { get; init; }\n}\nHow would we write a simple query to fetch a Newsletter by the Id?\nI think you can do this in your sleep.
using var dbContext = new AppDbContext();\n\nvar newsletter = dbContext.Set<Newsletter>().FirstOrDefault(n => n.Id == id);\nNow, how do we convert this query into a Complied Query?
\nThere are a few steps involved:
\nEF.CompileQueryYou can define the Compiled Query in a static field inside of the AppDbContext.\nAnd then expose a method that will accept an argument, and pass it to the\nCompiled Query to invoke it.
using Microsoft.EntityFrameworkCore;\n\npublic class AppDbContext\n{\n private static Func<AppDbContext, long, Newsletter?> GetNewsletter =\n EF.CompileQuery(\n (dbContext, id) =>\n dbContext.Set<Newsletter>().FirstOrDefault(n => n.Id == id));\n\n public Newsletter? GetNewsletter(long id)\n {\n return GetNewsletter(this, id);\n }\n}\nThis is how we would call the method which invokes the Compiled Query:
\nusing var dbContext = new AppDbContext();\n\nvar newsletter = dbContext.GetNewsletter(id);\nI ran some benchmarks, with the following setup:
\nThe Compiled Query was consistently around 10% faster.
\nI also tried running a no-tracking query by calling AsNoTracking() and\nobserved similar results.
So we can conclude that Compiled Queries are faster. But why is that?
\nLet's examine what happens when we execute an EF LINQ query. Before EF\ncan convert the query into valid SQL that can be executed in the database,\nit needs to compile the query. The compiled query is cached and EF will be\nable to reuse that cached query. In some situations the query needs to be\nrecompiled, introducing additional performance costs.
\nWhen we explicitly compile the query by calling EF.CompileQuery, we\ncan utilize some optimization techniques that aren't available at runtime.
Note that Compiled Queries only improve the performance of the in-memory\nportion of executing an EF query. The round trip time and materializing\nresults from the database remain unaffected.
\nI showed you how to write a synchronous Compiled Query. But due to\nperformance considerations we almost always want to execute database\nqueries asynchronously.
\nHere's how we can create an asynchronous Compiled Query:
\nusing Microsoft.EntityFrameworkCore;\n\npublic class AppDbContext\n{\n private static Func<AppDbContext, string, Task<Newsletter?>> GetByTitle =\n EF.CompileAsyncQuery(\n (AppDbContext context, string title) =>\n context.Set<Newsletter>().FirstOrDefault(c => c.Title == title));\n\n public async Task<Newsletter?> GetNewsletterByTitleAsync(string title)\n {\n return await GetByTitle(this, title);\n }\n}\nIt's interesting that we aren't writing an asynchronous query in the expression\npassed to EF.CompileAsyncQuery. It will be converted to an asynchronous query\nduring compilation.
You might be tempted to go and convert all of your EF queries into\nCompiled Queries, to squeeze out that last little bit of performance.\nI urge you not do it. Compiled Queries are a useful tool, but they\naren't the solution to all your problems.
\nInstead, I think we should use Compiled Queries sparingly, only in\nsituations where we really need to do these kinds of micro-optimizations.
\nAlthough Compiled Queries seem great, we can't deny they increase\nthe complexity of our code considerably. If you think the slight\nperformance improvement gained from using Compiled Queries justifies\nthe increase in complexity, then by all means, you should use them.\nOtherwise, I would look for other ways to improve performance.
\nYou add validation to the Options pattern with data annotation attributes like [Required] on the settings class, registered with AddOptions, BindConfiguration, and ValidateDataAnnotations.\nAdd ValidateOnStart and the validation runs when the application starts, instead of the first time you inject IOptions.
In this week's newsletter I will show you how to easily add validation\nto the strongly typed configuration objects injected with IOptions.
The Options pattern allows us to use classes to provide strongly typed\nconfiguration values in our application at runtime.
\nBut you have no guarantee that the configuration values injected with\nIOptions will be correctly read from the application settings.
Let's see how we can introduce validation for IOptions, and make sure the application settings are correct.
I first want to define a simple class that will represent our strongly\ntyped configuration. Let's say we want to integrate with the GitHub API,\nso we create a GitHubSettings class to hold our configuration:
public class GitHubSettings\n{\n public string AccessToken { get; init; }\n\n public string RepositoryName { get; init; }\n}\nInside of our appsettings.json file we need to create a section to\nhold our configuration values:
"GitHubSettings": {\n "AccessToken": "access-token-value",\n "RepositoryName": "youtube-projects"\n}\nAnd with this in place, we can configure our GitHubSettings:
builder.Services.Configure<GitHubSettings>(\n builder.Configuration.GetSection("GitHubSettings"));\nFinally, our GitHubSettings is properly configured and we can inject\nit with IOptions<GitHubSettings>.
If we leave the implementation like this, we're moving the responsibility\nfor providing the correct configuration values to the developer. I'm not\nsaying we are the problem, but I've forgotten to add application settings\na few times. I'm sure this happened to you also.
\nHere are just a few things that can go wrong:
\nIConfiguration.GetSectionappsettings.jsonDepending on which one of these mistakes is made, the application will\nbehave differently at runtime.
\nThe best case scenario is that the incorrect application settings cause\na runtime exception, and you realize you have a problem and fix it.
\nThe worst case scenario, and this happens more often than you may think,\nis that the application silently fails. The application settings aren't\ncorrectly set on the value provided by IOptions, but you don't get a\nruntime exception. The problem may go undetected for some time.
How do we solve this?
\nThere is a simple way to introduce validation to the settings class\nusing data annotations. We just add the validation attributes that\nwe need to the properties of the settings class.
\nFor example, we can add the Required attribute to the GitHubSettings\nproperties:
public class GitHubSettings\n{\n [Required]\n public string AccessToken { get; init; }\n\n [Required]\n public string RepositoryName { get; init; }\n}\nWe have to slightly change how we configure the GitHubSettings:
builder.Services\n .AddOptions<GitHubSettings>()\n .BindConfiguration("GitHubSettings")\n .ValidateDataAnnotations();\nA few things to note here:
\nAddOptions - returns an OptionsBuilder<TOptions> that binds to\nthe GitHubSettings classBindConfiguration - binds the values from the configuration sectionValidateDataAnnotations - enables validation using data annotationsWith this in place, if we try to inject GitHubSettings with any of\nthe properties missing a value, we will get a runtime exception.
You can also define a custom delegate for the validation logic, instead\nof using data annotations:
\nbuilder.Services\n .AddOptions<GitHubSettings>()\n .BindConfiguration("GitHubSettings")\n .Validate(gitHubSettings =>\n {\n if (string.IsNullOrEmpty(gitHubSettings.AccessToken))\n {\n return false;\n }\n\n return true;\n });\nIt would be great if we could run validation on the configuration values\nwhen our application is starting, instead of at runtime.
\nWe can do that by calling ValidateOnStart method when configuring\nour settings class:
builder.Services\n .AddOptions<GitHubSettings>()\n .BindConfiguration("GitHubSettings")\n .ValidateDataAnnotations()\n .ValidateOnStart(); // 👈 the magic happens here\nWhen we start the application, the validation will run on GitHubSettings\nand an exception is thrown if validation fails. The validation exception\nwill look something like this:
Unhandled exception. Microsoft.Extensions.Options.OptionsValidationException:\n DataAnnotation validation failed for 'GitHubSettings' members:\nThis shortens the feedback loop, and you will know right away that you have\na problem. This is much better than finding out that you have a problem at\nruntime, like in the previous examples.
\nThe Options pattern is very flexible and allows us to use strongly typed\nsettings in ASP.NET Core.
\nIf you want to see how to implement the Options pattern,\nI made a video about it where I go into the details.\nI covered the differences between IOptions, IOptionsSnapshot and IOptionsMonitor.
And now you know how to use the ValidateOnStart method, which was introduced\nin .NET 6, to validate your application settings on app start up. This allows\nyou to learn about configuration issues as soon as possible, instead of at runtime.
I also made a video showing how to add validation to the Option pattern.
\nIn this week's newsletter I will share 5 simple tips on how\nyou can be a better software engineer in 2023.
\nI find it a little amusing that the last newsletter of the year\nand is also coming out on the last day of the year.
\nHere are 5 tips for being a better software engineer in 2023:
\nI'm confident that you will become a better software engineer if you apply one of these, but I challenge you to work on all of them in the coming year.
\nLet's dive in.
\nThe field of software engineering is constantly evolving, so it's\nimportant to stay up-to-date with new technologies\nand best practices.
\nWe have a new .NET release every year, and it's easy to get lost\nwith the latest news. How I stay up to date is through online courses,\nattending conferences and meetups, or working on personal projects.
\nPersonal projects transition best to my day job, and I don't shy away\nfrom exploring new topics. I shared many of my personal projects on GitHub,\nmaybe you can find some inspiration over there.
\nIn addition to writing clean and readable code, it's important to also\nconsider the overall quality of your code.
\nThis includes things like performance, security, and maintainability.\nBy writing high-quality code, you'll be able to build systems that are\nmore reliable, scalable, and easier to maintain over time.
\nOne way to write clean and quality code is with the help of static code analysis.
\nInvesting in code quality will pay dividends in the later stages of any project.
\nIf you aspire to be senior engineer or software architect, you have to\nwork on complex systems. You need to be in a position to solve the toughest problems.
\nWhat do I consider to be a complex system?
\nThat's difficult to say, but here are some rough guidelines:
\nOf course, you don't need a fancy architecture to work in a complex system.
\nIf you are working in a business domain with many domain rules,\nI consider that a complex system also.
\nYou should strive to always be in a position to work on a challenging project,\nthis will help you grow.
\nThe cloud is here to stay, and you should be familiar with at least one\nof the major cloud providers:
\nMost of them give you free credits to get started and explore the services they offer.
\nI stayed away from cloud development for too long in my career, and now I wish I started sooner.
\nYou want to be comfortable in the cloud to be a better software engineer.
\nBeing a software engineer is mentally and physically demanding, and it's\nimportant to take care of yourself in order to maintain a healthy work-life balance.
\nThis includes getting enough sleep, eating well, and taking breaks when needed.
\nTaking care of yourself can also help you stay focused and productive in your work.
\nI like to take short breaks every hour or so, and not think about work for a few minutes.\nThis helps me replenish my energy, and allows me to continue to operate on a high level.
\nWhat I'm Doing To Make 2023 Amazing\nMaking New Year's resolutions is popular at the start of the year. The problem is most people get too excited about it, but then proceed to not accomplish anything in a few months.
\nI've found the simplest rule to always make progress is taking action. I try to make a small step forward every day. And when I look back on the year, I realize I made a lot of progress.
\nAgain, my 5 tips so you can be a better software engineer in 2023 are:
\nWhere I failed most in 2022 was taking care of myself, and this will be one of my main improvement points.
\nI also want to learn many new things, so I can share them with you in this newsletter and on my social media channels.
\nI wish you a very happy and prosperous New Year.\nWrite lots of code, squash many bugs,\nand may you have green unit tests year round.
\nStay awesome! 🎁
\nMilan
Clean Architecture organizes a system around an inner circle that holds the business rules, with the Infrastructure and Presentation layers around it.\nThe dependency rule points inward: the outer layers depend on the core, and never the other way around.\nThat separation is what makes the business rules easier to unit test and easier to modify.
\nIn the world of software development, there are countless approaches\nand methodologies to choose from. It's easy to get swayed with the\nlatest trends, and loose sight of architectural principles that really matter.
\nOne of the more popular ones is Clean Architecture, a design approach\nthat prioritizes maintainability, scalability, flexibility, and productivity.
\nIn this week's newsletter, we will explore the key benefits of using\nClean Architecture and how it can help your team build better software.
\nLet's dive in.
\nClean Architecture, also known as "The Onion Architecture," was first\nintroduced by Robert C. Martin (aka "Uncle Bob") in his book\n"Clean Architecture: A Craftsman's Guide to Software Structure and Design".
\nAt its core, Clean Architecture is a way of organizing a software system\nin a way that separates the concerns of the various components,\nmaking it easier to understand and maintain.
\nIn Clean Architecture, the core of the system is the "inner circle",\nwhich contains the business rules and logic.
\nSurrounding this inner circle are layers of abstraction,\neach one representing a different concern.
\n![\"Clean](\"https://milanjovanovic.tech/blogs/mnw_017/clean_architecture.png\")
\nThe typical outer layers are Infrastructure and Presentation layers.\nThe Infrastructure layer handles external concerns such as APIs and databases.\nWhile the Presentation layer exposes an interface for clients to interact with\nthe application.
\nThe key principle of Clean Architecture is that the inner circle\nshould not depend on the outer layers. Instead, the outer layers should\ndepend on the inner circle. This helps to ensure that the core of the\nsystem is flexible and easy to modify, without worrying about the impact\non other parts of the system.
\nI want to highlight some of the key benefits of using Clean Architecture.
\nOne of the primary benefits of using Clean Architecture is improved maintainability.\nBy separating the concerns of the various components and enforcing the dependency rule,\nit becomes much easier to understand and modify the code.\nDepending on abstractions allows you to design your business logic in a flexible way,\nwithout having to know the implementation details.
\nClean Architecture helps to create a clear separation of concerns\nwithin the codebase. Each layer has a specific purpose and is decoupled\nfrom the others, making it easier to understand and modify individual\ncomponents without affecting the rest of the system. This modularity\nalso makes it easier to reuse components in other projects.
\nClean Architecture also makes it easier to test and debug the code.\nBecause the inner circle is independent of the outer layers,\nit's easier to write unit tests that focus specifically on the business\nrules. This can help to catch errors early on in the development\nprocess and reduce the overall testing effort.
\nClean Architecture also promotes loose coupling between the various\ncomponents of the system. This means that it's easier to swap out\nexternal dependencies or make other modifications without affecting\nthe core business logic. This can be especially useful when it comes\nto upgrading or replacing technology.
\nAnother key benefit of Clean Architecture is increased flexibility.\nBy separating the concerns of the various components, it's easier\nto modify and adapt the code to changing requirements. This can be\nespecially useful in fast-paced environments where requirements\nare constantly evolving.
\nClean Architecture can help to improve team productivity.\nBy establishing clear separation of responsibilities and well-defined\nboundaries, it's easier for team members to understand their roles\nand responsibilities. This can improve communication and collaboration,\nleading to more efficient and effective work.
\nThis all sounds nice in theory, but how does Clean Architecture\nperform in the real world?
\nI have used Clean Architecture on roughly 10 projects in the\nlast 5 years, and I've had a lot of success with it. It was\neasy to add new features, and scale the applications when\nnecessary. Clean Architecture can easily be broken down\ninto multiple modules or services, if performance is suffering\nand there is a need to scale out.
\nOne problem with the Clean Architecture is that it is easy to overengineer.
\nDogmatism is a real issue, as I see many people with strong\nopinions of what Clean Architecture should be.\nI've been guilty of this myself in the past.
\nRecently, I try to be more pragmatic when using Clean Architecture.\nI apply what I like, and give myself the flexibility of "breaking"\nClean Architecture if I think it will simplify things in the long run.
\nBy following the principles of Clean Architecture, you can create a flexible\nand maintainable codebase that is well-suited to evolving requirements and technology.
\nHowever, it's important to be pragmatic with Clean Architecture and\nallow yourself to be flexible in the design, in order to simplify things in the long run.
\nIf you want to see how to apply Clean Architecture in practice,\nI have a\nplaylist with more than 20 videos on Clean Architecture.
\nMarten is a .NET library that turns a PostgreSQL database into a document store and an event store, using the JSONB support available since PostgreSQL 9.4.\nYou install the NuGet package, call AddMarten with a connection string, and store objects as JSON documents.\nQueries work with LINQ or plain SQL.
Did you know you can turn PostgreSQL into a fully-fledged Document database?
\nMarten is a .NET library that allows developers to use the PostgreSQL\ndatabase as both a document database and a fully-featured event store.
\nYou don't need to install anything else to be able to use PostgreSQL\nas a document database, outside of the Nuget package. Marten relies\non the JSONB support available since PostgreSQL 9.4.
\nIn this week's newsletter, I want to introduce you to the basics of working\nwith Marten and show you how easy it is to get started.
\nLet's dive in.
\nWhat are you going to need to start using PostgreSQL as a Document datbase?
\nOther than a running instance of PostgreSQL, of course, you will need\nto install the Marten Nuget package:
\ndotnet add package Marten\nMarten can build the required database schema and necessary tables on the fly,\nand I suggest using this approach in development.\nFor a production environment, you definitely want to apply schema\nchanges on your own with migration scripts.
\nTo register Marten with dependency injection, you need to call the AddMarten\nmethod.
Here's an example Marten configuration inside of a .NET 7 application:
\nbuilder.Services.AddMarten(options =>\n{\n options.Connection(builder.Configuration.GetConnectionString("Marten"));\n});\nThis will register a few services with dependency injection:
\nIDocumentStore - used to create sessions, generate schema migrations, and do bulk insertsIDocumentSession - used for read and write operationsIQuerySession - used for read operationsLet's see how we can work with documents using Marten.
\nStoring documents in the database is very straightforward. You need to create\na new DocumentStore instance, and open an IDocumentSession which exposes\nmethods for storing and persisting documents.
Let's see how we can store a Product document:
var store = DocumentStore.For("Connection string to PostgreSQL");\n\nusing var session = store.OpenSession();\n\nvar product = new Product\n{\n Name = "C# 11 and .NET 7 - Modern Cross-Platform Fundamentals",\n Price = 46.87\n};\n\nsession.Store(product);\n\nawait session.SaveChangesAsync();\nWe're creating a new DocumentStore instance which we use to open\na session to PostgreSQL. And then we just call Store and pass in\nthe Product instance. Note that Marten will populate the\nProduct.Id at this point. Marten can populate keys of Guid,\nint, long, and other data types. It uses the HiLo algorithm\nfor numeric keys. Finally, when we call SaveChangesAsync the\nProduct is serialized into JSON and persisted as a document.
An important thing to be aware of is that the IDocumentSession\ncreated by OpenSession doesn't track changes on the entities automatically.\nYou need to create a session with dirty checking enabled by\ncalling DirtyTrackedSession on the DocumentStore to enable\nautomatic change detection.
Marten has rich support for querying documents in the database.\nYou can write and execute queries using LINQ, which you are\nfamiliar with if you worked with EF Core. And you can also\nwrite and execute SQL queries, because it's still a PostgreSQL\ndatabase underneath.
\nHere's an example query to return products that have a higher price\nthan the one which is specified:
\nvar store = DocumentStore.For("Connection string to PostgreSQL");\n\nusing var session = store.QuerySession();\n\nvar products = session.Query<Product>().Where(p => p.Price > 9.99).ToList();\nMarten also has support for:
\nMarten can utilize the full capabilities PostgreSQL has to offer,\nnotably transactions and indexing. Marten sessions are transactional\nby default, either all of the documents are persisted together or\nnone of them are. And you can configure indexes on your documents\nfor faster queries.
\nMarten isn't just a document database on top of PostgreSQL!
\nYou have fully-fledged support for event sourcing with Marten,\nas well as projections. This makes it a perfect choice for\nimplementing CQRS. But this is a topic for a separate newsletter.
\nI'm absolutely amazed with Marten and what it has to offer.\nAnd PostgreSQL is also my favorite database, so it's like a match\nmade in heaven. I don't get too excited about learning new\ntechnologies, but Marten has been an endless source\nof joy this past week.
\nI still need to explore a few more topics before I can consider it\nfor production use:
\nConsidering that PostgreSQL is cheaper than most document databases,\nI think using Marten is an interesting alternative. And if you are\nfamiliar with SQL databases, you can still use all of that knowledge.
\nTo keep Minimal APIs maintainable, group endpoints by feature instead of defining them all in one file.\nYou can write an extension method on IEndpointRouteBuilder for each feature, or use a library like Carter and its module concept.\nEither way, related endpoints stay together as the API grows in complexity.
In this week's newsletter we are going to explore Minimal APIs,\nwhich were introduced in .NET 6.
\nMinimal APIs were introduced to remove some of the ceremony\nof creating traditional APIs with controllers.\nTo define an endpoint, you can use the new extension\nmethods, such as MapGet to define a GET endpoint.
I see one big issue with Minimal APIs, and that is the lack\nof clear guidance around how to structure applications\nbuilt with Minimal APIs.
\nIn this newsletter, I want to offer a few solutions for that problem.
\nLet's dive in.
\nLet's define a simple Minimal API application with two endpoints.\nWe're going to create one GET endpoint for getting a list of products.\nAnd one POST endpoint for saving a product to the database.
We're using the powerful DI feature that allows us to inject services\nas expression arguments, which you can see in the two expressions below\nwhere we are injecting the AppDbContext.
var builder = WebApplication.CreateBuilder(args);\n\n// Configure EF and other services...\n\nvar app = builder.Build();\n\napp.MapGet("/products", async (AppDbContext dbContext) =>\n{\n return Results.Ok(await dbContext.Products.ToListAsync());\n});\n\napp.MapPost("/products", async (Product product, AppDbContext dbContext) =>\n{\n dbContext.Products.Add(product);\n\n await dbContext.SaveChangesAsync();\n\n return Results.Ok(product);\n});\n\napp.Run();\nAnd with this we have a functioning Minimal API that we can develop further\nas we continue to add more endpoints.
\nThere is one potential problem with structuring our Minimal APIs like\nin the previous example. If we keep adding the Minimal API endpoints\nin the same file, our API will become hard to maintain as it grows\nin complexity. How can we solve the maintance problem with Minimal APIs?
\nOne solution can be to use extension methods to encapsulate the\ndefiniton of the Minimal API endpoints.
\nHere's an example of that:
\npublic static class ProductsModule\n{\n public static void RegisterProductsEndpoints(this IEndpointRouteBuilder endpoints)\n {\n endpoints.MapGet("/products", async (AppDbContext dbContext) =>\n {\n return Results.Ok(await dbContext.Products.ToListAsync());\n });\n\n endpoints.MapPost("/products", async (Product product, AppDbContext dbContext) =>\n {\n dbContext.Products.Add(product);\n\n await dbContext.SaveChangesAsync();\n\n return Results.Ok(product);\n });\n }\n}\nAnd then inside of Program we need to register the endpoints:
app.RegisterProductsEndpoints();\nYou can see that this simplifies our Minimal API definition,\nand we also have our endpoints grouped by feature in one place.\nI think this improve the maintainability of Minimal APIs,\nbut it comes at a cost. And that cost is having to define\nextension methods for each group of endpoints you want to encapsulate,\nand then you have to remember to call that extensions method in Program.
Can we do better?
\nI want to introduce you to an interesting open source library\ncalled Carter,\nwhich has a concept of modules that we can use to group endpoints.
\nHere's how we can define our ProductsModule with Carter:
public class ProductsModule : ICarterModule\n{\n public void AddRoutes(IEndpointRouteBuilder app)\n {\n app.MapGet("/products", async (AppDbContext dbContext) =>\n {\n return Results.Ok(await dbContext.Products.ToListAsync());\n });\n\n app.MapPost("/products", async (Product product, AppDbContext dbContext) =>\n {\n dbContext.Products.Add(product);\n\n await dbContext.SaveChangesAsync();\n\n return Results.Ok(product);\n });\n }\n}\nThis takes care of configuring our Minimal API endpoints, but we still\nneed to tell the framework to use these endpoints. We have to slightly\nmodify the Program to register the required Carter services by\ncalling AddCarter, and also map our endpoints by calling MapCarter.
var builder = WebApplication.CreateBuilder(args);\n\n// Configure EF and other services...\n\nbuilder.Services.AddCarter();\n\nvar app = builder.Build();\n\napp.MapCarter();\n\napp.Run();\nWhen we want to define additional Minimal API endpoints we just need to\nimplement a new ICarterModule, and register our endpoints. Carter will\nautomatically take care of registering the new endpoints after that.
I think Minimal APIs have evolved nicely since they were first introduced\nin .NET 6. I would be careful with using them in very large applications,\nbut I'm definitely going to explore options for using them on smaller projects.
\nA good use case can be for building a microservice that has a limited\nnumber of endpoints.
\nTo run a background task in ASP.NET Core, implement the IHostedService interface, or inherit from the BackgroundService class and override ExecuteAsync.\nRegister the task with builder.Services.AddHostedService, and it runs as a singleton service alongside your application.\nFor repeating work, use a PeriodicTimer inside ExecuteAsync to run the task on a fixed period.
In this week's newsletter we will talk about running background tasks in ASP.NET Core.\nAfter reading this newsletter, you will be able to set up a background task\nand have it up and running within minutes.
\nBackground tasks are used to offload some work in your application to the background,\noutside of the normal application flow. A typical example can be asynchronously\nprocessing messages from a queue.
\nI will show you how to create a simple background task that runs once and completes.
\nAnd you will also see how to configure a continuous background task, that repeats after a specific period.
\nLet's dive in.
\nYou can define a background task by implementing the IHostedService interface.\nIt has only two methods.
Here's what the IHostedService interface looks like:
public interface IHostedService\n{\n Task StartAsync(CancellationToken cancellationToken);\n\n Task StopAsync(CancellationToken cancellationToken);\n}\nAll you have to do is implement the StartAsync and StopAsync methods.
Inside of StartAsync you would usually perform the background processing.\nAnd inside of StopAsync you would perform any cleanup that is necessary,\nsuch as disposing of resources.
To configure the background task you have to call the AddHostedService method:
builder.Services.AddHostedService<MyBackgroundTask>();\nCalling AddHostedService will configure the background task\nas a singleton service.
So does dependency injection still work in IHostedService implementations?
\nYes, but you can only inject transient or singleton services.
However, I don't like to implement the IHostedService interface myself.\nI prefer using the BackgroundService class instead.
The BackgroundService class already implements the IHostedService interface,\nand it has an abstract method that you need to override - ExecuteAsync.\nWhen you are using the BackgroundService class, you only have to think about\nthe operation you want to implement.
Here's an example background task that runs EF migrations:
\npublic class RunEfMigrationsBackgroundTask : BackgroundService\n{\n private readonly IServiceProvider _serviceProvider;\n\n public RunEfMigrationsBackgroundTask(IServiceProvider serviceProvider)\n {\n _serviceProvider = serviceProvider;\n }\n\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n using IServiceScope scope = _serviceProvider.CreateScope();\n\n await using AppDbContext dbContext =\n scope.ServiceProvider.GetRequiredService<AppDbContext>();\n\n await dbContext.Database.MigrateAsync(stoppingToken);\n }\n}\nThe EF DbContext is a scoped service, which we can't inject directly\ninside of RunEfMigrationsBackgroundTask. We have to inject an instance of\nIServiceProvider which we can use to create a custom service scope,\nso that we can resolve the scoped AppDbContext.
I would not recommend running the RunEfMigrationsBackgroundTask in production.\nEF migrations can easily fail and you'll run into problems.\nHowever, I think it's perfectly fine for local development.
Sometimes we want run a background task continuously, and have it\nperform some operation on repeat. For example, we want consume messages\nfrom a queue every ten seconds. How do we build this?
\nHere's an example PeriodicBackgroundTask to get you started:
public class PeriodicBackgroundTask : BackgroundService\n{\n private readonly TimeSpan _period = TimeSpan.FromSeconds(5);\n private readonly ILogger<PeriodicBackgroundTask> _logger;\n\n public PeriodicBackgroundTask(ILogger<PeriodicBackgroundTask> logger)\n {\n _logger = logger;\n }\n\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\n {\n using PeriodicTimer timer = new PeriodicTimer(_period);\n\n while (!stoppingToken.IsCancellationRequested &&\n await timer.WaitForNextTickAsync(stoppingToken))\n {\n _logger.LogInformation("Executing PeriodicBackgroundTask");\n }\n }\n}\nWe're using a PeriodicTimer\nto asynchronously wait for a given period, before executing our background task.
\nIt should be obvious by now that IHostedService is useful when you need\nsimple background tasks that are running while your application is running.
What if you want to have a scheduled background task that runs at 2AM every day?
\nYou can probably build something like this yourself, but there are existing solutions\nthat you should consider first.
\nHere are two popular solutions for running background tasks that I worked with before:
\n\nI also have an example of using Quartz for processing Outbox messages\non my YouTube channel that you can take a look at.
\nEF Core 7 added the ExecuteUpdate and ExecuteDelete methods for running bulk updates and deletes.\nYou write a LINQ query that selects the target records, and EF Core translates it into a single UPDATE or DELETE statement that runs directly in the database.\nFrom my testing, that can be as much as 10x faster than loading entities and calling SaveChanges.
In this week's newsletter, we're going to explore the new\nExecuteUpdate and ExecuteDelete methods that were released with EF7.
ExecuteUpdate allows us to write a query and run a bulk update\noperation on the entities matching that query.
Similarly, ExecuteDelete allows us to write a query and delete\nthe entities matching that query.
We can significantly improve performance using the new methods in some scenarios, and I'm going to show you what those scenarios are.
\nLet's dive in.
\nIf you want to update a collection of entities before EF7,\nyou need to load the entities into memory using the DatabaseContext.
The EF ChangeTracker will then track any changes made to these entities.\nWhen you are ready to commit the changes to the database,\nyou simply call the SaveChanges method.
Here's an example where we load a few notifications,\nand we want to snooze them so they aren't sent:
\nvar notifications = dbContext\n .Notifications\n .Where(n => !n.Snoozed)\n .ToList();\n\nforeach(var notification in notifications)\n{\n notification.Snoozed = true;\n}\n\ndbContext.SaveChanges();\nEF7 will generate the following SQL statement to update the records in the database:
\nUPDATE [Notifications] n\nSET n.[Snoozed] = TRUE\nWHERE n.[Id] = @notificationId_1;\n\n...\n\nUPDATE [Notifications] n\nSET n.[Snoozed] = TRUE\nWHERE n.[Id] = @notificationId_N;\nNotice that for every notification we end up with one SQL UPDATE statement.\nThis won't scale well as the number of notifications increases.
\nWith EF7, we now have access to the new ExecuteUdpate method.\nIt also has an asynchronous version - ExecuteUpdateAsync.
How do you use it?
\nYou need to write a query that will select the records you want to update,\nand then call the ExecuteUpdate method on the resulting IQueryable.
Let's rewrite the previous example using the new approach:
\ndbContext\n .Notifications\n .Where(n => !n.Snoozed)\n .ExecuteUpdate(s => s.SetProperty(\n n => n.Snoozed,\n n => true));\nIn the call to ExecuteUpdate we call the SetProperty method to specify\nwhich properties we want to update, and what values we want to set.\nThe SetProperty method can be called multiple times, if you need to update more than one property.
In this case, EF7 will generate the following SQL query:
\nUPDATE n\nSET n.[Snoozed] = TRUE\nFROM [Notifications] AS n\nWHERE n.[Snoozed] = FALSE;\nNotice that this time we only have one SQL query being sent to the database.\nThis is a major performance improvement. It can be as much as 10x faster\nthan the old version, from my testing.
\nLet's also see how we can do bulk deletes using the ExecuteDelete and ExecuteDeleteAsync methods.
Again, you have to write a query that will select the records you want to delete,\nand then call the ExecuteDelete method on the resulting IQueryable.
If you want to delete all snoozed notifications:
\ndbContext\n .Notifications\n .Where(n => n.Snoozed)\n .ExecuteDelete();\nAnd EF7 will generate the following SQL query:
\nDELETE FROM n\nFROM [Notifications] AS n\nWHERE n.[Snoozed] = TRUE;\nI think this will be incredibly useful when you want to\ndelete records in the database based on a specific condition.
\nYou need to be aware how transactions and change tracking\nwork with the new bulk methods. ExecuteUpdate and ExecuteDelete will\nimmediately go to database, and run the SQL query.
What does this mean for transactions?
\nIf you want to run a bulk method together with other updates\napplied with SaveChanges, by default they won't run in the same transaction.\nYou need to open an explicit transaction using the DatabaseContext to keep everything consistent.
What does this mean for change tracking?
\nExecuteUpdate and ExecuteDelete run directly on the database, without loading any entities into memory.\nEF7 will not track these entities in the ChangeTracker.
If you have any database interceptors defined, they won't execute\nafter calling one of the bulk update methods.\nThis also means that if you override SaveChanges\nto add custom behavior, it won't be called.
Do Query Filters still work?
\nYes, query filters will be correctly applied when calling ExecuteUpdate or ExecuteDelete.
I think this is an excellent new addition to EF7,\nand it solves a real problem when you need to run\na typical UPDATE or DELETE query with a\nWHERE statement applied.
\nPreviously, you had to write raw SQL and execute it using something like Dapper.
\nI will likely use this approach when it applies to my projects.
\nThe options pattern uses classes to provide strongly typed settings in your application at runtime.\nYou bind a configuration section to an options class with IServiceCollection.Configure, and consume it through dependency injection with IOptions.\nThe values can come from multiple sources, most commonly application configuration.
In this week's newsletter I want to show you how you can use\nthe powerful options pattern in ASP.NET Core 7.
\nThe options pattern uses classes to provide strongly typed settings\nin your application at runtime.
\nThe values for the options instance can come from multiple sources.\nThe typical use case is to provide the settings from application configuration.
\nYou can configure the options pattern in a few different ways in ASP.NET Core.\nI want to discuss some of the approaches and their potential benefits.
\nLet's dive in.
\nI want to set the stage first, by creating the options class and\nexplaining what settings we want to bind to it.
\nWe want to configure JWT Authentication for our application,\nso we decided to create the JwtOptions class to hold that configuration:
public class JwtOptions\n{\n public string Issuer { get; init; }\n public string Audience { get; init; }\n public string SecretKey { get; init; }\n}\nAnd let's imagine that inside of our appsettings.json file\nwe have the following configuration values:
"Jwt": {\n "Issuer": "Gatherly",\n "Audience": "Gatherly",\n "SecretKey": "dont-tell-anyone!"\n}\nAlright, that's looking good. Now I want to show you a few ways to bind\nthe values from JSON to our JwtOptions class.
The most straightforward approach is to use the IConfiguration instance\nthat we can access while registering services.
We need to call the IServiceCollection.Configure<TOptions> method,\nand specify the JwtOptions as the generic argument:
builder.Services.Configure<JwtOptions>(\n builder.Configuration.GetSection("Jwt"));\nIt doesn't get simpler than this, does it?
\nThe only downside is that we are limited to the configuration\nvalues provided through application configuration.
\nThis can be extended to include environment variables and user secrets also.
\nIf you want a more robust approach, I have you covered.\nWe're going to use the IConfigureOptions interface to define a class\nto configure our strongly typed options.
There are two steps that we need to follow in this case:
\nIConfigureOptions implementationIServiceCollection.ConfigureOptions<TOptions> with our IConfigureOptions\nimplementation as the generic argumentTo start off, we will create the JwtOptionsSetup class:
public class JwtOptionsSetup : IConfigureOptions<JwtOptions>\n{\n private const string SectionName = "Jwt";\n private readonly IConfiguration _configuration;\n\n public JwtOptionsSetup(IConfiguration configuration)\n {\n _configuration = configuration;\n }\n\n public void Configure(JwtOptions options)\n {\n _configuration\n .GetSection(SectionName)\n .Bind(options);\n }\n}\nWe wrote more code, to achieve the same thing. Was it worth it?
\nPerhaps, if you consider that we now have access to dependency injection in the JwtOptionsSetup class.\nThis means that we can resolve other services that we can use to get the configuration values.
We also need to tell the application to use the JwtOptionsSetup class:
builder.Services.ConfigureOptions<JwtOptionsSetup>();\nWhen we try to inject our JwtOptions somewhere, the JwtOptionsSetup.Configure\nmethod will be called first the calculate the correct values.
We've seen a few examples for how to configure the options pattern with the JwtOptions class.
But how do we actually use the options pattern?
\nEasy, you just need to inject IOptions<JwtOptions> from the constructor.
I'll just show the JwtProvider constructor here, for brevity.
public JwtProvider(IOptions<JwtOptions> options)\n{\n _options = options.Value;\n}\nThe actual JwtOptions instance is available on the IOptions<JwtOptions>.Value property.
The IOptions instance that we injected here is configured\nas a Singleton in dependency injection. This is very important to be aware of.
If you want to use the latest configuration values every time\nyou inject an options class, then injecting IOptions won't work.
However, you can use the IOptionsSnapshot interface instead:
You can also use the IOptionsMonitor which retrieves the current\noption values at any time, and it's a Singleton service.
The options pattern gives us a way to use strongly typed configuration classes in our application.
\nWe can configure the options class in a simple way with IConfiguration,\nor we can create an IConfigureOptions\nimplementation if we need something more powerful.
When it comes to using the options pattern, we have three approaches:
\n\nDeciding which of them to use in your application depends on what kind of behavior you want.\nIf you don't need to support refreshing configuration values\nafter application start, IOptions is a perfect solution.
.NET 7 was released on November 8th, 2022, alongside C# 11.\nThe language highlights are required members, generic attributes, static abstract members in interfaces, and the file keyword.\nOn the library side, LINQ added the Order and OrderDescending methods, which sort an IEnumerable without a key selector.
In this week's newsletter I want to highlight a few interesting things\nthat are now available with the release of C# 11 and .NET 7.
\nIn case you missed it, .NET 7 was released November 8th.
\nThere are many new features, and you can be sure I had a hard time choosing which ones to highlight.
\nHere's what we are going to cover:
\nfile keywordLet's see what the new features look like!
\nWe can now define a class member as required by using the required keyword.\nIt can be applied to a field or property and it tells the compiler\nthese members must be initialized by all constructors or by the object initializer.
Why is this useful?
\nBefore C# 11, the only way to enforce a property being set was through a constructor.\nIf you used an object initializer you could bypass the constructor and not initialize some properties.
\nHere's how you can say that a property is required:
\npublic class ContentCreator\n{\n public required string Firstname { get; init; }\n public string? MiddleName { get; init; }\n public required string LastName { get; init; }\n}\nIf you try to create a new ContentCreator instance without initializing\nthe required properties you get a compile error:
var creator = new ContentCreator\n{\n FirstName = "Milan" // Error: No LastName\n}\nYou can now declare a generic class whose base class is Attribute.
Before C# 11, if you wanted to pass in a type as a parameter\nto an Attribute you would need to pass it through the constructor:
public class TypedAttribute : Attribute\n{\n public TypedAttribute(Type t) => Param = t;\n\n public Type Param { get; }\n}\nAnd here's how you would use it with the typeof operator:
[TypedAttribute(typeof(int))]\npublic int Method() => default;\nUsing the generic attributes feature, you can now define it like this:
\npublic class TypedAttribute<T> : Attribute { ... }\nNow, we can specify the type parameter as a generic argument:
\n[TypedAttribute<int>()]\npublic int Method() => default;\nThis is a very interesting feature that allows abstracting of static operations.\nAn example of this would be operators.
\npublic interface IMonoid<TSelf> where TSelf : IMonoid<TSelf>\n{\n public static abstract TSelf operator +(TSelf a, TSelf b);\n\n public static abstract TSelf Zero { get; }\n}\nHow can we use the IMonoid interface?
It may be confusing at first, since the members are virtual\nand there is no instance to call the virtual members on.\nThe solution is to use generics and let the compiler infer the rest.
\nHere's a simple example:
\nT AddAll<T>(params T[] elements) where T : IMonoid<T>\n{\n T result = T.Zero;\n\n foreach (var element in elements)\n {\n result += element;\n }\n\n return result;\n}\nIf you want to learn more, check out the docs on\nstatic abstract interface methods\nand generic math.
\nWith the new file keyword you can define a type whose scope and visibility\nis restricted to the file in which it is declared.
file class HiddenClass\n{\n}\nThis feature is practical when used inside of source generators, to avoid collisions when naming generated types.
\nBut you may be able to find a use for it in your application.
\nThe new Order and OrderDescending methods allow us to sort an\nIEnumerable, which simplifies the code for sorting.
Here's an example of ordering an array:
\nvar array = new[] { 19, 91, 21 };\n\nvar arrayAsc = array.Order();\n\nvar arrayDesc = array.OrderDescending();\nI want to highlight that IQueryable also supports the new methods.
.NET 7 is not an LTS (Long Term Support) release,\nand will be in support until May 2024,\nwith .NET 8 releasing in November 2023.
\nHere are a few reasons why you should consider upgrading:
\nI will be moving some of my new projects from .NET 6 to .NET 7.
\nAnd I will also upgrade all of my YouTube content to .NET 7.
\nThe fastest way to check a collection for duplicates is a single pass that adds every element to a HashSet and stops when Add returns false.\nThat is O(n), and in my benchmarks the plain foreach version was the clear winner.\nThe LINQ Any and All variants do the same work in one line.
In this week's newsletter, we will take a look at five different ways to check if a collection contains duplicates.
\nI'm going to explain the idea behind each algorithm, discuss the algorithm complexity (Big O Notation), and at the end, we'll look at some benchmark results.
\nThe five approaches for finding a duplicate will use the:
\n\nLet's see how we can implement each approach!
\nThe first implementation will use the foreach loop and the HashSet data structure.
Here's the code for the ContainsDuplicates method:
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)\n{\n HashSet<T> set = new();\n\n foreach(var element in enumerable)\n {\n if (!set.Add(element))\n {\n return true;\n }\n }\n\n return false;\n}\nThe idea is simple:
\nHashSetHashSet.Add returns false we found a duplicateIn terms of algorithm complexity, this would be O(n) or linear complexity.\nThis is because there's only one iteration through the collection.
\nAdding an element to a HashSet is a constant operation - O(1).\nSo it doesn't affect the overall complexity.
We'll combine the idea from the previous implementation of\nusing the HashSet and pair it with the LINQ Any\nmethod to iterate over the collection.
Here's the implementation for the ContainsDuplicates method:
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)\n{\n HashSet<T> set = new();\n\n return enumerable.Any(element => !set.Add(element));\n}\nYou can see this implementation is significantly shorter.\nBut it works the same as the one with the foreach loop.
If any element in the collection satisfies the specified expression,\nAny will short-circuit and return true.\nOtherwise, it will iterate over the entire collection and return false.
We're still looking at linear complexity here, O(n).
\nFor our third implementation, we will use the opposite\nof the LINQ Any method - the LINQ All method.
Here's the implementation with LINQ All:
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)\n{\n HashSet<T> set = new();\n\n return !enumerable.All(set.Add);\n}\nThe idea here is a little different than in the previous implementation.
\nAll will return true if all elements in a collection\nsatisfy the specified expression.
If at least one element doesn't satisfy the condition -\nin our case when a duplicate is found - it will short-circuit and return false.
This is still linear complexity, O(n).
\nSo far, we've seen a few implementations using the HashSet data structure.\nNow let's consider a different approach.
We can use the LINQ Distinct method to check for duplicates.
Here's the code for the ContainsDuplicates method:
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)\n{\n return enumerable.Distinct().Count() != enumerable.Count();\n}\nThe idea is first find the Distinct elements and Count them,\nand then compare that to the number of all elements.
If the number of distinct elements is not equal to\nthe number of all elements, we have a duplicate value.
\nIn terms of algorithm complexity, this is still linear complexity.
\nBut we have at least two iterations through the collection\nor three in the worst-case scenario.
\nWe have one iteration for Distinct and one more\niteration for the call to Count right after that.\nThe last call to Count can return in constant time,\nif the collection is an array or List.
For the last implementation we will use the LINQ ToHashSet method.
It takes a collection and creates a HashSet instance from it.
Here's what the ContainsDuplicates implementation looks like:
public bool ContainsDuplicates<T>(IEnumerable<T> enumerable)\n{\n return enumerable.ToHashSet().Count != enumerable.Count();\n}\nWe compare the number of elements in the HashSet to the number of elements in the collection.
If they are different, we have a duplicate value.
\nThis is also linear complexity, O(n).
\nNow that we've seen our implementations let's put them to the test.
\nI ran the benchmark for collections of varying sizes:
\nEach collection contains exactly one duplicate value located somewhere around the middle of the collection.
\nHere are the results:
\n![\"Benchmark](\"https://milanjovanovic.tech/blogs/mnw_010/benchmark.png\")
\nThe approach using the foreach loop comes out as the clear winner in terms of performance.
However, I would lean towards using the implementations with LINQ Any or All because of their simplicity.
You can find the source code for the benchmark\non my GitHub. Feel free to submit a PR with a faster implementation if you can think of one.
\nA global query filter is a condition you configure once with HasQueryFilter inside OnModelCreating, and EF Core applies it to every query for that entity type.\nIt removes repetitive conditions like the soft-delete check or a tenantId filter from your queries.\nCall IgnoreQueryFilters when a single query needs to skip it.
In this week's newsletter, I'll show you how you can remove repetitive conditions in EF Core database queries.
\nWhich kinds of queries fit this description?
\nAn example would be when you implement soft-delete, and have to check if a record was soft-deleted or not in every query.
\nAlso, it's practical if you're working in a multi-tenant system and need to specify a tenantId on every query.
EF Core has a powerful feature that can help you remove repetitive conditions from your code.
\nI'm talking about Query Filters.
\nLet's see how we can implement it.
\nBefore introducing Query Filters, we will see how the standard approach looks.\nWe have an Orders table that supports soft-deleting.\nAnd we never want to return soft-deleted orders.
We'll start with an Order entity that has an IsDeleted property.
public class Order\n{\n public int Id { get; set; }\n public bool IsDeleted { get; set; }\n}\nAnd we have a business requirement that we can only query orders that are not deleted.
\nHere's what an EF query to get a single Order might look like:
dbContext\n .Orders\n .Where(order => !order.IsDeleted)\n .Where(order => order.Id == orderId)\n .FirstOrDefault();\nThis works perfectly for what we need to do.
\nHowever, we need to remember to apply this condition every time we want to query the Order entity.
Now, let's see how we can define a Query Filter on the Order entity to\napply this check when querying the database.
Inside of the OnModelCreating method on the database context, we need to\ncall the HasQueryFilter method and specify the expression we want:
modelBuilder\n .Entity<Order>()\n .HasQueryFilter(order => !order.IsDeleted);\nNow we can omit the soft-delete check from the previous LINQ expression:
\ndbContext\n .Orders\n .Where(order => order.Id == orderId)\n .FirstOrDefault();\nAnd this is the SQL that EF will generate with the Query Filter:
\nSELECT o.*\nFROM Orders o\nWHERE o.IsDeleted = FALSE AND o.Id = @orderId\nYou may run into a situation where you need to disable Query Filters for a specific query.\nLuckily, there is an easy way to do this.
\nIn your LINQ expression, you need to call the IgnoreQueryFilters method,\nand all the Query Filters configured for this entity will be disabled:
dbContext\n .Orders\n .IgnoreQueryFilters()\n .Where(order => order.Id == orderId)\n .FirstOrDefault();\nBe careful when doing this, as you can easily introduce unwanted behavior in your application.
\nHere are a few more details that you should know about Query Filters before using them.\nHopefully, this will save you some trouble if you decide to use them in your application.
\nConfiguring multiple Query Filters
\nConfiguring multiple Query Filters on the same entity will only apply the last one.\nIf you need more than one condition, you can do that with the logical AND operator (&&).
Ignoring specific Query Filters
\nIf you need to ignore a specific expression in a Query Filter and leave the rest in place,\nunfortunately, you can't do that. Only one Query Filter is allowed per entity type.
\nOne solution is calling IgnoreQueryFilters, which will remove the configured Query Filter\nfor that entity type. And then manually apply the condition that you need for that specific query.
Locking is how you stop two threads from running the same block of code at the same time, so concurrent updates to a shared resource stay correct.\n.NET gives you the lock statement and the Semaphore class for synchronous code, and SemaphoreSlim when the critical section contains async calls.\nMonitor, Mutex, and ReaderWriterLock are the other options.
In this week's newsletter, we'll see how we can work with locking in .NET 6.
\nWe won't talk about how the lock is actually implemented at the operating system level.\nInstead, I will focus on application-level locking mechanisms.
\nLocking allows us to control how many threads can access some piece of code.\nWhy would you want to do this?
\nUsually because you want to protect access to expensive resources,\nand you need the concurrency control that locking enables.
\nWe will use a simple BankAccount class with a Deposit method\nto illustrate how to implement locking.
The C# language supports locking with the lock statement.\nYou can use the lock statement to define a code block that only one thread can access.
The lock statement acquires a mutual-exclusion lock (mutex) for a given object,\nexecutes the statement block, and releases the lock.
lock(_lock)\n{\n // Your code...\n}\nHere _lock is a reference type, usually an object instance.
Let's see how we can implement the BankAccount class using the lock statement:
public class BankAccount\n{\n private static readonly object _lock = new();\n private decimal _balance;\n\n public void Deposit(decimal amount)\n {\n lock(_lock)\n {\n _balance += amount;\n }\n }\n}\nThe first thread to reach and execute the lock statement will be allowed to update\nthe _balance. Any other threads will block until the lock is released.
The Semaphore\nclass is another option we can use to achieve the same effect.
We'll use the Semaphore constructor to set the initialCount to 1,\nwhich means that the Semaphore is open at the start.\nAnd we will also set the maximumCount to 1,\nwhich means that only one thread is allowed to enter the Semaphore.
Let's see how we can implement the BankAccount class using the Semaphore:
public class BankAccount\n{\n private static readonly Semaphore _semaphore = new(\n initialCount: 1,\n maximumCount: 1);\n\n private decimal _balance;\n\n public void Deposit(decimal amount)\n {\n _semaphore.WaitOne();\n\n _balance += amount;\n\n _semaphore.Release();\n }\n}\nTo enter the Semaphore, we have to call the WaitOne method.
If no thread was previously inside, our thread is allowed\nto enter the Semaphore and update the balance.
After updating the balance, we call the Release method to\nrelease the Semaphore for other threads that might be waiting.
What if we wanted to call an asynchronous method in a locked context?
\nWe can't use the lock statement as it doesn't support asynchronous calls.\nAwaiting an asynchronous call inside a lock statement will cause a compilation error.
The Semaphore class can solve this problem.
But I want to show you another option that we have, SemaphoreSlim.\nIt's a lightweight alternative to the Semaphore class and has async methods.
Let's see how we can implement the BankAccount class using SemaphoreSlim:
public class BankAccount\n{\n private static readonly SemaphoreSlim _semaphore = new(\n initialCount: 1,\n maximumCount: 1);\n\n private decimal _balance;\n\n public async Task Deposit(decimal amount)\n {\n await _semaphore.WaitAsync();\n\n _balance += amount;\n\n _semaphore.Release();\n }\n}\nNotice that I updated the Deposit method to return a Task.
This time, we're calling WaitAsync to block the current\nthread until it can enter the semaphore.
After updating the balance, we call the Release method\nto release the SemaphoreSlim like in the previous example.
So far I mentioned three options to implement locking:
\n\nHowever, .NET has other classes for concurrency control that you can\nexplore like\nMonitor,\nMutex,\nReaderWriterLock\nand many more.
I hope you enjoyed this brief introduction to a very complex topic.
\nI made an API endpoint 15x faster by finding the bottlenecks first, then fixing them one at a time.\nThat meant reducing database round trips, parallelizing independent external calls with Task.WhenAll, and leaving caching as a last resort for data that is frequently accessed but rarely modified.
Performance optimization is my favorite thing about software engineering.\nOver the last 5 years, I've encountered various performance problems\nthat taught me different ways to overcome them.
\nAbout a month ago, I ran into an issue with an API endpoint that wasn't scaling well.
\nThis endpoint is used to calculate a report for an e-commerce web application.\nIt needed to talk to multiple modules (services) to gather all the necessary data,\ncombine it and perform the calculations.
\nI made a post about it on LinkedIn\nthat resonated with many people.
\n![\"LinkedIn](\"https://milanjovanovic.tech/blogs/mnw_007/linkedin_post.png\")
\nIn this newsletter, I want to break down what I did to achieve a 15x performance improvement.
\nThe first thing I do when I'm solving a performance problem\nis determine where the slowest piece of the code is.\nFixing this part of the code will usually give the most significant improvement.
\nSolving one bottleneck can also reveal where the next bottleneck is.
\nThis is a continual process.
In my situation, there were a few bottlenecks:
\nHow can you measure performance?
\nA simple approach can be using System.Timers.Timer where you\nmanually log execution times between method calls.\nOr you can use a performance profiler.
A round trip between your application and a database\n(or some other service) can last 5-10ms, or more.\nIf you have many round trips in your flow, it's going to add up quickly.
\nHere are a few things you can do reduce the number of round trips:
\n SELECT * FROM [TableName] WHERE Id IN (list_of_ids)\nUse a query that returns multiple result sets from the database.\nOne library that supports this is Dapper, with the QueryMultiple method.
If you need to make multiple calls to another service, try to convert that into one call.\nAnd in the service, aggregate the required data and return everything at once.
\nI had a situation where I was awaiting multiple asynchronous calls from a few services.\nThese calls had no dependencies on each other, so I used a simple technique\nto gain a significant performance improvement.
\nLet's say you're awaiting two tasks:
\nvar task1Result = await CallService1Async();\n\nvar task2Result = await CallService2Async();\n\n// Use the results.\nA simple way to parallelize these calls is using the Task.WhenAll method:
var task1 = CallService1Async();\n\nvar task2 = CallService2Async();\n\nawait Task.WhenAll(task1, task2);\n\n// Use the results.\ntask1.Result;\ntask2.Result;\nNotice that I'm directly accessing the Result property on the tasks.\nThis can be detrimental if you're using it to block on an asynchronous call,\nand can even lead to deadlocks.
However, in this situation it is perfectly safe to do,\nbecause the two tasks will have completed after the call to Task.WhenAll completes.
Of course, whether or not these tasks will be executed in parallel\nwhen calling Task.WhenAll depends on a few factors, which I won't cover here.
I try to leave caching for the end, after I have exhausted\nall other possibilities to improve performance.\nWhile I love to use caching in general, I'm aware\nit can introduce some unwanted behavior when data is stale.
\nYou have to consider how long you can safely cache the data,\nand how you are going to clear the cache if the underlying data changes.
\nIn simple applications, I use IMemoryCache\nthat is available in ASP.NET Core out of the box.\nBut you can also use an external cache like Redis.
A good candidate for caching is data that is frequently accessed, but rarely modified.
\nI think that for most Web applications,\nperformance optimization can be boiled down to the following approaches:
\nI didn't talk about database optimization and indexes here,\nbut this should also be on your mind if the database is your bottleneck.
\nThe decorator pattern lets you add new behavior to an existing class without modifying the original class in any way.\nA wrapper class implements the same interface and delegates to the wrapped implementation.\nIn ASP.NET Core you can wire the decorator up manually in the DI container, or register it with a single Decorate call from the Scrutor library.
Let's imagine we have an existing Repository implementation, and we want to introduce caching to reduce the load on the database.
How can we achieve this without changing the original Repository implementation?
Decorator pattern is a structural design pattern that allows you\nto introduce new behavior to an existing class, without modifying the original class in any way.
\nI'll show you how you can implement this with the ASP.NET Core DI container.
\nWe'll start with an existing MemberRepository implementation that implements the IMemberRepository interface.
It has only one method, which loads the Member from the database.
Here's what the implementation looks like:
\npublic interface IMemberRepository\n{\n Member GetById(int id);\n}\n\npublic class MemberRepository : IMemberRepository\n{\n private readonly DatabaseContext _dbContext;\n\n public MemberRepository(DatabaseContext dbContext)\n {\n _dbContext = dbContext;\n }\n\n public Member GetById(int id)\n {\n return _dbContext\n .Set<Member>()\n .First(member => member.Id == id);\n }\n}\nWe want to introduce caching to the MemberRepository implementation without modifying the existing class.
To achieve this, we can use the Decorator pattern and create a wrapper around our MemberRepository implementation.
We can create a CachingMemberRepository that will have a dependency on IMemberRepository.
public class CachingMemberRepository : IMemberRepository\n{\n private readonly IMemberRepository _repository;\n private readonly IMemoryCache _cache;\n\n public CachingMemberRepository(\n IMemberRepository repository,\n IMemoryCache cache)\n {\n _repository = repository;\n _cache = cache;\n }\n\n public Member GetById(int id)\n {\n string key = $"members-{id}";\n\n return _cache.GetOrCreate(\n key,\n entry => {\n entry.SetAbsouluteExpiration(\n TimeSpan.FromMinutes(5));\n\n return _repository.GetById(id);\n });\n }\n}\nNow I'm going to show you the power of ASP.NET Core DI.
\nWe will configure the IMemberRepository to resolve an instance of CachingMemberRepository,\nwhile it will receive the MemberRepository instance as its dependency.
For the DI container to be able to resolve IMemberRepository as CachingMemberRepository,\nwe need to manually configure the service.
We can use the overload that exposes a service provider,\nthat we will use to resolve the services required to construct a MemberRepository.
Here's what the configuration would look like:
\nservices.AddScoped<IMemberRepository>(provider => {\n var context = provider.GetService<DatabaseContext>();\n var cache = provider.GetService<IMemoryCache>();\n\n return new CachingRepository(\n new MemberRepository(context),\n cache);\n});\nNow you can inject the IMemberRepository, and the DI will be able to resolve an instance of CachingMemberRepository.
If the previous approach seems cumbersome to you and like a lot of manual work - that's because it is.
\nHowever, there is a simpler way to achieve the same behavior.
\nWe can use the Scrutor library to register the decorator:
\nservices.AddScoped<IMemberRepository, MemberRepository>();\n\nservices.Decorate<IMemberRepository, CachingMemberRepository>();\nScrutor exposes the Decorate method.\nThe call to Decorate will register the CachingMemberRepository while ensuring\nthat it receives the expected MemberRepository instance as its dependency.
I think this approach is much simpler, and it's what I use in my projects.
\nIn this newsletter, we'll be covering three ways to create middleware in ASP.NET Core applications.
\nMiddleware allows us to introduce additional logic before or after executing an HTTP request.
\nYou are already using many of the built-in middleware available in the framework.
\nI'm going to show you three approaches to how you can define custom middleware:
\n\nLet's go over each of them and see how we can implement them in code.
\nThe first approach to defining a middleware is by writing a Request Delegate.
\nYou can do that by calling the Use method on the WebApplication instance\nand providing a lambda method with two arguments.\nThe first argument is the HttpContext and the second argument is\nthe actual next request delegate in the pipeline RequestDelegate.
Here's what this would look like:
\nvar builder = WebApplication.CreateBuilder(args);\nvar app = builder.Build();\n\napp.Use(async (context, next) =>\n{\n // Add code before request.\n\n await next(context);\n\n // Add code after request.\n});\nBy awaiting the next delegate, you are continuing the request pipeline execution.\nYou can short-circuit the pipeline by not invoking the next delegate.
This overload of the Use method is the one suggested by Microsoft.
The second approach requires us to create a class that will represent our middleware.\nWe have to follow the convention when creating this class so that we can use it as middleware in our application.
\nI'm first going to show you what this class looks like, and then explain what is the convention we are following here.
\nHere's how this class would look like:
\npublic class ConventionMiddleware(\n RequestDelegate next,\n ILogger<ConventionMiddleware> logger)\n{\n public async Task InvokeAsync(HttpContext context)\n {\n logger.LogInformation("Before request");\n\n await next(context);\n\n logger.LogInformation("After request");\n }\n}\nThe convention we are following has a few rules:
\nRequestDelegate in the constructorInvokeAsync method with an HttpContext argumentRequestDelegate and pass it the HttpContext instanceThere's one more thing that's required, and that is to tell our application to use this middleware.
\nWe can do that by calling the UseMiddleware method:
app.UseMiddleware<ConventionMiddleware>();\nAnd with this, we have a functioning middleware.
\nThe third and last approach requires us to also create a class that will represent our middleware.
\nHowever, this time we're going to implement the IMiddleware interface.\nThis interface has only one method - InvokeAsync.
Here's what this class would like:
\npublic class FactoryMiddleware(ILogger<FactoryMiddleware> logger) : IMiddleware\n{\n public async Task InvokeAsync(HttpContext context, RequestDelegate next)\n {\n logger.LogInformation("Before request");\n\n await next(context);\n\n logger.LogInformation("After request");\n }\n}\nThe FactoryMiddleware class will be resolved at runtime from dependency injection.
Because of this, we need to register it as a service:
\nbuilder.Services.AddTransient<FactoryMiddleware>();\nAnd like the previous example, we need to tell our application to use our factory-based middleware:
\napp.UseMiddleware<FactoryMiddleware>();\nWith this, we have a functioning middleware.
\nI'm a big fan of strong typing whenever possible.\nOut of the three approaches I just showed you, the one using the\nIMiddleware interface satisfies this constraint the most.\nThis is also my preferred way to implement middleware.
Since we're implementing an interface, it's very easy to create\na generic solution to never forget to register your middleware.
\nYou can use reflection to scan for classes implementing\nthe IMiddleware interface and add them to dependency injection,\nand also add them to the application by calling UseMiddleware.
Clean Architecture is a popular approach to structuring your application.
\nIt's a layered architecture that splits the project into four layers:
\n\nEach of the layers is typically one project in your solution.
\nHere's a visual representation of the Clean Architecture:
\n![\"Clean](\"https://milanjovanovic.tech/blogs/mnw_004/clean_architecture.png\")
\nHow do we create this in our .NET solutions?
\nThe Domain layer sits at the core of the Clean Architecture.\nHere we define things like: entities, value objects, aggregates, domain events, exceptions, repository interfaces, etc.
\nHere is the folder structure I like to use:
\n📁 Domain\n|__ 📁 DomainEvents\n|__ 📁 Entities\n|__ 📁 Exceptions\n|__ 📁 Repositories\n|__ 📁 Shared\n|__ 📁 ValueObjects\nYou can introduce more things here if you think it's required.
\nOne thing to note is that the Domain layer is not allowed to reference other projects in your solution.
\nThe Application layer sits right above the Domain layer.\nIt acts as an orchestrator for the Domain layer, containing the most important use cases in your application.
\nYou can structure your use cases using services or using commands and queries.
\nI'm a big fan of the CQRS pattern, so I like to use the command and query approach.
\nHere is the folder structure I like to use:
\n📁 Application\n|__ 📁 Abstractions\n |__ 📁 Data\n |__ 📁 Email\n |__ 📁 Messaging\n|__ 📁 Behaviors\n|__ 📁 Contracts\n|__ 📁 Entity1\n |__ 📁 Commands\n |__ 📁 Events\n |__ 📁 Queries\n|__ 📁 Entity2\n |__ 📁 Commands\n |__ 📁 Events\n |__ 📁 Queries\nIn the Abstractions folder, I define the interfaces required for the Application layer.\nThe implementations for these interfaces are in one of the upper layers.
For every entity in the Domain layer, I create one folder with the commands, queries, and events definitions.
\nThe Infrastructure layer contains implementations for external-facing services.
\nWhat would fall into this category?
\nHere is the folder structure I like to use:
\n📁 Infrastructure\n|__ 📁 BackgroundJobs\n|__ 📁 Services\n |__ 📁 Email\n |__ 📁 Messaging\n|__ 📁 Persistence\n |__ 📁 EntityConfigurations\n |__ 📁 Migrations\n |__ 📁 Repositories\n |__ #️⃣ ApplicationDbContext.cs\n|__ 📁 ...\nI place my DbContext implementation here if I'm using EF Core.
It's not uncommon to make the Persistence folder its project.\nI frequently do this to have all database facing-code inside of one project.
\nThe Presentation layer is the entry point to our system.\nTypically, you would implement this as a Web API project.
\nThe most important part of the Presentation layer is the Controllers, which define the API endpoints in our system.
Here is the folder structure I like to use:
\n📁 Presentation\n|__ 📁 Controllers\n|__ 📁 Middlewares\n|__ 📁 ViewModels\n|__ 📁 ...\n|__ #️⃣ Program.cs\nSometimes, I will move the Presentation layer away from the actual Web API project.\nI do this to isolate the Controllers and enforce stricter constraints.\nYou don't have to do this if it is too complicated for you.
You don't have to follow the folder structure I proposed to the T.\nClean Architecture is very flexible, and you can experiment with it and structure it the way you like.
\nDo you like more granularity? Create more specific projects.
\nDo you dislike a lot of projects? Separate concerns using folders.
\nI'm here to give you options to explore. But it's up to you to decide what's best.
\nQuery splitting, introduced in EF Core 5.0, lets you split a single LINQ query with Include statements into multiple SQL queries, one per included navigation.\nYou enable it by calling AsSplitQuery on a single query, or for every query with UseQuerySplittingBehavior.\nIt avoids the Cartesian explosion that can make a join-heavy query slow enough to time out.
I recently ran into an issue with Entity Framework Core.
\nThe query I was running was constantly timing out.
\nI tried to scale up the application server, and it didn't help.
\nI tried to scale up the database server, and it didn't help.
\nSo how did I solve the problem?
\nI'm working on an application in the e-commerce domain.\nTo be specific, it's an order management system for a kitchen cabinet manufacturer.
\nThe table that I frequently query on is the Orders table.\nThe Order can have one or more LineItems.\nA typical Order will contain 50 LineItems.\nAlso, LineItems have a table that contains the valid dimensions - LineItemDimensions.
This is the query I was trying to run:
\ndbContext\n .Orders\n .Include(order => order.LineItems)\n .ThenInclude(lineItem => lineItem.Dimensions)\n .First(order => order.Id == orderId);\nWhen EF Core converts this into SQL, this is what it will send to the database:
\nSELECT o.*, li.*, d.*\nFROM Orders o\nLEFT JOIN LineItems li ON li.OrderId = o.Id\nLEFT JOIN LineItemDimensions d ON d.LineItemId = li.Id\nWHERE o.Id = @orderId\nORDER BY o.Id, li.Id, d.Id;\nIn most cases, this query will execute just fine.
\nHowever, in my situation I was running into the problem of Cartesian Explosion.\nThis is mainly because of the join to the LineItemDimensions table.\nAnd this is what's causing my query to fail, and time out.
So how did I solve this problem?
\nWith the release of EF Core 5.0 we got a new feature called Query Splitting.\nThis allows us to specify that a given LINQ query should be split into multiple SQL queries.
To use Query Splitting, all you need to do is call the AsSplitQuery method:
dbContext\n .Orders\n .Include(order => order.LineItems)\n .ThenInclude(lineItem => lineItem.Dimensions)\n .AsSplitQuery()\n .First(order => order.Id == orderId);\nIn this case, EF Core will generate the following SQL queries:
\nSELECT o.*\nFROM Orders o\nWHERE o.Id = @orderId;\n\nSELECT li.*\nFROM LineItems li\nJOIN Orders o ON li.OrderId = o.Id\nWHERE o.Id = @orderId;\n\nSELECT d.*\nFROM LineItemDimensions d\nJOIN LineItems li ON d.LineItemId = li.Id\nJOIN Orders o ON li.OrderId = o.Id\nWHERE o.Id = @orderId;\nNotice that for each Include statement we have a separate SQL query.\nThe benefit here is that we are not duplicating data when fetching from the database,\nas we were in the previous case.
You can enable Query Splitting at the database context level.\nWhen configuring your database context you need to call the UseQuerySplittingBehavior method:
services.AddDbContext<ApplicationDbContext>(options =>\n options.UseSqlServer(\n "CONNECTION_STRING",\n o => o.UseQuerySplittingBehavior(\n QuerySplittingBehavior.SplitQuery)));\nThis will cause all queries that EF Core generates to be split queries.\nTo revert back to a single query, you need to call the AsSingleQuery method:
dbContext\n .Orders\n .Include(o => o.LineItems)\n .ThenInclude(li => li.Dimensions)\n .AsSingleQuery()\n .First(o => o.Id == orderId);\nAlthough query splitting is an excellent addition to EF Core, there are a few things you need to be aware of.
\nThere is no consistency guarantee for multiple SQL queries.\nYou may run into a problem if you have a concurrent update going through\nat the same time when you query your data.\nTo mitigate this, you can wrap the queries inside of a transaction, but this will only introduce performance issues elsewhere.
\nEach query will require one network round trip. This can degrade performance if your latency to the database is high.
\nNow that you are armed with this knowledge, go and make your EF queries faster!
\nNon-destructive mutation means producing a modified copy of an object instead of changing it.\nThe with expression, introduced in C# 9, creates a new record instance with only the specified properties changed, while the original remains unchanged.\nIt works with anonymous types too.
Today, I'm going to share some fascinating things you can do with records and anonymous types.\nI will introduce you to the concept of non-destructive mutation.\nAnd I will talk about when and why we might want to use this C# language feature.
\nWith C# 9 we can use records that are a new reference type.\nC# 10 introduced record structs so that you can define records as value types.\nRecords are distinct from classes in that record types use value-based equality.
\nLet's see how we would define a record:
public record Food(string Name, double Price);\nThis way of declaring a record is called a positional record.\nThe constructor we have defined here is called the primary constructor.
The Name and Price properties are init only properties.\nThis means they can only be set in the constructor or using a property initializer.
Since our properties are init only, is there any way to change their value?
\nWe said we can't modify the properties of our record, because the properties are init only.\nHowever, we can use the with expression (introduced in C# 9) to create a new instance\nof our record with modified values.
Let's see how we would use the with expression:
var banana = new Food("🍌", 1.95);\n\nvar bananaOnSale = banana with\n{\n Price = 0.99\n};\nIt's important to highlight two things here:
\nwith expression creates a new record instance with only the Price property modifiedI mentioned Anonymous Types in the title, so let me show you something interesting you can do with them.
\nDid you know that you can use the with expression with anonymous types?
Just a reminder that the with expression is available from C# 9 and later.
Let's create an anonymous type:
\nvar apple = new\n{\n Name = "🍎",\n Price = 1.21\n};\nThis is how we can modify it using the with expression:
\nvar orange = apple with\n{\n Name = "🍊"\n};\nAnd again the same rules apply:
\nI found this feature useful in LINQ method chains.
\nFor example, loading an anonymous type from the database where some properties have a default value.\nYou can then use this feature to calculate the values for these properties in memory.
\nA tall LINQ query puts each method call in the chain on its own line, so the expression grows vertically instead of stretching across the screen.\nEach step becomes easier to read, and easier to follow into the next one in the chain.
\nFirst, I want to welcome you to the first edition of Milan's .NET Weekly newsletter.
\nI hope that this newsletter can become a positive force in the .NET community.\nTo bring many of us together so that we can all continue learning and improving.
\nWith that out of the way, let's get into .NET!
\nLet's consider the following LINQ expression from a code style perspective.
\nI call this a wide LINQ expression because it stretches horizontally across the entire screen.
\ndbContext.Animals.Where(animal => animal.HasBigEars)\n .OrderBy(animal => animal.IsDangerous).Select(\n animal => (animal.Id, animal.Name)).ToList();\nTo improve this, I created a simple rule that you can follow:
\n\n\nWhen writing LINQ, try to go tall, not wide.
\n
So how do we write tall LINQ expressions?
\nI'm going to rewrite the previous expression, to improve it.
\nTry to follow the one dot per line rule:
\ndbContext\n .Animals\n .Where(animal => animal.HasBigEars)\n .OrderBy(animal => animal.IsDangerous)\n .Select(animal => (animal.Id, animal.Name))\n .ToList();\nIs the new version easier to read? Yes, very much so.
\nIt is easier to understand what each expression does,\nand how it feeds into the next one in the chain.
\nIf you are working in a team, try to propose this as a coding standard (if it isn't one already).
\nYou will see that over time this will make a noticeable difference.