DEV Community: Hossein Esmati

SDLC in the AI Era with Spec-Driven Development

Hossein Esmati — Sun, 12 Jul 2026 22:36:53 +0000

AI can generate an endpoint, a test fixture or a deployment manifest in seconds. That speed is useful, but it does not solve the expensive part of software delivery: deciding what the system should do, proving that the implementation matches that intent and controlling change across architecture, security and operations. In an AI-assisted SDLC, you need a stronger source of truth than a backlog item or a chat transcript. Spec-driven development gives you that control plane. You express behaviour, contracts, constraints and acceptance criteria in durable specifications, then let engineers and AI agents derive code, tests, documentation and delivery checks from them.

The specification becomes the delivery control plane

Traditional delivery often treats specifications as temporary input. A product owner writes a story, an engineer interprets it, and the details disperse into code, tests, pull-request comments and operational knowledge. AI amplifies the weakness of that model. A model will confidently fill gaps, choose defaults and optimise locally unless you provide explicit boundaries. The resulting code may compile while violating business rules, security assumptions or integration contracts.

Spec-driven development reverses that relationship. The specification remains authoritative throughout the lifecycle. It does not need to be one enormous document; it can be a versioned set of linked artefacts: an OpenAPI contract, domain rules, data schemas, architecture decisions, user-flow states, non-functional requirements and executable acceptance criteria. What matters is that every material implementation decision traces back to an agreed statement of intent.

For a .NET and Azure team, the specification can function as an engineering control plane. You can use it to constrain code generation, review proposed changes, generate contract tests, validate infrastructure and explain production behaviour. The code is still important, but it becomes one projection of the system rather than the only reliable description of it. That distinction makes AI assistance safer because generated output can be evaluated against stable, reviewable constraints.

Rebuild the lifecycle around executable intent

You do not need to replace the SDLC with an AI-specific methodology. You need to tighten the transitions between its stages. Discovery should produce measurable outcomes and explicit risks. Requirements should separate business behaviour from implementation preference. Architecture should record the constraints that generated code must respect. Implementation should begin only when the relevant specification is testable. Testing should verify the specification rather than merely exercising the code that happened to be written.

A practical flow looks like this: define the problem, elicit requirements, write the specification, validate it with stakeholders, derive the architecture, implement against the specification, derive tests from the same source, integrate continuously, release with observable controls and feed production evidence back into the next specification revision. AI can assist at every step, but it should not silently own any approval boundary. People remain accountable for intent, risk acceptance and trade-offs.

This changes the meaning of common delivery gates. Your Definition of Ready should require unambiguous acceptance criteria, identified data ownership, security classification, failure behaviour and measurable non-functional targets. Your Definition of Done should require traceability from requirement to specification, design, code, tests and telemetry. A pull request that adds working code without updating the governing specification is incomplete, just as a database migration without a rollback strategy is incomplete.

The lifecycle also becomes more iterative. Production telemetry can reveal that a latency target was unrealistic, a workflow causes abandonment or an integration fails under a particular tenant configuration. You should convert that evidence into a specification change before asking an agent to modify the implementation. That keeps learning explicit and prevents production behaviour from drifting away from documented intent.

Turn specifications into code, tests and quality gates

A useful specification is precise enough to be checked but small enough to review. Start with the highest-value slice of behaviour rather than trying to formalise the entire platform. For an order-submission capability, you might define the API contract, validation boundaries, accepted response, idempotency expectations, authorisation policy and service-level target. You can then provide the same artefacts to an engineer, a coding agent and the CI pipeline.

The following example creates a minimal API whose behaviour is explicit and testable. Create the project with dotnet new web -n OrderApi -f net10.0, then replace Program.cs with this file:

using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.MapPost("/orders", (SubmitOrder request) =>
{
    var validationResults = new List<ValidationResult>();
    var context = new ValidationContext(request);

    if (!Validator.TryValidateObject(
            request,
            context,
            validationResults,
            validateAllProperties: true))
    {
        var errors = validationResults
            .SelectMany(result => result.MemberNames.DefaultIfEmpty("request")
                .Select(member => new { member, result.ErrorMessage }))
            .GroupBy(item => item.member)
            .ToDictionary(
                group => group.Key,
                group => group.Select(item =>
                    item.ErrorMessage ?? "Invalid value").ToArray());

        return Results.ValidationProblem(errors);
    }

    var orderId = Guid.NewGuid();
    var response = new OrderAccepted(orderId, "accepted");

    return Results.Accepted($"/orders/{orderId}", response);
});

app.Run();

public sealed record SubmitOrder(
    [property: Required]
    [property: RegularExpression("^[A-Z0-9-]{3,32}$")]
    string ProductCode,

    [property: Range(1, 100)]
    int Quantity);

public sealed record OrderAccepted(Guid OrderId, string Status);

public partial class Program;

The implementation is deliberately small. The important point is that the rules are visible: product codes use a defined format, quantity has a bounded range, invalid input returns a validation problem and valid input returns 202 Accepted with a resource location. An AI agent should not invent different limits or response semantics because the governing specification and acceptance criteria have already fixed them.

Now create executable evidence. From the solution directory, run the following commands:

dotnet new xunit -n OrderApi.Tests -f net10.0
dotnet add OrderApi.Tests reference OrderApi
dotnet add OrderApi.Tests package Microsoft.AspNetCore.Mvc.Testing
dotnet add OrderApi.Tests package FluentAssertions

Replace the generated test file with this contract-focused test suite:

using System.Net;
using System.Net.Http.Json;
using FluentAssertions;
using Microsoft.AspNetCore.Mvc.Testing;

public sealed class OrderApiTests
    : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public OrderApiTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task Submit_valid_order_returns_accepted_resource()
    {
        var response = await _client.PostAsJsonAsync(
            "/orders",
            new { productCode = "AZURE-42", quantity = 3 });

        response.StatusCode.Should().Be(HttpStatusCode.Accepted);
        response.Headers.Location.Should().NotBeNull();
        response.Headers.Location!
            .ToString()
            .Should()
            .StartWith("/orders/");

        var body =
            await response.Content.ReadFromJsonAsync<OrderAccepted>();

        body!.Status.Should().Be("accepted");
        body.OrderId.Should().NotBeEmpty();
    }

    [Theory]
    [InlineData("x", 1)]
    [InlineData("VALID-1", 0)]
    [InlineData("VALID-1", 101)]
    public async Task Submit_invalid_order_returns_bad_request(
        string productCode,
        int quantity)
    {
        var response = await _client.PostAsJsonAsync(
            "/orders",
            new { productCode, quantity });

        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
    }
}

These tests are more than regression protection. They are executable acceptance criteria. You can require an AI-generated change to preserve them, extend them when the specification changes and reject code that changes behaviour without an approved contract update. The same pattern applies to Azure infrastructure: policy-as-code can enforce network exposure, managed identity, diagnostic settings, data residency and recovery requirements derived from non-functional specifications.

Govern AI-generated change without slowing delivery

AI governance should focus on evidence and authority, not on banning tools or adding ceremonial approval. Decide which artefacts an agent may propose, which it may modify automatically and which require human approval. An agent can usually generate scaffolding, mappings, tests, documentation and low-risk refactoring. It should not independently redefine a public API, weaken an authorisation policy, change a retention rule or accept a production risk.

You should also preserve the generation context. Record the specification version, model or agent, relevant prompts, changed files and validation results as part of the pull request or build metadata. You do not need to archive every conversational token, but you do need enough provenance to explain why a change exists and which constraints governed it. This becomes particularly important when several agents work across application code, Bicep or Terraform, pipelines and operational documentation.

Your CI pipeline should validate relationships, not only files. Check that every changed requirement has corresponding acceptance criteria. Validate OpenAPI and JSON Schema documents. Run architectural tests that prohibit forbidden dependencies. Compare infrastructure against Azure Policy. Run security scanning, unit tests, integration tests and performance thresholds. Finally, verify that telemetry exists for the outcomes and failure modes declared in the specification.

Metrics should reflect delivery quality rather than raw AI output. Track requirement-to-test traceability, escaped-defect rate, change-failure rate, lead time, mean time to recovery, specification churn and the proportion of generated changes accepted without substantial rework. Lines of generated code and prompt counts are activity measures; they tell you little about whether you built the right system.

Takeaway: build the right thing, then keep proving it

AI makes implementation cheaper, which increases the relative cost of ambiguity. When code can be produced quickly, unclear intent creates more wrong code at greater speed. Spec-driven development counters that risk by making agreed behaviour, constraints and evidence the centre of the lifecycle. It gives your engineers a shared language and gives AI agents a bounded problem they can solve reliably.

You should not aim for perfect formal specifications everywhere. Apply precision where mistakes are expensive: public contracts, financial rules, identity and access, data handling, integrations, deployment safety and operational objectives. Keep the specification versioned, reviewable and connected to executable checks. Then use AI aggressively inside those boundaries to accelerate analysis, implementation, testing, documentation and incident learning.

The operating principle is straightforward: build the right thing, build it right and keep proving that it remains right. In the AI era, the specification is not paperwork before development. It is the durable mechanism that connects business intent to architecture, code, tests, deployment and production evidence.

Practical compare-and-choose guide for Vertical Slice (feature folders) vs DDD in .NET (ASP.NET Core / Minimal APIs / Controllers)

Hossein Esmati — Fri, 26 Jun 2026 12:41:11 +0000

When to pick which

Situation	Prefer
Small team, rapid delivery, endpoints mostly CRUD	Vertical Slice
Complex invariants, rich business language, long-lived product	DDD (or hybrid)
Many independent endpoints with minimal cross-cutting rules	Vertical Slice
Multiple workflows touch the same core concepts; consistency is critical	DDD (Aggregates, UoW)
You expect frequent refactors of rules, not endpoints	DDD
You need easy local reasoning & test isolation per endpoint	Vertical Slice

Rule of thumb: if an “entity” has >3 invariants or cross-slice rules, promote it to a DDD Aggregate.

Typical folder layouts

Vertical Slice (feature folders)

/Features
  /Orders
    /Create
      CreateOrderEndpoint.cs
      CreateOrderRequest.cs
      CreateOrderHandler.cs
      CreateOrderValidator.cs
      Mapping.cs
      CreateOrderTests.cs
    /GetById
      ...

Handlers may use DbContext directly (simple) or a thin repository.

DDD (Clean-ish)

/Domain
  /Orders
    Order.cs            // Aggregate Root
    OrderId.cs          // Value Object
    IOrderRepository.cs
    Events/OrderPlaced.cs

/Application
  /Orders
    CreateOrderCommand.cs
    CreateOrderHandler.cs
    Validators/...

/Infrastructure
  Persistence/AppDbContext.cs
  Repositories/OrderRepository.cs
  Configurations/OrderConfig.cs  // EF Core

/Api (or /Web)
  Endpoints/Orders/CreateOrderEndpoint.cs

Minimal API + MediatR (Vertical Slice style)

// Program.cs
app.MapPost("/orders", async (CreateOrderRequest req, ISender sender, CancellationToken ct)
    => Results.Ok(await sender.Send(new CreateOrderCommand(req), ct)));

// Features/Orders/Create/CreateOrderCommand.cs
public record CreateOrderRequest(string CustomerId, List<OrderLineDto> Lines);
public record CreateOrderCommand(CreateOrderRequest Request) : IRequest<Guid>;

// Features/Orders/Create/CreateOrderHandler.cs
public class CreateOrderHandler(AppDbContext db) : IRequestHandler<CreateOrderCommand, Guid>
{
    public async Task<Guid> Handle(CreateOrderCommand cmd, CancellationToken ct)
    {
        // vertical-slice: simple rules inline
        var order = new OrderEntity { /* map from cmd.Request */ };
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        return order.Id;
    }
}

Pros: tiny surface area, fast to build, tests per slice.
Cons: domain rules can leak across handlers if the domain grows.

Same endpoint with a DDD core (hybrid)

// Application/Orders/CreateOrderHandler.cs
public class CreateOrderHandler(IOrderRepository repo, IUnitOfWork uow)
    : IRequestHandler<CreateOrderCommand, OrderId>
{
    public async Task<OrderId> Handle(CreateOrderCommand cmd, CancellationToken ct)
    {
        var order = Order.Create(
            new CustomerId(cmd.Request.CustomerId),
            cmd.Request.Lines.Select(l => new OrderLine(new Sku(l.Sku), l.Qty, Money.From(l.Price)))
        );
        await repo.AddAsync(order, ct);
        await uow.SaveChangesAsync(ct);
        return order.Id;
    }
}

// Domain/Orders/Order.cs
public class Order : AggregateRoot<OrderId>
{
    private readonly List<OrderLine> _lines = new();
    public static Order Create(CustomerId customerId, IEnumerable<OrderLine> lines)
    {
        if (!lines.Any()) throw new DomainException("Order must have at least one line.");
        var order = new Order(customerId);
        foreach (var l in lines) order.AddLine(l);
        // enforce invariants here, not in the handler
        return order;
    }
}

Pros: invariants live in the Domain, reused safely across slices.
Cons: a bit more plumbing (repos, UoW, configs).

Testing strategy

Vertical Slice: test each handler as a unit (validator + handler), add one or two in-memory DbContext integration tests per slice.
DDD: heavy domain unit tests around Aggregates/VOs; lighter app-layer tests; a handful of end-to-end tests per user journey.

Cross-cutting details that often decide it

Transactions:
- Slice: ambient DbContext per handler is fine.
- DDD: prefer UoW around a command; one Aggregate per transaction boundary.
Validation:
- Slice: FluentValidation per request.
- DDD: lightweight request validation + domain-level guards.
Pipelines (MediatR behaviors): logging, retries, outbox, validation → works with both.
EF Core:
- Slice: direct DbContext OK.
- DDD: repositories + aggregate configurations; embrace Owned types for VOs.

Practical recommendation for your stack (Blazor + Aspire)

Start vertical-slice for delivery (one folder per feature; endpoint + handler + validator + tests).
When a concept’s rules spread across 2+ slices, promote it into the Domain as an Aggregate + VOs, and switch the affected slices to use the domain API.
Keep Contracts (request/response DTOs) in a shared project for Blazor; map at the edge of each slice.
Add an Outbox + MediatR pipeline behavior if you publish integration events (Aspire comps make wiring infra easy).
Keep the Domain cohesive (not per-slice) to avoid duplicating ubiquitous language.

Cheatsheet

Mostly CRUD, simple rules → Vertical Slice.
Rich rules, invariants, ubiquitous language → DDD.
Unsure? Hybrid: slices for endpoints, DDD for complex cores.

Approach to Versioning REST APIs in .NET Core

Hossein Esmati — Fri, 26 Jun 2026 12:41:01 +0000

Approach to Versioning REST APIs

Core principles

Stability first: once released, don’t break clients. Favor additive, backward-compatible changes.
Predictable versioning: expose a clear, discoverable version and keep one latest stable plus one previous supported.
Explicit deprecation: communicate timelines, provide headers, and a migration guide.

Versioning styles (and when I use them)

URI versioning (preferred for public APIs)

Format: /v1/orders, /v2/orders/{id}
Pros: obvious, cache-friendly, great for docs & routing.
Cons: path churn when upgrading.
1. Header-based versioning (preferred for internal/partner APIs)
Custom header: x-api-version: 2025-09-01 or x-api-version: 2
Media type: Accept: application/vnd.contoso.orders+json;v=2
Pros: cleaner URIs, can support multiple representations of the same resource.
Cons: less discoverable; requires clients to set headers correctly.

Rule of thumb:

Public → URI.
Internal/advanced clients → header/media type.

Support one strategy per API to avoid confusion.

Backward-compatibility policy

Allowed without bumping major version: add fields (response), add endpoints, relax validation, add optional query params.
Requires new major version: remove/rename fields, change response shapes, tighten validation, repurpose semantics, change status codes.
Minor/patch versions: used internally for deployment tracking and SDK docs; never force clients to specify minor/patch.

Deprecation policy (what clients experience)

Announce deprecation in release notes & email/portal.
Emit headers for deprecated versions:
- Deprecation: true
- Sunset: Tue, 31 Mar 2026 00:00:00 GMT
- Link: </docs/migrate-v1-to-v2>; rel="deprecation"
Keep deprecated versions live for a fixed window (e.g., 9–12 months) with overlapping support.
Provide migration guides and change logs tied to OpenAPI diffs.

Contracts & communication

Single source of truth: OpenAPI (Swagger) checked into version control per major version (e.g., openapi.v1.yaml, openapi.v2.yaml).
Compatibility checks: run OpenAPI-diff in CI to block breaking changes.
Consumer comms: changelog, upgrade guides, sample payloads, and SDK bumps. For breaking changes, version both API and SDK.

Rollout workflow

Design changes; mark breaking vs non-breaking.
Update OpenAPI; generate docs & mock.
Implement vNext alongside existing version (side-by-side routing).
Canary with real traffic; monitor error/latency deltas.
Announce deprecation of old version with timelines.
After sunset, remove old routing & artifacts.

Example in ASP.NET Core (.NET)

Routing and Swagger grouping

// Program.cs
builder.Services.AddApiVersioning(o =>
{
    o.AssumeDefaultVersionWhenUnspecified = true;
    o.DefaultApiVersion = new ApiVersion(1, 0);
    o.ReportApiVersions = true; // adds API-supported/deprecated headers
});
builder.Services.AddVersionedApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV"; // v1, v2
    o.SubstituteApiVersionInUrl = true;
});

// Example controller with URI versioning
[ApiController]
[ApiVersion("1.0")]
[Route("v{version:apiVersion}/orders")]
public class OrdersControllerV1 : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(string id) => Ok(new { id, status = "processing" /* no breaking changes */ });
}

[ApiController]
[ApiVersion("2.0")]
[Route("v{version:apiVersion}/orders")]
public class OrdersControllerV2 : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(string id) => Ok(new { id, orderStatus = "processing" /* renamed → breaking, so v2 */ });
}

Header-based example

GET /orders/123 HTTP/1.1
Host: api.contoso.com
Accept: application/json
x-api-version: 2

Deprecation headers (middleware sketch)

app.Use(async (ctx, next) =>
{
    if (ctx.Request.Path.StartsWithSegments("/v1"))
    {
        ctx.Response.Headers["Deprecation"] = "true";
        ctx.Response.Headers["Sunset"] = "Tue, 31 Mar 2026 00:00:00 GMT";
        ctx.Response.Headers["Link"] = "</docs/migrate-v1-to-v2>; rel=\"deprecation\"";
    }
    await next();
});

Testing & monitoring

Contract tests from OpenAPI examples.
Backward-compat snapshot tests on representative payloads.
Dashboard by version: request volume, error rate, P95 latency.
Alert if deprecated version traffic > X% after N weeks.

Quick dos & don’ts

Do: keep versions immutable, document clearly, version breaking changes only.
Don’t: overload query parameters for versioning, mix multiple strategies, or silently change behavior within a version.

Ensuring Thread Safety — .NET core-centric

Hossein Esmati — Fri, 26 Jun 2026 12:35:51 +0000

Prefer immutability

What: Make data read-only after construction. Instead of editing objects, create new ones.

Why: If nothing changes, many threads can read safely with no locks.

How (.NET):

public readonly record struct Money(decimal Amount, string Currency);

public record Order(Guid Id, IReadOnlyList<OrderLine> Lines)
{
    public Order AddLine(OrderLine line) => this with { Lines = Lines.Append(line).ToList() };
}

Use record/readonly struct, IReadOnlyList<>, and with (copy-on-write).
Keep collections immutable (ImmutableList<T>, ImmutableDictionary<K,V>).

Avoid shared state

What: Don’t let unrelated code touch the same mutable object.

Why: If each operation owns its data, there’s nothing to synchronize.

How:

Per-request scope: create new service instances that hold request-specific state.
No static mutable fields; if you must cache, use ConcurrentDictionary:

private static readonly ConcurrentDictionary<string, Widget> _cache = new();
var widget = _cache.GetOrAdd(key, k => LoadWidget(k));

Use `lock` / `SemaphoreSlim` cautiously

What: Synchronization primitives that serialize access to critical sections.

When:

Short, minimal critical sections where mutation is unavoidable.
lock for synchronous code; SemaphoreSlim when await is involved (never block in async code).

Patterns & pitfalls:

private readonly object _gate = new();

void Update()
{
    lock (_gate) // keep work tiny inside
    {
        // mutate a small piece of shared state
        _count++;
    }
}

private readonly SemaphoreSlim _sem = new(1,1);

async Task UpdateAsync()
{
    await _sem.WaitAsync();
    try { _count++; }
    finally { _sem.Release(); }
}

Never lock(this) or a public object (external code could deadlock you).
Keep lock duration short; avoid I/O under locks.
If multiple locks are needed, fix a global order to prevent deadlocks.

Atomic counters (avoid locks entirely):

Interlocked.Increment(ref _count);

Leverage actor-style or message queues

What: Push work as messages to a single-threaded “actor” that owns its state. Or use an external queue/bus so workers don’t share memory.

Why: Eliminates shared writes; logic becomes “handle one message at a time.”

How (lightweight actors with Channels):

public sealed class CounterActor
{
    private readonly Channel<Action<State>> _in = Channel.CreateUnbounded<Action<State>>();
    private readonly State _state = new();

    public CounterActor()
    {
        _ = Task.Run(async () =>
        {
            await foreach (var msg in _in.Reader.ReadAllAsync())
                msg(_state); // single-threaded access
        });
    }

    public ValueTask Tell(Action<State> msg) => _in.Writer.WriteAsync(msg);

    public sealed class State { public int Count; }
}

At scale: use Orleans/Akka.NET (virtual actors) or external queues (Azure Service Bus/Storage Queues) to process messages concurrently without shared memory.

Timeouts, cancellation, and async correctness

Always pass CancellationToken so long operations end promptly—reduces lock contention.
In ASP.NET Core, never block the thread (.Result, .Wait()); use await to avoid thread pool starvation.

Observability for thread-safety issues

Metric: lock contention, queue length, actor mailbox size.
Logs with correlation IDs to trace races.
Load/stress tests that hammer critical paths (many parallel tasks) to catch races early.

Quick decision guide

Can it be immutable? Do that first.
Must it be shared & mutable? Encapsulate state behind an actor or a queue.
Tiny unavoidable mutation? Guard with Interlocked/lock/SemaphoreSlim (short, ordered, no I/O).
Collections? Prefer immutable or Concurrent* types.

Synchronous vs asynchronous in .NET core - how decide

Hossein Esmati — Fri, 26 Jun 2026 12:35:41 +0000

Rule of thumb

If your action waits on something external, make it async. If it’s instant CPU, keep it sync; for expensive CPU, offload.

The core idea

Async shines for I/O-bound work (DB calls, HTTP calls, queues, files). It frees the request thread while waiting, so the server can serve more requests with the same thread pool.
Sync is fine for trivial, short CPU work (formatting, small calculations) where you’re not awaiting anything and the handler returns in a few milliseconds.

When to choose async

You call EF Core (SaveChangesAsync, ToListAsync), HttpClient, Azure SDK (ServiceBusClient, BlobClient), file I/O, or any API with Async methods.
You expect latency from a dependency (tens–hundreds of ms).
You need cancellation and timeouts (propagate HttpContext.RequestAborted).

When sync is acceptable

The action is pure CPU and trivial (e.g., quick math, mapping, input validation) and returns immediately.
There are no I/O waits and no benefit from freeing the thread.

If it’s CPU-heavy (image processing, big JSON transforms), do not just make it async—offload to a background queue/worker or a separate compute service. Async won’t make CPU faster.

Pitfalls to avoid

Don’t block async: never use .Result / .Wait() on Tasks (deadlocks/thread-pool starvation).
Async all the way down: if the controller is async, downstream calls should be too.
Don’t fake async: returning Task.Run around synchronous I/O just burns threads.
Keep concurrency bounded when fanning out to multiple I/O calls.

Mini decision checklist

Any I/O? → Use async (end-to-end).
Pure CPU?

Tiny (≤ a few ms) → Sync is fine.
Heavy/variable → Offload to background worker; controller returns 202/Location or uses a queue.

ASP.NET Core examples

Async (I/O-bound) — recommended

[ApiController]
[Route("orders")]
public class OrdersController : ControllerBase
{
    private readonly OrdersDbContext _db;
    private readonly HttpClient _http;

    public OrdersController(OrdersDbContext db, IHttpClientFactory f)
    {
        _db = db;
        _http = f.CreateClient("catalog");
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<OrderDto>> Get(string id, CancellationToken ct)
    {
        var order = await _db.Orders.FindAsync([id], ct);
        if (order is null) return NotFound();

        // Call another service
        var resp = await _http.GetAsync($"/inventory/{order.Sku}", ct);
        resp.EnsureSuccessStatusCode();
        var inv = await resp.Content.ReadFromJsonAsync<InventoryDto>(cancellationToken: ct);

        return Ok(new OrderDto(order, inv));
    }
}

Sync (trivial CPU) — acceptable

[HttpGet("ping")]
public ActionResult<string> Ping() => "pong"; // no I/O, returns immediately

CPU-heavy work — offload rather than “asyncifying”

// Controller: accept request, enqueue, return 202
[HttpPost("render")]
public async Task<IActionResult> Render(RenderRequest req, [FromServices] IBackgroundQueue queue)
{
    var jobId = Guid.NewGuid().ToString("N");
    await queue.EnqueueAsync(jobId, req);
    return Accepted($"/render/{jobId}");
}

// Hosted service: single place that uses CPU, bounded concurrency
public class RenderWorker : BackgroundService
{
    private readonly IBackgroundQueue _q;
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var job in _q.DequeueAllAsync(stoppingToken))
        {
            // CPU-bound work here (e.g., image/video), controlled degree of parallelism
        }
    }
}

Tuning & tips

Pass CancellationToken from HttpContext.RequestAborted.
Use IHttpClientFactory and async Azure SDKs.
For streaming, expose IAsyncEnumerable<T> or chunked responses (async).
In ASP.NET Core there’s no UI SynchronizationContext, so ConfigureAwait(false) is usually unnecessary.

Shared Libraries Management in .NET and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:30:29 +0000

Core Principle: Avoid Domain Coupling

The fundamental rule is simple: shared libraries should contain only cross-cutting concerns, never domain logic. When you share domain entities across services, you break bounded context boundaries and create the very coupling microservices aim to eliminate.

Recommended Shared Library Structure

Solution Structure:
├── src/
│   ├── Services/
│   │   ├── OrderService/
│   │   │   └── OrderService.Domain/        # Private domain model
│   │   ├── CustomerService/
│   │   │   └── CustomerService.Domain/     # Private domain model
│   │   └── PaymentService/
│   │       └── PaymentService.Domain/      # Private domain model
│   └── Shared/
│       ├── Company.Common/                  # ✅ Utilities, extensions
│       ├── Company.Observability/           # ✅ Telemetry, logging
│       ├── Company.Messaging/               # ✅ Message bus abstractions
│       ├── Company.Authentication/          # ✅ Auth middleware
│       ├── Company.Contracts/               # ✅ Integration contracts (DTOs)
│       └── Company.ServiceDefaults/         # ✅ .NET Aspire defaults

What Belongs in Shared Libraries

1. Cross-Cutting Utilities (Company.Common)

Infrastructure code that has no business logic:

// Company.Common - Extensions and utilities
namespace Company.Common.Extensions;

public static class DateTimeExtensions
{
    public static DateTime ToUtc(this DateTime dateTime)
    {
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }

    public static DateOnly ToDateOnly(this DateTime dateTime)
        => DateOnly.FromDateTime(dateTime);
}

public static class StringExtensions
{
    public static bool IsNullOrWhiteSpace([NotNullWhen(false)] this string? value)
        => string.IsNullOrWhiteSpace(value);
}

// Result pattern for consistent error handling
public readonly record struct Result<T>
{
    public required T Value { get; init; }
    public required bool IsSuccess { get; init; }
    public string? Error { get; init; }

    public static Result<T> Success(T value) 
        => new() { Value = value, IsSuccess = true };

    public static Result<T> Failure(string error) 
        => new() { Value = default!, IsSuccess = false, Error = error };
}

2. Observability Infrastructure (Company.Observability)

Leveraging .NET 9's enhanced observability features:

// Company.Observability - Structured logging and telemetry
namespace Company.Observability;

public static class ObservabilityExtensions
{
    public static IHostApplicationBuilder AddCompanyObservability(
        this IHostApplicationBuilder builder)
    {
        // .NET 9 enhanced metrics
        builder.Services.AddMetrics();

        // OpenTelemetry with Azure Monitor
        builder.Services.AddOpenTelemetry()
            .WithMetrics(metrics =>
            {
                metrics.AddRuntimeInstrumentation()
                       .AddAspNetCoreInstrumentation()
                       .AddHttpClientInstrumentation();
            })
            .WithTracing(tracing =>
            {
                tracing.AddAspNetCoreInstrumentation()
                       .AddHttpClientInstrumentation()
                       .AddEntityFrameworkCoreInstrumentation();

                if (builder.Environment.IsProduction())
                {
                    tracing.AddAzureMonitorTraceExporter(options =>
                    {
                        options.ConnectionString = builder.Configuration
                            .GetConnectionString("ApplicationInsights");
                    });
                }
            });

        return builder;
    }
}

// Structured logging with LoggerMessage source generators (.NET 9)
public static partial class Log
{
    [LoggerMessage(
        EventId = 1001,
        Level = LogLevel.Information,
        Message = "Processing order {OrderId} for customer {CustomerId}")]
    public static partial void ProcessingOrder(
        ILogger logger, 
        Guid orderId, 
        Guid customerId);

    [LoggerMessage(
        EventId = 1002,
        Level = LogLevel.Error,
        Message = "Failed to process order {OrderId}")]
    public static partial void OrderProcessingFailed(
        ILogger logger, 
        Exception exception,
        Guid orderId);
}

3. Messaging Abstractions (Company.Messaging)

Event-driven communication patterns without business logic:

// Company.Messaging - Message contracts and infrastructure
namespace Company.Messaging;

// Base interfaces - no business rules
public interface IEvent
{
    Guid EventId { get; }
    DateTime OccurredAtUtc { get; }
    string EventType { get; }
}

public interface ICommand
{
    Guid CommandId { get; }
    string CommandType { get; }
}

// Abstract base with common behavior
public abstract record EventBase : IEvent
{
    public Guid EventId { get; init; } = Guid.NewGuid();
    public DateTime OccurredAtUtc { get; init; } = DateTime.UtcNow;
    public string EventType { get; init; }

    protected EventBase()
    {
        EventType = GetType().Name;
    }
}

// Generic message handlers
public interface IEventHandler<in TEvent> where TEvent : IEvent
{
    Task HandleAsync(TEvent @event, CancellationToken cancellationToken = default);
}

public interface ICommandHandler<in TCommand> where TCommand : ICommand
{
    Task HandleAsync(TCommand command, CancellationToken cancellationToken = default);
}

4. Integration Contracts (Company.Contracts)

Lightweight DTOs for inter-service communication - no domain logic, just data transfer:

// Company.Contracts - Integration events (versioned)
namespace Company.Contracts.Orders.V1;

// Integration event - published across service boundaries
public sealed record OrderCreatedEvent(
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount,
    DateTime CreatedAtUtc,
    string Currency = "USD") : EventBase;

// Integration event with versioning
public sealed record OrderStatusChangedEvent(
    Guid OrderId,
    string Status,
    DateTime ChangedAtUtc,
    string? Reason = null) : EventBase;

namespace Company.Contracts.Customers.V1;

public sealed record CustomerRegisteredEvent(
    Guid CustomerId,
    string Email,
    DateTime RegisteredAtUtc) : EventBase;

5. .NET Aspire Service Defaults (Company.ServiceDefaults)

Standardized service configuration for .NET Aspire orchestration:

// Company.ServiceDefaults - Aspire-ready defaults
namespace Company.ServiceDefaults;

public static class ServiceDefaultsExtensions
{
    public static IHostApplicationBuilder AddCompanyServiceDefaults(
        this IHostApplicationBuilder builder)
    {
        // Service discovery
        builder.Services.AddServiceDiscovery();

        // Resilience with Polly
        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            http.AddStandardResilienceHandler();
            http.AddServiceDiscovery();
        });

        // Health checks
        builder.Services.AddHealthChecks()
            .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);

        // Observability
        builder.AddCompanyObservability();

        // OpenAPI with scalar (new in .NET 9)
        builder.Services.AddOpenApi();

        return builder;
    }

    public static WebApplication MapCompanyDefaultEndpoints(
        this WebApplication app)
    {
        // Health checks
        app.MapHealthChecks("/health");
        app.MapHealthChecks("/alive", new() 
        {
            Predicate = r => r.Tags.Contains("live")
        });

        // OpenAPI
        if (app.Environment.IsDevelopment())
        {
            app.MapOpenApi();
            app.MapScalarApiReference(); // New in .NET 9
        }

        return app;
    }
}

What Does NOT Belong in Shared Libraries

❌ Shared Domain Models

This is the most common mistake:

// ❌ BAD: Company.Domain - DO NOT DO THIS
public class Order  // Shared domain entity - creates coupling!
{
    public Guid Id { get; set; }
    public Guid CustomerId { get; set; }
    public List<OrderLine> Lines { get; set; } = [];
    public OrderStatus Status { get; set; }

    public void AddLine(string productId, int quantity, decimal price)
    {
        // Business logic shared across services = coupling
        Lines.Add(new OrderLine(productId, quantity, price));
    }

    public decimal CalculateTotal() => Lines.Sum(l => l.Price * l.Quantity);
}

Why this is harmful:

Breaks bounded context boundaries
Forces all services to use the same domain model
Creates deployment dependencies
Prevents independent evolution
Violates DDD principles

✅ Correct Approach: Private Domain Models

Each service maintains its own domain model:

// ✅ GOOD: OrderService.Domain (private to OrderService)
namespace OrderService.Domain;

public sealed class Order
{
    private readonly List<OrderLine> _lines = [];

    public Guid Id { get; private set; }
    public Guid CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public decimal Total => _lines.Sum(l => l.LineTotal);
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();

    // Rich domain behavior specific to this service
    public Result<OrderLine> AddLine(string productId, decimal price, int quantity)
    {
        if (quantity <= 0)
            return Result<OrderLine>.Failure("Quantity must be positive");

        if (price < 0)
            return Result<OrderLine>.Failure("Price cannot be negative");

        var line = new OrderLine(Guid.NewGuid(), productId, price, quantity);
        _lines.Add(line);
        return Result<OrderLine>.Success(line);
    }

    public void MarkAsConfirmed()
    {
        if (Status != OrderStatus.Pending)
            throw new InvalidOperationException("Only pending orders can be confirmed");

        Status = OrderStatus.Confirmed;
    }

    // Convert to integration event for publishing
    public OrderCreatedEvent ToIntegrationEvent()
    {
        return new OrderCreatedEvent(
            Id, 
            CustomerId, 
            Total, 
            DateTime.UtcNow);
    }
}

// ✅ GOOD: ShippingService.Domain (different perspective on "Order")
namespace ShippingService.Domain;

// Shipping service has its own view of an order
public sealed class ShipmentOrder
{
    public Guid OrderId { get; private set; }
    public Address ShippingAddress { get; private set; }
    public List<ShipmentItem> Items { get; private set; } = [];
    public ShipmentStatus Status { get; private set; }

    // Different behavior, different invariants
    public void PrepareForShipment()
    {
        if (Items.Count == 0)
            throw new InvalidOperationException("Cannot ship empty order");

        Status = ShipmentStatus.ReadyForPickup;
    }

    // Maps from integration event
    public static ShipmentOrder FromOrderCreatedEvent(
        OrderCreatedEvent evt, 
        Address address)
    {
        return new ShipmentOrder
        {
            OrderId = evt.OrderId,
            ShippingAddress = address,
            Status = ShipmentStatus.Pending
        };
    }
}

Package Management with NuGet

Semantic Versioning Strategy

Follow Semantic Versioning and .NET Versioning Guidelines:

<!-- Directory.Build.props -->
<Project>
  <PropertyGroup>
    <!-- Central version management -->
    <VersionPrefix>2.1.0</VersionPrefix>
    <VersionSuffix Condition="'$(Configuration)' != 'Release'">preview</VersionSuffix>

    <!-- .NET 9 settings -->
    <TargetFramework>net9.0</TargetFramework>
    <LangVersion>13.0</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>

    <!-- Package defaults -->
    <Authors>Company Engineering</Authors>
    <Company>YourCompany</Company>
    <PackageProjectUrl>https://nova-globen.se</PackageProjectUrl>
    <RepositoryUrl>https://github.com/desmati/shared-libs</RepositoryUrl>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>
</Project>

<!-- Company.Common.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Company.Common</PackageId>
    <Description>Common utilities and extensions for Company microservices</Description>
    <PackageTags>utilities;extensions;microservices</PackageTags>
    <Version>$(VersionPrefix)$(VersionSuffix)</Version>
  </PropertyGroup>

  <ItemGroup>
    <!-- Source Link for better debugging -->
    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>

    <!-- Nullable annotations -->
    <PackageReference Include="System.Diagnostics.CodeAnalysis" Version="9.0.0" />
  </ItemGroup>

  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="\" />
  </ItemGroup>
</Project>

Versioning Strategies

Strategy 1: Independent Versioning (Recommended)

Each package evolves independently based on its own changes:

<!-- Company.Common - Version 2.1.0 -->
<PropertyGroup>
  <Version>2.1.0</Version>
</PropertyGroup>

<!-- Company.Messaging - Version 1.8.3 (depends on Common) -->
<PropertyGroup>
  <Version>1.8.3</Version>
</PropertyGroup>
<ItemGroup>
  <!-- Range allows patch and minor updates -->
  <PackageReference Include="Company.Common" Version="[2.1.0,3.0.0)" />
</ItemGroup>

<!-- Company.Contracts - Version 3.4.1 (depends on Messaging) -->
<PropertyGroup>
  <Version>3.4.1</Version>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Company.Messaging" Version="[1.8.0,2.0.0)" />
</ItemGroup>

Advantages:

Each package version reflects its actual changes
Clear semantic meaning
Services can upgrade dependencies independently
Reduces unnecessary updates

Use when: Packages have different rates of change and can evolve independently.

Strategy 2: Central Package Management (CPM)

.NET supports centralized version management:

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup>
    <!-- Internal packages -->
    <PackageVersion Include="Company.Common" Version="2.1.0" />
    <PackageVersion Include="Company.Messaging" Version="1.8.3" />
    <PackageVersion Include="Company.Contracts" Version="3.4.1" />
    <PackageVersion Include="Company.Observability" Version="2.0.5" />

    <!-- External dependencies -->
    <PackageVersion Include="Azure.Messaging.ServiceBus" Version="7.18.1" />
    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="9.0.0" />
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>
</Project>

<!-- In project files, just reference without version -->
<ItemGroup>
  <PackageReference Include="Company.Common" />
  <PackageReference Include="Company.Messaging" />
</ItemGroup>

Advantages:

Single source of truth for versions
Easier to ensure consistency
Prevents version conflicts
Better for monorepo scenarios

Strategy 3: Synchronized Suite Versioning

When packages are released together as a cohesive suite:

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CompanySuiteVersion>3.0.0</CompanySuiteVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Company.Common" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.Messaging" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.Contracts" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.Observability" Version="$(CompanySuiteVersion)" />
    <PackageVersion Include="Company.ServiceDefaults" Version="$(CompanySuiteVersion)" />
  </ItemGroup>
</Project>

Use when:

Packages are designed to work together
Breaking changes affect multiple packages
Simplified mental model for consumers
Regular coordinated releases

Hotfix and Patching Strategy

Scenario: Critical Bug in Company.Common

Current State:

Company.Common: 2.1.0
Company.Messaging: 1.8.3 (depends on Common [2.1.0, 3.0.0))
Company.Contracts: 3.4.1 (depends on Messaging)

Hotfix Process:

# 1. Create hotfix branch from release tag
git checkout -b hotfix/2.1.1 v2.1.0

# 2. Fix the bug
# ... make changes ...

# 3. Commit with conventional commit
git commit -m "fix: correct UTC conversion edge case

Fixes issue where DateTime.Kind was not preserved
when converting from local to UTC time.

BREAKING CHANGE: none
Closes #1234"

# 4. Update version to 2.1.1
# Edit Company.Common.csproj or Directory.Build.props

# 5. Create pull request and merge to main
# 6. Tag the release
git tag -a v2.1.1 -m "Hotfix: UTC conversion fix"
git push origin v2.1.1

Impact Analysis:

Company.Common: 2.1.0 → 2.1.1 (patch)
├── Company.Messaging: 1.8.3 (no change needed - accepts [2.1.0, 3.0.0))
│   └── Company.Contracts: 3.4.1 (no change needed)
└── Services automatically get fix on next build

Services using Company.Common will automatically receive the patch because:

Version range [2.1.0, 3.0.0) includes 2.1.1
NuGet restore pulls the latest compatible version
No breaking changes in patch releases

GitVersion Configuration

Automate versioning with GitVersion:

# GitVersion.yml
mode: ContinuousDelivery
assembly-versioning-scheme: MajorMinorPatch
tag-prefix: 'v'
continuous-delivery-fallback-tag: ci

branches:
  main:
    regex: ^main$
    mode: ContinuousDelivery
    tag: ''
    increment: Minor
    prevent-increment-of-merged-branch-version: true
    track-merge-target: false

  hotfix:
    regex: ^hotfix?[/-]
    mode: ContinuousDelivery
    tag: hotfix
    increment: Patch

  feature:
    regex: ^features?[/-]
    mode: ContinuousDelivery
    tag: feature
    increment: Minor

  release:
    regex: ^releases?[/-]
    mode: ContinuousDelivery
    tag: ''
    increment: Patch

  pull-request:
    regex: ^(pull|pull\-requests|pr)[/-]
    mode: ContinuousDelivery
    tag: pr
    increment: Inherit

CI/CD Pipeline with Azure DevOps

Build and Pack Pipeline

# azure-pipelines-pack.yml
trigger:
  branches:
    include:
    - main
    - release/*
    - hotfix/*
  paths:
    include:
    - 'src/Shared/**'
    - 'azure-pipelines-pack.yml'

pool:
  vmImage: 'ubuntu-latest'

variables:
  buildConfiguration: 'Release'
  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
  DOTNET_CLI_TELEMETRY_OPTOUT: true

stages:
- stage: Build
  jobs:
  - job: BuildAndPack
    steps:
    - checkout: self
      fetchDepth: 0  # Required for GitVersion

    - task: UseDotNet@2
      displayName: 'Install .NET 9 SDK'
      inputs:
        version: '9.0.x'

    - task: GitVersion@5
      displayName: 'Calculate Version'
      inputs:
        runtime: 'core'
        configFilePath: 'GitVersion.yml'

    - script: |
        echo "##vso[build.updatebuildnumber]$(GitVersion.SemVer)"
      displayName: 'Update Build Number'

    - task: DotNetCoreCLI@2
      displayName: 'Restore'
      inputs:
        command: 'restore'
        projects: 'src/Shared/**/*.csproj'

    - task: DotNetCoreCLI@2
      displayName: 'Build'
      inputs:
        command: 'build'
        projects: 'src/Shared/**/*.csproj'
        arguments: '--configuration $(buildConfiguration) --no-restore /p:Version=$(GitVersion.NuGetVersion)'

    - task: DotNetCoreCLI@2
      displayName: 'Run Tests'
      inputs:
        command: 'test'
        projects: 'tests/**/*.Tests.csproj'
        arguments: '--configuration $(buildConfiguration) --no-build --collect:"XPlat Code Coverage"'

    - task: PublishCodeCoverageResults@2
      displayName: 'Publish Code Coverage'
      inputs:
        codeCoverageTool: 'Cobertura'
        summaryFileLocation: '$(Agent.TempDirectory)/**/*cobertura.xml'

    - task: DotNetCoreCLI@2
      displayName: 'Pack NuGet Packages'
      inputs:
        command: 'pack'
        packagesToPack: 'src/Shared/**/*.csproj'
        configuration: $(buildConfiguration)
        nobuild: true
        versioningScheme: 'byEnvVar'
        versionEnvVar: 'GitVersion.NuGetVersion'
        packDirectory: '$(Build.ArtifactStagingDirectory)/packages'

    - task: PublishPipelineArtifact@1
      displayName: 'Publish Artifacts'
      inputs:
        targetPath: '$(Build.ArtifactStagingDirectory)/packages'
        artifact: 'nuget-packages'

- stage: PublishInternal
  dependsOn: Build
  condition: and(succeeded(), or(eq(variables['Build.SourceBranch'], 'refs/heads/main'), startsWith(variables['Build.SourceBranch'], 'refs/heads/release/'), startsWith(variables['Build.SourceBranch'], 'refs/heads/hotfix/')))
  jobs:
  - deployment: PublishToFeed
    environment: 'Internal NuGet Feed'
    strategy:
      runOnce:
        deploy:
          steps:
          - download: current
            artifact: 'nuget-packages'

          - task: NuGetCommand@2
            displayName: 'Push to Azure Artifacts'
            inputs:
              command: 'push'
              packagesToPush: '$(Pipeline.Workspace)/nuget-packages/**/*.nupkg;!$(Pipeline.Workspace)/nuget-packages/**/*.symbols.nupkg'
              nuGetFeedType: 'internal'
              publishVstsFeed: 'company-shared-libraries'
              allowPackageConflicts: false

Multi-Stage Pipeline with Approval Gates

# azure-pipelines-release.yml
stages:
- stage: Build
  # ... (same as above)

- stage: PublishInternal
  # ... (same as above)

- stage: PublishProduction
  dependsOn: PublishInternal
  condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/release/'))
  jobs:
  - deployment: PublishToNuGetOrg
    environment: 'Production NuGet' # Requires manual approval
    strategy:
      runOnce:
        deploy:
          steps:
          - download: current
            artifact: 'nuget-packages'

          - task: NuGetCommand@2
            displayName: 'Push to NuGet.org'
            inputs:
              command: 'push'
              packagesToPush: '$(Pipeline.Workspace)/nuget-packages/**/*.nupkg;!$(Pipeline.Workspace)/nuget-packages/**/*.symbols.nupkg'
              nuGetFeedType: 'external'
              publishFeedCredentials: 'NuGet.org Service Connection'

Integration with .NET Aspire

Aspire AppHost Configuration

// CompanyPlatform.AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

// Shared infrastructure
var redis = builder.AddRedis("cache");
var serviceBus = builder.AddAzureServiceBus("messaging");
var sql = builder.AddSqlServer("sql")
    .AddDatabase("orderdb");

// Services with shared defaults
var orderService = builder.AddProject<Projects.OrderService>("order-service")
    .WithReference(sql)
    .WithReference(serviceBus)
    .WithReference(redis);

var customerService = builder.AddProject<Projects.CustomerService>("customer-service")
    .WithReference(serviceBus);

var shippingService = builder.AddProject<Projects.ShippingService>("shipping-service")
    .WithReference(serviceBus);

// All services automatically get Company.ServiceDefaults behavior
builder.Build().Run();

Service Implementation

// OrderService/Program.cs
var builder = WebApplication.CreateBuilder(args);

// Apply company defaults (includes observability, resilience, health checks)
builder.AddCompanyServiceDefaults();

// Add Aspire components
builder.AddServiceDefaults();
builder.AddSqlServerDbContext<OrderDbContext>("orderdb");
builder.AddAzureServiceBusClient("messaging");

// Service-specific registrations
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();

app.MapCompanyDefaultEndpoints();
app.MapOrderEndpoints();

app.Run();

Package Consumption Best Practices

Version Pinning Strategy

<!-- For stable production services -->
<ItemGroup>
  <!-- Pin to exact versions for predictability -->
  <PackageReference Include="Company.Common" Version="2.1.0" />
  <PackageReference Include="Company.Messaging" Version="1.8.3" />
</ItemGroup>

<!-- For active development -->
<ItemGroup>
  <!-- Use ranges to get patches automatically -->
  <PackageReference Include="Company.Common" Version="[2.1.0,2.2.0)" />
  <PackageReference Include="Company.Messaging" Version="[1.8.0,2.0.0)" />
</ItemGroup>

Dependency Resolution

Configure NuGet to prioritize your internal feed:

<!-- nuget.config -->
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <!-- Company internal feed first -->
    <add key="Company" value="https://pkgs.dev.azure.com/yourorg/_packaging/company-shared-libraries/nuget/v3/index.json" />
    <!-- Public NuGet.org second -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="Company">
      <package pattern="Company.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Monitoring and Observability

Package Health Dashboard

Track package adoption and health:

// Custom metrics for package usage
public class PackageHealthMetrics
{
    private readonly Counter<int> _packageDownloads;
    private readonly Histogram<double> _buildDuration;

    public PackageHealthMetrics(IMeterFactory meterFactory)
    {
        var meter = meterFactory.Create("Company.Packages");

        _packageDownloads = meter.CreateCounter<int>(
            "package.downloads",
            description: "Number of package downloads");

        _buildDuration = meter.CreateHistogram<double>(
            "package.build.duration",
            unit: "s",
            description: "Package build duration");
    }

    public void RecordDownload(string packageId, string version)
    {
        _packageDownloads.Add(1, 
            new KeyValuePair<string, object?>("package.id", packageId),
            new KeyValuePair<string, object?>("package.version", version));
    }
}

Azure Monitor Integration

// Application Insights for package telemetry
builder.Services.AddApplicationInsightsTelemetry(options =>
{
    options.ConnectionString = builder.Configuration
        .GetConnectionString("ApplicationInsights");
});

// Custom telemetry for package health
builder.Services.AddSingleton<ITelemetryInitializer, PackageTelemetryInitializer>();

public class PackageTelemetryInitializer : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        if (telemetry is ISupportProperties propertyTelemetry)
        {
            propertyTelemetry.Properties["SharedLibVersion.Common"] = 
                typeof(Company.Common.Extensions.DateTimeExtensions)
                    .Assembly.GetName().Version?.ToString() ?? "unknown";
        }
    }
}

Breaking Changes Management

Communicating Breaking Changes

Use attributes and XML documentation to signal changes:

// Company.Common
namespace Company.Common.Extensions;

public static class DateTimeExtensions
{
    // Deprecated method - will be removed in v3.0.0
    [Obsolete("Use ToUtc() instead. This method will be removed in v3.0.0", false)]
    [EditorBrowsable(EditorBrowsableState.Never)]
    public static DateTime ConvertToUtc(this DateTime dateTime)
        => dateTime.ToUtc();

    /// <summary>
    /// Converts a DateTime to UTC, preserving the underlying instant in time.
    /// </summary>
    /// <param name="dateTime">The date and time to convert.</param>
    /// <returns>The date and time in UTC.</returns>
    /// <remarks>
    /// Added in v2.1.0. This replaces the deprecated ConvertToUtc method.
    /// </remarks>
    public static DateTime ToUtc(this DateTime dateTime)
    {
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }
}

Migration Guides

Include migration documentation in your packages:

<!-- MIGRATION-v3.0.md -->
# Migration Guide: v2.x to v3.0

## Breaking Changes

### Company.Common

**Removed: `DateTimeExtensions.ConvertToUtc()`**
- **Replacement:** Use `DateTimeExtensions.ToUtc()`
- **Migration:**

csharp
// Before (v2.x)
var utcTime = localTime.ConvertToUtc();

// After (v3.0)
var utcTime = localTime.ToUtc();


**Changed: `Result<T>` now uses `required` properties**
- **Impact:** Cannot use object initializer without all required properties
- **Migration:**

csharp
// Before (v2.x)
var result = new Result { Value = "test", IsSuccess = true };

// After (v3.0) - use factory methods
var result = Result.Success("test");


### Company.Messaging

**Removed: `EventBase.Timestamp`**
- **Replacement:** Use `EventBase.OccurredAtUtc`
- **Reason:** Improved clarity and UTC enforcement

## New Features

### Company.Common
- Added `StringExtensions.IsNullOrWhiteSpace()` with null checking
- Added `Result<T>.Map()` and `Result<T>.Bind()` for functional composition

### Company.Observability
- Full .NET 9 metrics API support
- Enhanced OpenTelemetry integration
- Azure Monitor auto-configuration

Advanced Patterns

Feature Flags in Shared Libraries

Enable gradual rollout of changes:

// Company.Common - Feature flag support
namespace Company.Common.Features;

public interface IFeatureManager
{
    Task<bool> IsEnabledAsync(string featureName);
    Task<T> GetVariantAsync<T>(string featureName, T defaultValue);
}

public static class FeatureExtensions
{
    public static IServiceCollection AddCompanyFeatureManagement(
        this IServiceCollection services)
    {
        services.AddFeatureManagement()
            .AddFeatureFilter<PercentageFilter>()
            .AddFeatureFilter<TargetingFilter>();

        return services;
    }
}

// Usage in shared library
public static class DateTimeExtensions
{
    public static async Task<DateTime> ToUtcAsync(
        this DateTime dateTime,
        IFeatureManager? featureManager = null)
    {
        // New implementation behind feature flag
        if (featureManager != null && 
            await featureManager.IsEnabledAsync("UseEnhancedUtcConversion"))
        {
            return EnhancedToUtc(dateTime);
        }

        // Legacy implementation
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }

    private static DateTime EnhancedToUtc(DateTime dateTime)
    {
        // New implementation with additional validations
        // ...
    }
}

Multi-Targeting for Backward Compatibility

Support multiple .NET versions when needed:

<!-- Company.Common.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
    <LangVersion>latest</LangVersion>
  </PropertyGroup>

  <!-- Conditional compilation -->
  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
    <PackageReference Include="System.Text.Json" Version="8.0.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
    <PackageReference Include="System.Text.Json" Version="9.0.0" />
  </ItemGroup>
</Project>

// Conditional compilation in code
namespace Company.Common.Serialization;

public static class JsonExtensions
{
#if NET9_0_OR_GREATER
    // Use new .NET 9 features
    public static T? Deserialize<T>(this string json, JsonSerializerOptions? options = null)
    {
        return JsonSerializer.Deserialize<T>(json, options ?? JsonSerializerOptions.Web);
    }
#else
    // Fallback for .NET 8
    public static T? Deserialize<T>(this string json, JsonSerializerOptions? options = null)
    {
        return JsonSerializer.Deserialize<T>(json, options ?? new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true,
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        });
    }
#endif
}

Testing Shared Libraries

Unit Testing Strategy

// Company.Common.Tests/Extensions/DateTimeExtensionsTests.cs
namespace Company.Common.Tests.Extensions;

public class DateTimeExtensionsTests
{
    [Theory]
    [InlineData("2025-01-15T10:30:00Z", DateTimeKind.Utc)]
    [InlineData("2025-01-15T10:30:00", DateTimeKind.Unspecified)]
    [InlineData("2025-01-15T10:30:00", DateTimeKind.Local)]
    public void ToUtc_ShouldReturnUtcDateTime(string dateTimeString, DateTimeKind kind)
    {
        // Arrange
        var dateTime = DateTime.Parse(dateTimeString);
        dateTime = DateTime.SpecifyKind(dateTime, kind);

        // Act
        var result = dateTime.ToUtc();

        // Assert
        result.Kind.Should().Be(DateTimeKind.Utc);
    }

    [Fact]
    public void ToUtc_WhenAlreadyUtc_ShouldReturnSameInstance()
    {
        // Arrange
        var utcTime = DateTime.UtcNow;

        // Act
        var result = utcTime.ToUtc();

        // Assert
        result.Should().BeSameAs(utcTime);
    }
}

Integration Testing with Test Containers

// Company.Messaging.Tests/ServiceBusIntegrationTests.cs
using Testcontainers.Azurite;

public class ServiceBusIntegrationTests : IAsyncLifetime
{
    private AzuriteContainer _azurite = null!;
    private IServiceProvider _services = null!;

    public async Task InitializeAsync()
    {
        _azurite = new AzuriteBuilder()
            .WithImage("mcr.microsoft.com/azure-storage/azurite:latest")
            .Build();

        await _azurite.StartAsync();

        var services = new ServiceCollection();
        services.AddAzureClients(builder =>
        {
            builder.AddServiceBusClient(_azurite.GetConnectionString());
        });

        _services = services.BuildServiceProvider();
    }

    [Fact]
    public async Task PublishEvent_ShouldSucceed()
    {
        // Arrange
        var publisher = _services.GetRequiredService<IEventPublisher>();
        var testEvent = new OrderCreatedEvent(Guid.NewGuid(), Guid.NewGuid(), 100m, DateTime.UtcNow);

        // Act
        await publisher.PublishAsync(testEvent);

        // Assert - event should be in queue
        // ...
    }

    public async Task DisposeAsync()
    {
        await _azurite.DisposeAsync();
    }
}

Contract Testing

Ensure backward compatibility of contracts:

// Company.Contracts.Tests/OrderCreatedEventTests.cs
public class OrderCreatedEventTests
{
    [Fact]
    public void OrderCreatedEvent_ShouldDeserializeFromV1Schema()
    {
        // Arrange - JSON from v1.0 contract
        var v1Json = """
        {
            "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "customerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "totalAmount": 299.99,
            "createdAtUtc": "2025-01-15T10:30:00Z"
        }
        """;

        // Act
        var evt = JsonSerializer.Deserialize<OrderCreatedEvent>(v1Json);

        // Assert
        evt.Should().NotBeNull();
        evt!.OrderId.Should().Be(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));
        evt.Currency.Should().Be("USD"); // Default value added in v1.1
    }

    [Fact]
    public void OrderCreatedEvent_ShouldSerializeWithAllFields()
    {
        // Arrange
        var evt = new OrderCreatedEvent(
            Guid.NewGuid(),
            Guid.NewGuid(),
            299.99m,
            DateTime.UtcNow,
            "EUR");

        // Act
        var json = JsonSerializer.Serialize(evt);
        var deserialized = JsonSerializer.Deserialize<OrderCreatedEvent>(json);

        // Assert
        deserialized.Should().BeEquivalentTo(evt);
    }
}

Security Considerations

Package Signing

Sign your NuGet packages for authenticity:

<!-- Directory.Build.props -->
<PropertyGroup>
  <SignAssembly>true</SignAssembly>
  <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)company-key.snk</AssemblyOriginatorKeyFile>

  <!-- NuGet package signing -->
  <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
</PropertyGroup>

# In Azure Pipeline
- task: NuGetCommand@2
  displayName: 'Sign NuGet Packages'
  inputs:
    command: custom
    arguments: 'sign $(Build.ArtifactStagingDirectory)/**/*.nupkg -CertificatePath $(SigningCertificate.secureFilePath) -CertificatePassword $(CertPassword) -Timestamper http://timestamp.digicert.com'

Dependency Scanning

Integrate security scanning into your pipeline:

# azure-pipelines-security.yml
- task: DotNetCoreCLI@2
  displayName: 'Restore with Dependency Check'
  inputs:
    command: 'restore'
    projects: '**/*.csproj'

- task: ComponentGovernanceComponentDetection@0
  displayName: 'Component Detection'
  inputs:
    scanType: 'Register'
    verbosity: 'Verbose'
    alertWarningLevel: 'High'

- script: |
    dotnet list package --vulnerable --include-transitive
  displayName: 'Check for Vulnerable Dependencies'

- script: |
    dotnet list package --deprecated
  displayName: 'Check for Deprecated Packages'

Secrets Management in Shared Libraries

Never hardcode secrets - use configuration:

// Company.Common - Secure configuration
namespace Company.Common.Configuration;

public static class SecureConfigurationExtensions
{
    public static IConfigurationBuilder AddCompanySecrets(
        this IConfigurationBuilder builder,
        IHostEnvironment environment)
    {
        if (environment.IsDevelopment())
        {
            builder.AddUserSecrets<Program>();
        }
        else
        {
            // Azure Key Vault in production
            var config = builder.Build();
            var keyVaultUri = config["KeyVault:Uri"];

            if (!string.IsNullOrEmpty(keyVaultUri))
            {
                builder.AddAzureKeyVault(
                    new Uri(keyVaultUri),
                    new DefaultAzureCredential());
            }
        }

        return builder;
    }
}

Documentation and Discoverability

XML Documentation

Comprehensive documentation improves adoption:

/// <summary>
/// Provides extension methods for <see cref="DateTime"/> operations with UTC handling.
/// </summary>
/// <remarks>
/// This class contains utility methods for working with dates and times, with a focus
/// on ensuring consistent UTC time handling across microservices.
/// 
/// <para>
/// <strong>Version History:</strong>
/// </para>
/// <list type="bullet">
/// <item><description>v2.1.0 - Added ToUtc() method</description></item>
/// <item><description>v2.0.0 - Initial release</description></item>
/// </list>
/// </remarks>
/// <example>
/// <code>
/// var localTime = DateTime.Now;
/// var utcTime = localTime.ToUtc();
/// Console.WriteLine($"UTC: {utcTime:u}");
/// </code>
/// </example>
public static class DateTimeExtensions
{
    /// <summary>
    /// Converts a <see cref="DateTime"/> to UTC, preserving the underlying instant in time.
    /// </summary>
    /// <param name="dateTime">The date and time to convert.</param>
    /// <returns>
    /// A <see cref="DateTime"/> with <see cref="DateTimeKind.Utc"/>.
    /// If the input is already UTC, returns the same instance.
    /// </returns>
    /// <exception cref="ArgumentException">
    /// Thrown when the DateTime represents an invalid time (e.g., during DST transition).
    /// </exception>
    /// <example>
    /// <code>
    /// var localTime = new DateTime(2025, 1, 15, 10, 30, 0, DateTimeKind.Local);
    /// var utcTime = localTime.ToUtc();
    /// // utcTime.Kind == DateTimeKind.Utc
    /// </code>
    /// </example>
    public static DateTime ToUtc(this DateTime dateTime)
    {
        return dateTime.Kind == DateTimeKind.Utc 
            ? dateTime 
            : dateTime.ToUniversalTime();
    }
}

README.md for Each Package

<!-- Company.Common/README.md -->
# Company.Common

[![NuGet Version](https://img.shields.io/nuget/v/Company.Common.svg)](https://www.nuget.org/packages/Company.Common/)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Company.Common.svg)](https://www.nuget.org/packages/Company.Common/)

Common utilities and extensions for Company microservices architecture.

## Installation

bash
dotnet add package Company.Common


## Features

- **DateTime Extensions**: UTC conversion utilities
- **String Extensions**: Null checking helpers
- **Result Pattern**: Functional error handling
- **Performance**: Zero-allocation where possible

## Quick Start

csharp
using Company.Common.Extensions;

// DateTime utilities
var utcTime = DateTime.Now.ToUtc();
var dateOnly = utcTime.ToDateOnly();

// String helpers
if (!input.IsNullOrWhiteSpace())
{
// Process input
}

// Result pattern
var result = Result.Success(42);
if (result.IsSuccess)
{
Console.WriteLine(result.Value);
}


## Documentation

Full documentation available at [nova-globen.se](https://nova-globen.se)

## Version Compatibility

| Company.Common | .NET Version | Support |
|----------------|--------------|---------|
| 2.x            | .NET 9       | ✅ Active |
| 1.x            | .NET 8       | ⚠️ Maintenance |

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md)

## License

MIT License - see [LICENSE](../../LICENSE)

csharp

Performance Considerations

Benchmarking Shared Libraries

Use BenchmarkDotNet to validate performance:

// Company.Common.Benchmarks/DateTimeExtensionsBenchmarks.cs
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

[MemoryDiagnoser]
[SimpleJob(warmupCount: 3, iterationCount: 10)]
public class DateTimeExtensionsBenchmarks
{
    private DateTime _localTime;
    private DateTime _utcTime;

    [GlobalSetup]
    public void Setup()
    {
        _localTime = DateTime.Now;
        _utcTime = DateTime.UtcNow;
    }

    [Benchmark(Baseline = true)]
    public DateTime ToUniversalTime_Baseline()
    {
        return _localTime.ToUniversalTime();
    }

    [Benchmark]
    public DateTime ToUtc_Extension()
    {
        return _localTime.ToUtc();
    }

    [Benchmark]
    public DateTime ToUtc_AlreadyUtc()
    {
        return _utcTime.ToUtc(); // Should be no-op
    }
}

// Results tracking
/*
| Method                 | Mean      | Error    | StdDev   | Gen0   | Allocated |
|----------------------- |----------:|---------:|---------:|-------:|----------:|
| ToUniversalTime_Base   | 45.23 ns  | 0.234 ns | 0.218 ns | -      | -         |
| ToUtc_Extension        | 45.18 ns  | 0.198 ns | 0.185 ns | -      | -         |
| ToUtc_AlreadyUtc       |  2.34 ns  | 0.012 ns | 0.011 ns | -      | -         |
*/

Optimizing Package Size

<!-- Reduce package size -->
<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <TrimMode>link</TrimMode>

  <!-- Debug symbols in separate package -->
  <DebugType>portable</DebugType>
  <IncludeSymbols>true</IncludeSymbols>
  <SymbolPackageFormat>snupkg</SymbolPackageFormat>

  <!-- Exclude unnecessary files -->
  <NoWarn>$(NoWarn);NU5128</NoWarn>
  <ContentTargetFolders>content</ContentTargetFolders>
</PropertyGroup>

<ItemGroup>
  <None Remove="**/*.Development.json" />
  <None Remove="**/*.local.json" />
</ItemGroup>

Governance and Ownership

Package Ownership Model

Define clear ownership:

# CODEOWNERS
# Shared libraries ownership

src/Shared/Company.Common/**           @platform-team @architecture-team
src/Shared/Company.Messaging/**        @platform-team @messaging-team
src/Shared/Company.Contracts/**        @api-team @architecture-team
src/Shared/Company.Observability/**    @platform-team @sre-team
src/Shared/Company.ServiceDefaults/**  @platform-team @devex-team

# Require approval from platform team for all shared library changes
src/Shared/**                          @platform-team

Change Request Process

<!-- .github/PULL_REQUEST_TEMPLATE.md -->
## Shared Library Change Request

### Package(s) Affected
- [ ] Company.Common
- [ ] Company.Messaging
- [ ] Company.Contracts
- [ ] Company.Observability
- [ ] Company.ServiceDefaults

### Change Type
- [ ] New Feature
- [ ] Bug Fix
- [ ] Breaking Change
- [ ] Performance Improvement
- [ ] Documentation

### Version Impact
- Current Version: x.y.z
- Proposed Version: x.y.z
- Justification: [Major/Minor/Patch]

### Breaking Changes
<!-- If yes, describe migration path -->
- [ ] No breaking changes
- [ ] Breaking changes documented in MIGRATION.md

### Impact Analysis
- Estimated services affected: X
- Migration effort: [Low/Medium/High]
- Rollout strategy: [describe]

### Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Performance benchmarks run
- [ ] Backward compatibility verified

### Documentation
- [ ] XML documentation updated
- [ ] README.md updated
- [ ] Migration guide created (if breaking)
- [ ] Changelog updated

### Checklist
- [ ] Code follows company standards
- [ ] No secrets or sensitive data
- [ ] Semantic versioning followed
- [ ] Release notes prepared

Summary and Best Practices

Key Takeaways

Keep shared libraries focused on infrastructure
- ✅ Logging, extensions, messaging abstractions
- ❌ Domain models, business logic
Each microservice owns its domain model
- Services communicate via contracts (DTOs/events)
- No shared domain entities across services
Use semantic versioning rigorously
- Major: Breaking changes
- Minor: New features (backward compatible)
- Patch: Bug fixes
Leverage .NET 9 features
- Enhanced metrics and observability
- Improved performance
- Better tooling support
Integrate with .NET Aspire
- Standardized service defaults
- Simplified local development
- Built-in observability
Automate everything
- CI/CD for package publishing
- Automated versioning with GitVersion
- Security scanning in pipelines
Document thoroughly
- XML documentation
- README files
- Migration guides for breaking changes
Monitor and measure
- Package download metrics
- Performance benchmarks
- Dependency health

Anti-Patterns to Avoid

❌ Don't do this:

Sharing domain entities across services
Including business logic in shared libraries
Creating "God packages" with everything
Breaking semantic versioning rules
Hardcoding configuration or secrets
Publishing without tests
Ignoring backward compatibility
Skipping documentation

✅ Do this instead:

Keep packages focused and cohesive
Share only contracts and infrastructure
Follow semantic versioning strictly
Automate testing and publishing
Document changes and migration paths
Monitor package health and adoption

Additional Resources

This guide is maintained by the Platform Engineering team. For questions or contributions, contact desmati@gmail.com or visit nova-globen.se for more architectural guidance.

Service Mesh in .NET core

Hossein Esmati — Fri, 26 Jun 2026 12:30:19 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

Key Benefits

Traffic Management: Load balancing, routing, and traffic splitting for canary deployments
Security: Mutual TLS (mTLS) encryption, authentication, and authorization between services
Observability: Distributed tracing, metrics, and logging for service interactions
Resilience: Automatic retries, circuit breaking, and timeout policies

Popular Service Mesh Options

Istio

Full-featured, Kubernetes-native service mesh offering comprehensive traffic management, security policies, and observability. Best for complex enterprise environments requiring fine-grained control.

Linkerd

Lightweight and simpler alternative focused on ease of use and minimal resource overhead. Ideal for teams wanting service mesh benefits without operational complexity.

Dapr (Distributed Application Runtime)

Multi-runtime, cloud-agnostic framework that works beyond Kubernetes across VMs, edge, and cloud environments. Provides building blocks for microservices including service invocation, pub/sub, state management, and more.

.NET Aspire: Cloud-Native Orchestration

.NET Aspire is Microsoft's opinionated stack for building observable, production-ready cloud-native applications with .NET 9. While not a traditional service mesh, Aspire provides service discovery, orchestration, and observability features that complement or serve as alternatives to service meshes in certain scenarios.

Key Aspire Features:

Automatic service discovery and health checks
Built-in OpenTelemetry integration for distributed tracing
Local development orchestration with production-ready patterns
Azure integration for seamless cloud deployment

// .NET Aspire App Host (Program.cs)
var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");
var messaging = builder.AddRabbitMQ("messaging");

var customerService = builder.AddProject<Projects.CustomerService>("customer-service")
    .WithReference(cache);

var orderService = builder.AddProject<Projects.OrderService>("order-service")
    .WithReference(cache)
    .WithReference(messaging)
    .WithReference(customerService); // Automatic service discovery

builder.Build().Run();

Dapr with .NET 9 and C# 13

Dapr integrates seamlessly with .NET 9, leveraging modern C# features and Azure services.

Service Invocation and Pub/Sub

using Dapr.Client;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

// Add Dapr services
builder.Services.AddControllers().AddDapr();
builder.Services.AddDaprClient();

var app = builder.Build();

app.MapControllers();
app.MapSubscribeHandler(); // Dapr pub/sub subscriptions

app.Run();

[ApiController]
[Route("api/[controller]")]
public class OrderController(DaprClient daprClient, IOrderService orderService) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        // Save order using primary constructor parameter
        var order = await orderService.CreateAsync(request);

        // Publish event via Dapr pub/sub to Azure Service Bus
        await daprClient.PublishEventAsync(
            "servicebus-pubsub",
            "order-events",
            new OrderCreatedEvent 
            { 
                OrderId = order.Id,
                CustomerId = request.CustomerId,
                CreatedAt = DateTime.UtcNow
            });

        // Invoke customer service with resilience (automatic retries)
        var customer = await daprClient.InvokeMethodAsync<Customer>(
            HttpMethod.Get,
            "customer-service",
            $"api/customers/{request.CustomerId}");

        return Ok(new { order, customer });
    }

    // Dapr pub/sub subscription
    [Topic("servicebus-pubsub", "payment-events")]
    [HttpPost("payment-processed")]
    public async Task<IActionResult> HandlePaymentProcessed(PaymentProcessedEvent @event)
    {
        await orderService.UpdatePaymentStatusAsync(@event.OrderId, @event.Status);
        return Ok();
    }
}

// Event records using C# 13 features
public record OrderCreatedEvent
{
    required public string OrderId { get; init; }
    required public string CustomerId { get; init; }
    required public DateTime CreatedAt { get; init; }
}

public record PaymentProcessedEvent(string OrderId, string Status);

State Management with Azure Cosmos DB

public class OrderService(DaprClient daprClient)
{
    private const string StateStoreName = "cosmosdb-state";

    public async Task<Order> CreateAsync(CreateOrderRequest request)
    {
        var order = new Order
        {
            Id = Guid.NewGuid().ToString(),
            CustomerId = request.CustomerId,
            Items = request.Items,
            Status = OrderStatus.Pending
        };

        // Save to Cosmos DB via Dapr state management
        await daprClient.SaveStateAsync(StateStoreName, order.Id, order);

        return order;
    }

    public async Task<Order?> GetAsync(string orderId)
    {
        return await daprClient.GetStateAsync<Order>(StateStoreName, orderId);
    }
}

Azure Integration with Dapr Components

Dapr Component for Azure Service Bus (components/servicebus-pubsub.yaml):

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: servicebus-pubsub
spec:
  type: pubsub.azure.servicebus.topics
  version: v1
  metadata:
  - name: connectionString
    secretKeyRef:
      name: azure-servicebus-connection
  - name: consumerID
    value: "order-service"

Dapr Component for Azure Cosmos DB (components/cosmosdb-state.yaml):

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: cosmosdb-state
spec:
  type: state.azure.cosmosdb
  version: v1
  metadata:
  - name: url
    value: "https://your-account.documents.azure.com:443/"
  - name: masterKey
    secretKeyRef:
      name: cosmosdb-key
  - name: database
    value: "orders-db"
  - name: collection
    value: "orders"

Choosing the Right Approach

Use .NET Aspire for cloud-native .NET applications requiring orchestration, observability, and Azure integration with minimal setup
Use Dapr for polyglot microservices, multi-cloud scenarios, or when you need portable building blocks across different hosting environments
Use Traditional Service Meshes (Istio/Linkerd) for Kubernetes-native applications requiring advanced traffic management and security policies at the infrastructure level

For comprehensive microservices patterns and best practices, visit nova-globen.se.

Additional Resources

Ready to modernize your microservices architecture? Explore more patterns and tutorials at nova-globen.se.

Service Discovery in Modern .NET Applications and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:25:09 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

Service Discovery in Kubernetes

How Kubernetes DNS Works

Kubernetes automatically creates DNS entries for services, enabling simple name-based discovery. A service named order-service in the production namespace becomes accessible at order-service.production.svc.cluster.local. For services within the same namespace, you can use the short name order-service.

Service Definition:

apiVersion: v1
kind: Service
metadata:
  name: order-service
  namespace: production
  labels:
    app: order-service
    version: v1
spec:
  selector:
    app: order-service
  ports:
  - name: http
    protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

Native Service Discovery in .NET 9

.NET 9 introduces enhanced service discovery capabilities with improved configuration and resilience features.

Basic Configuration:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Add service discovery with .NET 9 enhancements
builder.Services.AddServiceDiscovery();

// Configure HTTP client with service discovery
builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    // Use service name - discovery resolves to actual endpoint
    client.BaseAddress = new Uri("http://order-service");
})
.AddServiceDiscovery()
.AddStandardResilienceHandler(); // .NET 9 resilience patterns

var app = builder.Build();

Advanced Configuration with appsettings.json:

{
  "ServiceDiscovery": {
    "Providers": {
      "Kubernetes": {
        "Namespace": "production",
        "RefreshPeriod": "00:01:00"
      }
    },
    "Services": {
      "order-service": {
        "Scheme": "https",
        "EndpointNames": ["http", "https"],
        "HealthCheckPath": "/health"
      },
      "payment-service": {
        "Scheme": "http",
        "AllowAllHosts": false
      }
    },
    "AllowAllHosts": true,
    "AllowedHosts": ["*.svc.cluster.local"]
  }
}

Service-to-Service Communication Patterns

Using Typed HTTP Clients:

public interface IOrderServiceClient
{
    Task<Order> GetOrderAsync(Guid orderId, CancellationToken cancellationToken = default);
    Task<IEnumerable<Order>> GetOrdersByCustomerAsync(Guid customerId, CancellationToken cancellationToken = default);
}

public class OrderServiceClient : IOrderServiceClient
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<OrderServiceClient> _logger;

    public OrderServiceClient(HttpClient httpClient, ILogger<OrderServiceClient> logger)
    {
        _httpClient = httpClient;
        _logger = logger;
    }

    public async Task<Order> GetOrderAsync(Guid orderId, CancellationToken cancellationToken = default)
    {
        try
        {
            var response = await _httpClient.GetFromJsonAsync<Order>(
                $"api/orders/{orderId}", 
                cancellationToken);

            return response ?? throw new OrderNotFoundException(orderId);
        }
        catch (HttpRequestException ex)
        {
            _logger.LogError(ex, "Failed to retrieve order {OrderId}", orderId);
            throw;
        }
    }

    public async Task<IEnumerable<Order>> GetOrdersByCustomerAsync(
        Guid customerId, 
        CancellationToken cancellationToken = default)
    {
        return await _httpClient.GetFromJsonAsync<IEnumerable<Order>>(
            $"api/orders/customer/{customerId}", 
            cancellationToken) ?? [];
    }
}

Service Registration with Resilience:

builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    client.BaseAddress = new Uri("http://order-service");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddServiceDiscovery()
.AddStandardResilienceHandler(options =>
{
    // Configure circuit breaker
    options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(10);
    options.CircuitBreaker.FailureRatio = 0.5;
    options.CircuitBreaker.MinimumThroughput = 10;

    // Configure retry policy
    options.Retry.MaxRetryAttempts = 3;
    options.Retry.BackoffType = Polly.DelayBackoffType.Exponential;

    // Configure timeout
    options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(30);
});

Service Discovery in Azure Container Apps

Azure Container Apps provides built-in service discovery within the same environment, eliminating the need for manual endpoint configuration.

Environment Variables Approach

Container App Configuration:

{
  "properties": {
    "environmentId": "/subscriptions/.../containerappsenvironments/production-env",
    "configuration": {
      "ingress": {
        "external": false,
        "targetPort": 8080,
        "transport": "http",
        "allowInsecure": false
      }
    },
    "template": {
      "containers": [{
        "name": "api-service",
        "image": "myregistry.azurecr.io/api-service:latest",
        "env": [{
          "name": "OrderService__Url",
          "value": "https://order-service.internal.<environment-unique-id>.azurecontainerapps.io"
        },
        {
          "name": "ASPNETCORE_ENVIRONMENT",
          "value": "Production"
        }],
        "resources": {
          "cpu": 0.5,
          "memory": "1Gi"
        }
      }]
    }
  }
}

Consuming in .NET:

services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    var orderServiceUrl = configuration["OrderService:Url"] 
        ?? throw new InvalidOperationException("OrderService URL not configured");
    client.BaseAddress = new Uri(orderServiceUrl);
});

Native Service Discovery in Container Apps

Azure Container Apps now supports simplified service discovery using service names directly.

var builder = WebApplication.CreateBuilder(args);

// Add Azure Container Apps service discovery
builder.Services.AddServiceDiscovery();

builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    // Reference by Container App name within the same environment
    client.BaseAddress = new Uri("http://order-service");
})
.AddServiceDiscovery()
.AddStandardResilienceHandler();

// For external Container Apps (different environment)
builder.Services.AddHttpClient<IPaymentServiceClient, PaymentServiceClient>(client =>
{
    client.BaseAddress = new Uri("https://payment-service.politeocean-12345678.westeurope.azurecontainerapps.io");
})
.AddStandardResilienceHandler();

Dapr Integration for Service Invocation

Dapr (Distributed Application Runtime) provides a robust service invocation model with built-in retry, tracing, and security.

Dapr Configuration:

var builder = WebApplication.CreateBuilder(args);

// Add Dapr services
builder.Services.AddDaprClient();
builder.Services.AddControllers().AddDapr();

var app = builder.Build();
app.UseRouting();
app.UseCloudEvents(); // Enable CloudEvents for pub/sub
app.MapSubscribeHandler(); // Map Dapr subscription endpoint
app.MapControllers();

Service Invocation with Dapr:

public class OrderController : ControllerBase
{
    private readonly DaprClient _daprClient;
    private readonly ILogger<OrderController> _logger;

    public OrderController(DaprClient daprClient, ILogger<OrderController> logger)
    {
        _daprClient = daprClient;
        _logger = logger;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetOrder(Guid id)
    {
        try
        {
            // Invoke customer service via Dapr sidecar
            var customer = await _daprClient.InvokeMethodAsync<Customer>(
                HttpMethod.Get,
                "customer-service", // Dapr App ID
                $"api/customers/{id}");

            if (customer is null)
            {
                return NotFound();
            }

            return Ok(customer);
        }
        catch (DaprException ex)
        {
            _logger.LogError(ex, "Failed to invoke customer service for customer {CustomerId}", id);
            return StatusCode(503, "Service temporarily unavailable");
        }
    }

    [HttpPost]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // Invoke with request/response
        var inventoryCheck = await _daprClient.InvokeMethodAsync<InventoryCheckRequest, InventoryCheckResponse>(
            HttpMethod.Post,
            "inventory-service",
            "api/inventory/check",
            new InventoryCheckRequest 
            { 
                ProductId = request.ProductId, 
                Quantity = request.Quantity 
            });

        if (!inventoryCheck.IsAvailable)
        {
            return BadRequest("Insufficient inventory");
        }

        // Process order creation...
        return CreatedAtAction(nameof(GetOrder), new { id = Guid.NewGuid() }, null);
    }
}

Dapr Component Configuration for Container Apps:

# dapr-components.yaml
componentType: state.azure.cosmosdb
version: v1
metadata:
- name: url
  value: "https://mycosmosdb.documents.azure.com:443/"
- name: masterKey
  secretRef: cosmosdb-key
- name: database
  value: "ordersdb"
- name: collection
  value: "orders"
scopes:
- order-service

API Gateway and Ingress Patterns

What is an API Gateway?

An API gateway serves as a single entry point for client requests, providing:

Request routing to appropriate microservices
Authentication and authorization enforcement
Rate limiting and throttling to prevent abuse
Request/response transformation for protocol translation
Caching to improve performance
Load balancing across service instances
Monitoring and analytics for observability

Azure API Management

Azure API Management provides enterprise-grade API gateway capabilities with comprehensive policy support.

Read Configure ingress for an Azure Container Apps environment

Policy Configuration:

<policies>
    <inbound>
        <base />
        <!-- Rate limiting -->
        <rate-limit-by-key calls="100" 
                           renewal-period="60" 
                           counter-key="@(context.Request.IpAddress)" />

        <!-- JWT validation -->
        <validate-jwt header-name="Authorization" 
                      failed-validation-httpcode="401" 
                      failed-validation-error-message="Unauthorized">
            <openid-config url="https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration" />
            <required-claims>
                <claim name="roles" match="any">
                    <value>api.read</value>
                    <value>api.write</value>
                </claim>
            </required-claims>
        </validate-jwt>

        <!-- Dynamic backend routing -->
        <choose>
            <when condition="@(context.Request.Url.Path.StartsWith("/api/orders"))">
                <set-backend-service base-url="http://order-service.production.svc.cluster.local" />
            </when>
            <when condition="@(context.Request.Url.Path.StartsWith("/api/customers"))">
                <set-backend-service base-url="http://customer-service.production.svc.cluster.local" />
            </when>
            <otherwise>
                <return-response>
                    <set-status code="404" reason="Not Found" />
                </return-response>
            </otherwise>
        </choose>

        <!-- Add correlation ID -->
        <set-header name="X-Correlation-ID" exists-action="skip">
            <value>@(Guid.NewGuid().ToString())</value>
        </set-header>
    </inbound>
    <backend>
        <base />
        <retry condition="@(context.Response.StatusCode >= 500)" 
               count="3" 
               interval="2" 
               delta="1" 
               first-fast-retry="true" />
    </backend>
    <outbound>
        <base />
        <!-- Remove internal headers -->
        <set-header name="X-Powered-By" exists-action="delete" />
        <set-header name="X-AspNet-Version" exists-action="delete" />
    </outbound>
    <on-error>
        <base />
        <set-body>@{
            return new JObject(
                new JProperty("error", context.LastError.Message),
                new JProperty("correlationId", context.Request.Headers.GetValueOrDefault("X-Correlation-ID"))
            ).ToString();
        }</set-body>
    </on-error>
</policies>

YARP - .NET Native API Gateway

YARP (Yet Another Reverse Proxy) is a highly performant, .NET-native reverse proxy toolkit ideal for building custom API gateways.

Configuration:

{
  "ReverseProxy": {
    "Routes": {
      "order-route": {
        "ClusterId": "order-cluster",
        "Match": {
          "Path": "/api/orders/{**catch-all}"
        },
        "Transforms": [
          { "PathRemovePrefix": "/api" },
          { "RequestHeader": "X-Forwarded-For", "Append": "{RemoteIpAddress}" },
          { "RequestHeader": "X-Original-Host", "Set": "{OriginalHost}" }
        ],
        "Metadata": {
          "requireAuth": "true"
        }
      },
      "customer-route": {
        "ClusterId": "customer-cluster",
        "Match": {
          "Path": "/api/customers/{**catch-all}"
        },
        "RateLimiterPolicy": "fixed",
        "AuthorizationPolicy": "authenticated"
      },
      "websocket-route": {
        "ClusterId": "notification-cluster",
        "Match": {
          "Path": "/notifications"
        }
      }
    },
    "Clusters": {
      "order-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://order-service",
            "Health": "http://order-service/health"
          }
        },
        "HealthCheck": {
          "Active": {
            "Enabled": true,
            "Interval": "00:00:10",
            "Timeout": "00:00:05",
            "Policy": "ConsecutiveFailures",
            "Path": "/health"
          }
        },
        "LoadBalancingPolicy": "RoundRobin"
      },
      "customer-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://customer-service"
          },
          "destination2": {
            "Address": "http://customer-service-2"
          }
        }
      },
      "notification-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://notification-service"
          }
        }
      }
    }
  }
}

Program.cs with Advanced Features:

var builder = WebApplication.CreateBuilder(args);

// Add YARP with service discovery
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
    .AddServiceDiscovery();

// Add authentication
builder.Services.AddAuthentication()
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.microsoftonline.com/{tenant-id}/v2.0";
        options.Audience = "api://myapi";
    });

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("authenticated", policy =>
        policy.RequireAuthenticatedUser());
});

// Add rate limiting (.NET 9)
builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("fixed", opt =>
    {
        opt.Window = TimeSpan.FromMinutes(1);
        opt.PermitLimit = 100;
        opt.QueueLimit = 10;
    });

    options.AddSlidingWindowLimiter("sliding", opt =>
    {
        opt.Window = TimeSpan.FromMinutes(1);
        opt.PermitLimit = 100;
        opt.SegmentsPerWindow = 6;
    });
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

// Map YARP routes with custom middleware
app.MapReverseProxy(proxyPipeline =>
{
    proxyPipeline.Use(async (context, next) =>
    {
        // Add custom headers
        context.Request.Headers.Append("X-Gateway", "YARP");

        await next();

        // Log response
        var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
        logger.LogInformation(
            "Proxied {Method} {Path} -> {StatusCode}", 
            context.Request.Method, 
            context.Request.Path, 
            context.Response.StatusCode);
    });
});

app.Run();

Kubernetes Ingress

Kubernetes Ingress resources manage external access to services, providing HTTP/HTTPS routing with SSL termination.

Ingress Configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/rate-limit: "100"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://app.company.com"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - api.company.com
    secretName: api-tls-secret
  rules:
  - host: api.company.com
    http:
      paths:
      - path: /orders(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: order-service
            port:
              number: 80
      - path: /customers(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: customer-service
            port:
              number: 80
      - path: /payments(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: payment-service
            port:
              number: 80

Gateway API (Next Generation):

Kubernetes Gateway API provides more expressive and extensible routing capabilities.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: api-gateway
  namespace: production
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - name: api-tls-secret
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: order-route
  namespace: production
spec:
  parentRefs:
  - name: api-gateway
  hostnames:
  - "api.company.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/orders
    backendRefs:
    - name: order-service
      port: 80
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /

Best Practices

Health Checks

Implement comprehensive health checks for proper service discovery and load balancing.

builder.Services.AddHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database")
    .AddCheck<RedisHealthCheck>("redis")
    .AddHttpClient("order-service", client =>
    {
        client.BaseAddress = new Uri("http://order-service");
    })
    .AddCheck("order-service-health");

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = _ => true,
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("live")
});

Observability

Enable distributed tracing and metrics for monitoring service communication.

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddSource("OrderService");
    })
    .WithMetrics(metrics =>
    {
        metrics
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddRuntimeInstrumentation();
    });

Security Considerations

Always use HTTPS for external service communication
Implement mutual TLS (mTLS) for service-to-service communication
Use service mesh (Linkerd, Istio) for advanced security policies
Apply principle of least privilege for service accounts
Regularly rotate credentials and certificates
Implement API keys or OAuth for external API access

Summary

Service discovery is fundamental to building resilient microservices architectures. .NET 9 provides native service discovery capabilities that integrate seamlessly with Kubernetes, Azure Container Apps, and custom solutions. Combining service discovery with API gateways like YARP or Azure API Management creates a robust, scalable foundation for distributed applications.

Choose your approach based on your infrastructure:

Kubernetes: Use native DNS with .NET service discovery
Azure Container Apps: Leverage built-in service discovery or Dapr
Hybrid/Multi-cloud: Implement YARP or Azure API Management for unified routing

Always prioritize observability, security, and resilience patterns to ensure production-ready services.

Service Communication Patterns in .NET Core and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:24:59 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

Asynchronous Messaging with Azure Service Bus

Azure Service Bus provides enterprise-grade messaging infrastructure with advanced features for reliable message delivery, ordering guarantees, and complex routing scenarios.

Service Bus vs Azure Queue Storage

Azure Service Bus offers enterprise messaging capabilities including:

Topics and subscriptions for pub/sub patterns
Message sessions for ordered processing
Transaction support across operations
Dead-letter queues for failed messages
Messages up to 100MB (premium tier)
Advanced routing with filters and actions

Azure Queue Storage provides:

Simple FIFO queue operations
Lower cost for basic scenarios
Messages up to 64KB
Best for simple point-to-point messaging

When to Choose Service Bus

Use Azure Service Bus when you need:

Publish-subscribe patterns with multiple subscribers
Guaranteed message ordering with sessions
Transactional message processing
Message size beyond 64KB
Advanced routing and filtering
Integration with hybrid or on-premises systems

Implementation with .NET 9

.NET 9 introduces improved performance and simplified APIs for working with Azure Service Bus:

// Producer using .NET 9 with improved performance
public class OrderCreatedPublisher
{
    private readonly ServiceBusSender _sender;

    public OrderCreatedPublisher(ServiceBusClient client)
    {
        _sender = client.CreateSender("order-events");
    }

    public async Task PublishOrderCreatedAsync(Order order, CancellationToken cancellationToken = default)
    {
        var message = new ServiceBusMessage(JsonSerializer.Serialize(order))
        {
            MessageId = order.OrderId.ToString(),
            Subject = "OrderCreated",
            ContentType = "application/json",
            // .NET 9: Better support for distributed tracing
            ApplicationProperties = 
            {
                ["CorrelationId"] = Activity.Current?.Id ?? Guid.NewGuid().ToString(),
                ["OrderDate"] = order.CreatedAt.ToString("O")
            }
        };

        await _sender.SendMessageAsync(message, cancellationToken);
    }
}

// Consumer using BackgroundService
public class InventoryService : BackgroundService
{
    private readonly ServiceBusProcessor _processor;
    private readonly ILogger<InventoryService> _logger;
    private readonly IInventoryRepository _repository;

    public InventoryService(
        ServiceBusClient client, 
        ILogger<InventoryService> logger,
        IInventoryRepository repository)
    {
        _processor = client.CreateProcessor("order-events", "inventory-subscription");
        _processor.ProcessMessageAsync += ProcessMessageHandler;
        _processor.ProcessErrorAsync += ErrorHandler;
        _logger = logger;
        _repository = repository;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await _processor.StartProcessingAsync(stoppingToken);

        // .NET 9: Improved cancellation handling
        await Task.Delay(Timeout.InfiniteTimeSpan, stoppingToken);
    }

    public override async Task StopAsync(CancellationToken cancellationToken)
    {
        await _processor.StopProcessingAsync(cancellationToken);
        await base.StopAsync(cancellationToken);
    }

    private async Task ProcessMessageHandler(ProcessMessageEventArgs args)
    {
        try
        {
            var order = JsonSerializer.Deserialize<Order>(args.Message.Body);

            // Reserve inventory with idempotency check
            await _repository.ReserveInventoryAsync(order!, args.CancellationToken);

            // Complete the message
            await args.CompleteMessageAsync(args.Message, args.CancellationToken);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error processing order message {MessageId}", args.Message.MessageId);

            // Dead-letter the message if processing fails repeatedly
            if (args.Message.DeliveryCount > 3)
            {
                await args.DeadLetterMessageAsync(args.Message, 
                    "Processing failed after retries", 
                    ex.Message, 
                    args.CancellationToken);
            }
            else
            {
                await args.AbandonMessageAsync(args.Message, cancellationToken: args.CancellationToken);
            }
        }
    }

    private Task ErrorHandler(ProcessErrorEventArgs args)
    {
        _logger.LogError(args.Exception, "Service Bus processor error: {ErrorSource}", args.ErrorSource);
        return Task.CompletedTask;
    }
}

Dependency Injection Setup for .NET 9

// Program.cs with .NET 9 improvements
var builder = WebApplication.CreateBuilder(args);

// Azure Service Bus with managed identity
builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddServiceBusClient(builder.Configuration.GetSection("ServiceBus"))
        .WithCredential(new DefaultAzureCredential());
});

// Register background services
builder.Services.AddHostedService<InventoryService>();
builder.Services.AddSingleton<OrderCreatedPublisher>();

// Add health checks for Service Bus
builder.Services.AddHealthChecks()
    .AddAzureServiceBusQueue(
        builder.Configuration["ServiceBus:ConnectionString"]!,
        "order-events");

Pub/Sub vs Producer/Consumer Patterns

Understanding when to use each pattern is crucial for effective system design.

Publish-Subscribe Pattern

In pub/sub, events are broadcast to multiple independent subscribers who each receive a copy of every message. This pattern excels at:

Event notification across multiple services
Decoupling event producers from consumers
Allowing new subscribers without changing publishers
Broadcasting state changes to interested parties

Implementation Options:

Azure Service Bus Topics: Durable messaging with advanced filtering
Azure Event Grid: Lightweight, serverless event routing

Producer-Consumer Pattern

Producer-consumer implements point-to-point communication where each message is processed by exactly one consumer. Ideal for:

Work queue distribution
Load balancing across workers
Task processing with guaranteed completion
Rate limiting and backpressure handling

Implementation Options:

Azure Service Bus Queues: Enterprise features with transactions
Azure Queue Storage: Simple, cost-effective queuing
RabbitMQ: Self-hosted option with rich features

Azure Event Grid Example

public class EventGridPublisher
{
    private readonly EventGridPublisherClient _client;
    private readonly ILogger<EventGridPublisher> _logger;

    public EventGridPublisher(EventGridPublisherClient client, ILogger<EventGridPublisher> logger)
    {
        _client = client;
        _logger = logger;
    }

    public async Task PublishOrderEventAsync(OrderCreated orderEvent, CancellationToken cancellationToken = default)
    {
        var cloudEvent = new CloudEvent(
            source: "OrderService",
            type: "Order.Created",
            jsonSerializableData: orderEvent)
        {
            Id = Guid.NewGuid().ToString(),
            Time = DateTimeOffset.UtcNow,
            // .NET 9: Enhanced structured data support
            ExtensionAttributes = 
            {
                ["correlationId"] = orderEvent.CorrelationId,
                ["orderAmount"] = orderEvent.TotalAmount
            }
        };

        try
        {
            await _client.SendEventAsync(cloudEvent, cancellationToken);
            _logger.LogInformation("Published order event {OrderId}", orderEvent.OrderId);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to publish order event {OrderId}", orderEvent.OrderId);
            throw;
        }
    }
}

Azure Event Grid vs Azure Service Bus

When to Use Event Grid

Event Grid excels in event-driven architectures requiring:

Serverless integration: Trigger Azure Functions, Logic Apps
React to Azure service events: Storage changes, resource updates
Real-time notifications: Push updates to web clients
High throughput: Millions of events per second
Low latency: Sub-second delivery
Pay per event: Cost-effective for sporadic events

Best for: State change notifications, IoT telemetry, serverless workflows, webhook delivery

When to Use Service Bus

Service Bus is designed for enterprise messaging requiring:

Message sessions: Ordered processing of related messages
Transactions: ACID guarantees across operations
Dead-letter queues: Handle poison messages
Scheduled delivery: Defer message processing
Duplicate detection: Automatic deduplication
Large messages: Up to 100MB payloads

Best for: Order processing, financial transactions, workflow orchestration, hybrid cloud integration

Commands and Queries with CQRS

Command Query Responsibility Segregation separates write operations (commands) from read operations (queries), enabling independent optimization and scaling.

MediatR in .NET 9

MediatR provides in-process mediator pattern implementation with .NET 9 performance improvements:

// Command with validation
public record CreateOrderCommand(Guid CustomerId, List<OrderLineDto> Items) 
    : IRequest<Result<Guid>>;

// Fluent validation
public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty();
        RuleForEach(x => x.Items).SetValidator(new OrderLineValidator());
    }
}

// Command Handler with event publishing
public class CreateOrderCommandHandler 
    : IRequestHandler<CreateOrderCommand, Result<Guid>>
{
    private readonly IOrderRepository _repository;
    private readonly IPublisher _publisher;
    private readonly ILogger<CreateOrderCommandHandler> _logger;

    public async Task<Result<Guid>> Handle(
        CreateOrderCommand request, 
        CancellationToken cancellationToken)
    {
        try
        {
            // Create aggregate
            var order = Order.Create(request.CustomerId, request.Items);
            await _repository.AddAsync(order, cancellationToken);

            // Publish domain event
            await _publisher.Publish(
                new OrderCreatedEvent(order.Id, order.CustomerId, order.TotalAmount), 
                cancellationToken);

            _logger.LogInformation("Order {OrderId} created for customer {CustomerId}", 
                order.Id, order.CustomerId);

            return Result<Guid>.Success(order.Id);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to create order for customer {CustomerId}", request.CustomerId);
            return Result<Guid>.Failure("Failed to create order");
        }
    }
}

// Query with projection
public record GetOrderQuery(Guid OrderId) : IRequest<Result<OrderDto>>;

// Query Handler using read model
public class GetOrderQueryHandler 
    : IRequestHandler<GetOrderQuery, Result<OrderDto>>
{
    private readonly IOrderReadRepository _repository;
    private readonly IMemoryCache _cache;

    public async Task<Result<OrderDto>> Handle(
        GetOrderQuery request, 
        CancellationToken cancellationToken)
    {
        // .NET 9: Improved caching with GetOrCreateAsync
        var order = await _cache.GetOrCreateAsync(
            $"order:{request.OrderId}",
            async entry =>
            {
                entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5);
                return await _repository.GetByIdAsync(request.OrderId, cancellationToken);
            });

        return order is not null 
            ? Result<OrderDto>.Success(order) 
            : Result<OrderDto>.Failure("Order not found");
    }
}

Pipeline Behaviors for Cross-Cutting Concerns

// Validation behavior
public class ValidationBehavior<TRequest, TResponse> 
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly IEnumerable<IValidator<TRequest>> _validators;

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        if (!_validators.Any()) return await next();

        var context = new ValidationContext<TRequest>(request);
        var failures = _validators
            .Select(v => v.Validate(context))
            .SelectMany(result => result.Errors)
            .Where(f => f != null)
            .ToList();

        if (failures.Count != 0)
            throw new ValidationException(failures);

        return await next();
    }
}

// Logging behavior with .NET 9 structured logging
public class LoggingBehavior<TRequest, TResponse> 
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        var requestName = typeof(TRequest).Name;

        _logger.LogInformation("Handling {RequestName}", requestName);
        var stopwatch = Stopwatch.StartNew();

        try
        {
            var response = await next();
            stopwatch.Stop();

            _logger.LogInformation("Handled {RequestName} in {ElapsedMs}ms", 
                requestName, stopwatch.ElapsedMilliseconds);

            return response;
        }
        catch (Exception ex)
        {
            stopwatch.Stop();
            _logger.LogError(ex, "Error handling {RequestName} after {ElapsedMs}ms", 
                requestName, stopwatch.ElapsedMilliseconds);
            throw;
        }
    }
}

Common Anti-Patterns and Solutions

SignalR and CQRS Anti-Pattern

Using SignalR hubs for synchronous command-response patterns defeats the purpose of CQRS and creates a fragile, tightly-coupled system.

Anti-Pattern: Synchronous Command Over WebSocket

// BAD: Treating SignalR as synchronous RPC
public class OrderHub : Hub
{
    private readonly IOrderService _orderService;

    // This is NOT true CQRS - it's synchronous RPC over WebSockets
    public async Task<OrderResult> SubmitOrder(CreateOrderRequest request)
    {
        // Caller waits for complete processing
        return await _orderService.ProcessOrderAsync(request);
    }
}

Problems with this approach:

Couples UI latency directly to backend processing time
WebSocket connection can timeout or drop during processing
No retry mechanism if connection fails
Cannot scale command processing independently
Creates artificial synchronous behavior in an async system

Recommended Pattern: Async Command Processing with SignalR Notifications

Implement true asynchronous command handling with status updates pushed via SignalR:

// GOOD: Async command submission with correlation
public class OrderHub : Hub
{
    private readonly ServiceBusSender _commandSender;
    private readonly ILogger<OrderHub> _logger;

    public async Task<CommandAccepted> SubmitOrder(CreateOrderRequest request)
    {
        var correlationId = Guid.NewGuid().ToString();

        // Add user to correlation group for status updates
        await Groups.AddToGroupAsync(Context.ConnectionId, correlationId);

        // Enqueue command to Service Bus
        var command = new CreateOrderCommand(request.CustomerId, request.Items)
        {
            CorrelationId = correlationId,
            UserId = Context.User?.Identity?.Name
        };

        var message = new ServiceBusMessage(JsonSerializer.Serialize(command))
        {
            MessageId = correlationId,
            Subject = "CreateOrder",
            ApplicationProperties = { ["UserId"] = command.UserId }
        };

        await _commandSender.SendMessageAsync(message);

        _logger.LogInformation("Order command queued with correlation {CorrelationId}", correlationId);

        // Return 202 Accepted immediately
        return new CommandAccepted(correlationId, "Order is being processed");
    }
}

// Command handler processes asynchronously
public class CreateOrderCommandHandler : IConsumer<CreateOrderCommand>
{
    private readonly IOrderRepository _repository;
    private readonly IHubContext<OrderHub> _hubContext;
    private readonly IPublisher _publisher;

    public async Task Consume(ConsumeContext<CreateOrderCommand> context)
    {
        var command = context.Message;

        try
        {
            // Send processing notification
            await _hubContext.Clients.Group(command.CorrelationId)
                .SendAsync("OrderStatusUpdate", new { Status = "Processing", command.CorrelationId });

            // Process business logic
            var order = Order.Create(command.CustomerId, command.Items);
            await _repository.AddAsync(order);

            // Publish domain events to update read models
            await _publisher.Publish(new OrderCreatedEvent(order.Id, command.CorrelationId));

            // Send completion notification
            await _hubContext.Clients.Group(command.CorrelationId)
                .SendAsync("OrderCompleted", new { order.Id, command.CorrelationId });
        }
        catch (Exception ex)
        {
            // Send error notification
            await _hubContext.Clients.Group(command.CorrelationId)
                .SendAsync("OrderFailed", new { Error = ex.Message, command.CorrelationId });
        }
    }
}

// Read model updater for queries
public class OrderProjection : IEventHandler<OrderCreatedEvent>
{
    private readonly IOrderReadRepository _readRepository;

    public async Task Handle(OrderCreatedEvent evt, CancellationToken cancellationToken)
    {
        // Update denormalized read model for fast queries
        await _readRepository.UpsertAsync(evt.OrderId, evt.ToDto(), cancellationToken);
    }
}

Complete Async Flow Architecture

Client → SignalR Hub: Submit command, receive correlation ID immediately
Hub: Validate, enqueue to message broker, return 202 Accepted
Command Handler: Process business logic, emit domain events, update write model
Event Handlers: Update read models and projections
Notifications: Push progress via SignalR using correlation ID
Client: Query read model endpoint for latest state

Key Principles

CQRS Does Not Require Async: CQRS fundamentally means separating command and query models. You can implement commands synchronously in a monolith and still follow CQRS. Asynchrony and message queues are architectural choices for scalability and decoupling, not strict CQRS requirements.

Eventual Consistency is Common: When using async commands with CQRS, read models are typically eventually consistent. This is acceptable for most business scenarios and enables independent scaling.

Implementation Best Practices

Transport Layer: Use Rebus or MassTransit with Azure Service Bus for command transport. Reserve SignalR exclusively for pushing notifications to clients, never for inter-service communication.

Outbox Pattern: Implement transactional outbox to ensure commands and events are persisted atomically with domain changes, guaranteeing at-least-once delivery without duplicates.

Idempotency: Make all command handlers idempotent using command IDs or correlation IDs to safely handle retries and duplicate messages.

Correlation: Thread correlation IDs through logs, messages, and SignalR groups to trace operations across distributed components.

Security: Never trust hub payloads. Revalidate all commands in handlers. Use per-user or per-correlation groups in SignalR to prevent unauthorized access to status updates.

User Experience: Return fast with 202 Accepted, display processing status, push updates via SignalR, and query the read model endpoint for authoritative data.

Chatty Services Anti-Pattern

Chatty services make excessive synchronous calls between services, creating network overhead, increased latency, and tight coupling.

Example of Anti-Pattern:

// BAD: Multiple sequential synchronous calls
public async Task<OrderSummary> GetOrderSummaryAsync(Guid orderId)
{
    // Each call waits for the previous to complete
    var order = await _orderClient.GetOrderAsync(orderId);
    var customer = await _customerClient.GetCustomerAsync(order.CustomerId);
    var payment = await _paymentClient.GetPaymentAsync(orderId);
    var shipping = await _shippingClient.GetShippingAsync(orderId);
    var inventory = await _inventoryClient.GetInventoryStatusAsync(orderId);

    // High latency: sum of all service calls plus network overhead
    return new OrderSummary(order, customer, payment, shipping, inventory);
}

Problems:

Total latency is sum of all service calls
Single point of failure if any service is unavailable
Tight coupling between services
Poor scalability under load
Difficult to version and evolve independently

Solution: Materialized Views and CQRS

Implement event-driven read models that aggregate data asynchronously:

// GOOD: Query pre-aggregated materialized view
public class OrderSummaryQueryHandler : IRequestHandler<GetOrderSummaryQuery, OrderSummaryDto>
{
    private readonly IOrderSummaryReadRepository _repository;
    private readonly IMemoryCache _cache;

    public async Task<OrderSummaryDto> Handle(
        GetOrderSummaryQuery request, 
        CancellationToken cancellationToken)
    {
        // Query optimized read model - single database call
        var summary = await _cache.GetOrCreateAsync(
            $"order-summary:{request.OrderId}",
            async entry =>
            {
                entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5);
                return await _repository.GetOrderSummaryAsync(request.OrderId, cancellationToken);
            });

        return summary;
    }
}

// Update materialized view via domain events
public class OrderSummaryProjection : 
    IEventHandler<OrderCreatedEvent>,
    IEventHandler<PaymentCompletedEvent>,
    IEventHandler<ShippingUpdatedEvent>
{
    private readonly IOrderSummaryReadRepository _repository;

    public async Task Handle(OrderCreatedEvent evt, CancellationToken cancellationToken)
    {
        var summary = new OrderSummaryDto
        {
            OrderId = evt.OrderId,
            CustomerId = evt.CustomerId,
            TotalAmount = evt.TotalAmount,
            Status = "Created",
            CreatedAt = evt.CreatedAt
        };

        await _repository.UpsertAsync(summary, cancellationToken);
    }

    public async Task Handle(PaymentCompletedEvent evt, CancellationToken cancellationToken)
    {
        await _repository.UpdatePaymentStatusAsync(
            evt.OrderId, 
            "Paid", 
            evt.PaymentMethod, 
            cancellationToken);
    }

    public async Task Handle(ShippingUpdatedEvent evt, CancellationToken cancellationToken)
    {
        await _repository.UpdateShippingStatusAsync(
            evt.OrderId, 
            evt.Status, 
            evt.TrackingNumber, 
            cancellationToken);
    }
}

Alternative: Backend for Frontend (BFF) Pattern

For scenarios where real-time consistency is required, implement a BFF that intelligently aggregates:

// BFF with parallel calls and circuit breaker
public class OrderBffService
{
    private readonly IOrderClient _orderClient;
    private readonly ICustomerClient _customerClient;
    private readonly IPaymentClient _paymentClient;
    private readonly ILogger<OrderBffService> _logger;

    public async Task<OrderSummary> GetOrderSummaryAsync(
        Guid orderId, 
        CancellationToken cancellationToken)
    {
        // Execute calls in parallel to reduce total latency
        var orderTask = _orderClient.GetOrderAsync(orderId, cancellationToken);

        // Wait for order to get customer ID
        var order = await orderTask;

        // Now parallel calls for remaining data
        var customerTask = _customerClient.GetCustomerAsync(order.CustomerId, cancellationToken);
        var paymentTask = _paymentClient.GetPaymentAsync(orderId, cancellationToken);
        var shippingTask = _shippingClient.GetShippingAsync(orderId, cancellationToken);

        await Task.WhenAll(customerTask, paymentTask, shippingTask);

        return new OrderSummary(
            order, 
            customerTask.Result, 
            paymentTask.Result, 
            shippingTask.Result);
    }
}

Monitoring Chatty Services

Proactively identify chatty service patterns using Azure Application Insights:

// Configure Application Insights with enhanced dependency tracking
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry(options =>
{
    options.EnableDependencyTrackingTelemetryModule = true;
    options.EnableRequestTrackingTelemetryModule = true;
    options.ConnectionString = builder.Configuration["ApplicationInsights:ConnectionString"];
});

// Add custom telemetry for detailed tracking
builder.Services.AddSingleton<ITelemetryInitializer, ServiceCallTelemetryInitializer>();

KQL Queries for Detection

Use Kusto Query Language to identify problematic patterns:

// Detect excessive service-to-service calls
dependencies
| where timestamp > ago(1h)
| where type == "HTTP" or type == "Azure Service Bus"
| summarize 
    CallCount = count(), 
    AvgDuration = avg(duration),
    P95Duration = percentile(duration, 95),
    P99Duration = percentile(duration, 99)
    by target, name, operation_Name
| where CallCount > 100
| order by CallCount desc

// Identify sequential call chains (chatty pattern indicator)
requests
| where timestamp > ago(1h)
| join kind=inner (
    dependencies
    | where timestamp > ago(1h)
) on operation_Id
| summarize 
    DependencyCount = dcount(name),
    TotalDuration = sum(duration),
    RequestDuration = max(duration1)
    by operation_Id, operation_Name
| where DependencyCount > 5
| order by DependencyCount desc

// Find slow operations with many dependencies
requests
| where timestamp > ago(24h)
| where duration > 1000 // over 1 second
| join kind=inner (
    dependencies
    | summarize DepCount = count(), DepDuration = sum(duration) by operation_Id
) on operation_Id
| where DepCount > 3
| project 
    timestamp, 
    operation_Name, 
    duration, 
    DepCount, 
    DepDuration,
    ChattyRatio = DepDuration / duration * 100
| order by ChattyRatio desc

Alerting Setup

Create proactive alerts in Azure Monitor:

// High dependency call rate alert
{
    "name": "High Service Dependency Calls",
    "description": "Alert when service makes excessive calls to dependencies",
    "severity": 2,
    "evaluationFrequency": "PT5M",
    "windowSize": "PT15M",
    "criteria": {
        "allOf": [{
            "query": "dependencies | where timestamp > ago(15m) | summarize count() by target | where count_ > 500",
            "threshold": 0,
            "operator": "GreaterThan"
        }]
    }
}

Advanced Patterns in .NET 9

Using Keyed Services for Multi-Tenant Messaging

.NET 9 introduces keyed services for better dependency injection:

// Register multiple Service Bus clients for different tenants
builder.Services.AddKeyedSingleton<ServiceBusClient>("tenant-a", (sp, key) =>
    new ServiceBusClient(builder.Configuration["ServiceBus:TenantA:ConnectionString"]));

builder.Services.AddKeyedSingleton<ServiceBusClient>("tenant-b", (sp, key) =>
    new ServiceBusClient(builder.Configuration["ServiceBus:TenantB:ConnectionString"]));

// Use in services
public class MultiTenantOrderPublisher
{
    private readonly IServiceProvider _serviceProvider;

    public async Task PublishAsync(string tenantId, Order order)
    {
        var client = _serviceProvider.GetRequiredKeyedService<ServiceBusClient>(tenantId);
        var sender = client.CreateSender("orders");
        await sender.SendMessageAsync(new ServiceBusMessage(JsonSerializer.Serialize(order)));
    }
}

TimeProvider for Testable Time-Based Operations

// Use TimeProvider abstraction for testable delayed messages
public class ScheduledOrderService
{
    private readonly ServiceBusSender _sender;
    private readonly TimeProvider _timeProvider;

    public ScheduledOrderService(ServiceBusSender sender, TimeProvider timeProvider)
    {
        _sender = sender;
        _timeProvider = timeProvider;
    }

    public async Task ScheduleOrderProcessingAsync(Order order, TimeSpan delay)
    {
        var message = new ServiceBusMessage(JsonSerializer.Serialize(order))
        {
            ScheduledEnqueueTime = _timeProvider.GetUtcNow().Add(delay)
        };

        await _sender.SendMessageAsync(message);
    }
}

// In tests, use FakeTimeProvider
var fakeTime = new FakeTimeProvider();
var service = new ScheduledOrderService(sender, fakeTime);

Conclusion

Building resilient distributed systems requires careful selection of communication patterns. Use asynchronous messaging for decoupling, implement CQRS properly with event-driven read models, avoid chatty service patterns with materialized views, and leverage .NET 9's enhanced performance and features for optimal results.

Monitor your services continuously with Application Insights and KQL queries to detect anti-patterns early. Following these proven patterns will help you build scalable, maintainable microservices architectures on Azure.

Service Boundaries and Domain-Driven Design in .NET Core and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:19:48 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

What “Explicit Context Mapping” means (in DDD terms)

In DDD, context mapping is how you define and document the relationships between bounded contexts (separate domain models owned by different teams or services). Making it explicit means you don’t let integration “just happen” through ad-hoc calls or shared tables—you codify the relationships, the integration style (e.g., Customer-Supplier, Shared Kernel, Open Host Service), and the translation layer between models so it’s visible in code and contracts, not tribal knowledge. (martinfowler.com)

How to do it in .NET (Core) — a minimal, workable recipe

Carve out bounded contexts

Split into separate projects (or services) with their own models, persistence, and language.

/src
  /SalesContext.Api
  /SalesContext.Domain
  /SalesContext.Infrastructure (EF Core, Migrations)
  /BillingContext.Api
  /BillingContext.Domain
  /BillingContext.Infrastructure
  /Contracts (versioned DTOs/events)

Document the relationship (e.g., Sales is upstream, Billing is downstream using Customer-Supplier with Published Language via events/HTTP). (ddd-crew on GitHub)

Choose an integration style and make it concrete

Common explicit patterns:

Open Host Service + Published Language (HTTP/REST or gRPC with explicit contracts)
Event Publication (messages with versioned schemas)
Anti-Corruption Layer (ACL) (an adapter/translator that shields your domain from upstream models)

Pick one per interaction and stick it in code (see next steps). (InfoQ)

Define explicit contracts (don’t leak domain models)

Create a Contracts assembly shared only as schemas (not domain types).

// Contracts/Orders/v1/OrderPlaced.v1.cs
namespace Contracts.Orders.V1;
public record OrderPlacedV1(
    Guid OrderId,
    Guid CustomerId,
    decimal TotalAmount,
    string Currency,
    DateTimeOffset OccurredAt);

Version contracts (V1, V2…) and keep them stable.

Build an Anti-Corruption Layer in the downstream context

Put all mapping code in one place so domain stays pure.

// BillingContext.Infrastructure/Integration/OrdersAcl.cs
using Contracts.Orders.V1;
using BillingContext.Domain.Billing;

public interface IOrdersAcl {
    InvoiceDraft Translate(OrderPlacedV1 evt);
}

public sealed class OrdersAcl : IOrdersAcl {
    public InvoiceDraft Translate(OrderPlacedV1 evt) =>
        InvoiceDraft.Create(
            invoiceId: Guid.NewGuid(),
            orderId: evt.OrderId,
            customerId: evt.CustomerId,
            amount: Money.Of(evt.TotalAmount, evt.Currency),
            issuedAt: evt.OccurredAt);
}

You can hand-roll mappings (fast/explicit), or use a mapper (AutoMapper/Mapster/TransverseMapper) if you prefer. Mapster supports code-gen for explicit mapper classes if you want compile-time safety. (GitHub)

Wire it through messaging or HTTP

Example: event consuming (MassTransit/NServiceBus/ReBus or raw Rabbit/Kafka). Here’s a handler calling the ACL:

// BillingContext.Api/Consumers/OrderPlacedConsumer.cs
using Contracts.Orders.V1;
using MassTransit;

public class OrderPlacedConsumer : IConsumer<OrderPlacedV1> {
    private readonly IOrdersAcl _acl;
    private readonly IBillingRepository _repo;

    public OrderPlacedConsumer(IOrdersAcl acl, IBillingRepository repo) {
        _acl = acl; _repo = repo;
    }

    public async Task Consume(ConsumeContext<OrderPlacedV1> context) {
        var draft = _acl.Translate(context.Message);
        await _repo.SaveDraftAsync(draft, context.CancellationToken);
    }
}

For Open Host Service: expose a minimal API in Sales with DTOs from Contracts, consume in Billing, then pass through the ACL.

Keep persistence mapping internal to each context

Use EF Core configurations inside each context; never expose these types across contexts.

// BillingContext.Infrastructure/Config/InvoiceConfig.cs
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

internal sealed class InvoiceConfig : IEntityTypeConfiguration<Invoice> {
    public void Configure(EntityTypeBuilder<Invoice> b) {
        b.ToTable("Invoices");
        b.HasKey(i => i.Id);
        b.OwnsOne(i => i.Amount, m => {
            m.Property(p => p.Value).HasColumnName("Amount");
            m.Property(p => p.Currency).HasColumnName("Currency").HasMaxLength(3);
        });
        b.Property(i => i.IssuedAt);
        // etc.
    }
}

(These are regular EF Core mappings—separate from context mapping—but important to keep bounded context persistence clean.) ([Anton Dev Tips][5])

Test the map (contract tests)

Consumer tests in Billing verify that a recorded OrderPlacedV1 yields the expected InvoiceDraft.
Provider tests in Sales verify it emits OrderPlacedV1 matching schema. This locks the integration map and catches breaking changes early.

Tiny, end-to-end example (HTTP, Open Host + ACL)

Sales exposes an endpoint with a published language:

// SalesContext.Api/OrdersController.cs
[ApiController]
[Route("api/orders")]
public class OrdersController : ControllerBase {
    [HttpGet("{id:guid}")]
    public ActionResult<Contracts.Orders.V1.OrderDtoV1> Get(Guid id) {
        var order = _app.GetOrder(id);
        return new Contracts.Orders.V1.OrderDtoV1(
            order.Id, order.CustomerId, order.Total.Value, order.Total.Currency);
    }
}

Billing calls it and uses the ACL:

// BillingContext.Infrastructure/Integration/OrdersClient.cs
public sealed class OrdersClient(HttpClient http) {
    public async Task<OrderDtoV1?> Get(Guid id, CancellationToken ct) =>
        await http.GetFromJsonAsync<OrderDtoV1>($"api/orders/{id}", ct);
}

// BillingContext.Application/UseCases/GenerateInvoice.cs
public sealed class GenerateInvoice {
    private readonly OrdersClient _client;
    private readonly IOrdersAcl _acl;
    private readonly IBillingRepository _repo;

    public async Task Handle(Guid orderId, CancellationToken ct) {
        var dto = await _client.Get(orderId, ct) ?? throw new InvalidOperationException();
        var draft = _acl.Translate(new OrderPlacedV1(dto.OrderId, dto.CustomerId, dto.Total, dto.Currency, DateTimeOffset.UtcNow));
        await _repo.SaveDraftAsync(draft, ct);
    }
}

The map is explicit: contracts, translation, and the chosen relationship are all visible in code and docs.

Tips & pitfalls

Never reference another context’s domain types—only contracts.
Put all cross-context translations in one ACL layer, not scattered.
Version contracts (V1/V2) and don’t break old consumers.
Prefer domain language inside each context; translations happen only at the edges.
Document the chosen patterns (Customer-Supplier, Shared Kernel, etc.) in your repo’s /architecture/ folder.

Tools for Bounded Context Definition:

Context Mapper: A DSL for strategic DDD
EventStorming: Workshop-based approach to identify boundaries
C4 Model diagrams: Visual documentation of contexts
.NET Aspire: For local development orchestration of bounded contexts

Example with .NET Aspire:

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var orderService = builder.AddProject<Projects.OrderService>("order-service");
var customerService = builder.AddProject<Projects.CustomerService>("customer-service");
var inventoryService = builder.AddProject<Projects.InventoryService>("inventory-service");

builder.Build().Run();

Analyzing Coupling

Coupling Analysis Techniques:

Static Code Analysis using NDepend or Roslyn Analyzers:

// Custom Roslyn Analyzer to detect cross-boundary references
[DiagnosticAnalyzer(LanguageNames.CSharp)]
public class BoundedContextAnalyzer : DiagnosticAnalyzer
{
    public override void Initialize(AnalysisContext context)
    {
        context.RegisterSyntaxNodeAction(AnalyzeNode, 
            SyntaxKind.UsingDirective);
    }

    private void AnalyzeNode(SyntaxNodeAnalysisContext context)
    {
        // Check for references across bounded contexts
    }
}

Dependency Graphs - Use Visual Studio or Rider's architecture tools
ArchUnit.NET for architectural testing:

[Test]
public void OrderService_Should_Not_Reference_CustomerService()
{
    var architecture = new ArchLoader()
        .LoadAssemblies(typeof(OrderService).Assembly)
        .Build();

    var rule = Types()
        .That().ResideInNamespace("OrderManagement")
        .Should().NotDependOnAny("CustomerManagement.Domain");

    rule.Check(architecture);
}

Analyzing Communication

Tools and Approaches:

Application Insights with dependency tracking:

services.AddApplicationInsightsTelemetry(options =>
{
    options.ConnectionString = configuration["ApplicationInsights:ConnectionString"];
    options.EnableDependencyTrackingTelemetryModule = true;
});

Distributed Tracing with OpenTelemetry:

services.AddOpenTelemetry()
    .WithTracing(tracerProviderBuilder =>
    {
        tracerProviderBuilder
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddAzureMonitorTraceExporter();
    });

Service Mesh (like Dapr or Linkerd) provides communication analytics out-of-the-box.

Security Best Practices in .NET Core and Azure

Hossein Esmati — Fri, 26 Jun 2026 12:19:38 +0000

This article is part of the Comprehensive Guide to Microservices Architecture in .NET Core, Cloud and Azure series.

This article explores essential security patterns and best practices for .NET applications, with a focus on Azure integration and modern authentication protocols.

Authentication and Authorization

Proper authentication verifies user identity, while authorization ensures users can only access resources they're permitted to use.

JWT Bearer Authentication

JSON Web Tokens (JWT) provide a stateless authentication mechanism ideal for distributed systems:

// Configure JWT authentication in Program.cs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Auth:Authority"];
        options.Audience = builder.Configuration["Auth:Audience"];
        options.MetadataAddress = builder.Configuration["Auth:MetadataAddress"];

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.Zero, // No tolerance for expired tokens
            NameClaimType = "name",
            RoleClaimType = "roles"
        };

        options.Events = new JwtBearerEvents
        {
            OnAuthenticationFailed = context =>
            {
                if (context.Exception is SecurityTokenExpiredException)
                {
                    context.Response.Headers.Append("Token-Expired", "true");
                }

                context.Response.Headers.Append("Token-Error", 
                    context.Exception.Message);

                return Task.CompletedTask;
            },

            OnTokenValidated = context =>
            {
                // Additional validation logic
                var userId = context.Principal?.FindFirst("sub")?.Value;
                // Log successful authentication, check revocation list, etc.
                return Task.CompletedTask;
            },

            OnChallenge = context =>
            {
                // Custom challenge handling
                context.HandleResponse();
                context.Response.StatusCode = StatusCodes.Status401Unauthorized;
                context.Response.ContentType = "application/json";

                var result = JsonSerializer.Serialize(new
                {
                    error = "unauthorized",
                    error_description = context.ErrorDescription
                });

                return context.Response.WriteAsync(result);
            }
        };

        // For development only - disable HTTPS requirement
        if (builder.Environment.IsDevelopment())
        {
            options.RequireHttpsMetadata = false;
        }
    });

var app = builder.Build();

// Enable authentication and authorization middleware
app.UseAuthentication();
app.UseAuthorization();

Authorization Policies

Define fine-grained authorization policies for different access levels:

builder.Services.AddAuthorization(options =>
{
    // Role-based policy
    options.AddPolicy("AdminOnly", policy =>
        policy.RequireRole("Admin", "SuperAdmin"));

    // Claims-based policy
    options.AddPolicy("CanViewOrders", policy =>
        policy.RequireClaim("permissions", "orders:read"));

    options.AddPolicy("CanManageOrders", policy =>
        policy.RequireClaim("permissions", "orders:write", "orders:delete"));

    // Custom requirement policy
    options.AddPolicy("CanCreateOrders", policy =>
        policy.Requirements.Add(new MinimumAgeRequirement(18)));

    // Combined requirements
    options.AddPolicy("SeniorAdmin", policy =>
    {
        policy.RequireRole("Admin");
        policy.RequireClaim("seniority", "senior");
        policy.Requirements.Add(new MinimumAgeRequirement(25));
    });

    // Default policy for all authorized endpoints
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

Custom Authorization Handlers

Implement custom authorization logic for complex business rules:

// Custom requirement
public class MinimumAgeRequirement : IAuthorizationRequirement
{
    public int MinimumAge { get; }

    public MinimumAgeRequirement(int minimumAge)
    {
        MinimumAge = minimumAge;
    }
}

// Handler for the requirement
public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
    private readonly ILogger<MinimumAgeHandler> _logger;

    public MinimumAgeHandler(ILogger<MinimumAgeHandler> logger)
    {
        _logger = logger;
    }

    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        MinimumAgeRequirement requirement)
    {
        var dateOfBirthClaim = context.User.FindFirst(c => 
            c.Type == "date_of_birth" || c.Type == "birthdate");

        if (dateOfBirthClaim == null)
        {
            _logger.LogWarning("Date of birth claim not found for user");
            return Task.CompletedTask;
        }

        if (DateTime.TryParse(dateOfBirthClaim.Value, out var dateOfBirth))
        {
            var age = DateTime.Today.Year - dateOfBirth.Year;
            if (dateOfBirth.Date > DateTime.Today.AddYears(-age))
            {
                age--;
            }

            if (age >= requirement.MinimumAge)
            {
                _logger.LogDebug(
                    "User age {Age} meets minimum requirement {MinAge}",
                    age, requirement.MinimumAge);
                context.Succeed(requirement);
            }
            else
            {
                _logger.LogWarning(
                    "User age {Age} does not meet minimum requirement {MinAge}",
                    age, requirement.MinimumAge);
            }
        }

        return Task.CompletedTask;
    }
}

// Resource-based authorization
public class OrderAuthorizationHandler : 
    AuthorizationHandler<OperationAuthorizationRequirement, Order>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        OperationAuthorizationRequirement requirement,
        Order resource)
    {
        var userId = context.User.FindFirst("sub")?.Value;

        if (requirement.Name == "Edit" || requirement.Name == "Delete")
        {
            // Only order owner or admin can edit/delete
            if (resource.CustomerId.ToString() == userId || 
                context.User.IsInRole("Admin"))
            {
                context.Succeed(requirement);
            }
        }
        else if (requirement.Name == "View")
        {
            // Order owner, admin, or support can view
            if (resource.CustomerId.ToString() == userId || 
                context.User.IsInRole("Admin") ||
                context.User.IsInRole("Support"))
            {
                context.Succeed(requirement);
            }
        }

        return Task.CompletedTask;
    }
}

// Register handlers
builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();
builder.Services.AddSingleton<IAuthorizationHandler, OrderAuthorizationHandler>();

Using Authorization in Controllers

Apply authorization policies to protect endpoints:

[ApiController]
[Route("api/[controller]")]
[Authorize] // Requires authentication for all actions
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;
    private readonly IAuthorizationService _authorizationService;

    public OrdersController(
        IOrderService orderService,
        IAuthorizationService authorizationService)
    {
        _orderService = orderService;
        _authorizationService = authorizationService;
    }

    [HttpGet]
    [Authorize(Policy = "CanViewOrders")]
    public async Task<IActionResult> GetOrders()
    {
        var orders = await _orderService.GetOrdersAsync();
        return Ok(orders);
    }

    [HttpPost]
    [Authorize(Policy = "CanCreateOrders")]
    public async Task<IActionResult> CreateOrder(CreateOrderRequest request)
    {
        var order = await _orderService.CreateOrderAsync(request);
        return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetOrder(Guid id)
    {
        var order = await _orderService.GetOrderByIdAsync(id);

        if (order == null)
            return NotFound();

        // Resource-based authorization
        var authResult = await _authorizationService.AuthorizeAsync(
            User, 
            order, 
            "View");

        if (!authResult.Succeeded)
            return Forbid();

        return Ok(order);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateOrder(Guid id, UpdateOrderRequest request)
    {
        var order = await _orderService.GetOrderByIdAsync(id);

        if (order == null)
            return NotFound();

        var authResult = await _authorizationService.AuthorizeAsync(
            User,
            order,
            "Edit");

        if (!authResult.Succeeded)
            return Forbid();

        await _orderService.UpdateOrderAsync(id, request);
        return NoContent();
    }

    [HttpDelete("{id}")]
    [Authorize(Roles = "Admin")]
    public async Task<IActionResult> DeleteOrder(Guid id)
    {
        await _orderService.DeleteOrderAsync(id);
        return NoContent();
    }
}

Azure Entra ID (formerly Azure AD) Integration

For enterprise applications, integrate with Azure Entra ID:

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);

        options.Events = new JwtBearerEvents
        {
            OnTokenValidated = async context =>
            {
                // Validate additional claims
                var tenantId = context.Principal?.FindFirst("tid")?.Value;
                var allowedTenants = builder.Configuration
                    .GetSection("AllowedTenants")
                    .Get<List<string>>();

                if (allowedTenants != null && 
                    !allowedTenants.Contains(tenantId))
                {
                    context.Fail("Unauthorized tenant");
                }
            }
        };
    },
    options => builder.Configuration.Bind("AzureAd", options));

// appsettings.json
/*
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "yourdomain.onmicrosoft.com",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "Audience": "api://your-api-id"
  },
  "AllowedTenants": ["tenant-id-1", "tenant-id-2"]
}
*/

Service-to-Service Authentication

Secure communication between microservices using Azure Managed Identity:

// Configure HTTP client with managed identity authentication
builder.Services.AddHttpClient<IOrderServiceClient, OrderServiceClient>(client =>
{
    client.BaseAddress = new Uri(builder.Configuration["Services:OrderService:Url"]!);
    client.DefaultRequestHeaders.Add("User-Agent", "CustomerService/1.0");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddHttpMessageHandler<ManagedIdentityHandler>()
.AddPolicyHandler(GetRetryPolicy())
.AddPolicyHandler(GetCircuitBreakerPolicy());

// Managed identity authentication handler
public class ManagedIdentityHandler : DelegatingHandler
{
    private readonly TokenCredential _credential;
    private readonly string _scope;
    private readonly ILogger<ManagedIdentityHandler> _logger;
    private AccessToken? _cachedToken;

    public ManagedIdentityHandler(
        IConfiguration configuration,
        ILogger<ManagedIdentityHandler> logger)
    {
        // DefaultAzureCredential works locally (using Azure CLI, VS, etc.) 
        // and in Azure (using Managed Identity)
        _credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = false,
            ExcludeWorkloadIdentityCredential = false,
            ExcludeManagedIdentityCredential = false,
            ExcludeSharedTokenCacheCredential = true,
            ExcludeVisualStudioCredential = false,
            ExcludeVisualStudioCodeCredential = false,
            ExcludeAzureCliCredential = false,
            ExcludeAzurePowerShellCredential = true,
            ExcludeInteractiveBrowserCredential = true
        });

        _scope = configuration["Services:OrderService:Scope"]!;
        _logger = logger;
    }

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        // Check if cached token is still valid
        if (_cachedToken == null || 
            _cachedToken.Value.ExpiresOn <= DateTimeOffset.UtcNow.AddMinutes(5))
        {
            try
            {
                var tokenContext = new TokenRequestContext(new[] { _scope });
                _cachedToken = await _credential.GetTokenAsync(
                    tokenContext, 
                    cancellationToken);

                _logger.LogDebug("Successfully acquired access token");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to acquire access token");
                throw;
            }
        }

        request.Headers.Authorization = 
            new AuthenticationHeaderValue("Bearer", _cachedToken.Value.Token);

        return await base.SendAsync(request, cancellationToken);
    }
}

// Polly retry policy
static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy()
{
    return HttpPolicyExtensions
        .HandleTransientHttpError()
        .OrResult(msg => msg.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        .WaitAndRetryAsync(3, retryAttempt => 
            TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));
}

// Circuit breaker policy
static IAsyncPolicy<HttpResponseMessage> GetCircuitBreakerPolicy()
{
    return HttpPolicyExtensions
        .HandleTransientHttpError()
        .CircuitBreakerAsync(5, TimeSpan.FromSeconds(30));
}

API Rate Limiting

Protect your APIs from abuse and ensure fair resource usage with rate limiting (.NET 7+):

using System.Threading.RateLimiting;

builder.Services.AddRateLimiter(options =>
{
    // Global rejection response
    options.OnRejected = async (context, cancellationToken) =>
    {
        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;

        if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
        {
            context.HttpContext.Response.Headers.RetryAfter = 
                retryAfter.TotalSeconds.ToString();
        }

        await context.HttpContext.Response.WriteAsJsonAsync(
            new { error = "Too many requests. Please try again later." },
            cancellationToken: cancellationToken);
    };

    // Fixed window limiter
    options.AddFixedWindowLimiter("fixed", options =>
    {
        options.PermitLimit = 100;
        options.Window = TimeSpan.FromMinutes(1);
        options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        options.QueueLimit = 10;
    });

    // Sliding window limiter - more granular than fixed window
    options.AddSlidingWindowLimiter("sliding", options =>
    {
        options.PermitLimit = 100;
        options.Window = TimeSpan.FromMinutes(1);
        options.SegmentsPerWindow = 6; // Divides window into 10-second segments
    });

    // Token bucket - allows bursts while maintaining average rate
    options.AddTokenBucketLimiter("token", options =>
    {
        options.TokenLimit = 100;
        options.ReplenishmentPeriod = TimeSpan.FromMinutes(1);
        options.TokensPerPeriod = 20;
        options.AutoReplenishment = true;
    });

    // Concurrency limiter - limits concurrent requests
    options.AddConcurrencyLimiter("concurrency", options =>
    {
        options.PermitLimit = 50;
        options.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        options.QueueLimit = 100;
    });

    // Per-user rate limiting using partition
    options.AddPolicy("per-user", httpContext =>
    {
        var username = httpContext.User.Identity?.Name ?? "anonymous";

        return RateLimitPartition.GetSlidingWindowLimiter(
            partitionKey: username,
            factory: _ => new SlidingWindowRateLimiterOptions
            {
                PermitLimit = 100,
                Window = TimeSpan.FromMinutes(1),
                SegmentsPerWindow = 6
            });
    });

    // Per-IP rate limiting
    options.AddPolicy("per-ip", httpContext =>
    {
        var ipAddress = httpContext.Connection.RemoteIpAddress?.ToString() ?? "unknown";

        return RateLimitPartition.GetTokenBucketLimiter(
            partitionKey: ipAddress,
            factory: _ => new TokenBucketRateLimiterOptions
            {
                TokenLimit = 50,
                ReplenishmentPeriod = TimeSpan.FromMinutes(1),
                TokensPerPeriod = 10,
                AutoReplenishment = true
            });
    });

    // Tiered rate limiting based on user role
    options.AddPolicy("tiered", httpContext =>
    {
        var tier = httpContext.User.IsInRole("Premium") ? "premium" : "free";

        var limits = tier == "premium"
            ? new { PermitLimit = 1000, Window = TimeSpan.FromMinutes(1) }
            : new { PermitLimit = 100, Window = TimeSpan.FromMinutes(1) };

        return RateLimitPartition.GetSlidingWindowLimiter(
            partitionKey: $"{tier}:{httpContext.User.Identity?.Name}",
            factory: _ => new SlidingWindowRateLimiterOptions
            {
                PermitLimit = limits.PermitLimit,
                Window = limits.Window,
                SegmentsPerWindow = 6
            });
    });
});

var app = builder.Build();

// Enable rate limiting middleware (must be before UseAuthorization)
app.UseRateLimiter();

Applying Rate Limiting to Endpoints

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    // Apply named policy
    [EnableRateLimiting("per-user")]
    [HttpGet]
    public async Task<IActionResult> GetProducts()
    {
        // Implementation
        return Ok();
    }

    // Disable rate limiting for specific endpoint
    [DisableRateLimiting]
    [HttpGet("health")]
    public IActionResult Health()
    {
        return Ok(new { status = "healthy" });
    }

    // Apply different policy
    [EnableRateLimiting("token")]
    [HttpPost]
    public async Task<IActionResult> CreateProduct(Product product)
    {
        // Implementation
        return Created();
    }
}

// Apply rate limiting to minimal APIs
app.MapGet("/api/orders", async (IOrderService service) =>
{
    var orders = await service.GetOrdersAsync();
    return Results.Ok(orders);
})
.RequireRateLimiting("per-user");

// Apply globally to all endpoints
app.MapGroup("/api")
    .RequireRateLimiting("sliding");

Secrets Management with Azure Key Vault

Never store secrets in code or configuration files. Use Azure Key Vault:

// Install packages:
// - Azure.Identity
// - Azure.Extensions.AspNetCore.Configuration.Secrets

var keyVaultUrl = builder.Configuration["KeyVault:Url"];

if (!string.IsNullOrEmpty(keyVaultUrl))
{
    builder.Configuration.AddAzureKeyVault(
        new Uri(keyVaultUrl),
        new DefaultAzureCredential());
}

// Access secrets through IConfiguration
public class OrderService
{
    private readonly string _apiKey;
    private readonly string _connectionString;

    public OrderService(IConfiguration configuration)
    {
        // These are loaded from Key Vault
        _apiKey = configuration["PaymentGateway-ApiKey"];
        _connectionString = configuration["Database-ConnectionString"];
    }
}

// For more control, use SecretClient directly
builder.Services.AddSingleton(sp =>
{
    var keyVaultUrl = builder.Configuration["KeyVault:Url"];
    return new SecretClient(
        new Uri(keyVaultUrl),
        new DefaultAzureCredential());
});

public class PaymentService
{
    private readonly SecretClient _secretClient;

    public PaymentService(SecretClient secretClient)
    {
        _secretClient = secretClient;
    }

    public async Task<string> GetApiKeyAsync()
    {
        var secret = await _secretClient.GetSecretAsync("PaymentGateway-ApiKey");
        return secret.Value.Value;
    }
}

Data Protection and Encryption

Encrypt Sensitive Data at Rest

using Microsoft.AspNetCore.DataProtection;

// Configure data protection with Azure Key Vault
builder.Services.AddDataProtection()
    .PersistKeysToAzureBlobStorage(
        new Uri(builder.Configuration["DataProtection:BlobUri"]!),
        new DefaultAzureCredential())
    .ProtectKeysWithAzureKeyVault(
        new Uri(builder.Configuration["DataProtection:KeyVaultKeyUri"]!),
        new DefaultAzureCredential())
    .SetApplicationName("MyApp");

// Use data protection to encrypt sensitive data
public class CustomerService
{
    private readonly IDataProtector _protector;

    public CustomerService(IDataProtectionProvider provider)
    {
        _protector = provider.CreateProtector("CustomerService.v1");
    }

    public string EncryptSensitiveData(string plainText)
    {
        return _protector.Protect(plainText);
    }

    public string DecryptSensitiveData(string cipherText)
    {
        return _protector.Unprotect(cipherText);
    }
}

Always Use HTTPS

// Enforce HTTPS
builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = StatusCodes.Status308PermanentRedirect;
    options.HttpsPort = 443;
});

builder.Services.AddHsts(options =>
{
    options.MaxAge = TimeSpan.FromDays(365);
    options.IncludeSubDomains = true;
    options.Preload = true;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseHsts();
}

app.UseHttpsRedirection();

Security Headers

Add security headers to protect against common attacks:

app.Use(async (context, next) =>
{
    // Prevent clickjacking
    context.Response.Headers.Append("X-Frame-Options", "DENY");

    // Prevent MIME type sniffing
    context.Response.Headers.Append("X-Content-Type-Options", "nosniff");

    // XSS protection
    context.Response.Headers.Append("X-XSS-Protection", "1; mode=block");

    // Content Security Policy
    context.Response.Headers.Append("Content-Security-Policy",
        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';");

    // Referrer policy
    context.Response.Headers.Append("Referrer-Policy", "strict-origin-when-cross-origin");

    // Permissions policy
    context.Response.Headers.Append("Permissions-Policy",
        "geolocation=(), microphone=(), camera=()");

    await next();
});

// Or use a middleware package
// Install: NWebsec.AspNetCore.Middleware
app.UseXContentTypeOptions();
app.UseReferrerPolicy(opts => opts.StrictOriginWhenCrossOrigin());
app.UseXXssProtection(opts => opts.EnabledWithBlockMode());
app.UseXfo(opts => opts.Deny());

Input Validation and Sanitization

Always validate and sanitize user input:

public class CreateOrderRequest
{
    [Required]
    [StringLength(100, MinimumLength = 1)]
    public string CustomerName { get; set; } = string.Empty;

    [Required]
    [EmailAddress]
    public string Email { get; set; } = string.Empty;

    [Required]
    [Range(1, int.MaxValue)]
    public decimal Amount { get; set; }

    [Required]
    [MinLength(1)]
    [MaxLength(100)]
    public List<OrderItem> Items { get; set; } = new();
}

// Custom validation
public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderRequestValidator()
    {
        RuleFor(x => x.CustomerName)
            .NotEmpty()
            .MaximumLength(100)
            .Matches(@"^[a-zA-Z\s]+$").WithMessage("Name can only contain letters");

        RuleFor(x => x.Email)
            .NotEmpty()
            .EmailAddress();

        RuleFor(x => x.Amount)
            .GreaterThan(0)
            .LessThan(1000000);

        RuleFor(x => x.Items)
            .NotEmpty()
            .Must(items => items.Count <= 100)
            .WithMessage("Cannot exceed 100 items per order");
    }
}

Best Practices Summary

Authentication & Authorization:

Use Azure Entra ID for enterprise applications
Implement JWT with short expiration times
Apply principle of least privilege
Use resource-based authorization for fine-grained control
Regularly rotate secrets and credentials

Service-to-Service:

Use Managed Identity for Azure resources
Implement certificate-based authentication for non-Azure services
Never embed credentials in code
Use Azure Key Vault for all secrets

API Protection:

Implement rate limiting on all public APIs
Use different rate limits for different user tiers
Monitor and alert on rate limit violations
Consider using Azure API Management for advanced scenarios

Data Security:

Encrypt sensitive data at rest and in transit
Use Azure Key Vault for key management
Implement data protection with key rotation
Follow GDPR and compliance requirements

General Security:

Always use HTTPS in production
Implement proper security headers
Validate and sanitize all user input
Log security events for monitoring
Conduct regular security audits
Keep dependencies updated
Use Azure Security Center for threat detection
Implement proper error handling without exposing sensitive information

Azure-Specific:

Enable Azure DDoS Protection
Use Azure Front Door WAF for web application protection
Implement Azure Monitor and Log Analytics for security monitoring
Use Azure Private Link for secure service connections
Enable diagnostic logging on all Azure resources
Use Azure Policy to enforce security standards

Strategies for resilient HTTP calls in .NET core

Hossein Esmati — Fri, 26 Jun 2026 12:14:28 +0000

What “resilience” means

Your app depends on other services (payments, search, auth). Networks hiccup, services spike, and anything can slow or fail. Resilience means your outbound HTTP calls degrade gracefully instead of cascading failures through your system.

Resilient HTTP calls
Designing HttpClient calls to cope with transient failures (network flakiness, 5xx, 429), limit blast radius, and recover gracefully instead of crashing or hanging.

Why this order?

Timeout (inner) caps each attempt.
Retry wraps timeouts/transient failures to try again.
Circuit Breaker observes failures and opens if things look bad.
Bulkhead (outer) preserves capacity across features.

Failure types to design for

Transient: brief spikes, 5xx/429, timeouts → retry with jittered backoff.
Persistent: sustained failure/outage → circuit-break, fall back, or fail fast.
Slowdown: high latency, thread/connection starvation → timeouts, bulkheads, concurrency limits.

Core building blocks (with .NET lenses)

Timeouts

Cap each attempt (e.g., 1–3s) and cap the overall call budget (e.g., ≤ client SLA).

Never wait forever. Set a per-try timeout that’s smaller than your overall budget. Prefer Polly’s Timeout (per attempt) over only HttpClient.Timeout.

Retries with jittered backoff

2–3 tries on transient errors only; add randomness to avoid herds.

Retries
Automatically try again on transient errors (e.g., HttpRequestException, 5xx, 408, 429). Only retry idempotent operations (GET, or POST with idempotency keys). Cap attempts.

Jittered backoff
Wait longer between retries (exponential backoff) plus randomness (“jitter”) to avoid a thundering herd. Example: base * 2^n + random(0..x) milliseconds.

Circuit breakers

Open after a failure rate/volume threshold; try again after cool-down (half-open).

Circuit breakers: Track recent failures. After a threshold, the breaker opens and short-circuits calls for a cool-down period (protects the downstream and your thread pool). States: Closed → Open → Half-Open.

Bulkheads

Limit concurrent calls to a dependency (and optionally queue a few) to contain blast radius. If one service is slow, it can’t starve your whole app—other features keep working.

Cancellation tokens: propagate from incoming request → HttpClient.SendAsync(ct). Cooperative cancellation for callers: pass a CancellationToken to SendAsync so work stops quickly when the user navigates away, the request times out, or the server shuts down.
Observability: log correlation IDs; metrics for success/failure/timeout/retry/break counts; traces.
Observability around failure rates Measure and see what’s happening: logs (with correlation IDs), metrics (success/timeout/retry/break counts, P95 latency), and traces (distributed tracing). Alert when error or open-breaker rates exceed thresholds.

In .NET, use HttpClientFactory + Polly (or .NET 8’s AddStandardResilienceHandler) to compose these policies per dependency.

Polly
A .NET resilience library that provides policies such as Retry, Timeout, Circuit Breaker, and Bulkhead. You compose these to protect your outbound calls.

Designing the “latency & retry budget”

Think top-down from the user SLO:

If the page SLO is 2.0s, budget maybe 1.2s for remote calls.
Choose per-try timeout (T) and retries (N) so: overall ≈ N * T + backoff ≤ 1.2s. Example: T=300ms, N=3, backoff ≈ 100–200ms → ~1.1–1.2s.
Never let outer gateways (e.g., APIM) and clients both retry aggressively → tune one layer to own retries.

Idempotency & correctness

Retry only idempotent ops (GET, HEAD).
For POST/PUT, use idempotency keys so duplicates don’t double-charge/create.
Treat 429/503 as retryable; 400/401/403 as non-retryable.

Capacity & connection hygiene

Use HttpClientFactory (avoids socket exhaustion, good DNS refresh).
Tune SocketsHttpHandler:
- PooledConnectionLifetime to rotate connections (DNS changes).
- MaxConnectionsPerServer to prevent oversubscription.
- ConnectTimeout (don’t wait forever to connect).

Degrade gracefully (fallbacks)

Stale cache or reduced quality response when upstream is down.
Async handoff for non-urgent work (queue to Azure Service Bus/Storage Queues, process later).
Feature flags to turn off non-critical integrations under stress.

Observability you absolutely need

Metrics per dependency: success rate, error rate, open-breaker count, bulkhead rejections, P95/P99 latency.
Structured logs with correlation/trace IDs.
Traces (OpenTelemetry + App Insights): one span per remote call with outcome & attempt count.
Alert when:
- Error rate or P95 latency crosses thresholds.
- Traffic to deprecated/unstable endpoints rises.
- Circuit is open for > X minutes.

Testing resilience (shift-left)

Unit: verify policies wired correctly (right status codes retry).
Integration: inject faults (timeouts/5xx/429) and measure behavior.
Staging/chaos: latency injection, dependency kill switches; confirm breakers open and recover.

Architecture do’s & don’ts

Apply policies per dependency (payments vs. search need different budgets).
Keep retry counts small (2–3) and add jitter.
Document policies next to the client (readme + code comments).

Don’t

Nest multiple retry layers unknowingly (SDK + gateway + client).
Use infinite or giant timeouts.
Retry non-idempotent operations without safeguards.

Quick .NET/Azure cookbook

.NET 8: AddStandardResilienceHandler() or Polly policies via AddPolicyHandler.
Azure Functions/App Service: propagate CancellationToken, set app-level request timeout consistent with your budgets.
Azure API Management: use light retry at the edge or in the app—avoid both. Add request/response size and duration limits.
App Insights + OpenTelemetry: export metrics/traces; create dashboards/alerts by dependency and version.

Minimal .NET example (Polly + HttpClientFactory)

// Program.cs
using Polly;
using Polly.Bulkhead;
using Polly.CircuitBreaker;
using Polly.Retry;
using Polly.Timeout;

var services = new ServiceCollection();

var retry = Policy<HttpResponseMessage>
    .Handle<HttpRequestException>()
    .OrResult(r => (int)r.StatusCode is 408 or 429 or >= 500)
    .WaitAndRetryAsync(
        retryCount: 3,
        sleepDurationProvider: attempt =>
            TimeSpan.FromMilliseconds(200 * Math.Pow(2, attempt)) +
            TimeSpan.FromMilliseconds(Random.Shared.Next(0, 200)), // jitter
        onRetry: (outcome, delay, attempt, ctx) =>
            Console.WriteLine($"Retry {attempt} after {delay}"));

var timeout = Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(2));

var breaker = Policy<HttpResponseMessage>
    .Handle<HttpRequestException>()
    .OrResult(r => (int)r.StatusCode >= 500)
    .CircuitBreakerAsync(
        handledEventsAllowedBeforeBreaking: 10,
        durationOfBreak: TimeSpan.FromSeconds(30),
        onBreak: (outcome, span) => Console.WriteLine($"Breaker OPEN for {span}"),
        onReset: () => Console.WriteLine("Breaker RESET"),
        onHalfOpen: () => Console.WriteLine("Breaker HALF-OPEN"));

var bulkhead = Policy.BulkheadAsync<HttpResponseMessage>(
    maxParallelization: 50,
    maxQueuingActions: 100,
    onBulkheadRejectedAsync: _ => {
        Console.WriteLine("Bulkhead rejected");
        return Task.CompletedTask;
    });

// Recommended order (outer → inner): Bulkhead → CircuitBreaker → Retry → Timeout
var pipeline = Policy.WrapAsync(bulkhead, breaker, retry, timeout);

services.AddHttpClient("resilient")
    .AddPolicyHandler(pipeline);

var provider = services.BuildServiceProvider();
var client = provider.GetRequiredService<IHttpClientFactory>().CreateClient("resilient");

// Usage with cancellation
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var resp = await client.GetAsync("https://api.example.com/data", cts.Token);

DEV Community: Hossein Esmati

SDLC in the AI Era with Spec-Driven Development

The specification becomes the delivery control plane

Rebuild the lifecycle around executable intent

Turn specifications into code, tests and quality gates

Govern AI-generated change without slowing delivery

Takeaway: build the right thing, then keep proving it

Practical compare-and-choose guide for Vertical Slice (feature folders) vs DDD in .NET (ASP.NET Core / Minimal APIs / Controllers)

When to pick which

Typical folder layouts

Vertical Slice (feature folders)

DDD (Clean-ish)

Minimal API + MediatR (Vertical Slice style)

Same endpoint with a DDD core (hybrid)

Testing strategy

Cross-cutting details that often decide it

Practical recommendation for your stack (Blazor + Aspire)

Cheatsheet

Approach to Versioning REST APIs in .NET Core

Approach to Versioning REST APIs

Core principles

Versioning styles (and when I use them)

Rule of thumb:

Backward-compatibility policy

Deprecation policy (what clients experience)

Contracts & communication

Rollout workflow

Example in ASP.NET Core (.NET)

Testing & monitoring

Quick dos & don’ts

Ensuring Thread Safety — .NET core-centric

Prefer immutability

Avoid shared state

Use lock / SemaphoreSlim cautiously

Leverage actor-style or message queues

Timeouts, cancellation, and async correctness

Observability for thread-safety issues

Quick decision guide

Synchronous vs asynchronous in .NET core - how decide

Rule of thumb

The core idea

When to choose async

When sync is acceptable

Pitfalls to avoid

Mini decision checklist

ASP.NET Core examples

Tuning & tips

Shared Libraries Management in .NET and Azure

Core Principle: Avoid Domain Coupling

Recommended Shared Library Structure

What Belongs in Shared Libraries

1. Cross-Cutting Utilities (Company.Common)

2. Observability Infrastructure (Company.Observability)

3. Messaging Abstractions (Company.Messaging)

4. Integration Contracts (Company.Contracts)

5. .NET Aspire Service Defaults (Company.ServiceDefaults)

What Does NOT Belong in Shared Libraries

❌ Shared Domain Models

✅ Correct Approach: Private Domain Models

Package Management with NuGet

Semantic Versioning Strategy

Versioning Strategies

Strategy 1: Independent Versioning (Recommended)

Strategy 2: Central Package Management (CPM)

Strategy 3: Synchronized Suite Versioning

Hotfix and Patching Strategy

Scenario: Critical Bug in Company.Common

GitVersion Configuration

CI/CD Pipeline with Azure DevOps

Build and Pack Pipeline

Multi-Stage Pipeline with Approval Gates

Integration with .NET Aspire

Aspire AppHost Configuration

Service Implementation

Package Consumption Best Practices

Version Pinning Strategy

Dependency Resolution

Monitoring and Observability

Package Health Dashboard

Azure Monitor Integration

Use `lock` / `SemaphoreSlim` cautiously