Agentless logging skips the Agent: your application sends its logs directly to Datadog's HTTPS intake. There are two ways to do it in .NET.

#Option 1: the Serilog sink

If you use Serilog, or are happy to, this is the simplest route. Add the Serilog.AspNetCore and Serilog.Sinks.Datadog.Logs packages:

builder.Services.AddSerilog((services, logger) => logger
    .ReadFrom.Configuration(builder.Configuration)
    .Enrich.FromLogContext()
    .WriteTo.DatadogLogs(
        apiKey: builder.Configuration["Datadog:ApiKey"],
        source: "csharp",
        service: "orders-api",
        host: Environment.MachineName,
        tags: [$"env:{builder.Environment.EnvironmentName.ToLowerInvariant()}", "version:1.4.0"],
        configuration: new DatadogConfiguration
        {
            Url = "https://http-intake.logs.datadoghq.com"
        }));

Your code keeps using ILogger<T> as usual. Serilog sits behind it and batches log events to Datadog over HTTPS on port 443.

Set the URL for your Datadog site. Accounts live in different regions, and each has its own intake address. http-intake.logs.datadoghq.com is for US1; EU accounts use http-intake.logs.datadoghq.eu, and other regions have their own. Check the site in your Datadog URL and the logs documentation if you're unsure. Sending to the wrong site fails quietly.

#Option 2: the Datadog .NET tracer

If you already use Datadog APM, or want it, the .NET tracer can send logs directly too, from plain Microsoft.Extensions.Logging with no Serilog required. Add the Datadog.Trace.Bundle NuGet package, enable automatic instrumentation with the CORECLR_* environment variables from Datadog's setup guide for your OS, and set:

DD_API_KEY=<your API key>
DD_SITE=datadoghq.com
DD_LOGS_DIRECT_SUBMISSION_INTEGRATIONS=ILogger
DD_ENV=production
DD_SERVICE=orders-api
DD_VERSION=1.4.0

DD_LOGS_DIRECT_SUBMISSION_INTEGRATIONS also accepts Serilog, NLog and Log4Net, separated by semicolons. By default it sends Information and above; change that with DD_LOGS_DIRECT_SUBMISSION_MINIMUM_LEVEL, or filter by category under a Datadog key in the Logging section of appsettings.json.

The big advantage is log and trace correlation: the tracer adds trace and span IDs to every log entry, so in Datadog you can jump from a slow request's trace straight to the logs it wrote. Note that this option relies on the tracer's automatic instrumentation, which is more setup than a single NuGet package, and traces themselves are sent separately from logs.

#Make the logs worth searching

Agentless or not, a few habits decide whether the logs are useful:

• Use message templates, not string interpolation. logger.LogInformation("Order {OrderId} shipped", id) sends OrderId as its own attribute. In Datadog, create a facet on it and you can filter and group by order.
• Use unified service tagging. Consistent env, service and version values on logs, traces and metrics let Datadog connect them, and let you compare error rates before and after a deployment.
• Watch volume. Datadog bills by logs ingested and indexed. Send Information and above from production, keep Debug for development, and use exclusion filters in Datadog for noisy entries you don't need to keep.

#Things to know before you rely on it

• Protect the API key. It allows anyone to send data into your account. Keep it in Key Vault or a secret app setting, never in appsettings.json in the repository.
• Logs are sent from your process. They're batched in memory and sent in the background. If Datadog is unreachable for long enough, the queue fills and new entries are dropped, and anything still queued when the process is killed is lost. Flush on shutdown (Log.CloseAndFlush() if you use Serilog's static logger), and keep critical audit records somewhere durable as well.
• There's no local copy. With the Agent approach, a log file stays on disk if the network fails. Agentless trades that resilience for simplicity.

#Takeaway

For App Service, Functions and small containers, agentless logging is the quickest way to get .NET logs into Datadog. Use the Serilog sink for the simplest setup, or the .NET tracer's direct submission if you want APM and log-trace correlation. Either way, point it at the right Datadog site, keep the API key secret, and log with message templates so every value is searchable.

That wasted work adds up under load, and it's easy to avoid. .NET already tells you when the caller has gone. You just have to listen.

#Where the token comes from

In ASP.NET Core, add a CancellationToken parameter to an action or a minimal API handler and the framework binds it to HttpContext.RequestAborted. It is cancelled when the client disconnects.

app.MapGet("/orders/{id:int}", async (int id, OrdersService orders, CancellationToken ct) =>
{
    var order = await orders.GetAsync(id, ct);
    return order is null ? Results.NotFound() : Results.Ok(order);
});

Background services get one too: the stoppingToken passed to ExecuteAsync is cancelled when the host shuts down.

#Pass it through every layer

A token only helps if it reaches the code that does the slow work. Every async method in between should accept one and hand it on:

public async Task<Order?> GetAsync(int id, CancellationToken ct)
{
    var order = await db.Orders.FirstOrDefaultAsync(o => o.Id == id, ct);
    if (order is null) return null;

    order.Shipping = await shippingClient.GetStatusAsync(order.TrackingNumber, ct);
    return order;
}

EF Core, HttpClient, Stream and most Azure SDK clients take a token on their async methods. If one method in the chain doesn't pass it on, everything below that point keeps running after the caller has gone.

#Add your own timeout

Sometimes you want to give up before the caller does, for example when a downstream API is slow. Link a timeout to the incoming token so that either one cancels the work:

using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
cts.CancelAfter(TimeSpan.FromSeconds(5));

var status = await shippingClient.GetStatusAsync(trackingNumber, cts.Token);

#Don't treat cancellation as an error

When a token is cancelled, the awaited call throws OperationCanceledException (or TaskCanceledException, which derives from it). That is expected, so don't log it as a failure or retry it:

catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
    // The caller went away. Nothing to report.
}

The when filter matters. If your own timeout fired instead, ct isn't cancelled, and you probably do want to log that.

Tip: turn on the CA2016 analyzer rule. It flags async calls that could take the token you already have but don't.

#Takeaway

Accept a CancellationToken in every async method and pass it to every call that takes one. It costs one parameter, and your service stops doing work nobody is waiting for.

It happens more often than you'd think. Your handler processes an order, writes to the database, and then crashes, times out or loses its lock before it completes the message. Service Bus sees a message that was never completed and delivers it again. If the handler charges a card or sends an email, the customer gets it twice.

The fix isn't to prevent redelivery. It's to make processing the same message a second time harmless. That property is called idempotency.

#How duplicates happen

With the default peek-lock mode, receiving a message locks it rather than removing it. Your handler has until the lock expires to complete it. If the handler throws, the process dies or the lock runs out first, the message becomes available again and its delivery count goes up. After MaxDeliveryCount attempts (10 by default) it moves to the dead-letter queue.

Duplicates can also start at the sender. If a send times out after the broker has already stored the message, the sender retries and the queue now holds two copies.

Neither kind of duplicate waits politely for the first copy to finish:

• With several instances of your service, or a processor running with MaxConcurrentCalls above 1, two copies of a sender-side duplicate can be picked up within milliseconds of each other.
• If a handler runs past its lock, Service Bus hands the message to another receiver while the first is still working on it. The processor renews locks for you, up to MaxAutoLockRenewalDuration (5 minutes by default), but a slow dependency or a long pause can still outlast it.

So your handler has to be safe not only when the same message comes back later, but when two copies are being processed at the same moment.

#Duplicate detection helps, but only on the way in

Service Bus has a duplicate detection feature. When it's on, the broker drops any message whose MessageId it has already seen within a time window (10 minutes by default, up to 7 days). That stops the sender-side duplicates above, as long as the retry reuses the same MessageId.

It does nothing for redelivery to your receiver. It also has to be turned on when the queue or topic is created. You can't enable it later.

#Why "check, then do the work" isn't enough

The obvious approach is to keep a table of processed message IDs and check it first:

if (await db.ProcessedMessages.AnyAsync(m => m.Id == messageId, ct))
    return; // already handled

// ... do the work, then record the message ID ...

This handles a message that comes back a minute later. It fails when two copies arrive together. Both handlers run the check before either has saved anything, both see "not processed", and both do the work. Any check followed by a separate write has this gap, however fast the code is.

The check and the claim have to be one operation that the database decides, so only one copy can win.

#Claim the message first, and let the database pick the winner

Insert the processed-message record before doing the work, inside the same transaction, and make the message ID its primary key:

processor.ProcessMessageAsync += async args =>
{
    await using var scope = services.CreateAsyncScope();
    var db = scope.ServiceProvider.GetRequiredService<ShippingDb>();
    var order = args.Message.Body.ToObjectFromJson<OrderPlaced>();
    var ct = args.CancellationToken;

    await using var tx = await db.Database.BeginTransactionAsync(ct);
    try
    {
        // 1. Claim the message. The primary key on Id lets only one transaction hold it.
        db.ProcessedMessages.Add(new ProcessedMessage(args.Message.MessageId, DateTimeOffset.UtcNow));
        await db.SaveChangesAsync(ct);

        // 2. Do the work in the same transaction.
        db.Shipments.Add(Shipment.For(order));
        await db.SaveChangesAsync(ct);

        await tx.CommitAsync(ct);
    }
    catch (DbUpdateException ex) when (IsDuplicateKey(ex))
    {
        // Another copy already claimed this message and did the work.
        await tx.RollbackAsync(ct);
    }

    // 3. Complete only after the transaction has finished.
    await args.CompleteMessageAsync(args.Message, ct);
};

static bool IsDuplicateKey(DbUpdateException ex) =>
    ex.InnerException is SqlException { Number: 2627 or 2601 }; // SQL Server

Here's what happens when two copies arrive at the same instant:

1. Both handlers try to insert the same message ID.
2. SQL Server lets the first insert through and makes the second wait on that key until the first transaction finishes.
3. When the first commits, the second insert fails with a duplicate key error. The handler rolls back, having done no work, and completes its copy.
4. If the first handler crashes and rolls back instead, the second insert goes through and that copy does the work. Either way the work happens exactly once.

The database's unique key is the only thing both handlers can see at the same time, which is why it has to make the decision.

A few details matter:

• Use a fresh DbContext for each message, as the scope above does. After a failed SaveChangesAsync, the context still holds the rejected entities, and handlers running in parallel must not share one.
• Create the processor with AutoCompleteMessages = false, so you decide when to complete. Completing before the commit, then crashing, loses the message.
• Senders must set MessageId to something stable, such as the order ID plus the event type. A random ID makes a retried send look like a brand-new message, and none of this can catch it.
• Keep the transaction short. The claim holds a lock until you commit, so the losing copy waits for as long as the work takes.

On MongoDB: use the message ID as the _id of a processed-messages document. A second insert with the same _id fails with duplicate key error 11000. To keep the claim and the work together, run both in a multi-document transaction. That needs a replica set; every MongoDB Atlas cluster is one.

#Add a business-level constraint as a backstop

The message ID protects you from the same message twice. It can't help when the sender publishes the same event twice with different IDs. A unique index on the business key, such as one shipment per order, catches that case as well:

modelBuilder.Entity<Shipment>()
    .HasIndex(s => s.OrderId)
    .IsUnique();

Handle a violation of that index the same way: roll back and complete the message.

#Or process one order at a time with sessions

If messages about the same entity must never be processed in parallel, sessions let Service Bus do the serializing. Set SessionId to the order ID when sending and receive with a ServiceBusSessionProcessor. Only one receiver holds a session at a time, so messages for the same order are handled one after another, in order, while different orders still run in parallel.

Sessions have to be enabled when the queue is created, and they cap throughput per session. They don't replace the claim either: a redelivered message still comes back through the same session. What they remove is the race.

#When the work isn't in your database

Some work can't join your transaction, like calling a payment API. Claiming the message first still stops a second copy from starting, but if your handler crashes after the payment and before the commit, the redelivered message will try again. For those calls, pass an idempotency key to the other system (many payment and email APIs accept one) and build it from the same message ID. Retrying with the same key then returns the original result instead of repeating the action.

#Takeaway

Assume every message can arrive more than once, and sometimes at the same moment. A check followed by a write can't stop two copies racing each other. Claim the message ID with an insert that a unique key protects, do the work in the same transaction, and complete the message only after the commit. Add a unique business key as a backstop, and use sessions when order matters.

#Keep it small and focused

• One change per pull request. A refactor, a bug fix and a new feature are three pull requests, even if you did them together.
• Separate moves from changes. If you rename files or move code, do that in its own pull request, so the reviewer isn't hunting for a logic change inside 40 moved files.
• Aim for something a reviewer can read in one sitting, usually a few hundred lines at most. Large features can be merged in steps behind a feature flag.

#Write a description that answers the reviewer's questions

A reviewer needs to know:

• Why this change exists: the problem or requirement, with a link to the work item
• What changed, in a sentence or two, and anything deliberately left out
• How it was tested, including anything manual
• Risks: migrations, configuration changes, behavior changes for other teams, anything that needs care when deploying

Screenshots for UI changes and example requests and responses for API changes save the reviewer from running the code just to understand it.

#Make it the default with a template

Azure Repos picks up a pull request template from a file such as .azuredevops/pull_request_template.md in the default branch:

## Why
<!-- The problem this solves. Link the work item. -->

## What changed

## How I tested it
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manually verified:

## Deployment notes
<!-- Migrations, new settings, feature flags, anything to watch after release -->

Every new pull request starts with these headings, so writing a good description becomes the easy path.

#Let tools handle the trivia

Reviews shouldn't spend time on formatting or naming conventions. Put those rules in .editorconfig, turn on analyzers, and run dotnet format --verify-no-changes and the build in a build validation branch policy. Machines check the style, so people can focus on design, correctness and risk.

#Reviewing well

• Review the design first, then the details. A comment that the whole approach should change is more useful on day one than after 30 line-level comments.
• Ask questions instead of issuing verdicts: "What happens if this list is empty?" invites a better answer than "This is wrong."
• Label the weight of your comments, so the author knows what blocks approval and what's a suggestion.
• Respond quickly. A pull request waiting two days for review costs more than the review itself.

#Takeaway

Keep pull requests small and focused, explain why, what and how it was tested, and use a template so that's the default. Automate formatting and style checks, and spend review time on design and correctness.

The idea at the core is simple: reading data and changing data have different needs, so don't force them through the same model.

#The problem with one model for both

In a typical layered app, a screen that lists orders loads Order entities through a repository, with their line items and customer, then maps them to a DTO. The domain model was designed to protect business rules when things change. For reading, those rules don't matter, and loading full entities just to build a list is wasted work and wasted joins.

#Commands: through the domain model

Changes go through entities that enforce the rules:

public async Task<Result> CancelOrderAsync(Guid orderId, string reason, CancellationToken ct)
{
    var order = await db.Orders.Include(o => o.Lines).SingleOrDefaultAsync(o => o.Id == orderId, ct);
    if (order is null) return Result.NotFound();

    order.Cancel(reason, time.GetUtcNow());   // invariants live here
    await db.SaveChangesAsync(ct);
    return Result.Success();
}

#Queries: straight to the shape you need

Reads skip the domain model entirely and project directly into what the screen or API returns:

public Task<List<OrderSummary>> GetRecentOrdersAsync(string customerId, CancellationToken ct) =>
    db.Orders
        .AsNoTracking()
        .Where(o => o.CustomerId == customerId)
        .OrderByDescending(o => o.CreatedAt)
        .Take(20)
        .Select(o => new OrderSummary(o.Id, o.CreatedAt, o.Status.ToString(), o.Lines.Sum(l => l.Price * l.Quantity)))
        .ToListAsync(ct);

EF Core translates the projection into a single query that selects only the columns needed. No tracking, no entities, no mapping layer. For complex reports, a raw SQL query or Dapper is equally fine on the read side.

That's CQRS: same database, same DbContext, different paths for reads and writes.

#What you don't need (yet)

• A separate read database. Add a read replica or a denormalized read store only when read load or query complexity actually demands it.
• Event sourcing. It's a separate pattern with its own costs. It pairs well with CQRS, but neither requires the other.
• A mediator library. Commands and queries can be plain methods or handler classes called directly.

#Where it pays off

• Read performance: queries fetch exactly what they need.
• Simpler domain model: entities only need to support changes, not every screen's display needs.
• Clear intent: a method either changes state or returns data, never both, which makes code easier to reason about and test.

#Takeaway

Start CQRS with a simple split in code: commands load entities and change them through the domain model; queries project straight to DTOs with no tracking. Add separate stores, events or libraries only when you have a concrete reason.

#The default: immediate redelivery

When the function fails, the message is abandoned. Its lock is released, its delivery count goes up, and it's available again straight away. The function picks it up again within milliseconds and fails again. That repeats until the delivery count reaches the queue's MaxDeliveryCount (10 by default), at which point the message moves to the dead-letter queue.

So a five-minute outage at the partner turns into ten failures in a couple of seconds and a dead-lettered message. No backoff at all.

Azure Functions has its own retry policies with fixed or exponential delays, but they don't apply to the Service Bus trigger, which relies on Service Bus's delivery count instead.

#Sort failures into three kinds

Permanent failures, such as invalid data or a record that doesn't exist. Retrying won't help. Dead-letter immediately with a reason:

await actions.DeadLetterMessageAsync(message,
    deadLetterReason: "InvalidPayload", deadLetterErrorDescription: ex.Message, cancellationToken: ct);

Brief transient failures, such as a dropped connection or a single timeout. Retry inside the function with a resilience handler on the HttpClient, a few attempts over a few seconds, before the function fails at all.

Longer outages, where you need minutes between attempts. That needs a scheduled retry.

#Scheduled retries

Instead of failing, complete the original message and schedule a copy for later, with an attempt counter in its properties:

catch (HttpRequestException) when (Attempt(message) < 5)
{
    var attempt = Attempt(message) + 1;
    var retry = new ServiceBusMessage(message)   // copies body and properties
    {
        ScheduledEnqueueTime = DateTimeOffset.UtcNow.AddMinutes(Math.Pow(2, attempt))   // 2, 4, 8, 16, 32 minutes
    };
    retry.ApplicationProperties["RetryAttempt"] = attempt;

    await retrySender.SendMessageAsync(retry, ct);
    await actions.CompleteMessageAsync(message, ct);
}

static int Attempt(ServiceBusReceivedMessage m) =>
    m.ApplicationProperties.TryGetValue("RetryAttempt", out var value) ? Convert.ToInt32(value) : 0;

retrySender is a ServiceBusSender for the same queue, registered through dependency injection. After the last attempt, the exception propagates as usual and the message eventually dead-letters.

Two cautions. The copy keeps the original's MessageId, so if duplicate detection is turned on for the queue, give it a new one, such as the original ID plus the attempt number, or the broker drops it as a duplicate. And sending the copy and completing the original aren't atomic, so a crash in between can produce a duplicate. Handlers must be idempotent either way.

#Tune the host

In host.json, under extensions.serviceBus, two settings matter most:

• maxConcurrentCalls limits how many messages each instance processes at once. Lower it if the downstream system can't take the load.
• maxAutoLockRenewalDuration controls how long the host keeps renewing a message's lock. It should comfortably exceed your longest expected processing time, or the message is redelivered while still being processed.

#Takeaway

The Service Bus trigger retries failed messages immediately until the delivery count runs out. Dead-letter permanent failures straight away, retry brief glitches in-process, and schedule delayed copies of the message when you need real backoff.

#1. Is the request well formed? At the edge

Required fields, string lengths, formats and ranges. These checks are about the shape of the input, and they belong where the input arrives: the API endpoint or message handler.

public record PlaceOrderRequest(
    [property: Required] Guid? CustomerId,
    [property: Required, MinLength(1)] List<LineItemRequest> Items,
    [property: EmailAddress] string? ConfirmationEmail);

Data annotations, FluentValidation, or the built-in validation for minimal APIs added in .NET 10 (builder.Services.AddValidation()) all work here. The point is to reject bad requests with a clear 400 before any real work starts.

#2. Does it obey the business rules? In the domain

"An order can't be shipped before it's paid." "A discount can't exceed 50%." "A cancelled subscription can't be renewed." These are invariants: they must hold however the change is made, whether from the API, a background job, a message or an admin tool.

So they belong in the domain model, enforced by the methods that change state:

public void ApplyDiscount(decimal percent)
{
    if (percent is < 0 or > 50)
        throw new DomainException("Discounts must be between 0% and 50%.");
    if (Status != OrderStatus.Draft)
        throw new DomainException("Discounts can only be applied to draft orders.");

    DiscountPercent = percent;
}

If these rules live only in a request validator, the first background job that changes orders directly skips them.

#3. Does it fit the current data? In the application layer

"The customer must exist." "The SKU must be in stock." "The email must not already be registered." These need a database lookup, so they belong in the handler or application service that coordinates the use case. They usually return a not-found or conflict result rather than a validation error.

#4. The last line of defense: the database

Uniqueness checked in code has a race: two requests can both check, both find nothing, and both insert. A unique index in the database is what actually guarantees it. Use constraints, foreign keys and NOT NULL columns as a backstop for the rules that matter most, and translate their violations into proper responses.

#Avoiding duplication

The same rule at several layers isn't always duplication. "Quantity must be at least 1" at the edge gives the user a friendly message, and the domain enforcing it again keeps the model safe from every other caller. What you want to avoid is business rules that exist only at the edge.

#Takeaway

Validate request shape at the edge, enforce business invariants in the domain model, check rules that need current data in the application layer, and back critical guarantees with database constraints.

Templates let you define pipeline steps, jobs or stages once and reference them from every pipeline.

#A step template

Put shared steps in their own file, with parameters for the parts that vary:

# templates/build-dotnet.yml
parameters:
  - name: project
    type: string
  - name: dotnetVersion
    type: string
    default: '10.0.x'
  - name: runTests
    type: boolean
    default: true

steps:
  - task: UseDotNet@2
    inputs:
      version: ${{ parameters.dotnetVersion }}

  - script: dotnet build ${{ parameters.project }} --configuration Release
    displayName: Build

  - ${{ if eq(parameters.runTests, true) }}:
    - script: dotnet test --configuration Release --no-build --collect:"XPlat Code Coverage"
      displayName: Test

  - script: dotnet publish ${{ parameters.project }} --configuration Release --no-build --output $(Build.ArtifactStagingDirectory)
    displayName: Publish

#Use it in a pipeline

# azure-pipelines.yml
trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - template: templates/build-dotnet.yml
    parameters:
      project: src/Orders.Api/Orders.Api.csproj

The pipeline file is now a few lines long and only says what's specific to this service.

#Share templates across repositories

Keep templates in a dedicated repository and reference it as a resource:

resources:
  repositories:
    - repository: templates
      type: git
      name: Platform/pipeline-templates
      ref: refs/tags/v3

steps:
  - template: build-dotnet.yml@templates
    parameters:
      project: src/Orders.Api/Orders.Api.csproj

Pinning ref to a tag means a change to the shared template doesn't break every pipeline at once. Teams move to v4 when they're ready.

#Templates at every level

• Step templates for a sequence of steps, like the build above
• Job templates for a whole job, such as "run integration tests in a container"
• Stage templates for a complete stage, such as "deploy to an environment with approvals and a slot swap"
• Extends templates, where a pipeline extends a central template that controls its overall structure. This is how organizations enforce required steps, such as security scanning, that individual pipelines can't remove.

#Template expressions vs runtime variables

${{ parameters.x }} is resolved when the pipeline is compiled, before anything runs. That's why it can include or exclude whole steps with ${{ if }}. $(variable) is resolved at runtime. Mixing them up is the most common source of confusing template behavior.

#Takeaway

Move shared build and deploy steps into parameterized templates, keep them in their own repository, pin versions, and let each service's pipeline describe only what makes it different.

#Safe changes: add, don't change

Adding an optional field is safe:

// Before
public record OrderPlaced(Guid OrderId, string CustomerId, decimal Total);

// After
public record OrderPlaced(Guid OrderId, string CustomerId, decimal Total, string? Currency = null);

Old consumers don't know about Currency and ignore it: System.Text.Json skips unknown properties by default. New consumers reading old messages get null and must handle that, for example by assuming the currency the old system always used.

#Breaking changes

These break consumers:

• Renaming or removing a field
• Changing a field's type or meaning, such as Total switching from including tax to excluding it
• Making an optional field required

Changing meaning is the most dangerous, because nothing fails. Every consumer keeps working, with wrong numbers.

#Making a breaking change safely

Introduce a new message type and run both for a while:

1. Define OrderPlacedV2 with the new shape.
2. Update the producer to publish both OrderPlaced and OrderPlacedV2 for every order.
3. Each consumer team moves to V2 at its own pace.
4. When no subscriber needs V1 any more, stop publishing it.

Put the type and version where consumers and subscription filters can see them without reading the body:

var message = new ServiceBusMessage(BinaryData.FromObjectAsJson(v2))
{
    Subject = "OrderPlaced",
    MessageId = $"order-placed-v2-{v2.OrderId}"
};
message.ApplicationProperties["MessageType"] = "OrderPlaced";
message.ApplicationProperties["SchemaVersion"] = 2;

#Habits that make this easier

• Be a tolerant reader. Consumers should read only the fields they need and ignore everything else.
• Don't send internal types. Messages built from your entities change whenever the entity does. Define message contracts separately and deliberately.
• Include identifiers and enough context. Consumers that have to call back to you for basic details are coupled to your API as well as your messages.
• Keep contracts in one place, such as a shared contracts package or a schema registry, so changes are visible and reviewed.
• Deploy consumers before producers. When you add a field that consumers must handle, update them first so they're ready when it starts arriving.

#Takeaway

Treat message formats as public contracts. Make additive, optional changes freely, never change a field's meaning silently, and introduce a new versioned message type for breaking changes, publishing both until every consumer has moved.

var parts = line.Split(',');
var sku = parts[0];
var quantity = int.Parse(parts[1]);
var price = decimal.Parse(parts[2], CultureInfo.InvariantCulture);

For each line, Split allocates an array plus one new string per field. Across a file with five million lines, that's tens of millions of short-lived objects for the garbage collector to clean up, most of which you only needed for a moment to parse a number.

#ReadOnlySpan<char>: a view, not a copy

A ReadOnlySpan<char> is a window onto existing memory. Slicing it doesn't copy anything:

ReadOnlySpan<char> line = "ABC-1,3,19.99";

int first = line.IndexOf(',');
ReadOnlySpan<char> sku = line[..first];        // "ABC-1", no new string
ReadOnlySpan<char> rest = line[(first + 1)..];

Most parsing methods accept spans directly:

int quantity = int.Parse(rest[..rest.IndexOf(',')]);

#Splitting into ranges

Since .NET 8, MemoryExtensions.Split writes the positions of each field into a Span<Range> you provide, instead of creating strings:

static OrderLine ParseLine(ReadOnlySpan<char> line)
{
    Span<Range> fields = stackalloc Range[4];
    int count = line.Split(fields, ',');
    if (count != 3)
        throw new FormatException($"Expected 3 fields, found {count}.");

    return new OrderLine(
        Sku: line[fields[0]].ToString(),   // allocate only for the value you keep
        Quantity: int.Parse(line[fields[1]]),
        Price: decimal.Parse(line[fields[2]], CultureInfo.InvariantCulture));
}

The only allocation left is the SKU string, because the result needs to keep it. The numbers are parsed straight from the original text. (The range span has one extra slot so a line with too many fields is detected rather than silently merged into the last field.)

#Where spans can't go

Span<T> is a ref struct: it can only live on the stack. You can't store one in a field of a class, capture it in a lambda, or keep it across an await. Parse synchronously, line by line, inside a non-async method, and keep your async code at the level of reading lines from the stream.

#Is it worth it?

For a config file or an API response, no: readability wins, and string.Split is fine. Spans pay off when you parse a lot of text repeatedly, such as large import files, high-volume message processing or hot request paths. Measure first with BenchmarkDotNet or a memory profiler, and optimize where the allocations actually are.

#Real CSV is harder

Simple splitting breaks on quoted fields containing commas, escaped quotes and embedded line breaks. For real-world CSV, use a proper parser such as CsvHelper or Sep, which are themselves built on these techniques.

#Takeaway

When parsing large volumes of text, slice ReadOnlySpan<char> instead of creating substrings, parse numbers directly from spans, and only allocate strings for values you keep. Keep it for measured hot paths, and use a real CSV library for real CSV.

#Create indexes from code

The C# driver can create indexes with strongly typed definitions:

var orders = database.GetCollection<Order>("orders");

var byCustomerAndDate = new CreateIndexModel<Order>(
    Builders<Order>.IndexKeys
        .Ascending(o => o.CustomerId)
        .Descending(o => o.CreatedAt),
    new CreateIndexOptions { Name = "customer_createdAt" });

var uniqueExternalId = new CreateIndexModel<Order>(
    Builders<Order>.IndexKeys.Ascending(o => o.ExternalId),
    new CreateIndexOptions { Name = "externalId_unique", Unique = true });

await orders.Indexes.CreateManyAsync([byCustomerAndDate, uniqueExternalId], ct);

Creating an index that already exists with the same definition does nothing, so running this at startup or from a deployment step is safe. For large collections, prefer a deployment step, since building a new index takes time and resources.

#Order compound index fields well

For a compound index, the order of fields matters. A useful guideline is ESR: Equality, Sort, Range:

1. Fields you match exactly first, such as CustomerId
2. Then fields you sort by, such as CreatedAt
3. Then fields you filter by range, such as Total > 100

The index above serves this query perfectly:

var recent = await orders
    .Find(o => o.CustomerId == customerId)
    .SortByDescending(o => o.CreatedAt)
    .Limit(20)
    .ToListAsync(ct);

MongoDB finds the customer's entries in the index, already in date order, and stops after 20. No sorting in memory and no scanning.

#Check that the index is used

Ask MongoDB how it runs the query. In mongosh or MongoDB Compass:

db.orders.find({ CustomerId: "C-42" }).sort({ CreatedAt: -1 }).limit(20).explain("executionStats")

Look for:

• IXSCAN in the winning plan: an index was used. COLLSCAN means a full collection scan.
• totalDocsExamined close to nReturned. Examining 50,000 documents to return 20 means the index doesn't fit the query.

If you use MongoDB Atlas, its Performance Advisor watches slow queries and suggests indexes for them.

#Useful index options

• Unique indexes enforce business rules, such as one order per external ID, and protect you from duplicate inserts.
• TTL indexes delete documents automatically after a period, which is ideal for logs, idempotency keys and other temporary data: new CreateIndexOptions { ExpireAfter = TimeSpan.FromDays(7) } on a date field.

#Don't index everything

Every index has to be updated on every write and takes memory. Index the queries your application actually runs often, and remove indexes that aren't used.

#Takeaway

Create indexes from code for the queries you run often, order compound index fields by equality, then sort, then range, and use explain to confirm queries use them. Unique and TTL indexes also enforce rules and clean up data for you.

That plan has a track record. The rewrite takes longer than expected, the old system keeps changing while you build, and the cutover day reveals all the behavior nobody knew about.

#The strangler fig

The strangler fig pattern, named by Martin Fowler after a vine that slowly grows around a tree until it replaces it, takes the opposite approach:

1. Put a routing layer in front of the legacy system. At first it sends everything to the old app.
2. Build one piece of functionality in the new system.
3. Route just that piece to the new system.
4. Repeat until nothing goes to the old system, then switch it off.

At every step you have a working system in production, and each step is small enough to roll back.

#The routing layer with YARP

For web apps, a reverse proxy is the natural router, and YARP (Yet Another Reverse Proxy) runs inside an ASP.NET Core app:

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapControllers();      // routes the new app handles itself
app.MapReverseProxy();     // everything else goes to the legacy app

app.Run();

{
  "ReverseProxy": {
    "Routes": {
      "legacy": { "ClusterId": "legacy", "Match": { "Path": "{**catch-all}" }, "Order": 1000 }
    },
    "Clusters": {
      "legacy": { "Destinations": { "main": { "Address": "https://legacy.internal.example.com/" } } }
    }
  }
}

The new ASP.NET Core app is the front door. Endpoints it implements are handled directly, and the catch-all route with a high Order value proxies everything else to the old app. Moving a feature is a matter of implementing its endpoints. Microsoft uses the same approach in its guidance for incrementally migrating ASP.NET Framework apps to ASP.NET Core.

#Pick the order carefully

• Start with something small and low-risk to prove the routing, deployment and monitoring work.
• Then go after the areas that change most often. That's where the old system costs you most, and where the new one pays off soonest.
• Leave stable, rarely touched areas for last. Some may never be worth moving.

#The hard part is data

Routing requests is easy. Shared data is hard. While both systems run, they often need the same database. Options include letting the new system read and write the legacy database at first, then moving each area's tables to the new system's database along with its feature. Whatever you choose, decide for each table which system owns it at each stage.

Shared concerns such as login and sessions need a plan too, so users don't notice which system served a page.

#Takeaway

Don't rewrite a legacy system in one go. Put a routing layer in front of it, move features across one route at a time, starting small, and plan data ownership as carefully as the code. You deliver value continuously, and every step can be rolled back.

#Know your defaults

Those are generous fallbacks, not good choices. If your own API promises a response in 5 seconds, a 100-second call inside it makes no sense.

#Work backwards from the caller

Start with how long the caller of your service will wait, and budget from there. If an API endpoint should respond within 10 seconds and calls two dependencies in sequence, each call gets well under 5 seconds, including any retries.

The rule: every timeout must be shorter than the one waiting on it. Otherwise your caller gives up, but your service keeps working on a response nobody will read.

#Layer the timeouts for HTTP

With the resilience handler there are two timeouts that matter:

• Attempt timeout: how long a single try may take.
• Total timeout: how long the whole operation, including retries and their delays, may take.

builder.Services.AddHttpClient<PricingClient>()
    .AddStandardResilienceHandler(options =>
    {
        options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(2);
        options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(6);
        options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(10); // must be at least twice the attempt timeout
    });

Watch out for HttpClient.Timeout itself. It wraps the entire handler pipeline, retries included, so if it's shorter than the total resilience timeout it cuts the retries off. With a resilience handler, leave it at its default or set it higher than the total timeout, and let the handler do the timing.

#Pass cancellation through

A timeout in one place should stop work everywhere below it. Accept a CancellationToken and pass it to every async call, so when a request times out or the caller disconnects, the database query and downstream calls are cancelled too, rather than finishing for nobody.

For your own deadline inside a method:

using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
cts.CancelAfter(TimeSpan.FromSeconds(3));

var prices = await pricing.GetPricesAsync(skus, cts.Token);

#Don't forget the database

EF Core's command timeout applies per command. For a known slow report, raise it for that query only, rather than globally:

db.Database.SetCommandTimeout(TimeSpan.FromMinutes(2));

And if a normal request regularly needs more than a few seconds of database time, the fix is usually an index or a different query, not a longer timeout.

#Takeaway

Never rely on default timeouts. Budget from what your caller will wait, make each inner timeout shorter than the one around it, set attempt and total timeouts on HTTP calls, and pass cancellation tokens all the way down.

#Switch expressions

decimal ShippingCost(Order order) => order switch
{
    { Total: >= 100m } => 0m,
    { Destination.Country: "US", Express: true } => 25m,
    { Destination.Country: "US" } => 8m,
    { Express: true } => 60m,
    _ => 30m
};

Each line is one rule, checked top to bottom, and the first match wins. That example combines several pattern types.

#Property patterns

{ Total: >= 100m } matches when Total is at least 100. Patterns can reach into nested properties with a dot, as in { Destination.Country: "US" }, and several properties in one pattern must all match.

#Relational and logical patterns

Comparisons and and, or, not let you express ranges directly:

string RiskBand(int score) => score switch
{
    < 0 or > 1000 => throw new ArgumentOutOfRangeException(nameof(score)),
    >= 800 => "Low",
    >= 500 => "Medium",
    _ => "High"
};

is not null is the clearest null check in C# for the same reason:

if (order.Coupon is not null) { /* ... */ }

#Type patterns with conditions

Handling different message types is a natural fit:

Task HandleAsync(object message, CancellationToken ct) => message switch
{
    OrderPlaced { Total: > 10_000m } large => fraudCheck.ReviewAsync(large, ct),
    OrderPlaced placed => fulfillment.StartAsync(placed, ct),
    OrderCancelled cancelled => fulfillment.StopAsync(cancelled.OrderId, ct),
    _ => throw new NotSupportedException($"Unknown message {message.GetType().Name}")
};

#List patterns

Since C# 11 you can match on the shape of arrays and lists:

string Describe(string[] parts) => parts switch
{
    [] => "empty",
    [var only] => $"just {only}",
    [var first, .., var last] => $"from {first} to {last}"
};

That's handy for parsing simple command formats or CSV lines without index arithmetic.

#Let the compiler check exhaustiveness

If a switch expression on an enum doesn't handle every value, the compiler warns you (CS8509). Add a value to the enum later and every switch that forgot it gets flagged. Avoid a catch-all _ arm on enums when you want that safety net.

#Know when to stop

A switch with fifteen arms and three levels of nested patterns isn't more readable than the if statements it replaced. If a rule needs a comment to explain it, give it a well-named method or variable instead.

#Takeaway

Use switch expressions with property, relational and list patterns to write business rules as a list of cases that reads like the requirement. Let the compiler check that you've covered every case, and keep each pattern simple enough to read at a glance.

A feature flag is a switch your code checks at runtime. Deploy the code with the flag off, turn it on when you're ready, and turn it off again in seconds if something goes wrong.

#Setting it up

Store flags in Azure App Configuration and read them with the feature management libraries:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri("https://my-config.azconfig.io"), new DefaultAzureCredential())
           .UseFeatureFlags(flags => flags.SetRefreshInterval(TimeSpan.FromSeconds(30)));
});

builder.Services.AddAzureAppConfiguration();
builder.Services.AddFeatureManagement();

var app = builder.Build();
app.UseAzureAppConfiguration();   // refreshes flags as requests come in

The packages are Microsoft.Azure.AppConfiguration.AspNetCore and Microsoft.FeatureManagement.AspNetCore.

#Checking a flag

app.MapGet("/quotes/{id}", async (Guid id, IFeatureManager features, QuoteService quotes) =>
{
    var quote = await features.IsEnabledAsync("NewPricingEngine")
        ? await quotes.PriceWithNewEngineAsync(id)
        : await quotes.PriceAsync(id);

    return Results.Ok(quote);
});

For MVC controllers or actions, [FeatureGate("NewPricingEngine")] returns a 404 while the flag is off.

#Rolling out gradually

A flag doesn't have to be all or nothing. Built-in filters let you enable it for:

• A percentage of requests, for example 10%, then 50%, then 100%
• Specific users or groups, through the targeting filter, such as internal staff first
• A time window, such as a promotion that switches itself on and off

You change these in the App Configuration portal, and apps pick up the change at their next refresh, within the interval you set.

#The kill switch

Flags aren't only for new features. Wrapping a risky integration, such as a call to a new partner API, in a flag gives you an off switch that works faster than any deployment and doesn't need a developer.

#Clean up

Every flag is an if statement with two code paths to test and maintain. Once a feature is fully rolled out and stable, remove the flag and the old code path. Keep a short list of active flags with an owner and an expected removal date, or they accumulate for years.

#Takeaway

Use feature flags to separate deploying code from releasing it. Store them in Azure App Configuration, roll features out gradually to a percentage or a group of users, keep a kill switch around risky integrations, and remove flags once they've done their job.

Six months later, those names and codes are in your services, your database and your business rules. Then the CRM team renames a status, or you switch CRM vendors, and you're changing code everywhere.

#Translate at the edge

An anti-corruption layer (a term from Domain-Driven Design) is a thin piece of code at the boundary that translates between an external system's model and yours. Nothing outside it knows the external model exists.

// The CRM's shape, internal to the integration
internal record CrmAccountDto(string Id, string Name, string Acct_Status__c, string? Created_Date);

// Your shape, used everywhere else
public record Customer(CustomerId Id, string Name, CustomerStatus Status, DateOnly? Since);

public enum CustomerStatus { Prospect, Active, Suspended, Closed }

public class CrmCustomerSource(CrmClient crm) : ICustomerSource
{
    public async Task<Customer?> GetAsync(CustomerId id, CancellationToken ct)
    {
        var dto = await crm.GetAccountAsync(id.Value, ct);
        return dto is null ? null : ToCustomer(dto);
    }

    internal static Customer ToCustomer(CrmAccountDto dto) => new(
        new CustomerId(dto.Id),
        dto.Name.Trim(),
        dto.Acct_Status__c switch
        {
            "Prospect - Cold" or "Prospect - Warm" => CustomerStatus.Prospect,
            "Customer" => CustomerStatus.Active,
            "On Hold" => CustomerStatus.Suspended,
            "Churned" => CustomerStatus.Closed,
            var unknown => throw new UnknownCrmStatusException(unknown)
        },
        DateOnly.TryParse(dto.Created_Date, out var date) ? date : null);
}

The rest of your code depends on ICustomerSource and Customer. It never sees Acct_Status__c.

#What the layer is responsible for

• Names and shapes. Map external fields to your own names and types.
• Codes and statuses. Collapse their status values into yours, and decide explicitly what happens with values you don't recognize. Failing loudly is usually better than silently guessing.
• Formats. Parse dates, numbers and currencies once, here.
• Quirks. Trim whitespace, treat empty strings as missing, handle the field that's sometimes a string and sometimes a number.

#Test the mapping

The translation is pure code, which makes it easy to test thoroughly. Keep a few real (anonymized) API responses as test fixtures and assert on the domain objects they produce. When the external API changes, these tests tell you exactly what broke.

#When it's worth it

Not every integration needs a formal layer. If an external API is simple, stable and its model already matches yours, a small DTO and a mapping method may be all you need. The more the external model differs from yours, and the more likely it is to change or be replaced, the more the boundary pays off.

#Takeaway

Don't let external systems' models leak into your code. Translate their data into your own types at the boundary, handle unknown values deliberately, and test the mapping with real responses. When they change, only the boundary changes.

For years every codebase invented its own IClock or ISystemClock. Since .NET 8 there's a standard one: TimeProvider.

#Use it in your code

Inject TimeProvider and ask it for the time:

public class InvoiceService(TimeProvider time)
{
    public bool IsOverdue(Invoice invoice) =>
        time.GetUtcNow() > invoice.DueDate.AddDays(30);
}

Register the real one once:

builder.Services.AddSingleton(TimeProvider.System);

#Use the fake in tests

The Microsoft.Extensions.TimeProvider.Testing package includes FakeTimeProvider, which you control:

[Fact]
public void Invoice_becomes_overdue_after_30_days()
{
    var time = new FakeTimeProvider(new DateTimeOffset(2026, 6, 1, 0, 0, 0, TimeSpan.Zero));
    var service = new InvoiceService(time);
    var invoice = new Invoice { DueDate = new DateTimeOffset(2026, 6, 1, 0, 0, 0, TimeSpan.Zero) };

    time.Advance(TimeSpan.FromDays(30));
    Assert.False(service.IsOverdue(invoice));

    time.Advance(TimeSpan.FromSeconds(1));
    Assert.True(service.IsOverdue(invoice));
}

The test runs in microseconds and gives the same result every time.

#It covers delays and timers too

TimeProvider isn't just "what time is it". Timers and delays can use it as well:

await Task.Delay(TimeSpan.FromMinutes(5), time, ct);

using var timer = new PeriodicTimer(TimeSpan.FromMinutes(1), time);

With FakeTimeProvider, those waits complete when you call Advance, so you can test retry delays, polling loops and timeouts without actually waiting.

#Watch for the hidden calls

Switching to TimeProvider only helps if you switch everywhere. Search the code for DateTime.Now, DateTime.UtcNow, DateTimeOffset.UtcNow and plain Task.Delay calls. A banned-API analyzer rule (Microsoft.CodeAnalysis.BannedApiAnalyzers) can stop new ones from creeping back in.

While you're there: prefer DateTimeOffset and UTC for anything stored or compared. DateTime.Now depends on the server's time zone, which is a different source of bugs.

#Takeaway

Inject TimeProvider instead of reading the clock directly, register TimeProvider.System in production, and use FakeTimeProvider in tests to move time forward on demand. Time-dependent logic becomes fast and reliable to test.

Deployment slots fix both. A slot is a separate, live copy of your app, such as staging, with its own hostname, running on the same App Service plan. They're available on the Standard tier and above, and also for Azure Functions.

#The flow

1. Deploy to the staging slot. Production keeps serving traffic untouched.
2. Warm it up and check it. Hit the staging URL, run smoke tests, check the health endpoint.
3. Swap. App Service warms up the staging instances, then switches the routing so staging becomes production. Users don't see a restart.
4. If something's wrong, swap back. The previous version is still sitting in the other slot, already warm. Rollback takes seconds.

#In Azure Pipelines

- task: AzureWebApp@1
  inputs:
    azureSubscription: 'my-service-connection'
    appType: 'webApp'
    appName: 'orders-api'
    deployToSlotOrASE: true
    resourceGroupName: 'orders-rg'
    slotName: 'staging'
    package: '$(Pipeline.Workspace)/drop/*.zip'

- script: curl --fail --retry 5 --retry-delay 10 https://orders-api-staging.azurewebsites.net/health/ready
  displayName: Smoke test staging

- task: AzureAppServiceManage@0
  inputs:
    azureSubscription: 'my-service-connection'
    Action: 'Swap Slots'
    WebAppName: 'orders-api'
    ResourceGroupName: 'orders-rg'
    SourceSlot: 'staging'

#Sticky settings

When slots swap, their app settings swap too, by default. That's usually what you want for most settings, but not for everything. Some must stay with the slot, such as a connection string pointing staging at a test database, or a flag that turns off scheduled jobs in staging.

Mark those as deployment slot settings (the checkbox in Configuration, or slotSetting: true in infrastructure code). They stay put while the code moves.

Check this carefully before your first swap. A staging connection string that follows the code into production is a very bad afternoon.

#Warm-up

App Service sends requests to the staging instances before swapping, so the first real user doesn't pay the startup cost. You can point the warm-up at a specific path, such as a health endpoint, with the WEBSITE_SWAP_WARMUP_PING_PATH app setting, and set WEBSITE_SWAP_WARMUP_PING_STATUSES to the status codes that count as ready.

#Things to watch

• Background work runs in both slots. Timer-triggered functions and hosted services in staging run too, unless you turn them off with a sticky setting.
• Database migrations aren't swapped. Schema changes apply to the shared database before the swap, so they must work with both the old and new code.
• Slots share the plan's resources. A heavy smoke test in staging competes with production for CPU and memory.

#Takeaway

Deploy to a staging slot, verify it, then swap. Mark environment-specific settings as slot settings, keep migrations backward-compatible, and keep the previous version in the other slot as your instant rollback.

#Domain events: inside the boundary

A domain event records something that happened in your domain model, for other parts of the same service or module to react to:

public record OrderShipped(Guid OrderId, DateTimeOffset ShippedAt) : IDomainEvent;

public class Order
{
    private readonly List<IDomainEvent> _events = [];
    public IReadOnlyList<IDomainEvent> Events => _events;

    public void Ship(DateTimeOffset now)
    {
        if (Status != OrderStatus.Paid)
            throw new InvalidOperationException("Only paid orders can be shipped.");

        Status = OrderStatus.Shipped;
        _events.Add(new OrderShipped(Id, now));
    }
}

Handlers run in-process, often just before or after SaveChanges, for example from an EF Core interceptor that dispatches each entity's events. They can update another aggregate, write an audit entry or schedule work. They're free to use internal types, because no one outside the service sees them, and you can change them whenever you like.

#Integration events: across boundaries

An integration event tells other services something happened. It travels through a message broker such as Service Bus, and it's a published contract:

// In a shared contracts package
public record OrderShippedV1(Guid OrderId, string CustomerId, string Carrier, DateTimeOffset ShippedAt);

Different rules apply:

• It's a public API. Other teams depend on its shape. Changing it needs versioning and a migration plan.
• It contains only what consumers need, using simple types, not your internal entities or value objects.
• It must be published reliably, typically through an outbox, so it's never lost if the publish fails after the database commit.
• Consumers receive it at least once, later, and possibly out of order.

#How they connect

The common pattern: a domain event handler translates the domain event into an integration event and writes it to the outbox, in the same transaction.

public class PublishOrderShipped(OrdersDb db) : IDomainEventHandler<OrderShipped>
{
    public Task HandleAsync(OrderShipped e, CancellationToken ct)
    {
        var order = db.Orders.Local.Single(o => o.Id == e.OrderId);
        db.Outbox.Add(OutboxMessage.From(
            new OrderShippedV1(order.Id, order.CustomerId, order.Carrier, e.ShippedAt)));
        return Task.CompletedTask;
    }
}

Not every domain event becomes an integration event. Most stay internal. Publishing externally is a deliberate decision about what other services should know.

#The mistake to avoid

Publishing domain events directly to the broker feels efficient: one event type, no translation. But now other services depend on your domain model's internal structure. Renaming a property in your entity becomes a breaking change for three other teams, and the boundary you designed exists only on paper.

#Takeaway

Use domain events to react to changes inside a service, and change them freely. Use integration events, published reliably through an outbox and versioned like an API, to tell other services what happened. Translate between the two on purpose.

By default, a new subscription receives every message sent to the topic. Often that's not what you want: the EU warehouse only cares about EU orders, and the fraud check only about orders over a certain value. Filtering in each consumer's code works, but it wastes delivery and processing on messages that are thrown away. Subscription filters do it in the broker.

#Filters work on properties, not the body

Service Bus never looks inside the message body. Filters evaluate the message's system properties and its application properties, so the publisher sets those for anything subscribers might route on:

var message = new ServiceBusMessage(BinaryData.FromObjectAsJson(orderPlaced))
{
    Subject = "OrderPlaced",
    MessageId = $"order-placed-{orderPlaced.OrderId}"
};
message.ApplicationProperties["Region"] = orderPlaced.Region;   // "EU", "US", ...
message.ApplicationProperties["Total"] = orderPlaced.Total;

await sender.SendMessageAsync(message, ct);

#Two kinds of filter

Correlation filters match exact values on properties. They're the most efficient and cover most cases:

await admin.CreateRuleAsync("orders", "eu-warehouse", new CreateRuleOptions("eu-orders",
    new CorrelationRuleFilter { Subject = "OrderPlaced", ApplicationProperties = { ["Region"] = "EU" } }));

SQL filters allow conditions with comparisons, AND, OR, IN and more:

await admin.CreateRuleAsync("orders", "fraud-check", new CreateRuleOptions("large-orders",
    new SqlRuleFilter("Total > 5000 AND Region IN ('EU', 'US')")));

admin is a ServiceBusAdministrationClient.

#Remove the default rule

Every new subscription starts with a rule named $Default that matches everything. A message is delivered if any rule matches, so adding your filter without removing the default changes nothing:

await admin.DeleteRuleAsync("orders", "eu-warehouse", RuleProperties.DefaultRuleName);

Better still, define subscriptions and their rules in your infrastructure code, such as Bicep or Terraform, so they're created correctly from the start and reviewed like any other change.

#Design tips

• Decide routing properties up front and treat them as part of the message contract, like the body.
• Prefer correlation filters. Use SQL filters only when you need comparisons or combinations.
• Watch for messages no subscription wants. If no filter matches, the message is simply dropped. That might be fine, or it might hide a bug.

#Takeaway

Use a topic when several consumers need the same events, put routing information in application properties, and give each subscription a filter, removing the $Default rule, so each consumer gets only the messages it actually handles.

#What it actually does

When you await a task, the code after the await resumes on the captured synchronization context, if there is one. In a WinForms or WPF app, that's the UI thread. In classic ASP.NET on .NET Framework, it's the request context.

ConfigureAwait(false) says "I don't need to come back to that context; resume on any thread pool thread." That avoids the cost of switching back, and it avoids a classic deadlock: code that blocks on an async method with .Result while holding the context the method is waiting to resume on.

#ASP.NET Core has no synchronization context

ASP.NET Core doesn't install a SynchronizationContext. Continuations already run on the thread pool, so ConfigureAwait(false) changes nothing there. The same is true for console apps, worker services and Azure Functions.

So in application code that only runs in those hosts, such as your controllers, handlers and services, you can leave it out. It's noise.

#Libraries still need it

If you write a library, such as a NuGet package or a shared client used across teams, you don't know where it will run. Someone might call it from a WPF app, or from an old ASP.NET application that blocks on .Result. Using ConfigureAwait(false) on every await in the library protects those callers from deadlocks and avoids needless context switches.

public async Task<Customer?> GetCustomerAsync(string id, CancellationToken ct = default)
{
    using var response = await _http.GetAsync($"customers/{id}", ct).ConfigureAwait(false);
    if (response.StatusCode == HttpStatusCode.NotFound) return null;

    response.EnsureSuccessStatusCode();
    return await response.Content.ReadFromJsonAsync<Customer>(ct).ConfigureAwait(false);
}

The analyzer rule CA2007 flags missing ConfigureAwait calls. Turn it on in library projects only.

#The real fix for deadlocks

ConfigureAwait(false) in a library protects callers who block on async code. The better fix is not to block at all: async all the way up, no .Result and no .Wait(). In ASP.NET Core, blocking doesn't deadlock, but it still ties up thread pool threads and hurts throughput under load.

#A newer option

Since .NET 8, Task.ConfigureAwait also accepts ConfigureAwaitOptions. For example, ConfigureAwaitOptions.SuppressThrowing lets you await a task purely to wait for it to finish, without rethrowing its exception. That's handy when shutting down background work.

#Takeaway

In ASP.NET Core, worker and Functions application code, skip ConfigureAwait(false). In reusable libraries, keep using it on every await. Either way, don't block on async code with .Result or .Wait().

How that token is signed matters more than most people realize.

#Two kinds of SAS

• Account key SAS (service SAS). Signed with the storage account's access key. To revoke a leaked token early, you have to rotate the key, which breaks everything else using it. It also means your app needs the key in the first place.
• User delegation SAS. Signed with a user delegation key that your app obtains with its Entra ID identity, such as a managed identity. No account key involved, the delegation key is valid for at most seven days, and access is logged against the identity that created it.

If your app already uses managed identity, user delegation SAS is the natural choice. You can then turn off shared key access on the storage account entirely.

#Creating one

var service = new BlobServiceClient(
    new Uri("https://mystorage.blob.core.windows.net"), new DefaultAzureCredential());

var now = DateTimeOffset.UtcNow;
UserDelegationKey key = await service.GetUserDelegationKeyAsync(
    startsOn: now.AddMinutes(-5), expiresOn: now.AddHours(1));

var sas = new BlobSasBuilder
{
    BlobContainerName = "invoices",
    BlobName = "2026/05/INV-1042.pdf",
    Resource = "b",                          // a single blob
    StartsOn = now.AddMinutes(-5),           // allow for clock differences
    ExpiresOn = now.AddMinutes(15),
    Protocol = SasProtocol.Https
};
sas.SetPermissions(BlobSasPermissions.Read);

var uri = new BlobUriBuilder(service.Uri)
{
    BlobContainerName = sas.BlobContainerName,
    BlobName = sas.BlobName,
    Sas = sas.ToSasQueryParameters(key, service.AccountName)
}.ToUri();

The app's identity needs permission to request delegation keys. The Storage Blob Data Contributor role includes it; the narrower Storage Blob Delegator role grants just that permission.

You can cache the user delegation key and reuse it for many SAS tokens until it expires, rather than requesting a new one for every download.

#Keep tokens tight

• Short expiry. Minutes for a download link, not days. The client can always ask for a new one.
• One blob, minimum permissions. Read on a single blob, not Read and List on the container.
• HTTPS only.
• Start slightly in the past, a few minutes, so small clock differences don't make a fresh token look not yet valid.

#Takeaway

When you hand out blob access, use a user delegation SAS signed with your app's managed identity instead of the account key. Scope it to one blob, give it read-only access and a short lifetime, and turn off shared key access on the account once nothing depends on it.

The EF Core in-memory provider doesn't catch those either. It isn't a relational database: no constraints, no transactions, no SQL translation. Microsoft's own guidance discourages using it for testing.

The better option is to run tests against a real database in a container.

#The pieces

• WebApplicationFactory<Program> (from Microsoft.AspNetCore.Mvc.Testing) starts your real API in memory, with its real startup, middleware and dependency injection, and gives you an HttpClient to call it.
• Testcontainers (the Testcontainers.MsSql package, with others for PostgreSQL, MongoDB and more) starts a disposable database container for the test run and removes it afterwards.

#Setting it up with xUnit

public class ApiFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    private readonly MsSqlContainer _sql = new MsSqlBuilder()
        .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
        .Build();

    public async Task InitializeAsync()
    {
        await _sql.StartAsync();

        using var scope = Services.CreateScope();
        var db = scope.ServiceProvider.GetRequiredService<OrdersDb>();
        await db.Database.MigrateAsync();
    }

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureTestServices(services =>
        {
            services.RemoveAll<DbContextOptions<OrdersDb>>();
            services.AddDbContext<OrdersDb>(o => o.UseSqlServer(_sql.GetConnectionString()));
        });
    }

    public new async Task DisposeAsync() => await _sql.DisposeAsync();
}

A test then calls the API like a real client would:

public class PlaceOrderTests(ApiFactory factory) : IClassFixture<ApiFactory>
{
    [Fact]
    public async Task Placing_an_order_returns_its_location()
    {
        var client = factory.CreateClient();

        var response = await client.PostAsJsonAsync("/orders", new
        {
            customerId = Guid.NewGuid(),
            items = new[] { new { sku = "ABC-1", quantity = 2 } }
        });

        Assert.Equal(HttpStatusCode.Created, response.StatusCode);
        Assert.NotNull(response.Headers.Location);
    }
}

With top-level statements, add public partial class Program { } at the end of Program.cs so the test project can reference it.

#Keeping it fast

• Share one container per test class or the whole test run with fixtures, rather than one per test. Starting SQL Server takes seconds; running a test takes milliseconds.
• Run migrations, not EnsureCreated, so the tests also prove your migrations work.
• Isolate data between tests, by using unique IDs per test or resetting tables between tests. The Respawn library can wipe data quickly while keeping the schema.

#Replace only what's outside your control

Use real infrastructure you own, like the database. Replace third-party APIs with fakes in ConfigureTestServices, or with a stub HTTP server such as WireMock.Net, so tests don't depend on someone else's sandbox being up.

#In the pipeline

Testcontainers needs Docker. Microsoft-hosted Linux agents in Azure Pipelines, such as ubuntu-latest, have it available, so the same tests run in CI with no extra setup.

#Takeaway

Test your API the way it runs in production: start it with WebApplicationFactory, point it at a real database in a container, and fake only the services you don't own. These tests catch the bugs mocks and in-memory providers miss.

They can't know whether the first request worked, so they can't safely decide whether to retry. The fix has to come from your API.

#The idea

The client generates a unique key, usually a GUID, for each logical operation and sends it in a header:

POST /payments
Idempotency-Key: 6f1c2f4e-0d5b-4a8e-9a77-3e3c0f5d8b21
Content-Type: application/json

The first time your API sees that key, it does the work and saves the response alongside the key. If the same key arrives again, it skips the work and returns the saved response. Retries become safe, however many there are.

Payment providers have worked this way for years, and there's an IETF draft standardizing the Idempotency-Key header.

#Store keys in your database

public class IdempotencyRecord
{
    public required string Key { get; init; }          // primary key
    public required string RequestHash { get; init; }
    public int? StatusCode { get; set; }
    public string? ResponseBody { get; set; }
    public DateTimeOffset CreatedAt { get; init; }
}

The flow for each request:

1. No key? Reject with 400, or process normally if keys are optional for this endpoint.
2. Try to insert a record with the key and a hash of the request body. The primary key on Key makes this atomic: if two identical retries arrive at the same moment, only one insert succeeds.
3. Insert succeeded: do the work, then store the status code and response body on the record.
4. Insert failed because the key exists: - Response saved: return it as-is. - No response yet: the original request is still running. Return 409 Conflict so the client tries again shortly. - Different request hash: the client reused a key for a different request. Return 422 Unprocessable Content.

Putting the record insert and the business work in the same database transaction keeps them consistent: if the work fails and rolls back, the key isn't left behind as "in progress".

#Practical details

• Scope keys per client, for example by combining them with the caller's ID, so two clients can't collide.
• Expire old keys after a day or so. Retries happen within seconds or minutes, not weeks.
• Only cache meaningful outcomes. If the request failed with a 500, don't store it; let the retry try again.
• Document it. Tell clients to generate one key per operation and reuse it only for retries of that operation.

#Takeaway

Any POST that creates something, especially money movements or orders, should accept an idempotency key. Claim the key atomically, store the response with it, and return the saved response on retries. Your clients can then retry safely, and duplicates stop being your problem.

public class OrderService(OrdersDb db, ILogger<OrderService> logger)
{
    public async Task CancelAsync(Guid id, CancellationToken ct)
    {
        var order = await db.Orders.FindAsync([id], ct);
        logger.LogInformation("Cancelling order {OrderId}", id);
        // ...
    }
}

No private fields, no constructor body, no assignments. It's a clear improvement. But primary constructor parameters on a class behave differently from what you might assume.

#1. They aren't readonly

Parameters are captured as mutable state. Nothing stops this:

public class OrderService(OrdersDb db)
{
    public void Reset() => db = null!;   // compiles
}

You'd never write that on purpose, but an accidental reassignment can slip through review. If immutability matters, assign the parameter to a readonly field:

public class OrderService(OrdersDb db)
{
    private readonly OrdersDb _db = db;
}

Then use only _db in the class body.

#2. Using both the parameter and a field stores it twice

If you initialize a field from the parameter and also use the parameter elsewhere, the compiler stores two copies:

public class OrderService(OrdersDb db)
{
    private readonly OrdersDb _db = db;

    public Task SaveAsync() => db.SaveChangesAsync();   // warning CS9124
}

The warning tells you the parameter is captured as well as used to initialize a member. Pick one and use it consistently.

#3. They're not properties

On a record, positional parameters become public properties. On a class or struct, they don't: they're only visible inside the type. Copying a record declaration into a class and expecting service.Db to work won't compile.

#4. Validation needs a field initializer

There's no constructor body to put checks in. Use a field or property initializer:

public class RetryPolicy(int maxAttempts)
{
    private readonly int _maxAttempts = maxAttempts > 0
        ? maxAttempts
        : throw new ArgumentOutOfRangeException(nameof(maxAttempts));
}

Or write a normal constructor. Primary constructors are a convenience, not a requirement.

#Where they fit best

• Dependency injection in services, handlers, controllers and hosted services, where the parameters are just dependencies to call.
• Simple types with no validation and no need for immutability guarantees.

For domain types with invariants, an explicit constructor with readonly fields is often clearer.

#Takeaway

Primary constructors remove a lot of DI boilerplate. Remember that their parameters are mutable captured variables, not readonly fields or properties. Assign to a readonly field when that matters, don't mix the field and the parameter, and use a normal constructor when you need validation.

Durable Functions solves this with an orchestration: a function that coordinates other functions, survives restarts and can wait for many parallel tasks.

#The pattern

1. Fan out: start one activity per item.
2. Fan in: wait for all of them and combine the results.

public class AccountSync(CrmClient crm, SyncService syncService)
{
    [Function(nameof(SyncAllAccounts))]
    public async Task<SyncSummary> SyncAllAccounts(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var accountIds = await context.CallActivityAsync<List<string>>(nameof(GetAccountIds));

        var tasks = accountIds
            .Select(id => context.CallActivityAsync<bool>(nameof(SyncAccount), id))
            .ToList();

        var results = await Task.WhenAll(tasks);

        return new SyncSummary(Total: results.Length, Failed: results.Count(ok => !ok));
    }

    [Function(nameof(GetAccountIds))]
    public Task<List<string>> GetAccountIds([ActivityTrigger] object? input, FunctionContext ctx)
        => crm.GetActiveAccountIdsAsync();

    [Function(nameof(SyncAccount))]
    public async Task<bool> SyncAccount([ActivityTrigger] string accountId, FunctionContext ctx)
    {
        // call the external API, write the result; return false on a handled failure
        return await syncService.SyncAsync(accountId);
    }
}

(The example uses the isolated worker model, with dependencies injected through the class's constructor.)

Each activity runs as its own function execution, spread across instances. The orchestrator checkpoints its progress to storage, so if an instance restarts halfway through, completed activities aren't run again.

Start the orchestration from any trigger:

string instanceId = await durableClient.ScheduleNewOrchestrationInstanceAsync(nameof(SyncAllAccounts));

#The orchestrator rules

An orchestrator function is replayed from its history every time it wakes up. To replay correctly, its code must be deterministic:

• No I/O in the orchestrator. Database calls and HTTP requests go in activities.
• No DateTime.UtcNow. Use context.CurrentUtcDateTime.
• No random values or new GUIDs generated directly; generate them in an activity, or use context.NewGuid().

Breaking these rules causes errors or strange behavior on replay, often only under load.

#Don't overwhelm the other side

Starting 5,000 activities at once can easily exceed the external API's rate limit. Two ways to control it:

• Limit concurrency per instance with maxConcurrentActivityFunctions in host.json.
• Fan out in batches: process 100 items, wait, then the next 100.

#Large lists

Each orchestration's history grows with every activity it starts. For very large jobs, split the work into sub-orchestrations (for example, one per batch of 500) with CallSubOrchestratorAsync, so no single history gets huge.

#Takeaway

When a job needs to process many items in parallel and must survive restarts, use a Durable Functions orchestration: fan out an activity per item, fan in with Task.WhenAll, keep the orchestrator deterministic, and limit concurrency so you don't flood the systems you're calling.

Controllers/OrdersController.cs
Services/OrderService.cs
Services/IOrderService.cs
Repositories/OrderRepository.cs
Repositories/IOrderRepository.cs
Models/PlaceOrderRequest.cs
Validators/PlaceOrderValidator.cs

To change how an order is placed, you touch most of those files. OrderService grows to 1,500 lines because every order feature goes through it. And a change for one feature risks breaking another that happens to share a method.

#Slice by use case instead

Vertical slice architecture groups code by what it does for the user. Each slice contains everything one use case needs, from the endpoint to the database:

Features/
  Orders/
    PlaceOrder.cs
    CancelOrder.cs
    GetOrderDetails.cs
    ListOrdersForCustomer.cs
  Shipping/
    ShipOrder.cs

A slice can be a single file:

public static class PlaceOrder
{
    public record Request(Guid CustomerId, List<LineItem> Items);
    public record Response(Guid OrderId, decimal Total);

    public static void Map(IEndpointRouteBuilder app) =>
        app.MapPost("/orders", Handle);

    private static async Task<IResult> Handle(Request request, OrdersDb db, CancellationToken ct)
    {
        if (request.Items.Count == 0)
            return Results.ValidationProblem(new Dictionary<string, string[]>
            {
                ["items"] = ["An order needs at least one item."]
            });

        var order = Order.Create(request.CustomerId, request.Items);
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);

        return Results.Created($"/orders/{order.Id}", new Response(order.Id, order.Total));
    }
}

#Why it works

• Changes stay local. A new requirement for placing orders changes PlaceOrder.cs and nothing else.
• Each slice can be as simple or complex as it needs. A read-only list can project straight from DbContext to a DTO. A complex command can use a rich domain model. No layer forces every feature through the same ceremony.
• Less abstraction for its own sake. No IOrderService with one implementation and no repository that only wraps DbContext.
• Easier to delete. Removing a feature means removing a file or folder.

#What's still shared

Slices aren't a ban on sharing. The domain model, such as the Order entity and its rules, is shared. So are infrastructure concerns: the DbContext, authentication, logging, validation and error handling. What you avoid is a shared service layer that every feature has to squeeze through.

When two slices really do need the same logic, extract it then, into the domain or a small helper. Don't start with the abstraction.

#Do you need MediatR?

Many vertical slice examples send each request through a mediator library. It's not required. Minimal API endpoints or controller actions calling a handler directly are a perfectly good slice. Add a mediator only if you want its pipeline behaviors and are happy with the dependency.

#Takeaway

Group code by feature, so one use case lives in one place. Share the domain model and infrastructure, not a service layer, and extract common code only when duplication actually appears.

GET /contacts?offset=0&limit=100
GET /contacts?offset=100&limit=100
GET /contacts?offset=200&limit=100

It runs every night without errors, and yet a few contacts never arrive. The reason is that the data changes while you're paging through it.

#Why offset paging drifts

Say you've read page one, records 1 to 100. Before you request page two, someone deletes record 50. Everything after it shifts up by one, so the record that was 101 is now 100. Your request for "offset 100" starts at the old record 102, and the old record 101 is never read.

Insertions cause the opposite problem: a record shifts down onto the next page and you read it twice. Duplicates are annoying; silently missed records are worse, because nothing tells you they happened.

#Prefer cursors when the API offers them

Many APIs return a cursor, an opaque token that marks your position:

GET /contacts?limit=100
→ { "items": [...], "nextCursor": "eyJpZCI6..." }

GET /contacts?limit=100&cursor=eyJpZCI6...

The cursor encodes where you were, usually the sort key of the last item, so inserts and deletes elsewhere don't move you. If an API offers both offset and cursor paging, use the cursor.

#Sync by modification date, with overlap

For incremental syncs, page by "modified since" rather than reading everything:

• Store the latest modifiedAt you processed.
• Next run, request records modified at or after that time, minus a small overlap such as a few minutes, to cover clock differences and records that were mid-update.
• Make your writes idempotent, an upsert by external ID, so the overlap's duplicates are harmless.

#Building your own API: keyset paging

If you're the one exposing the data, give callers a stable way to page. Keyset paging filters on the last key seen instead of skipping rows:

public async Task<Page<OrderDto>> GetOrdersAsync(DateTimeOffset? afterCreated, Guid? afterId, int limit, CancellationToken ct)
{
    var query = db.Orders.AsNoTracking();

    if (afterCreated is { } created && afterId is { } id)
    {
        query = query.Where(o => o.CreatedAt > created || (o.CreatedAt == created && o.Id > id));
    }

    var items = await query
        .OrderBy(o => o.CreatedAt).ThenBy(o => o.Id)
        .Take(limit)
        .Select(o => new OrderDto(o.Id, o.CreatedAt, o.Total))
        .ToListAsync(ct);

    return new Page<OrderDto>(items, items.Count == limit ? EncodeCursor(items[^1]) : null);
}

Two details make it work:

• Order by a unique combination. CreatedAt alone can have ties; adding Id makes the order total, so no row is skipped or repeated at a page boundary.
• Index those columns. With an index on (CreatedAt, Id), each page is a quick seek, however deep into the data you are. Offset paging gets slower with every page because the database still reads every skipped row.

Encode the last item's values into an opaque cursor string, so you can change the scheme later without breaking clients.

#Takeaway

Don't page through changing data with offsets. Use cursors when an API provides them, sync incrementally by modification date with a small overlap and idempotent writes, and give your own APIs keyset paging on a unique, indexed sort order.

The source generator does the same work at compile time.

#Set it up

Declare a partial context class listing the types you serialize:

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(OrderPlaced))]
[JsonSerializable(typeof(List<OrderSummary>))]
public partial class AppJsonContext : JsonSerializerContext
{
}

The compiler generates the serialization metadata for those types. Then pass it when you serialize:

var json = JsonSerializer.Serialize(message, AppJsonContext.Default.OrderPlaced);
var order = JsonSerializer.Deserialize(json, AppJsonContext.Default.OrderPlaced);

The overloads that take a JsonTypeInfo<T> are strongly typed, so there's no need for a generic argument either.

#Use it in ASP.NET Core

Register the context so minimal APIs use it for request and response bodies:

builder.Services.ConfigureHttpJsonOptions(options =>
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default));

Types that aren't in your context still fall back to the default reflection-based resolver, so you can add types gradually.

#What you get

• Faster startup. No reflection pass the first time each type is serialized. That's most noticeable in Azure Functions and other apps that start often.
• Trimming and Native AOT support. Required if you publish trimmed or AOT-compiled apps, where reflection-based serialization doesn't work.
• Compile-time feedback. Some unsupported type shapes show up as build warnings instead of runtime surprises.

#When it isn't worth it

For a long-running web API where startup time doesn't matter, the gains are modest. And the context has to know every type up front, which doesn't fit code that serializes arbitrary types at runtime, such as a generic object payload. Use it where startup, trimming or AOT matter, and don't feel you have to convert everything else.

#Takeaway

Add a JsonSerializerContext for the types you serialize most, pass its type info when you serialize, and register it with ASP.NET Core. You get faster startup and support for trimming and Native AOT, and you can adopt it one type at a time.

Using exceptions for them has costs:

• The signature hides them. Order Ship(Guid orderId) doesn't tell you it can fail because the order was cancelled. You find out by reading the implementation or from a production log.
• Control flow gets hard to follow. A throw deep in a service is caught in middleware three layers up, which maps it to an HTTP status code.
• They're slow for hot paths. Throwing captures a stack trace. For an expected outcome that happens thousands of times a minute, that's wasted work.

#A minimal result type

You don't need a library to start:

public record Error(string Code, string Message);

public record Result<T>
{
    public T? Value { get; }
    public Error? Error { get; }
    public bool IsSuccess => Error is null;

    private Result(T? value, Error? error) => (Value, Error) = (value, error);

    public static Result<T> Success(T value) => new(value, null);
    public static Result<T> Failure(Error error) => new(default, error);
}

public async Task<Result<Shipment>> ShipAsync(Guid orderId, CancellationToken ct)
{
    var order = await db.Orders.FindAsync([orderId], ct);
    if (order is null)
        return Result<Shipment>.Failure(new("order.not_found", "Order not found."));
    if (order.Status == OrderStatus.Cancelled)
        return Result<Shipment>.Failure(new("order.cancelled", "Cancelled orders can't be shipped."));

    var shipment = order.Ship();
    await db.SaveChangesAsync(ct);
    return Result<Shipment>.Success(shipment);
}

The return type now says "this can fail", and the caller has to look at the result to get the value.

#Mapping to HTTP

At the edge, translate errors to status codes in one place:

app.MapPost("/orders/{id:guid}/ship", async (Guid id, ShippingService shipping, CancellationToken ct) =>
{
    var result = await shipping.ShipAsync(id, ct);
    if (result.IsSuccess) return Results.Ok(result.Value);

    return result.Error!.Code switch
    {
        "order.not_found" => Results.NotFound(result.Error),
        _ => Results.Conflict(result.Error)
    };
});

#Keep exceptions for exceptional things

Results don't replace exceptions. A database timeout, a null reference or a misconfigured connection string should still throw: there's nothing sensible the immediate caller can do, and the global exception handler should log it and return a 500.

A useful rule: if the business would describe the outcome, return a result. If only a developer would, throw.

#Libraries

If you'd rather not maintain your own type, FluentResults, ErrorOr and OneOf are popular options with helpers for chaining and matching. Pick one and use it consistently. Mixing styles is worse than either.

#Takeaway

Return a result for failures the business expects, so they're visible in the method signature and handled on purpose. Keep exceptions for the truly unexpected, and translate results to HTTP status codes in one place at the edge.