In this guide, we’ll build a scalable configuration approach that validates settings early, supports controlled changes, and allows applications to react to updated configuration without introducing unpredictable production behavior.

Configuration Looks Easy Until the Application Grows

Consider a small ASP.NET Core application.

Its configuration might contain:

{
  "Catalog": {
    "PageSize": 25
  }
}

Reading the value is straightforward.

var pageSize =
    builder.Configuration.GetValue<int>("Catalog:PageSize");

For a small application, this works perfectly well.

Now imagine the same system two years later.

It contains:

• Multiple ASP.NET Core services

• Development, staging, and production environments

• Several geographic regions

• Feature settings

• Retry policies

• API endpoints

• Cache expiration rules

• Queue settings

• Connection information

• Operational limits

Suddenly, configuration is no longer just a file.

It is a distributed operational dependency.

Why Configuration Deserves Architectural Attention

A configuration change can alter application behavior without changing application code.

That is powerful.

It is also dangerous.

Imagine someone changes:

{
  "Payments": {
    "TimeoutSeconds": 30
  }
}

to:

{
  "Payments": {
    "TimeoutSeconds": 3000
  }
}

The application still compiles.

The deployment may succeed.

But requests could now remain active far longer than intended.

Configuration errors are particularly difficult because they often look like application failures.

The code has not changed, yet production behavior has.

That is why mature systems treat configuration with many of the same disciplines applied to code.

Understanding ASP.NET Core Configuration Providers

ASP.NET Core builds configuration from one or more configuration providers.

Common sources include:

• JSON files

• Environment variables

• Command-line arguments

• User secrets during development

• In-memory configuration

• External configuration systems

These sources are combined into a single configuration model.

A simplified setup might look like:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration
    .AddJsonFile(
        "appsettings.json",
        optional: false,
        reloadOnChange: true)
    .AddJsonFile(
        $"appsettings.{builder.Environment.EnvironmentName}.json",
        optional: true,
        reloadOnChange: true)
    .AddEnvironmentVariables();

The order matters because later providers can override values supplied by earlier providers.

That gives us a useful layering model.

Base Configuration
        ↓
Environment Configuration
        ↓
Environment Variables
        ↓
Final Effective Configuration

The application consumes the final result.

Configuration Precedence Matters

Suppose appsettings.json contains:

{
  "Catalog": {
    "PageSize": 20
  }
}

Production configuration contains:

{
  "Catalog": {
    "PageSize": 50
  }
}

And an environment variable supplies:

Catalog__PageSize=100

The effective value may become:

100

That flexibility is useful for deployments, but it can also create confusion.

When debugging configuration problems, the important question is often not:

What does appsettings.json say?

It is:

Which provider supplied the value the application is actually using?

Stop Passing IConfiguration Everywhere

A common early-stage pattern looks like this:

public class CatalogService
{
    private readonly IConfiguration _configuration;

    public CatalogService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public int GetPageSize()
    {
        return _configuration
            .GetValue<int>("Catalog:PageSize");
    }
}

This works.

But it has several weaknesses.

The service depends on string-based configuration paths.

Typos become runtime problems.

The expected configuration structure is hidden inside application logic.

Validation is difficult.

Testing requires constructing configuration.

For larger applications, the Options pattern is usually a better approach.

Strongly Typed Configuration

Let’s define configuration as a class.

public sealed class CatalogOptions
{
    public const string SectionName = "Catalog";

    public int PageSize { get; init; }

    public int CacheMinutes { get; init; }
}

Our configuration becomes:

{
  "Catalog": {
    "PageSize": 50,
    "CacheMinutes": 10
  }
}

Then register it:

builder.Services.Configure<CatalogOptions>(
    builder.Configuration.GetSection(
        CatalogOptions.SectionName));

Now application code works with normal C# properties rather than configuration strings.

public class CatalogService
{
    private readonly CatalogOptions _options;

    public CatalogService(
        IOptions<CatalogOptions> options)
    {
        _options = options.Value;
    }
}

This gives configuration a clear contract.

Why Strong Typing Matters at Scale

Compare these:

configuration["Payments:Retry:MaximumAttempts"]

and:

options.MaximumAttempts

The second approach is easier to understand, test, refactor, and validate.

More importantly, it tells developers exactly which settings a component expects.

Configuration stops being an invisible collection of strings and becomes part of the application’s type system.

Configuration Must Be Validated

Strong typing does not automatically make configuration correct.

This is perfectly valid C#:

{
  "Catalog": {
    "PageSize": -500,
    "CacheMinutes": 0
  }
}

The values bind successfully.

But they make no business sense.

ASP.NET Core’s options infrastructure allows us to validate configuration.

For example:

builder.Services
    .AddOptions<CatalogOptions>()
    .Bind(
        builder.Configuration.GetSection(
            CatalogOptions.SectionName))
    .Validate(
        options => options.PageSize > 0,
        "PageSize must be greater than zero.")
    .Validate(
        options => options.CacheMinutes > 0,
        "CacheMinutes must be greater than zero.");

Now invalid values can be detected deliberately rather than producing strange behavior later.

Fail Fast with ValidateOnStart

There is another important question.

When should invalid configuration be discovered?

Suppose a payment configuration is invalid.

One option is to discover the problem when the first customer attempts a payment.

That is far too late.

For critical configuration, we usually want the application to fail during startup.

builder.Services
    .AddOptions<PaymentOptions>()
    .Bind(
        builder.Configuration.GetSection("Payments"))
    .Validate(
        options => options.TimeoutSeconds > 0,
        "Payment timeout must be positive.")
    .ValidateOnStart();

Now configuration is checked when the application starts.

This is an important production principle:

A service that cannot operate correctly should fail before it starts accepting traffic.

Data Annotation Validation

For straightforward rules, data annotations can make option classes easy to understand.

public sealed class PaymentOptions
{
    [Range(1, 120)]
    public int TimeoutSeconds { get; init; }

    [Range(0, 10)]
    public int MaximumRetries { get; init; }
}

Then:

builder.Services
    .AddOptions<PaymentOptions>()
    .BindConfiguration("Payments")
    .ValidateDataAnnotations()
    .ValidateOnStart();

The rules now live directly beside the properties they protect.

Cross-Property Validation

Real configuration often has relationships between values.

Imagine:

public sealed class UploadOptions
{
    public long WarningSizeBytes { get; init; }

    public long MaximumSizeBytes { get; init; }
}

Both numbers could individually be positive while still being logically incorrect.

For example:

WarningSize = 100 MB
MaximumSize = 50 MB

We need a rule such as:

.Validate(
    options =>
        options.WarningSizeBytes <
        options.MaximumSizeBytes,
    "WarningSizeBytes must be lower than MaximumSizeBytes.")

This is why configuration validation should express operational rules, not merely type correctness.

IOptions, IOptionsSnapshot, and IOptionsMonitor

ASP.NET Core provides several ways to consume options, and understanding the differences becomes important when configuration can change.

The three common interfaces are:

IOptions<T>
IOptionsSnapshot<T>
IOptionsMonitor<T>

They sound similar, but they serve different purposes.

IOptions<T>

IOptions<T> provides an options value that is effectively consumed as a stable value by the application.

It works well when configuration is not expected to change during the process lifetime.

public CatalogService(
    IOptions<CatalogOptions> options)
{
    _options = options.Value;
}

For many settings, this is exactly what we want.

Database architecture, protocol choices, and other structural settings should not necessarily change while the application is running.

IOptionsSnapshot<T>

IOptionsSnapshot<T> is scoped and recalculates options once per request scope.

This can be useful in request-based applications where updated configuration should become visible to subsequent requests.

public CatalogController(
    IOptionsSnapshot<CatalogOptions> options)
{
    _options = options.Value;
}

A request sees a consistent snapshot.

A later request can receive updated settings.

IOptionsMonitor<T>

IOptionsMonitor<T> is designed for scenarios where an application needs access to the current option value and may need to react when that value changes.

public class PricingService
{
    private readonly IOptionsMonitor<PricingOptions> _options;

    public PricingService(
        IOptionsMonitor<PricingOptions> options)
    {
        _options = options;
    }

    public decimal Calculate(decimal price)
    {
        var settings = _options.CurrentValue;

        return price * settings.Multiplier;
    }
}

If the underlying configuration provider supports reloads, CurrentValue can reflect updated configuration.

Reacting to Configuration Changes

IOptionsMonitor<T> also exposes change notifications.

public class PricingConfigurationObserver
{
    private readonly IDisposable? _subscription;

    public PricingConfigurationObserver(
        IOptionsMonitor<PricingOptions> options,
        ILogger<PricingConfigurationObserver> logger)
    {
        _subscription = options.OnChange(updated =>
        {
            logger.LogInformation(
                "Pricing configuration changed. Multiplier: {Multiplier}",
                updated.Multiplier);
        });
    }
}

This looks extremely powerful.

Change a configuration value and the application reacts immediately.

But this is also where configuration becomes dangerous.

Dynamic Configuration Is Not Automatically Better

Imagine changing:

MaximumConcurrentJobs = 100

to:

MaximumConcurrentJobs = 10

while 75 jobs are already running.

What should happen?

Should 65 jobs be cancelled?

Should the new limit apply only to future work?

Should the application wait until concurrency naturally falls below 10?

The configuration system cannot answer those questions.

They are application semantics.

This leads to one of the most important rules in dynamic configuration:

Being able to reload a setting does not mean the setting is safe to reload.

Classify Configuration by Behavior

A useful production approach is to classify settings into three groups.

Static Settings

These require application restart.

Examples:

• Fundamental infrastructure choices

• Certain hosting settings

• Major dependency topology

• Settings used only during service registration

Reloadable Settings

These can change safely while the application is running.

Examples might include:

• Some timeout values

• UI behavior

• Operational thresholds

• Non-critical feature behavior

Controlled Dynamic Settings

These can change at runtime, but only through explicit application logic.

Examples include:

• Concurrency limits

• Pricing rules

• Traffic percentages

• Resource thresholds

This classification prevents teams from treating every configuration value as equally dynamic.

Safe Reloading Requires Boundaries

Suppose we have:

public sealed class WorkerOptions
{
    public int BatchSize { get; init; }
}

A background worker could read:

var batchSize =
    _optionsMonitor.CurrentValue.BatchSize;

before beginning each batch.

That gives us a natural boundary.

Batch 1 uses 100
        ↓
Configuration changes to 50
        ↓
Batch 2 uses 50

The current batch remains consistent.

The new value applies to future work.

That is far safer than changing behavior halfway through an operation.

Configuration Should Be Immutable During an Operation

Consider a request that performs several calculations.

If configuration can change halfway through the request, we could theoretically get:

Step 1 → Tax rate 10%
Step 2 → configuration reload
Step 3 → Tax rate 12%

One operation has now used two different business rules.

For important calculations, capture the required configuration once at the start of the operation.

Then use that snapshot consistently.

Dynamic configuration should change between operations, not unpredictably inside them.

What Happens When Reloaded Configuration Is Invalid?

This is where production systems need careful design.

Suppose:

{
  "Worker": {
    "BatchSize": 100
  }
}

changes to:

{
  "Worker": {
    "BatchSize": -10
  }
}

The new value is invalid.

A mature system should not blindly adopt it.

Validation needs to remain part of the options pipeline, and operationally you should also make configuration failures visible through logging and monitoring.

The goal is simple:

New Configuration
       ↓
Validation
   /       \
Valid     Invalid
 ↓           ↓
Use it    Surface failure

Never make “the file changed” equivalent to “the change is safe.”

External Configuration Systems

Once an organization runs many application instances, local JSON files become difficult to manage dynamically.

Imagine 50 instances of the same service.

Changing a JSON file manually on each server is obviously not a scalable strategy.

This is where centralized configuration providers can help.

Depending on the environment, organizations may use systems such as:

• Azure App Configuration

• Cloud configuration services

• Kubernetes configuration mechanisms

• Dedicated internal configuration platforms

The architectural pattern becomes:

Central Configuration
        ↓
    Application A
    Application B
    Application C
    Application D

Teams can manage settings centrally rather than maintaining independent copies everywhere.

Configuration Is Not the Same as Secrets

This distinction matters.

Configuration might contain:

PageSize = 50
RetryCount = 3
FeatureMode = Standard

Secrets include things such as:

Database password
API credential
Private key
Signing secret

Both may enter an application through configuration providers, but they should not necessarily be managed in the same place or with the same access policies.

Secrets deserve stronger controls, auditing, rotation, and restricted visibility.

Do not turn appsettings.json into a password vault.

Environment Variables

Environment variables remain extremely useful for containerized and cloud deployments.

Nested configuration keys use double underscores.

For example:

Payments__TimeoutSeconds=20

maps to:

Payments:TimeoutSeconds

This allows deployment platforms to override application defaults without modifying files inside the application package.

Environment-Specific Files

ASP.NET Core commonly uses files such as:

appsettings.json
appsettings.Development.json
appsettings.Production.json

This is useful for environment-specific defaults.

But avoid allowing these files to drift into completely different application configurations.

If production contains 40 settings that development does not even know exist, configuration becomes difficult to test.

The environments should differ in values, not unexpectedly in the fundamental shape of configuration.

Validate Production-Like Configuration Before Production

Configuration validation during application startup is valuable.

But discovering an invalid setting during the production deployment is still later than ideal.

A stronger delivery pipeline validates production configuration earlier.

Conceptually:

Configuration Change
       ↓
Schema / Options Validation
       ↓
Automated Tests
       ↓
Staging
       ↓
Production

Treat configuration changes as deployable changes.

They deserve review and testing.

Configuration Versioning

Imagine an incident begins at 14:32.

The code has been running successfully for three days.

What changed?

A mature configuration system should make it possible to answer:

What changed?
Who changed it?
When?
From what value?
To what value?
Which services received it?

This is why version history becomes important at scale.

Configuration without history makes incident investigation much harder.

Rollback Matters

If configuration can be changed quickly, it should also be possible to reverse the change quickly.

Suppose a new timeout causes failures.

A rollback path should look like:

Version 41
   ↓
Version 42
   ↓
Problems detected
   ↓
Rollback
   ↓
Version 41

The ability to restore a known-good configuration is often more valuable during an incident than the ability to edit individual values manually.

Avoid Giant Global Configuration Objects

Another common mistake is creating:

public class ApplicationSettings
{
    // 150 unrelated properties
}

Then every service depends on it.

This creates unnecessary coupling.

Instead, define configuration around capabilities.

PaymentOptions
CatalogOptions
CacheOptions
ShippingOptions
NotificationOptions

Each component receives only the configuration it needs.

This mirrors the same modularity principles we apply to application architecture.

Names Matter

Avoid settings such as:

Timeout = 30
Limit = 100
Enabled = true

Thirty what?

Seconds?

Milliseconds?

What limit?

What exactly is enabled?

Prefer explicit names:

RequestTimeoutSeconds
MaximumConcurrentRequests
EnableAutomaticRetry

Configuration is an interface between developers and operators.

Clarity matters.

Do Not Use Configuration as a Database

Once dynamic configuration becomes convenient, teams sometimes begin putting everything into it.

That is a mistake.

Configuration is excellent for controlling application behavior.

It is not a replacement for transactional business data.

A customer’s current account balance does not belong in configuration.

Neither does an order’s status.

Ask:

Is this describing how the application should behave, or is this information the application owns?

If it is business data, store it as business data.

Feature Flags Are a Separate Concern

Feature flags and configuration overlap, but they solve different problems.

Configuration usually describes operational behavior.

Feature flags control whether particular functionality is available, often for specific users, tenants, or rollout groups.

For example:

RequestTimeoutSeconds = 20

is configuration.

EnableNewCheckoutForBetaCustomers = true

is closer to feature management.

Keeping that distinction clear prevents configuration systems from becoming overloaded with rollout logic.

Observing Configuration Changes

Configuration changes should produce operational signals.

At minimum, important changes should be logged.

For example:

logger.LogInformation(
    "Catalog configuration updated. PageSize={PageSize}",
    options.PageSize);

Be careful not to log secrets.

For important systems, useful telemetry can include:

• Configuration reload count

• Validation failures

• Last successful refresh

• Configuration version

• Refresh latency

Configuration is an operational dependency, so it deserves observability.

Health Checks and Configuration

Some configuration failures can also affect service health.

Suppose an application depends on centrally refreshed configuration and has not successfully refreshed for several hours.

Whether that should make the service unhealthy depends on the system.

Do not automatically mark a service unhealthy simply because a configuration provider is temporarily unavailable if the application can safely continue using its last known configuration.

This is an important resilience principle:

A temporary inability to refresh configuration should not necessarily destroy an otherwise healthy application.

Last Known Good Configuration

That leads to another useful pattern.

Imagine the configuration service becomes unavailable.

The application already has a valid configuration.

Should it stop working?

Often, no.

A resilient architecture can continue using the last known good configuration while reporting that refresh attempts are failing.

Configuration Provider
        X
        │
Application
        │
        └── Continue with last known good settings

This prevents a configuration outage from automatically becoming an application outage.

Of course, some security-sensitive settings may require stricter behavior.

Again, the correct policy depends on what the setting controls.

Configuration Across Multiple Instances

Suppose we run ten instances of an Orders API.

A configuration value changes.

The instances may not all observe the update at exactly the same instant.

For a brief period:

Instance 1 → Version 18
Instance 2 → Version 18
Instance 3 → Version 17
Instance 4 → Version 18

Can the system tolerate that?

For many operational settings, yes.

For some business rules, absolutely not.

If every instance must change atomically, ordinary dynamic configuration may be the wrong mechanism.

This is another reason to distinguish operational settings from transactional business state.

Configuration and .NET Aspire

In our previous article, we explored how .NET Aspire helps describe and connect distributed applications.

Configuration fits naturally into that story.

Aspire can help applications receive connection information and resource references without requiring developers to manually coordinate endpoints across multiple projects.

The larger architectural principle remains the same:

Applications should depend on named capabilities and structured configuration rather than scattered hardcoded infrastructure details.

As distributed systems grow, this becomes increasingly important.

A Practical Production Pattern

Imagine an ASP.NET Core order-processing service.

It needs:

OrderProcessingOptions
PaymentOptions
ShippingOptions
QueueOptions

Each option type is:

1. Strongly typed.

2. Bound to its own configuration section.

3. Validated.

4. Validated during startup when appropriate.

5. Classified as static or reloadable.

6. Monitored when dynamic changes are required.

Critical settings fail startup if invalid.

Reloadable settings change only at safe operational boundaries.

Configuration changes are logged.

The configuration platform maintains version history.

Rollbacks are possible.

Secrets are managed separately.

This is no longer “reading settings.”

It is configuration engineering.

A Real-World Scenario

Imagine a large ticket-booking platform.

During normal traffic:

MaximumSearchResults = 100
SearchTimeoutSeconds = 5
MaximumConcurrentSearches = 500
CacheMinutes = 10

A major concert goes on sale.

Traffic suddenly increases dramatically.

Operations decides to reduce:

MaximumSearchResults

from:

100

to:

50

The goal is to reduce backend work per search.

A properly designed configuration system allows the change to be introduced without rebuilding the application.

New requests use the updated limit.

Existing requests continue using the configuration they started with.

Telemetry confirms the new configuration version has reached application instances.

Latency begins falling.

If the change causes unexpected behavior, operations rolls back to the previous version.

That is the value of dynamic configuration when it is designed correctly.

The Configuration Maturity Ladder

We can think of configuration maturity in stages.

Level 1
Hardcoded values

        ↓

Level 2
appsettings.json

        ↓

Level 3
Environment-specific configuration

        ↓

Level 4
Strongly typed options

        ↓

Level 5
Validation

        ↓

Level 6
Centralized configuration

        ↓

Level 7
Safe dynamic reload

        ↓

Level 8
Versioning, auditing, rollback, and observability

Not every application needs Level 8.

But as systems become more distributed and operationally important, configuration deserves increasingly deliberate engineering.

Common Mistakes to Avoid

The most common problems usually come from treating configuration as an afterthought.

Avoid:

• Hardcoded infrastructure addresses

• Configuration strings scattered throughout application code

• Missing validation

• Secrets committed to configuration files

• Reloading every setting dynamically

• Changing values halfway through operations

• Giant global settings classes

• Unclear units and names

• No version history

• No rollback mechanism

• Logging secret values

• Assuming every instance reloads simultaneously

Most of these mistakes are easy to avoid when configuration is treated as an explicit architectural concern.

How This Fits Our ASP.NET Core Journey

The previous article introduced .NET Aspire and showed how distributed applications can be modeled as connected resources.

That naturally leads to configuration.

Once applications span multiple services, environments, and infrastructure dependencies, every component needs reliable information about how it should behave.

The challenge is no longer simply loading that information.

The challenge becomes controlling its lifecycle.

We need to know whether configuration is valid, when it can change, how changes reach running services, what happens when the provider fails, and how we recover when a bad value reaches production.

Those questions become increasingly important as ASP.NET Core systems grow.

And they lead directly into our next architectural problem.

What happens when a perfectly configured application receives more work than it can possibly process?

That is where backpressure and overload protection enter the picture.

Coming Next

In the next article, we’ll explore Designing Backpressure in ASP.NET Core: Handling Overload Without Crashing Your System.

We’ll look at what happens when producers generate work faster than consumers can process it, why unlimited queues can quietly destroy application stability, and how bounded channels, concurrency limits, load shedding, cancellation, and graceful degradation help ASP.NET Core applications remain responsive under extreme load.

Closing Thoughts

Configuration begins as a convenience and eventually becomes part of the operational architecture of an application.

ASP.NET Core gives us a strong foundation through configuration providers, the Options pattern, validation, startup validation, snapshots, and monitoring. But the framework cannot decide which settings are safe to change while an application is running.

That responsibility belongs to us.

The most reliable systems distinguish static configuration from genuinely dynamic settings. They validate important values before accepting traffic, apply runtime changes at safe boundaries, preserve known-good settings when appropriate, record configuration history, and provide a fast rollback path when something goes wrong.

At scale, configuration should not be a collection of mysterious values scattered across files and environment variables.

It should be a controlled, validated, observable input into application behavior.

When we treat it that way, configuration stops being one of the easiest ways to accidentally break production and becomes one of the safest ways to operate a system without constantly redeploying it.

Subscribe Now

Enjoying the series? Subscribe to ASP Today for practical ASP.NET Core tutorials, advanced architecture deep dives, and production-focused .NET engineering guides. Join our Substack Chat to discuss configuration strategies, distributed systems, and the challenges of running modern ASP.NET Core applications at scale.

Subscribe now

In this guide, we'll build a practical mental model of .NET Aspire and explore how orchestration, service discovery, health checks, and OpenTelemetry can make distributed ASP.NET Core development much easier.

The Problem with Distributed Applications

A traditional ASP.NET Core application might be relatively simple.

Browser
   ↓
ASP.NET Core
   ↓
Database

As the application grows, that picture changes.

We might introduce:

Web Frontend
     ↓
API Gateway
     ↓
 ┌───┼─────────┐
 ↓   ↓         ↓
Orders Products Payments
 ↓       ↓        ↓
SQL    Redis    Message Queue

Soon, running the application locally means starting several projects and infrastructure dependencies.

Developers need to know which ports services use.

Configuration files contain connection strings.

One service must start before another.

Databases and containers need to be running.

Telemetry is spread across multiple consoles.

The architecture may be well designed, but the development experience becomes increasingly difficult.

This is one of the problems Aspire is designed to solve.

What Is .NET Aspire?

Aspire provides tooling for building and operating distributed applications, with a strong emphasis on orchestration and observability.

Rather than treating each application, database, cache, and supporting service as an unrelated component, Aspire lets us describe the entire system as a collection of connected resources.

Microsoft currently describes Aspire as a code-first orchestration and observability layer for distributed applications.

That distinction matters.

Aspire is not another web framework replacing ASP.NET Core.

Your APIs remain ASP.NET Core applications.

Your background workers remain .NET workers.

Redis remains Redis.

PostgreSQL remains PostgreSQL.

Aspire provides a model that connects these components and makes the distributed application easier to develop and understand.

Think of Aspire as the Application Coordinator

Imagine an orchestra.

The musicians already know how to play their instruments.

The conductor does not replace them.

Instead, the conductor coordinates when everyone starts, how the pieces fit together, and how the entire performance behaves.

Aspire plays a similar role.

Your services already know how to perform their individual jobs.

Aspire helps coordinate the system around them.

The AppHost

The center of an Aspire application is the AppHost.

The AppHost describes your distributed application.

Instead of maintaining a collection of disconnected scripts and manually configured ports, you describe your resources and relationships in code.

A simplified AppHost might look like this:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.CatalogApi>("catalog");

builder.AddProject<Projects.WebApp>("web")
       .WithReference(api);

builder.Build().Run();

We now have two resources:

Catalog API
     ↑
     │
   Web App

The important part is the relationship.

The web application references the API.

Aspire can use that relationship to provide connection information and service discovery rather than requiring the application to depend on a manually configured port.

Microsoft’s current Aspire guidance describes the AppHost as a code-first model for defining application architecture and relationships.

Resources Are More Than ASP.NET Core Projects

An Aspire resource does not have to be an ASP.NET Core project.

A distributed application might contain:

• ASP.NET Core APIs

• Worker services

• Databases

• Redis

• Message brokers

• Containers

• Executables

• Frontend applications

The AppHost becomes a map of the entire application.

For example:

             Web
              │
              ▼
          Catalog API
           /       \
          ▼         ▼
     PostgreSQL    Redis

Instead of expecting every developer to reconstruct this architecture mentally, we can express it directly.

Adding Infrastructure

Suppose our Catalog API requires Redis.

Conceptually, our AppHost might define the cache and reference it from the API:

var builder = DistributedApplication.CreateBuilder(args);

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

var api = builder
    .AddProject<Projects.CatalogApi>("catalog")
    .WithReference(cache);

builder.Build().Run();

WithReference() tells Aspire that the API depends on the cache.

Aspire integrations can then provide the consuming application with the connection information it needs.

This is far cleaner than telling every developer:

“Start Redis manually, make sure it uses this port, then copy this connection string into your local configuration.”

Why Code-First Orchestration Matters

Infrastructure relationships often exist only in documentation.

That documentation becomes outdated.

Someone changes a port.

A new database is introduced.

A service gets renamed.

Another developer joins the team and spends half a day figuring out how everything fits together.

With Aspire, the application topology lives alongside the application.

That makes relationships:

• Visible

• Version controlled

• Repeatable

• Easier to modify

The architecture becomes something developers can run rather than something they merely read about.

Orchestration Does Not Mean Business Orchestration

There is an important distinction here.

Aspire application orchestration is not the same thing as orchestrating business workflows.

For example, Aspire does not replace the Saga pattern we explored earlier.

A Saga might coordinate:

Create Order
    ↓
Reserve Stock
    ↓
Process Payment
    ↓
Arrange Shipping

Aspire coordinates the resources required to run the application.

Start Database
      ↓
Start API
      ↓
Start Frontend

These solve completely different problems.

Controlling Startup Dependencies

Distributed applications often suffer from startup races.

Imagine the frontend starts immediately and calls the API.

The API is still starting.

The first request fails.

Or perhaps the API starts before its database is ready.

Aspire allows resource relationships to express readiness dependencies.

For example:

var api = builder
    .AddProject<Projects.CatalogApi>("catalog");

builder
    .AddProject<Projects.WebApp>("web")
    .WithReference(api)
    .WaitFor(api);

WaitFor() can prevent the dependent resource from starting until the referenced resource is ready according to its lifecycle or health state. Microsoft’s current Aspire getting-started guidance demonstrates this alongside health checks to prevent startup race conditions.

This sounds like a small improvement.

Across a system with many dependencies, it becomes extremely valuable.

Service Discovery

Now we reach one of the biggest headaches in distributed development.

How does one service find another?

Suppose our Catalog API runs locally at:

https://localhost:7143

A developer might configure:

{
  "CatalogApi": "https://localhost:7143"
}

But another developer might receive:

https://localhost:7288

Production uses a completely different hostname.

Containers introduce another network environment.

Hardcoded addresses become fragile quickly.

Logical Service Names

Service discovery solves this problem.

Instead of thinking:

Call https://localhost:7143

the application thinks:

Call catalog

Aspire knows where catalog actually lives.

A client can therefore use a logical service address rather than a hardcoded endpoint.

For example:

builder.Services.AddHttpClient<CatalogClient>(client =>
{
    client.BaseAddress =
        new Uri("https+http://catalog");
});

Aspire’s service discovery resolves the logical service name to the appropriate endpoint at runtime. Microsoft’s documentation specifically describes this model as using logical names instead of hardcoded URLs.

Why This Changes Local Development

Imagine five developers working on the same system.

Without service discovery, everyone needs matching port configuration.

With service discovery:

Web
 ↓
"catalog"
 ↓
Service Discovery
 ↓
Actual Catalog Endpoint

The consuming code no longer cares whether Catalog runs:

localhost:5237

or somewhere else entirely.

The same basic service relationship can work across different environments because endpoint resolution is separated from application logic.

Adding a Database

Let’s make the example more realistic.

Suppose the Catalog API needs PostgreSQL.

The AppHost can model that dependency too.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");

var catalogDb =
    postgres.AddDatabase("catalogdb");

var catalog = builder
    .AddProject<Projects.CatalogApi>("catalog")
    .WithReference(catalogDb);

builder.AddProject<Projects.WebApp>("web")
       .WithReference(catalog)
       .WaitFor(catalog);

builder.Build().Run();

Our topology is now:

Web
 ↓
Catalog API
 ↓
PostgreSQL
 ↓
Catalog Database

The code itself explains the relationship.

Adding Redis

Now suppose product information is frequently requested.

We introduce Redis.

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

var catalog = builder
    .AddProject<Projects.CatalogApi>("catalog")
    .WithReference(catalogDb)
    .WithReference(cache);

The architecture becomes:

             Web
              │
              ▼
          Catalog API
           /       \
          ▼         ▼
   PostgreSQL      Redis

Notice what is happening.

We aren’t adding Redis-specific orchestration logic to our web application.

We’re describing the dependency at the application-model level.

Aspire Integrations

Aspire provides integrations for many common infrastructure components and services.

These integrations help model resources and provide appropriate configuration to applications consuming them.

The important idea is not memorizing a list of integrations.

It is understanding the pattern:

Define Resource
      ↓
Reference Resource
      ↓
Aspire Supplies Configuration
      ↓
Application Uses Resource

This creates a much more consistent way to wire distributed applications together.

Service Defaults

Distributed applications tend to repeat the same infrastructure configuration.

Every service needs:

• Health checks

• Telemetry

• Service discovery

• Resilience configuration

Copying the same setup into every project creates maintenance problems.

Aspire addresses this through Service Defaults.

A Service Defaults project centralizes common configuration that can be reused across projects in the solution.

Microsoft’s Aspire templates describe Service Defaults as reusable configuration for areas including resilience, service discovery, and telemetry.

Why Service Defaults Matter

Imagine ten ASP.NET Core services.

Without shared defaults:

Orders     → configure telemetry
Payments   → configure telemetry
Catalog    → configure telemetry
Shipping   → configure telemetry
Identity   → configure telemetry

Someone eventually configures one differently.

With shared defaults:

          Service Defaults
        /    /    |    \    \
       ↓    ↓     ↓     ↓    ↓
Orders Payments Catalog Shipping Identity

The teams begin with a consistent baseline.

Individual applications can still add their own configuration where necessary.

Observability from the Beginning

Distributed applications are difficult to debug because a single user action may cross several services.

Imagine a checkout request:

Browser
   ↓
Web
   ↓
Orders API
   ↓
Inventory API
   ↓
Payment API
   ↓
Database

The user sees:

Checkout failed.

Where did it fail?

Without distributed observability, developers may need to inspect several log files and manually correlate timestamps.

Aspire encourages observability as part of the development experience rather than something added just before production.

The Aspire Dashboard

One of Aspire’s most useful features is its dashboard.

When you run an AppHost, the dashboard provides a centralized view of the resources in your distributed application.

Instead of switching between terminal windows, developers get a place to inspect the system.

The dashboard works with OpenTelemetry data and can surface logs, traces, metrics, resource information, and endpoints. Microsoft’s documentation notes that the dashboard launches automatically in common AppHost development workflows.

This dramatically improves the local debugging experience.

Structured Logs

Suppose the Orders API produces:

logger.LogInformation(
    "Processing order {OrderId}",
    order.Id);

Structured logging keeps OrderId as meaningful data rather than burying it inside a text string.

Across distributed services, this becomes particularly useful because developers can search and correlate events much more effectively.

Distributed Traces

We explored OpenTelemetry and distributed tracing earlier in this series.

Aspire makes those concepts immediately useful during development.

Suppose a request travels:

Web
 │
 └── Orders API          35 ms
       │
       ├── Inventory     18 ms
       │
       └── Payments     840 ms

The problem becomes obvious.

Payments is taking most of the time.

Instead of guessing which service caused the delay, the trace shows the request’s journey.

Metrics

Logs tell us what happened.

Traces show how a request moved.

Metrics tell us how the system behaves over time.

Useful metrics might include:

Requests per second
Request duration
Failed requests
CPU usage
Memory usage
Dependency latency

Aspire’s Service Defaults can configure OpenTelemetry collection for logging, tracing, and metrics, while OTLP allows telemetry to be exported to compatible monitoring systems.

Health Checks

Observability tells us what is happening.

Health checks answer another important question:

Can this service actually do its job?

An application process may technically be running while its database is unavailable.

That service isn’t truly healthy.

ASP.NET Core health checks can represent conditions such as:

API running            ✓
Database reachable     ✓
Redis reachable        ✓
Message broker         ✗

Aspire can incorporate health information into resource orchestration and visibility.

A More Complete Example

Let’s imagine we’re building an online store.

Our system contains:

Web Frontend
Catalog API
Orders API
PostgreSQL
Redis

The AppHost could conceptually describe the system like this:

var builder =
    DistributedApplication.CreateBuilder(args);

var postgres =
    builder.AddPostgres("postgres");

var ordersDb =
    postgres.AddDatabase("ordersdb");

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

var catalog =
    builder.AddProject<Projects.CatalogApi>("catalog")
           .WithReference(cache);

var orders =
    builder.AddProject<Projects.OrdersApi>("orders")
           .WithReference(ordersDb)
           .WithReference(catalog)
           .WaitFor(ordersDb);

builder.AddProject<Projects.WebApp>("web")
       .WithReference(catalog)
       .WithReference(orders)
       .WaitFor(catalog)
       .WaitFor(orders);

builder.Build().Run();

Now look at what the application model communicates.

                 Web
                /   \
               ▼     ▼
          Catalog   Orders
             │       /  \
             ▼      ▼    ▼
           Redis   DB   Catalog

Someone joining the project can understand much of the topology simply by reading the AppHost.

Adding a New Developer

This is where Aspire can make a noticeable difference.

Imagine joining a project containing eight services.

Traditionally, onboarding instructions might say:

1. Install PostgreSQL.

2. Install Redis.

3. Configure these connection strings.

4. Start Orders first.

5. Start Catalog.

6. Make sure Catalog uses port 7182.

7. Start the frontend.

8. Open three terminals for logs.

9. Configure your tracing environment.

That is a lot of tribal knowledge.

A well-designed Aspire application can encode much more of that setup in the application model.

The developer starts the AppHost.

The system topology comes to life.

Aspire and Containers

Containers remain useful.

Aspire does not make Docker irrelevant.

Instead, it can model containerized dependencies alongside your application projects.

For local development, that means infrastructure such as Redis or PostgreSQL can participate in the same application model rather than being treated as completely separate setup tasks.

This complements the Docker and Kubernetes concepts we’ve already explored in this series.

Aspire and Kubernetes

Another important distinction:

Aspire is not Kubernetes.

Kubernetes is an orchestration platform for deploying and operating containerized workloads.

Aspire’s AppHost provides a code-first application model that can be used during development and can participate in deployment workflows.

You should not think:

Aspire OR Kubernetes

Think:

Application Model
        ↓
Deployment Environment

The deployment environment might eventually involve containers, Kubernetes, Azure services, or another supported target.

Aspire’s current documentation explicitly separates application modeling from deployment topology and supports multiple deployment directions rather than tying the model to a single hosting destination.

Aspire Is Not Only for New Applications

You do not need to rebuild an existing ASP.NET Core system from scratch.

Aspire can be introduced incrementally.

For example, you might start by adding an AppHost that models:

Existing API
Existing Worker
Redis
PostgreSQL

Then introduce common telemetry.

Later, add service discovery.

Then model more infrastructure.

Microsoft’s current guidance specifically supports adding Aspire to existing applications and gradually modeling containers, databases, caches, queues, workers, and other resources.

That makes adoption much less risky.

Where Aspire Helps Most

Aspire becomes particularly valuable when an application contains enough moving parts that local development starts becoming painful.

Imagine:

Frontend
API Gateway
Identity Service
Catalog Service
Orders Service
Payment Service
Worker
Redis
PostgreSQL
RabbitMQ

Running all of that manually is frustrating.

Understanding it is harder.

Debugging it is harder still.

The value of a unified application model grows with the number of dependencies.

Where Aspire May Be Unnecessary

Not every ASP.NET Core application needs distributed orchestration.

Suppose you have:

Razor Pages App
      ↓
SQL Database

The system is simple.

Adding additional tooling may provide little value.

This is an important architectural lesson we’ve repeated throughout this series:

Use complexity to solve complexity. Do not introduce complexity merely because a technology is interesting.

Common Mistake: Treating Aspire as Magic

Aspire does not make distributed systems simple.

Network failures still happen.

Databases still become unavailable.

Services still experience latency.

Distributed transactions are still difficult.

Security still matters.

What Aspire improves is our ability to model, connect, run, and observe those systems.

Good architecture remains essential.

Common Mistake: Hiding Architecture

Because Aspire makes adding resources convenient, developers may be tempted to keep adding services.

That would be the wrong lesson.

If one ASP.NET Core application solves the problem well, splitting it into six services does not automatically improve the architecture.

The AppHost should describe a sensible architecture.

It should not justify an unnecessarily complicated one.

Common Mistake: Ignoring Production Differences

A beautiful local environment does not guarantee a healthy production environment.

Production introduces:

• Real network latency

• Authentication

• Secrets

• Scaling

• Regional failures

• Cost

• Resource limits

Use Aspire to improve development and application modeling, but continue designing explicitly for the environment where the system will actually operate.

A Real-World Scenario

Imagine a logistics company building a parcel-processing platform.

Its system contains:

Operations Portal
       ↓
Shipment API
       ↓
 ┌─────┼──────────┐
 ▼     ▼          ▼
Pricing Tracking Notifications
 │       │
 ▼       ▼
Redis PostgreSQL

Background Workers
       ↓
Message Broker

Without a unified development model, every engineer must understand how to launch and configure all of these pieces.

With Aspire, the AppHost describes them as resources and relationships.

Developers start the distributed application.

Service discovery connects the services.

Health checks reveal whether dependencies are ready.

OpenTelemetry records activity.

The dashboard exposes the system’s behavior.

When a shipment request becomes slow, developers inspect its trace.

They discover that Pricing is waiting on a downstream dependency.

Instead of searching through five terminal windows, they can follow the request through the distributed system.

That is where Aspire becomes much more than a convenient project launcher.

It becomes a development environment for understanding the architecture itself.

How This Fits Our ASP.NET Core Journey

Over the course of this series, we’ve explored many pieces of distributed application architecture individually.

We’ve covered:

• Microservices

• Docker

• Kubernetes

• Event-driven architecture

• gRPC

• Health checks

• Resilience

• Distributed caching

• Distributed tracing

• API Gateways

• Service meshes

• Internal Developer Platforms

Aspire does not replace those concepts.

It provides a way to bring many of them into a more coherent developer experience.

Instead of thinking about an application as ten unrelated projects and five infrastructure components, we can model it as one distributed system.

That is an important shift.

What Aspire Gives Us

The easiest way to remember Aspire is through four questions.

What runs?

The AppHost describes the resources.

What depends on what?

References describe relationships.

How do services find each other?

Service discovery resolves logical names to endpoints.

How do we understand what is happening?

OpenTelemetry and the Aspire dashboard provide observability.

Together, those capabilities attack some of the most frustrating parts of distributed application development.

Closing Thoughts

Distributed architecture gives development teams powerful ways to scale applications, isolate responsibilities, and choose the right technology for each workload. But every new service also creates another endpoint, dependency, configuration problem, health state, and source of telemetry.

Aspire tackles that operational complexity from the developer’s perspective.

With a code-first AppHost, we can describe our distributed application as a system rather than a collection of unrelated processes. Service discovery removes the need to hardcode changing endpoints. Shared defaults give services a consistent foundation for resilience, health checks, and telemetry. OpenTelemetry and the Aspire dashboard then help us see how those services behave together.

The result is not a simpler architecture by magic.

It is an architecture that is easier to run, easier to understand, easier to observe, and easier for the next developer to work with.

And as our ASP.NET Core systems become increasingly distributed, that developer experience matters just as much as the individual services themselves.

Subscribe Now

Enjoying the series? Subscribe to ASP Today for practical ASP.NET Core tutorials, advanced architecture guides, and real-world .NET engineering strategies. Join our Substack Chat to discuss distributed applications, share development experiences, and connect with developers building modern ASP.NET Core systems.

Subscribe now

In this guide, we’ll explore what edge computing means for ASP.NET Core developers, where it makes sense, how edge and cloud systems work together, and how to design practical applications that remain fast, secure, and resilient.

What Does “The Edge” Actually Mean?

We’ve spent years moving applications into the cloud.

Now we’re talking about moving some of them back?

Not exactly.

Edge computing does not mean abandoning the cloud. It means deciding where each piece of work should happen.

Imagine a factory in Germany sending sensor readings to a cloud data center hundreds of kilometers away. If every machine decision requires a round trip to that cloud, network latency and connectivity become part of the production process.

Instead, the factory can run some application services locally.

Those services process important information immediately and send selected data to the cloud afterward.

That local computing environment is the edge.

The edge could be a small server in a factory, a computer inside a retail store, an industrial gateway, a regional data center, or another computing system located near the source of the data.

The exact hardware matters less than the architectural idea.

Move time-sensitive processing closer to where the data is created or consumed.

Cloud Computing vs Edge Computing

Traditional cloud architecture often looks like this:

Device
   │
   │ Internet
   ▼
Cloud Application
   │
   ▼
Cloud Database

Every important operation depends on reaching the cloud.

An edge architecture introduces another layer:

Device
   │
   ▼
Edge Application
   │
   ├── Local Processing
   ├── Local Storage
   └── Immediate Decisions
   │
   │ Internet
   ▼
Cloud Platform

The edge handles work that benefits from being local.

The cloud continues handling workloads that benefit from centralized infrastructure.

This distinction is important because edge computing and cloud computing are not competitors. In most real applications, they complement each other.

Why Put ASP.NET Core at the Edge?

ASP.NET Core is well suited to many edge scenarios because .NET runs across Windows and Linux, can be deployed in containers, provides high-performance web APIs, and includes mature support for dependency injection, configuration, background services, security, and observability.

An ASP.NET Core application running at an edge location might expose APIs to local devices, process incoming information, store temporary data, make immediate decisions, and periodically communicate with cloud services.

Developers can use many of the same programming patterns they already know.

The biggest difference is the environment.

At the edge, you cannot assume the network is always available.

The Latency Problem

Latency is the delay between sending a request and receiving a response.

For many business applications, a little network latency is perfectly acceptable.

If someone requests a monthly sales report, an extra fraction of a second probably does not matter.

But consider a manufacturing system detecting a dangerous machine condition.

Waiting for:

Machine
   ↓
Internet
   ↓
Cloud
   ↓
Analysis
   ↓
Internet
   ↓
Machine

may be unnecessary when the decision could happen locally.

With edge processing:

Machine
   ↓
Local ASP.NET Core Service
   ↓
Immediate Response

The cloud can receive the event afterward for analytics, reporting, and long-term storage.

Edge Computing Is About More Than Speed

Latency receives most of the attention, but it is only one reason to use edge computing.

Connectivity is another.

Imagine a delivery warehouse where handheld scanners depend entirely on a cloud API.

If the internet connection fails, workers may no longer be able to:

• Scan packages

• Locate inventory

• Confirm collections

• Record deliveries

An edge service inside the warehouse can keep those operations running locally.

When connectivity returns, the edge system synchronizes its data with the cloud.

That is a major architectural advantage.

Designing for Intermittent Connectivity

Cloud applications are often designed around an assumption:

The network is available.

Edge applications should make the opposite assumption:

The network will eventually fail.

That changes how we design software.

Instead of immediately sending every operation to the cloud, an edge application may record work locally.

For example:

public async Task RecordScanAsync(PackageScan scan)
{
    await _localRepository.SaveAsync(scan);

    await _syncQueue.EnqueueAsync(scan.Id);
}

The scan succeeds locally.

A background process can attempt cloud synchronization separately.

This prevents temporary connectivity problems from stopping the user’s work.

Background Synchronization

ASP.NET Core’s hosted services are useful for synchronization workloads.

A simplified worker might look like this:

public class CloudSyncWorker : BackgroundService
{
    private readonly ISyncService _syncService;

    public CloudSyncWorker(ISyncService syncService)
    {
        _syncService = syncService;
    }

    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await _syncService.PushPendingChangesAsync(
                stoppingToken);

            await Task.Delay(
                TimeSpan.FromSeconds(30),
                stoppingToken);
        }
    }
}

Production synchronization is more complicated, but the pattern is straightforward.

Perform the user’s work locally first.

Synchronize with the central platform when possible.

Local Storage at the Edge

Once an application can operate offline, it usually needs local storage.

Depending on the workload, that might include a relational database, embedded database, local files, cache, or message queue.

The edge service might store:

• Pending transactions

• Device readings

• Configuration

• Product information

• Inventory data

• Synchronization state

The important question is not simply what database to choose.

You must decide which data belongs at the edge and which data remains authoritative in the cloud.

That distinction prevents synchronization from becoming chaotic.

Data Synchronization Gets Complicated

Suppose a retail store loses its internet connection.

While offline, the store sells the final item in stock.

At the same time, the online store sells what it believes is the same final item.

When the connection returns, two valid systems disagree.

Which one wins?

This is a synchronization conflict.

Edge systems need explicit rules for situations like this.

Possible strategies include timestamps, version numbers, optimistic concurrency, business-specific conflict resolution, or manual review.

There is no universal answer.

The correct strategy depends on what the data represents.

Idempotency Matters Again

Our earlier discussion of idempotency becomes particularly useful at the edge.

Suppose an edge application sends an order to the cloud.

The cloud processes it successfully, but the network disconnects before the edge receives the response.

Did the operation succeed?

The edge cannot know.

If it blindly retries, the customer could receive two orders.

An idempotency key allows the cloud service to recognize the repeated operation.

For example:

POST /orders
Idempotency-Key: 91d57e2f-2e8a-4b11

If the same request arrives again, the server can return the previous result rather than creating another order.

Reliable synchronization depends heavily on patterns like this.

Practical Use Case: Manufacturing

Factories are a natural environment for edge computing.

Modern equipment can generate enormous streams of sensor data.

Sending every temperature reading, vibration measurement, and machine event to the cloud may be unnecessary.

An edge ASP.NET Core application can collect the readings locally.

It can detect abnormal conditions immediately.

For example:

if (reading.Temperature > safetyLimit)
{
    await _machineController.StopAsync();
}

The edge application reacts immediately.

Meanwhile, summarized measurements and important events can still be sent to the cloud for long-term analytics.

Practical Use Case: Retail Stores

Imagine a supermarket with:

• Checkout systems

• Barcode scanners

• Electronic price displays

• Inventory terminals

If every interaction depends on the internet, a network outage could disrupt the entire store.

A local ASP.NET Core service can maintain essential product and pricing information.

Checkout operations continue.

Transactions are queued.

When connectivity returns, the store synchronizes with central systems.

The cloud still provides centralized management, but the store is no longer completely dependent on it.

Practical Use Case: Logistics

Delivery and logistics systems are another excellent example.

Warehouses may process thousands of package scans every hour.

A local edge application can validate scans, update warehouse state, coordinate sorting equipment, and maintain operations even during temporary cloud outages.

The central platform receives synchronized events as connectivity permits.

The warehouse gets responsiveness.

Head office gets centralized visibility.

Both benefit.

Practical Use Case: Remote Locations

Not every application runs in a city with excellent connectivity.

Consider:

• Ships

• Mines

• Farms

• Construction sites

• Remote energy facilities

Network connections may be slow, expensive, intermittent, or unavailable.

Edge computing allows important operations to continue locally.

The cloud becomes a synchronization and management layer rather than a constant dependency.

Edge AI

Our previous article explored integrating AI and machine learning with ASP.NET Core.

Edge computing adds another interesting possibility.

Some AI inference can happen locally.

Imagine a manufacturing camera inspecting products on a conveyor belt.

Sending every image to the cloud introduces bandwidth usage and delay.

Instead, a local model can inspect the image.

Only unusual results might be uploaded.

The workflow becomes:

Camera
   ↓
Edge AI Model
   ↓
ASP.NET Core Service
   ↓
Immediate Decision
   ↓
Selected Results
   ↓
Cloud

This combination of AI and edge computing can be particularly useful when low latency, privacy, or bandwidth efficiency matters.

Containers at the Edge

Containers make edge deployment much easier.

An ASP.NET Core service can be packaged into a container and deployed consistently across many locations.

The same application image might run in:

• 50 stores

• 200 warehouses

• 1,000 industrial sites

Containers provide consistency, but deployment at this scale creates another challenge.

How do you update all those locations safely?

Managing Edge Deployments

Centralized management is essential.

You need to know:

• Which application version each location runs

• Whether deployments succeeded

• Which devices are online

• Whether an edge node is healthy

• When updates failed

Updates should also tolerate interruptions.

If connectivity disappears halfway through an upgrade, the site should not become unusable.

Versioned deployments and rollback strategies become especially important.

Security at the Edge

Edge computing changes your security boundary.

A cloud server usually lives inside a carefully controlled data center.

An edge server might live:

• Behind a checkout counter

• Inside a warehouse

• On a factory floor

• In a remote cabinet

Someone may be able to physically access it.

That means security must account for both network and physical threats.

Sensitive information stored locally should be protected appropriately, credentials should not be hardcoded into deployments, and each edge node should have a strong identity.

Zero Trust at the Edge

Our earlier Zero Trust discussion applies particularly well here.

The cloud should not automatically trust an edge device simply because it belongs to the company.

Each device or service should authenticate itself.

Likewise, edge services should verify cloud endpoints.

This can involve certificates, managed identities where supported, short-lived credentials, or other workload identity mechanisms.

The principle remains simple:

Verify the identity of every participant rather than trusting its network location.

Protecting Local Data

Edge systems sometimes contain sensitive information.

That data may include:

• Customer details

• Transactions

• Operational information

• Authentication credentials

Encryption at rest becomes important, especially when hardware could be lost or stolen.

Data retention should also be considered carefully.

If an edge node only needs seven days of local information, keeping six months may create unnecessary risk.

Store only what the edge actually needs.

Observability at the Edge

Monitoring a cloud application is relatively straightforward because the infrastructure is continuously connected.

Edge environments are different.

A node might disappear for hours.

Does that mean the application failed?

Or did the internet connection fail?

Your observability strategy needs to distinguish between the two.

Useful signals include:

• Application health

• CPU and memory usage

• Synchronization backlog

• Last successful cloud connection

• Local storage capacity

• Application version

When connectivity returns, telemetry may also need to be uploaded in batches.

Distributed Tracing

Distributed tracing becomes interesting when a request begins at the edge and continues in the cloud.

A correlation or trace identifier can follow the operation across both environments.

For example:

Warehouse Scanner
      ↓
Edge API
      ↓
Local Queue
      ↓
Cloud Sync
      ↓
Order API
      ↓
Inventory Service

A distributed trace helps developers understand the complete journey.

OpenTelemetry remains valuable here, although telemetry collection needs to account for intermittent connections and buffering.

API Gateways and Edge Computing

Our recent API Gateway article focused on providing a central entrance to backend services.

Edge architectures may introduce gateways at multiple levels.

A local gateway might route requests between devices and edge services.

A cloud gateway handles requests entering the central platform.

The architecture could resemble:

Local Devices
      ↓
Edge Gateway
      ↓
ASP.NET Core Edge Services
      ↓
Cloud API Gateway
      ↓
Cloud Microservices

The same architectural concepts appear at different physical locations.

Service Meshes at the Edge

Our previous article explored service meshes.

In larger edge installations with multiple local services, mesh-style capabilities may also be useful for secure service-to-service communication, traffic management, and observability.

However, complexity matters.

A small store running two services probably does not need the same infrastructure as a Kubernetes cluster running hundreds of microservices.

Edge architecture rewards simplicity.

Every extra component must operate when connectivity is poor and remote troubleshooting is difficult.

What Should Stay in the Cloud?

Edge computing does not mean moving everything locally.

Centralized workloads often belong in the cloud.

Examples include:

• Organization-wide analytics

• Long-term storage

• Central reporting

• Model training

• Cross-location coordination

• Large-scale batch processing

The edge should handle workloads that genuinely benefit from proximity.

A useful question is:

What breaks if the connection to the cloud disappears for an hour?

The answer often reveals which capabilities belong locally.

Avoiding the “Mini Cloud Everywhere” Trap

A common mistake is recreating the entire cloud platform at every edge location.

That can become extremely expensive and difficult to operate.

Imagine maintaining dozens of databases, message brokers, monitoring systems, gateways, and orchestration platforms across hundreds of locations.

The operational burden grows quickly.

Instead, keep edge environments focused.

Run only the services necessary for local operation.

Centralize everything else where practical.

A Complete Edge Architecture

Imagine a chain of smart manufacturing facilities.

Each factory runs an ASP.NET Core edge service.

Locally it:

• Receives machine telemetry.

• Stores recent readings.

• Detects safety conditions.

• Controls local workflows.

• Queues cloud synchronization.

The cloud platform:

• Stores long-term data.

• Compares performance across factories.

• Trains predictive models.

• Distributes configuration.

• Provides central dashboards.

The two layers work together.

If the cloud disappears temporarily, the factory keeps operating.

When connectivity returns, synchronization resumes.

That is the real strength of edge architecture.

When You Probably Don’t Need Edge Computing

Not every application needs an edge layer.

A traditional business website serving users over the internet may work perfectly well from cloud infrastructure.

Adding edge services introduces:

• Deployment complexity

• Synchronization challenges

• Additional security concerns

• Remote monitoring requirements

• More infrastructure to maintain

Use edge computing when there is a clear reason.

Low latency, intermittent connectivity, local autonomy, privacy, or bandwidth constraints are good reasons.

“Edge is popular” is not.

How This Fits Your ASP.NET Core Journey

Our recent articles have gradually expanded the boundaries of an ASP.NET Core application.

We started with services and distributed architecture.

Then we explored API Gateways for managing incoming traffic.

Service meshes helped manage communication inside the platform.

AI and machine learning introduced intelligent processing.

Now edge computing asks a different architectural question:

Where should that processing actually happen?

Sometimes the answer is the cloud.

Sometimes it is a server sitting meters away from the user or machine.

Increasingly, the answer is both.

Closing Thoughts

Edge computing is less about a particular technology and more about making intelligent decisions about where software should run.

ASP.NET Core gives .NET developers a strong foundation for building edge services because the same APIs, dependency injection patterns, background workers, security practices, and observability tools used in cloud applications can also be applied closer to users and devices.

The architectural challenge is learning to design for a world where connectivity is not guaranteed. Applications need local autonomy, reliable synchronization, secure device identities, careful data management, and strong observability.

When those pieces come together, edge computing allows cloud and local infrastructure to complement each other rather than compete.

The cloud provides scale and centralized intelligence.

The edge provides proximity and independence.

Together, they can create ASP.NET Core applications that keep working exactly where they’re needed most.

Subscribe Now

Enjoying the series? Subscribe to ASP Today for practical ASP.NET Core tutorials, cloud-native architecture guides, and real-world development strategies. Join our Substack Chat to discuss modern .NET development, share ideas, and connect with developers building the next generation of applications.

Subscribe now

Fortunately, ASP.NET Core provides an excellent foundation for integrating modern AI services and machine learning models into existing applications. Whether you're calling cloud-hosted large language models, running local ML.NET predictions, or combining multiple AI services into a single workflow, today's tools make it easier than ever to build intelligent applications.

In this guide, we'll explore practical ways to add AI to ASP.NET Core applications, understand where machine learning fits into modern software architecture, and learn how to build AI features that solve real business problems.

Why AI Matters Today

Almost every modern application now contains some form of intelligence.

Examples include:

• Product recommendations

• Smart search

• Image recognition

• Voice assistants

• Email categorization

• Fraud detection

• Predictive maintenance

• Customer support chatbots

Users increasingly expect applications to understand context instead of simply responding to button clicks.

The good news is that developers no longer need a PhD in machine learning to build these capabilities.

Many AI services are available through straightforward APIs that integrate naturally with ASP.NET Core.

Artificial Intelligence vs Machine Learning

These terms are often used interchangeably, but they describe different concepts.

Artificial Intelligence is the broader goal of building systems that perform tasks requiring human-like intelligence.

Machine Learning is one approach to achieving that goal.

Instead of programming every rule manually, machine learning models learn patterns from data.

Think of it this way.

Traditional software follows instructions.

Machine learning discovers instructions from examples.

A Simple Example

Suppose you’re building an email application.

Traditional code might look like this:

If subject contains "Invoice"
Move to Finance folder.

Machine learning instead examines thousands of previous emails and learns which messages belong together, even when the word “invoice” never appears.

Where ASP.NET Core Fits

ASP.NET Core rarely performs heavy AI training itself.

Instead, it acts as the application layer.

It:

• Receives requests

• Sends prompts or data to AI services

• Validates responses

• Stores results

• Serves users

This separation keeps applications maintainable while allowing AI models to evolve independently.

Common AI Integration Patterns

Most ASP.NET Core applications use one of three approaches.

Cloud AI APIs

The application calls hosted AI services.

Examples include:

• Azure AI Foundry

• Azure AI Vision

• Azure AI Document Intelligence

• Azure AI Speech

• OpenAI API
  

This is often the quickest way to introduce AI features.

ML.NET Models

Sometimes organizations prefer running prediction models locally.

ML.NET enables developers to train and execute machine learning models directly within .NET applications.

Official documentation:

This approach works well when:

• Internet connectivity is limited.

• Sensitive information cannot leave the organization.

• Predictions must happen with very low latency.
  

Hybrid Solutions

Many enterprise applications combine both approaches.

For example:

• ML.NET performs fraud scoring.

• Azure AI extracts document text.

• OpenAI summarizes the results.

Each tool performs the task it handles best.

Using AI Through Dependency Injection

AI clients fit naturally into ASP.NET Core.

Example:

builder.Services.AddSingleton<IAIService, AIService>();

Controllers remain focused on business logic while dedicated services manage AI interactions.

Calling an AI Service

Example:

public class ProductController : ControllerBase
{
    private readonly IAIService _ai;

    public ProductController(IAIService ai)
    {
        _ai = ai;
    }

    [HttpPost("summarize")]
    public async Task<string> Summarize(string text)
    {
        return await _ai.SummarizeAsync(text);
    }
}

Notice how the controller doesn’t know which AI provider is being used.

This abstraction makes future changes much easier.

Practical Use Case: Intelligent Customer Support

Suppose customers submit support requests.

Instead of manually categorizing tickets, AI can automatically determine:

• Billing issue

• Technical problem

• Shipping question

• Feature request

Support teams spend less time sorting requests and more time solving problems.

Practical Use Case: Smart Search

Traditional keyword searches often disappoint users.

AI-powered semantic search understands intent.

Searching for:

“Laptop won’t charge”

can return documents discussing:

• Power adapter failures

• Battery problems

• Charging ports

even when those exact words never appear.

Practical Use Case: Document Processing

Many businesses process:

• Contracts

• Invoices

• Insurance claims

• Medical forms

Azure AI Document Intelligence can extract structured information automatically.

ASP.NET Core then validates, stores, and presents the results.

Manual data entry is dramatically reduced.

Official documentation:

Practical Use Case: Chatbots

Modern chatbots go far beyond scripted conversations.

Using large language models, chatbots can:

• Answer product questions

• Explain documentation

• Guide customers through troubleshooting

• Escalate complex issues

ASP.NET Core becomes the orchestration layer connecting users with AI services.

Recommendation Engines

Streaming platforms and online stores rely heavily on recommendations.

Machine learning analyzes:

• Purchase history

• Viewing habits

• User preferences
  

Applications can then recommend relevant products automatically.

Fraud Detection

Financial systems constantly evaluate transactions.

Machine learning models examine:

• Transaction amounts

• Purchase frequency

• Device information

• Geographic location

Suspicious activity receives higher fraud scores.

Human investigators review only the highest-risk transactions.

Image Recognition

Applications can analyze uploaded images.

Examples include:

• Detecting damaged vehicles

• Classifying products

• Identifying plant diseases

• Reading handwritten forms

ASP.NET Core uploads the image while specialized AI services perform analysis.

Voice Applications

Speech services allow applications to:

• Convert speech into text.

• Convert text into speech.

• Translate conversations.
  

Customer service systems increasingly combine speech recognition with language models.

Responsible AI

Adding AI introduces new responsibilities.

Developers should consider:

• Privacy

• Security

• Bias

• Transparency
  

Users should understand when AI generates content or makes recommendations.

Human review remains important for high-impact decisions.

Protecting Sensitive Data

Never send unnecessary confidential information to AI services.

Before submitting requests:

• Remove sensitive identifiers.

• Minimize personal data.

• Encrypt communication.

• Follow organizational compliance requirements.
  

This connects directly with our earlier articles on Data Protection and Zero Trust Architecture.

Observability

AI systems should be monitored like every other service.

Track:

• Response time

• Token usage

• Error rates

• Model latency

• Request volume
  

OpenTelemetry integrates well with AI-powered applications.

Observability helps teams understand cost as well as performance.

Prompt Engineering

Large language models respond according to the instructions they receive.

Well-designed prompts produce more reliable results.

Rather than asking:

“Summarize this.”

Consider:

“Summarize this customer complaint in three bullet points highlighting the primary issue, urgency level, and recommended next action.”

Clear prompts often improve output quality dramatically.

Cost Management

AI services usually charge per request or per token.

Applications should:

• Cache repeated responses.

• Limit unnecessary requests.

• Select appropriate model sizes.

• Monitor usage.
  

Good architecture reduces operational costs significantly.

Real-World Example

Imagine a global logistics company.

Customers upload shipping documents.

The workflow becomes:

1. ASP.NET Core receives the document.

2. Azure AI extracts structured information.

3. ML.NET predicts shipping delays.

4. A language model summarizes unusual issues.

5. Results appear inside the operations dashboard.

No single AI model performs everything.

Each specializes in one task.

ASP.NET Core coordinates the entire workflow.

How This Fits Your ASP.NET Core Journey

Throughout this series we’ve explored:

• Microservices

• API Gateways

• Service Meshes

• Distributed Tracing

• Zero Trust Security

• Internal Developer Platforms

Artificial Intelligence becomes another service within this architecture.

Rather than replacing traditional software design, AI enhances existing systems by making them more intelligent, adaptive, and helpful.

Closing Thoughts

Artificial Intelligence is changing how users interact with software, but successful AI applications still rely on strong software engineering principles.

ASP.NET Core provides an excellent foundation for integrating AI services, managing workflows, securing sensitive data, and exposing intelligent capabilities through clean APIs.

Whether you’re building chatbots, recommendation engines, document processing systems, or predictive analytics platforms, treating AI as one component of a well-designed architecture leads to applications that are easier to maintain, easier to scale, and far more valuable to users.

The future of software isn’t simply AI-powered. It’s thoughtfully engineered systems where traditional software and intelligent services work together to solve real business problems.

Subscribe Now

Enjoying this series? Subscribe to ASP Today for practical ASP.NET Core tutorials, cloud-native architecture guides, AI integration strategies, and enterprise development best practices. Join our Substack Chat to discuss modern .NET development with developers from around the world.

Subscribe now

This is where a service mesh comes in. Rather than adding networking logic to every ASP.NET Core application, a service mesh transparently manages communication between services, providing traffic control, encryption, security policies, and deep observability without requiring changes to your application code.

Life Before a Service Mesh

Imagine an online retail platform built with ASP.NET Core.

It contains separate services for:

• Products

• Orders

• Inventory

• Payments

• Shipping

• Notifications

• Customer Accounts

The API Gateway successfully routes incoming requests.

However, after the request enters your platform, the services begin talking to one another.

An order service might contact inventory, payment, shipping, and notification services during a single customer purchase.

As the system grows, each service must handle:

• Secure communication

• Authentication

• Retries

• Timeouts

• Load balancing

• Logging

• Distributed tracing

• Encryption

• Circuit breakers

Every development team ends up writing nearly identical networking code.

Maintaining that code across dozens of services quickly becomes difficult.

What Is a Service Mesh?

A service mesh is dedicated infrastructure that manages communication between your microservices.

Instead of placing networking logic inside every ASP.NET Core application, the mesh handles those responsibilities automatically.

Your application continues focusing on business logic while the service mesh manages communication behind the scenes.

Unlike an API Gateway, which handles traffic entering your platform, a service mesh focuses on traffic moving inside your platform.

Understanding Sidecar Proxies

The heart of a service mesh is the sidecar proxy.

Each ASP.NET Core service runs alongside its own lightweight proxy.

Client
   │
   ▼
API Gateway
   │
   ▼
Order Service ←→ Sidecar Proxy
                     │
                     ▼
            Inventory Sidecar
                     │
                     ▼
           Inventory Service

Every request passes through these proxies.

The application never communicates directly with another service.

Instead, the sidecars handle networking responsibilities.

Why Sidecars Matter

Because every request flows through a proxy, the service mesh can automatically provide:

• Mutual TLS encryption

• Traffic routing

• Load balancing

• Retries

• Timeouts

• Observability

• Authentication

• Authorization

• Policy enforcement

Your ASP.NET Core applications remain clean and focused.

Traffic Management

Suppose version two of your Product Service has just been deployed.

Instead of sending every request to the new version immediately, the mesh can gradually shift traffic.

For example:

• 95% of requests continue using Version 1

• 5% use Version 2

If everything performs well, the percentage gradually increases.

This approach enables safer deployments.

Canary Releases

Canary deployments become extremely simple.

Rather than modifying application code, the service mesh controls how traffic flows between service versions.

If problems appear, traffic can immediately return to the previous version.

No code changes are required.

Load Balancing

Suppose your Inventory Service now runs on six different containers.

The service mesh distributes traffic automatically across healthy instances.

Applications simply call Inventory Service.

The mesh decides which instance should receive the request.

Automatic Retries

Temporary failures happen frequently.

A container may restart.

A network connection might briefly fail.

Instead of every ASP.NET Core application implementing retry logic independently, the mesh retries failed requests automatically according to configurable policies.

Timeouts

Long-running requests can consume valuable resources.

The mesh applies timeout policies before failures spread throughout the system.

Applications don’t need to implement timeout logic repeatedly.

Circuit Breaking

We previously discussed circuit breakers.

Service meshes implement them automatically.

When a downstream service becomes unhealthy, the mesh temporarily stops forwarding requests.

This prevents cascading failures across your platform.

Security Between Services

One of the biggest advantages of a service mesh is security.

Without a mesh, developers often need to configure secure communication manually.

With a mesh, secure communication becomes the default.

Mutual TLS

Most developers are familiar with HTTPS protecting communication between browsers and servers.

Inside a microservices platform, every service should also verify the identity of every other service.

Service meshes accomplish this using Mutual TLS (mTLS).

Every connection becomes:

• Authenticated

• Encrypted

• Verified

No application code changes are required.

Identity Instead of IP Addresses

Traditional systems often trust network locations.

Modern service meshes trust service identities instead.

Even if containers move between servers, identities remain consistent.

This aligns closely with the Zero Trust principles discussed in earlier articles.

Policy Enforcement

Administrators can define rules such as:

• Payment Service can call Inventory Service.

• Notification Service cannot call Payment Service.

• Reporting Service has read-only access.

Policies are managed centrally rather than inside dozens of applications.

Observability

Understanding distributed systems is difficult.

One customer request may travel through fifteen services.

Finding performance problems without visibility becomes almost impossible.

Service meshes automatically collect telemetry.

Metrics

Without changing your code, the mesh records:

• Request count

• Latency

• Success rate

• Error rate

• Response times

These metrics help teams understand application health.

Distributed Tracing

Each request receives a trace identifier.

As requests move between services, the mesh records every step.

Developers can visualize exactly where delays occur.

This works beautifully alongside OpenTelemetry, which we explored in our previous observability article.

Logging

Because every request passes through sidecars, the mesh automatically records communication between services.

This simplifies troubleshooting without requiring custom logging logic in every application.

Popular Service Mesh Technologies

Several mature service mesh platforms are widely used.

The most common include:

• Istio

• Linkerd

• Kuma

• Consul Connect

Most integrate naturally with Kubernetes, where ASP.NET Core applications are commonly deployed.

Does ASP.NET Core Need Special Code?

One of the biggest advantages is that your application usually requires very little modification.

Your ASP.NET Core services continue communicating using standard HTTP or gRPC.

The mesh intercepts traffic transparently.

Business logic remains completely separate from networking infrastructure.

API Gateway vs Service Mesh

These technologies complement one another rather than compete.

API Gateway responsibilities include:

• Client authentication

• External routing

• Rate limiting

• Public APIs

Service Mesh responsibilities include:

• Internal routing

• Service authentication

• Mutual TLS

• Retries

• Traffic shaping

• Observability

• Policy enforcement

Many modern cloud-native systems use both together.

Common Mistakes

Avoid expecting the service mesh to replace good application design.

A mesh improves networking, but it does not replace:

• Clean architecture

• Domain boundaries

• Reliable code

• Proper error handling

It should enhance your platform, not compensate for poor software design.

Real-World Example

Imagine a global airline booking platform.

A customer books a flight.

The API Gateway accepts the request.

Behind the scenes:

• Booking Service contacts Inventory.

• Inventory contacts Pricing.

• Pricing contacts Loyalty.

• Booking contacts Payments.

• Payments contacts Notifications.

The customer sees a single confirmation screen.

Meanwhile, the service mesh securely manages dozens of encrypted service-to-service conversations, balances traffic, retries temporary failures, collects telemetry, and records distributed traces without requiring each application to implement those capabilities individually.

How This Fits Your ASP.NET Core Journey

So far, we’ve explored:

• API Gateways

• Zero Trust Security

• Distributed Tracing

• Chaos Engineering

• Internal Developer Platforms

• Advanced Authorization

Service meshes tie these concepts together by providing a secure, observable communication layer for modern microservices.

Closing Thoughts

As ASP.NET Core applications continue evolving toward cloud-native architectures, reliable communication between services becomes just as important as the services themselves.

A service mesh removes much of the complexity traditionally embedded inside application code. By managing traffic, encryption, retries, authentication, and observability at the infrastructure layer, it allows development teams to focus on building business features instead of repeatedly solving networking challenges.

Whether you’re deploying a handful of services or operating hundreds across Kubernetes clusters, understanding service mesh concepts will help you build systems that are more secure, more resilient, and significantly easier to operate.

Subscribe Now

If you’re enjoying this cloud-native architecture series, subscribe to ASP Today for practical ASP.NET Core tutorials, real-world architecture guides, and enterprise development best practices. Join our Substack Chat to discuss modern .NET development with developers building scalable applications around the world.

Subscribe now

In this guide, we’ll explore how API Gateways work, how to implement them using ASP.NET Core, and how they improve routing, security, scalability, and developer experience in modern distributed systems.

Why Microservices Need a Front Door

Imagine an online shopping application built using microservices.

Instead of one application, you now have:

• Product Service

• Orders Service

• Inventory Service

• Payment Service

• Shipping Service

• Notification Service

If a mobile application communicates directly with every service, several problems appear.

The client must know:

• Where each service lives

• Which URLs to call

• Which authentication tokens are required

• Which service owns which data

Every new microservice increases complexity.

This quickly becomes difficult to maintain.

What Is an API Gateway?

An API Gateway sits between clients and your microservices.

Instead of calling services directly, every request goes through the gateway.

Mobile App
Web App
Desktop App
        │
        ▼
   API Gateway
        │
 ┌──────┼────────┐
 ▼      ▼        ▼
Orders Products Payments

The gateway becomes the single public entry point.

Clients only need to know one address.

Why API Gateways Matter

API Gateways simplify communication.

Instead of exposing every internal service, the gateway handles:

• Routing

• Authentication

• Authorization

• Rate limiting

• Request aggregation

• Logging

• Monitoring

• Response transformation

Microservices remain focused on business logic.

The gateway handles cross-cutting concerns.

Understanding Request Routing

The primary responsibility of an API Gateway is routing.

For example:

/api/products
        │
        ▼
Product Service

/api/orders
        │
        ▼
Orders Service

/api/payments
        │
        ▼
Payment Service

Clients don’t need to know where services are hosted.

The gateway forwards requests automatically.

Building an API Gateway with ASP.NET Core

ASP.NET Core provides several options.

One of the most popular is YARP (Yet Another Reverse Proxy), developed by Microsoft.

YARP documentation

Install:

dotnet add package Yarp.ReverseProxy

Configuring YARP

Register the reverse proxy.

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

Then enable it.

app.MapReverseProxy();

Your gateway is now ready to forward requests.

Configuring Routes

Example configuration:

{
  "ReverseProxy": {
    "Routes": {
      "products": {
        "ClusterId": "products",
        "Match": {
          "Path": "/products/{**catch-all}"
        }
      }
    }
  }
}

Clients continue calling one API while YARP forwards traffic to the correct service.

Request Aggregation

Sometimes a client needs data from multiple services.

Imagine loading a product page.

The application needs:

• Product details

• Inventory

• Reviews

• Pricing

Without a gateway:

The browser makes four separate requests.

With aggregation:

The browser makes one request.

The gateway gathers information from multiple services before returning a single response.

This reduces network traffic and improves performance.

Example Aggregation Flow

Client
   │
   ▼
Gateway
 ├── Product Service
 ├── Inventory Service
 ├── Review Service
 └── Pricing Service
        │
        ▼
 Combined Response

The client receives one complete response.

Authentication at the Gateway

One of the biggest advantages of an API Gateway is centralized authentication.

Instead of every service validating JWT tokens independently, the gateway performs the initial authentication.

Example:

builder.Services
.AddAuthentication()
.AddJwtBearer();

Only authenticated requests reach internal services.

This simplifies service development.

Authorization

Authentication identifies users.

Authorization determines what they can access.

Policy-based authorization works well inside gateways.

Example:

[Authorize(Policy = "Orders.Read")]

Unauthorized requests are rejected before reaching downstream services.

Rate Limiting

Gateways are an ideal location for rate limiting.

ASP.NET Core includes built-in support.

Example:

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter(
        "api",
        limiter =>
        {
            limiter.PermitLimit = 100;
            limiter.Window =
                TimeSpan.FromMinutes(1);
        });
});

Rate limiting protects services from abuse.

Response Caching

Frequently requested data can be cached.

Instead of contacting the Product Service repeatedly, the gateway serves cached responses.

Benefits include:

• Faster responses

• Reduced backend load

• Lower infrastructure costs

Caching should be applied carefully to avoid serving stale data.

Load Balancing

A Product Service may run multiple instances.

Gateway
   │
 ┌─┼─────────────┐
 ▼ ▼ ▼
Instance A
Instance B
Instance C

The gateway distributes traffic across available instances.

Users experience higher availability without knowing multiple servers exist.

Service Discovery

Microservices often change location.

Containers restart.

Pods move.

New instances appear.

Instead of hardcoding addresses, the gateway integrates with service discovery solutions.

Examples include:

• Kubernetes

• Consul

• Azure Container Apps

Requests always reach healthy instances.

Circuit Breakers

If a downstream service fails, the gateway should avoid repeatedly sending requests.

Circuit breakers temporarily stop traffic to unhealthy services.

This improves overall system stability.

It also complements the resilience strategies we explored in previous articles.

Logging Requests

Every request passes through the gateway.

This makes it an excellent place to capture:

• Request paths

• Response codes

• Processing times

• Client IP addresses

These logs become valuable for troubleshooting.

Distributed Tracing

The gateway also plays an important role in observability.

Using OpenTelemetry, it can:

• Start trace spans

• Propagate trace context

• Record latency

• Capture downstream service performance

This connects directly with our earlier article on distributed tracing.

API Versioning

Gateways simplify API evolution.

Clients may continue using:

/api/v1/orders

While newer clients use:

/api/v2/orders

The gateway routes requests appropriately without exposing internal service complexity.

Security Benefits

The gateway strengthens security by:

• Hiding internal services

• Centralizing authentication

• Applying authorization policies

• Enforcing HTTPS

• Performing request validation

• Blocking malicious traffic

Internal services remain inaccessible from the public internet.

Common Mistakes

Avoid making the gateway responsible for business logic.

The gateway should coordinate requests.

Business decisions belong inside services.

Also avoid:

• Creating a single massive gateway

• Hardcoding routes

• Ignoring monitoring

• Forgetting rate limiting

• Bypassing authentication

A lightweight gateway is easier to maintain.

Real-World Example

Imagine an airline booking platform.

Customers use one mobile app.

Behind the scenes the gateway communicates with:

• Flight Service

• Booking Service

• Payment Service

• Loyalty Service

• Notification Service

The mobile app makes a single request.

The gateway handles routing, authentication, aggregation, and response formatting.

The customer experiences one seamless interaction despite multiple backend services working together.

How This Fits Your ASP.NET Core Journey

Our recent articles explored:

• Microservices

• Zero Trust Architecture

• Data Protection

• Advanced Authorization

• Internal Developer Platforms

API Gateways bring these ideas together.

They become the secure front door through which every request enters your distributed system.

They enforce security, simplify communication, improve observability, and create a better experience for both developers and users.

Closing Thoughts

As applications continue moving toward microservices, API Gateways become an essential architectural component.

They reduce client complexity, centralize security, simplify routing, and provide a single location for cross-cutting concerns such as authentication, logging, caching, and monitoring.

ASP.NET Core, together with Microsoft’s YARP project, provides an excellent foundation for building lightweight, high-performance API Gateways that scale with modern cloud-native applications.

Rather than exposing dozens of services directly, let your gateway become the intelligent front door that protects, organizes, and simplifies your entire platform.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core tutorials, cloud-native architecture guides, and enterprise development best practices. Join the Substack Chat to discuss modern ASP.NET Core development with developers building scalable applications around the world.

Subscribe now

In this guide, we’ll explore how to build an Internal Developer Platform using ASP.NET Core and create a foundation that allows development teams to focus on writing business features instead of managing infrastructure.

Why Development Slows as Teams Grow

A small startup might have:

• Five developers

• One application

• One deployment pipeline

Everyone knows where everything is.

Need a database?

Someone creates one.

Need a new API?

Someone builds it.

Need production access?

Just ask.

Everything works.

Until it doesn’t.

As organizations grow, so do requests.

Developers begin asking questions like:

• Can someone create a Kubernetes namespace?

• Can I get a SQL database?

• Who creates Azure resources?

• Where do I request secrets?

• How do I deploy to staging?

• Which logging standard should I follow?

Eventually engineers spend more time waiting than building.

What Is an Internal Developer Platform?

An Internal Developer Platform is software built for developers inside an organization.

Instead of manually requesting resources, developers use a platform to provision them themselves.

Think of it as an internal app store.

Instead of installing games, developers request:

• New projects

• Databases

• Storage accounts

• API keys

• Kubernetes environments

• Deployment pipelines

Everything follows company standards automatically.

Why Organizations Build Internal Platforms

The biggest goal is reducing developer friction.

Without an IDP:

Developer writes ticket.

Operations creates infrastructure.

Security reviews access.

Platform team configures deployment.

Developer waits.

With an IDP:

Developer clicks a button.

Platform performs everything automatically.

The developer continues working.

Platform Engineering vs DevOps

These terms are closely related.

DevOps focuses on collaboration between development and operations.

Platform Engineering creates products that help developers succeed.

Instead of manually helping every team, platform engineers build reusable tools.

Those tools become the Internal Developer Platform.

Understanding Self-Service Development

Imagine buying groceries.

Years ago, every item required asking a shop assistant.

Today we simply use self-checkout.

Internal platforms work the same way.

Instead of requesting resources manually, developers provision them independently.

The platform performs all the complicated work behind the scenes.

What Can an Internal Developer Platform Provide?

A mature platform might offer:

• Project templates

• API creation

• Infrastructure provisioning

• Secret management

• Logging configuration

• Monitoring dashboards

• CI/CD pipelines

• Deployment approvals

• Security scanning

• Documentation

Developers interact with one consistent interface.

Why ASP.NET Core Is a Great Choice

ASP.NET Core excels at building internal tools.

It offers:

• High performance

• Cross-platform support

• Excellent security

• REST API development

• Background services

• Identity integration

• Cloud-native capabilities

These features make it ideal for building platform APIs.

Designing the Platform

Think of the platform as multiple services working together.

Developer Portal
        │
        ▼
Platform API
        │
 ┌──────┼────────┐
 ▼      ▼        ▼
Templates Deployments Infrastructure
        │
        ▼
Cloud Resources

Each component has a specific responsibility.

This separation keeps the platform maintainable.

Building the Platform API

Everything begins with an API.

Developers request services through HTTP endpoints.

Example:

POST /projects

Payload:

{
  "name": "InventoryService",
  "template": "webapi"
}

The platform performs the remaining work automatically.

Creating the API

Example:

app.MapPost("/projects",
(ProjectRequest request) =>
{
    return Results.Ok(
        $"Creating {request.Name}");
});

Simple APIs often orchestrate much larger workflows.

Automating Project Creation

Suppose every microservice requires:

• Standard folder structure

• Logging

• Health checks

• Docker support

• OpenTelemetry

• Authentication

Instead of manually configuring each project, developers choose a template.

The platform generates everything consistently.

Project Templates

Templates eliminate repetitive work.

A template might include:

• Authentication configured

• Swagger enabled

• Logging configured

• Dockerfile included

• CI/CD pipeline ready

• Unit tests added

Every new service begins with the same high-quality foundation.

Managing Templates

Templates evolve over time.

For example:

Version 1:

• .NET 8

• Basic logging

Version 2:

• OpenTelemetry

• Health checks

• Distributed tracing

• Rate limiting

Developers automatically benefit from platform improvements.

Infrastructure as Code

Infrastructure should never be created manually.

Instead use:

• Bicep

• Terraform

• ARM Templates

The platform invokes these tools automatically.

Developers simply request resources.

Provisioning Cloud Resources

Imagine a developer needs:

• Azure SQL

• Azure Storage

• Service Bus

• Key Vault

Instead of opening multiple Azure portals, they submit one request.

The platform provisions everything.

Background Processing

Some operations take several minutes.

Examples:

• Creating Kubernetes clusters

• Deploying infrastructure

• Provisioning databases

ASP.NET Core Background Services handle these long-running jobs efficiently.

Example:

public class ProvisioningWorker
    : BackgroundService
{
    protected override async Task ExecuteAsync(
        CancellationToken token)
    {
        while (!token.IsCancellationRequested)
        {
            await Task.Delay(5000, token);
        }
    }
}

Background workers keep APIs responsive.

Building a Developer Portal

The portal becomes the front door of the platform.

Developers can:

• Create projects

• Request environments

• View deployments

• Browse documentation

• Monitor applications

Everything is available from one location.

Authentication

Only authorized developers should access platform resources.

ASP.NET Core Identity integrates easily with:

• Microsoft Entra ID

• Azure AD

• OAuth

• OpenID Connect

Authentication ensures platform requests remain secure.

Authorization

Different developers require different permissions.

Examples:

Developers

• Create projects

Team Leads

• Approve production deployments

Platform Engineers

• Manage templates

Administrators

• Configure infrastructure

Policy-based authorization keeps permissions manageable.

This builds directly on concepts from our previous article on advanced authorization.

API Versioning

Internal platforms evolve continuously.

Versioning prevents breaking existing developer workflows.

Example:

/api/v1/projects

/api/v2/projects

Existing automation continues working while new features are introduced.

Logging Platform Activity

Everything the platform does should be logged.

Examples:

• Project created

• Deployment started

• Database provisioned

• Secret generated

Audit logging becomes especially valuable for compliance and troubleshooting.

As discussed in our previous article, audit logs provide accountability across complex systems.

Monitoring Platform Health

An Internal Developer Platform quickly becomes business-critical.

Monitor:

• API availability

• Provisioning success rate

• Deployment duration

• Queue lengths

• Failed workflows

Health checks and OpenTelemetry provide excellent visibility.

This connects naturally with our recent observability articles.

Building for Reuse

One of the biggest goals of an IDP is eliminating duplicated effort.

Instead of every team solving the same problems independently, the platform provides reusable solutions that everyone benefits from.

This creates consistency across the entire organization.

Coming in Part 2

Our Internal Developer Platform can now provide developers with self-service tools and standardized project creation, but there’s still more work to do before it becomes a truly enterprise-ready platform.

In Part 2, we’ll automate CI/CD pipelines, provision development and production environments on demand, manage secrets securely, implement deployment approvals and governance, and explore how to scale the platform across multiple teams. We’ll finish by building a complete real-world Internal Developer Platform that helps developers deliver software faster while maintaining security, consistency, and operational excellence.

Closing Thoughts

An Internal Developer Platform is much more than a collection of internal tools. It becomes the foundation that enables development teams to work faster, deliver more consistently, and spend less time on repetitive operational tasks. By providing self-service capabilities, standardized templates, automated infrastructure provisioning, and reusable APIs, organizations can reduce bottlenecks while improving security, reliability, and developer experience. As your platform evolves, you can expand it with automated deployment pipelines, environment provisioning, secret management, governance controls, and observability, transforming it into a central hub that supports every stage of the software development lifecycle.

Subscribe Now

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core tutorials, architecture deep dives, and real-world engineering guides. Join our Substack Chat to connect with fellow developers, ask questions, and stay up to date with the latest ASP.NET Core best practices.

Subscribe now

In this guide, you’ll learn how to build audit logging into ASP.NET Core applications, automatically capture meaningful events, support regulatory compliance, and create audit trails that remain useful as your applications grow.

Why Audit Logging Matters

Imagine a customer calls support and says:

“I never changed my shipping address.”

A week later another customer reports:

“My account was deleted.”

An administrator notices that sensitive information has disappeared from the database.

Without an audit log, you only know that something happened.

You don’t know:

• Who made the change

• When it happened

• What the previous value was

• What the new value became

• Which application made the change

Audit logging fills in these missing details.

It creates a permanent history of important events that helps developers troubleshoot problems, helps administrators investigate incidents, and helps organizations satisfy compliance requirements.

Application Logs vs Audit Logs

Many developers assume ordinary application logs are enough.

They are not.

Application logs record how the application behaves.

Examples include:

• Exceptions

• Startup events

• Performance metrics

• Debug information

Audit logs answer business questions instead.

Examples include:

• Who updated this customer?

• Who approved this payment?

• Who downloaded this report?

• Who deleted this document?

The two logging systems complement each other.

They should not replace one another.

What Should Be Audited?

Not every action deserves an audit record.

Focus on events that affect business operations or security.

Examples include:

• User logins

• Failed login attempts

• Password changes

• Profile updates

• Record creation

• Record modification

• Record deletion

• Permission changes

• Role assignments

• Administrative actions

• Data exports

• Financial approvals

Auditing every tiny event often creates unnecessary noise.

Choose events that would matter during an investigation.

Designing an Audit Record

Every audit entry should answer five simple questions.

Who?

What?

When?

Where?

Why?

A typical audit record might contain:

• User ID

• Username

• Action performed

• Entity affected

• Previous values

• New values

• Timestamp

• IP address

• Browser or device

• Correlation ID

The more context captured, the more useful the audit log becomes.

A Simple Audit Model

Example:

public class AuditLog
{
    public int Id { get; set; }

    public string UserId { get; set; }

    public string Action { get; set; }

    public string Entity { get; set; }

    public string OldValues { get; set; }

    public string NewValues { get; set; }

    public DateTime Timestamp { get; set; }

    public string IpAddress { get; set; }
}

This model provides a solid starting point.

Real-world systems often add more metadata.

Capturing User Identity

Audit logs become much more valuable when every action is linked to a specific user.

ASP.NET Core makes this easy.

Example:

var username = User.Identity?.Name;

For applications using JWT authentication:

var userId =
    User.FindFirst("sub")?.Value;

Capturing user identity should be standard practice.

Recording Request Information

Sometimes the request itself provides useful evidence.

Consider recording:

• IP address

• HTTP method

• URL

• User agent

• Correlation ID

Example:

var ip =
    HttpContext.Connection
        .RemoteIpAddress?
        .ToString();

These details help reconstruct what happened during investigations.

Automatically Auditing Entity Framework Core

One of the easiest ways to implement audit logging is by intercepting Entity Framework Core changes.

Every tracked entity already knows whether it has been:

• Added

• Modified

• Deleted

This makes EF Core an excellent source of audit events.

Detecting Changes

Example:

foreach (var entry in
    ChangeTracker.Entries())
{
    if (entry.State ==
        EntityState.Modified)
    {
        // Create audit record
    }
}

Instead of manually writing audit code throughout the application, you centralize it in one place.

This greatly simplifies maintenance.

Overriding SaveChanges

A common pattern is overriding SaveChangesAsync.

Example:

public override async Task<int>
SaveChangesAsync(
CancellationToken cancellationToken)
{
    CreateAuditEntries();

    return await
        base.SaveChangesAsync(
            cancellationToken);
}

Every database change automatically produces an audit record.

Developers no longer need to remember to create one manually.

Capturing Old and New Values

Suppose a customer changes their email address.

Instead of recording only:

Customer updated

Capture:

Old:
john@example.com

New:
john.smith@example.com

This information becomes invaluable during troubleshooting.

Recording Authentication Events

Authentication activity should also be audited.

Examples include:

• Successful logins

• Failed logins

• Account lockouts

• Password resets

• Multi-factor authentication failures

Security teams frequently investigate these events.

Recording Authorization Events

Authorization changes often have significant business impact.

Examples include:

• Administrator granted

• Permission revoked

• Role changed

• Access denied

These records help identify accidental or unauthorized permission changes.

Soft Deletes vs Hard Deletes

Deleting data permanently removes valuable evidence.

Many organizations prefer soft deletes.

Instead of removing a record:

IsDeleted = true

The audit log records:

• Who deleted it

• When

• Why

The record remains recoverable if needed.

Tamper Resistance

Audit logs should not be easy to modify.

Otherwise attackers can simply erase their tracks.

Common approaches include:

• Write-once storage

• Append-only databases

• Restricted permissions

• Digital signatures

An audit log should be treated as evidence.

Separating Audit Logs from Application Logs

Do not mix audit logs with application diagnostics.

Instead:

• Application logs → troubleshooting

• Audit logs → accountability

Keeping them separate improves security and simplifies compliance reporting.

Correlation IDs

Modern applications often span multiple services.

A single customer request might involve:

• API Gateway

• Orders Service

• Inventory Service

• Payment Service

Using a Correlation ID allows every audit record to be connected to the same business operation.

Example:

var correlationId =
    HttpContext.TraceIdentifier;

This becomes especially useful in distributed systems.

Audit Logging in Microservices

Microservices introduce new challenges.

Each service produces its own audit events.

Questions include:

• Should every service keep its own audit log?

• Should logs be centralized?

• How are timestamps synchronized?

Many organizations collect audit events into a centralized platform for easier analysis.

Asynchronous Audit Logging

Writing audit records synchronously can slow applications.

Instead consider:

• Background queues

• Azure Service Bus

• RabbitMQ

Applications remain responsive while audit records are written in the background.

This connects nicely with our earlier article on messaging systems.

Protecting Audit Data

Audit logs themselves often contain sensitive information.

Protect them using:

• Encryption

• Restricted access

• Backup policies

• Data retention rules

Never assume audit data is harmless.

Compliance Requirements

Many regulations require organizations to maintain audit trails.

Examples include:

GDPR

Requires accountability for personal data access.

HIPAA

Requires auditing of healthcare information.

PCI DSS

Requires tracking access to payment information.

SOC 2

Emphasizes monitoring and accountability.

Audit logging helps organizations demonstrate compliance.

What Audit Logs Should Not Contain

Avoid recording:

• Passwords

• Encryption keys

• Credit card numbers

• Authentication tokens

• Sensitive secrets

Instead record enough information to investigate activity without exposing confidential data.

Common Mistakes

Several mistakes appear repeatedly.

Logging Too Much

Huge audit tables become difficult to search.

Logging Too Little

Critical investigations become impossible.

Missing User Information

An action without a user has little value.

Ignoring Failed Attempts

Unauthorized access attempts often matter as much as successful ones.

Real-World Example

Imagine a banking application.

A customer transfers money.

The audit log records:

• User identity

• Source account

• Destination account

• Amount

• Timestamp

• IP address

• Approval status

• Correlation ID

Months later an investigation occurs.

The organization can reconstruct the entire transaction history within seconds.

How Audit Logging Supports Earlier Topics

This article connects naturally with several recent posts.

Zero Trust verifies identities.

Authorization controls permissions.

Data Protection secures information.

Audit Logging records every important action.

Distributed Tracing follows requests across services.

Together these practices create applications that are secure, observable, and accountable.

Best Practices Checklist

When designing an audit logging system:

• Audit important business events rather than every operation.

• Capture user identity and request context.

• Record previous and new values where appropriate.

• Keep audit logs separate from application logs.

• Protect audit records from unauthorized modification.

• Encrypt sensitive audit data.

• Use asynchronous processing for high-volume systems.

• Define retention policies that satisfy compliance requirements.

• Regularly review audit logs for suspicious activity.

Following these practices helps build audit systems that remain valuable as applications grow.

Closing Thoughts

Building secure applications involves much more than preventing unauthorized access.

Organizations also need visibility into what happens after users sign in.

Audit logging provides that visibility by recording important events in a consistent, reliable, and searchable way.

ASP.NET Core offers all the building blocks needed to create robust audit logging systems, especially when combined with Entity Framework Core, authentication, authorization, and distributed tracing.

As your applications grow in complexity, audit logging becomes one of the most valuable tools for troubleshooting, security investigations, and regulatory compliance.

Knowing what happened yesterday often determines how quickly you can solve tomorrow’s problem.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture, security, and enterprise development guides. Join the Substack Chat to discuss modern ASP.NET Core development with developers building secure, scalable applications.

Subscribe now

In this guide, you’ll learn how advanced authorization works, when to use policy-based and attribute-based approaches, and how to build scalable authorization rules for real-world applications.

Authentication vs Authorization

These two concepts are closely related but solve different problems.

Authentication answers:

Who are you?

Authorization answers:

What are you allowed to do?

Imagine entering an airport.

Showing your passport proves your identity.

That is authentication.

Your boarding pass determines which gate you may enter and whether you can access the airline lounge.

That is authorization.

ASP.NET Core separates these responsibilities, making applications easier to secure and maintain.

Why Authorization Becomes Difficult

Small applications often begin with simple roles.

Examples include:

• Administrator

• Manager

• Employee

• Customer

Initially this works well.

As applications grow, new questions appear.

Can managers approve expenses over $10,000?

Can support engineers edit customer information but not delete it?

Can finance users export reports only during business hours?

Can users manage only projects belonging to their own department?

Roles alone cannot answer these questions cleanly.

Understanding Role-Based Authorization

ASP.NET Core supports role-based authorization out of the box.

Example:

[Authorize(Roles = "Administrator")]
public IActionResult DeleteUser()
{
    return Ok();
}

Only users belonging to the Administrator role can access this action.

Simple.

Easy to understand.

Perfect for straightforward scenarios.

However, real businesses usually require more flexibility.

The Limitations of Roles

Imagine an organization with:

• Sales Manager

• Regional Sales Manager

• Global Sales Manager

• Finance Manager

• HR Manager

• Support Manager

• Operations Manager
  

Soon the number of roles begins to grow rapidly.

Eventually you encounter:

• Duplicate permissions

• Conflicting responsibilities

• Difficult maintenance

• Authorization bugs
  

This is often called role explosion.

Policies solve this problem.

What Is Policy-Based Authorization?

A policy defines rules instead of roles.

Instead of asking:

“Is this user an Administrator?”

You ask:

“Does this user satisfy these requirements?”

A policy can evaluate:

• Claims

• Roles

• Permissions

• Custom business rules

• Time of day

• Department

• Resource ownership
  

Policies provide much greater flexibility.

Creating a Policy

Example:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "CanApproveOrders",
        policy =>
        {
            policy.RequireClaim(
                "permission",
                "orders.approve");
        });
});

The policy now checks whether the user has the required permission claim.

Applying a Policy

[Authorize(Policy = "CanApproveOrders")]
public IActionResult Approve()
{
    return Ok();
}

Notice how the controller contains no business logic.

The authorization system handles everything.

Understanding Claims

Claims describe information about a user.

Examples include:

• Name

• Department

• Country

• Permission

• Subscription Level

• Employee Number
  

Unlike roles, claims provide detailed information that policies can evaluate.

Claims-Based Authorization

Suppose users receive:

Department = Finance

Permission = ApproveInvoices

Your policy can require either or both.

This creates much more granular authorization.

Combining Multiple Requirements

Policies may require multiple conditions.

Example:

options.AddPolicy(
    "SeniorFinance",
    policy =>
    {
        policy.RequireRole("Manager");

        policy.RequireClaim(
            "Department",
            "Finance");
    });

Only finance managers satisfy the policy.

Custom Authorization Requirements

Sometimes business rules become very specific.

Example:

A project manager may edit only projects belonging to their own region.

This requires custom authorization.

Create a requirement:

public class RegionRequirement
    : IAuthorizationRequirement
{
}

Then implement an authorization handler.

The handler contains your business logic.

This keeps controllers clean and reusable.

Resource-Based Authorization

Sometimes authorization depends on the resource itself.

Example:

A customer may edit only their own profile.

Not someone else’s.

Instead of checking only user claims, ASP.NET Core evaluates:

• User

• Resource

• Policy
  

Together.

This is called resource-based authorization.

Attribute-Based Access Control (ABAC)

Attribute-Based Access Control goes even further.

Instead of checking only roles or permissions, it evaluates attributes.

Examples include:

User attributes:

• Department

• Clearance level

• Country
  

Resource attributes:

• Owner

• Classification

• Status
  

Environment attributes:

• Time

• Device

• Network location
  

Actions:

• Read

• Update

• Delete
  

All these factors influence authorization decisions.

Example Scenario

Suppose an employee wants to download payroll information.

Rules:

• Must belong to HR

• Must use a company device

• Must be inside the corporate network

• Must access during working hours
  

A single role cannot express this.

Attribute-based authorization can.

Authorization Handlers

Authorization handlers evaluate custom requirements.

Example:

public class MinimumAgeHandler
    : AuthorizationHandler<
        MinimumAgeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        MinimumAgeRequirement requirement)
    {
        // Validation logic

        return Task.CompletedTask;
    }
}

Handlers keep authorization logic centralized.

Dynamic Policies

Large enterprise systems often load permissions from databases.

Instead of hardcoding every policy, applications generate them dynamically.

Benefits include:

• Easier administration

• Less code duplication

• Business-managed permissions
  

This approach is common in SaaS platforms.

Authorization in Minimal APIs

Policies also work with Minimal APIs.

Example:

app.MapGet("/reports", () =>
{
    return Results.Ok();
})
.RequireAuthorization("CanViewReports");

Security remains consistent across application styles.

Authorization and Microservices

In a microservices architecture, authorization becomes distributed.

Each service should verify:

• Identity

• Permissions

• Claims
  

Never assume another service has already performed sufficient authorization.

This aligns with the Zero Trust principles discussed in our previous article.

Combining Authentication and Authorization

Authentication produces identity.

Authorization evaluates identity.

Neither replaces the other.

Together they provide layered security.

Common Authorization Mistakes

Avoid:

• Hardcoding permissions

• Mixing authorization into controllers

• Relying only on roles

• Trusting client-side validation

• Forgetting API authorization
  

Centralized authorization policies improve consistency.

Testing Authorization

Authorization should be tested just like business logic.

Verify:

• Authorized users succeed.

• Unauthorized users receive 403 Forbidden.

• Anonymous users receive 401 Unauthorized when appropriate.
  

Automated tests help prevent accidental permission changes.

Real-World Example

Imagine a project management platform.

Users include:

• Developers

• Team Leads

• Project Managers

• Clients
  

Developers may edit only assigned tasks.

Project Managers approve budgets.

Clients view only their own projects.

Finance exports reports.

Instead of creating dozens of overlapping roles, policies evaluate permissions, ownership, and department.

The authorization model remains clean even as the application grows.

Authorization and Compliance

Strong authorization also supports compliance requirements.

Frameworks such as:

• GDPR

• HIPAA

• SOC 2

• PCI DSS
  

Require organizations to restrict access to sensitive information.

Policy-based authorization helps enforce these restrictions consistently.

How This Fits Your ASP.NET Core Journey

Over the past several articles we’ve explored:

• Zero Trust Architecture

• Data Protection

• Encryption

• Key Management

• Secure Microservices
  

Advanced authorization builds directly on those concepts.

Authentication proves identity.

Encryption protects data.

Authorization determines who can use that data.

Together they form the foundation of secure ASP.NET Core applications.

Closing Thoughts

Authorization is much more than checking whether a user is an administrator.

Modern applications require flexible, maintainable access control that adapts to changing business requirements.

ASP.NET Core’s policy-based and attribute-based authorization features provide a scalable way to secure APIs, web applications, and distributed systems without filling controllers with complex permission logic.

As your applications grow, investing in a strong authorization strategy pays dividends in security, maintainability, and compliance.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture, security, and cloud-native development guides. Join the Substack Chat to discuss modern ASP.NET Core development with developers from around the world.

Subscribe now

In this guide, we’ll explore how ASP.NET Core supports data protection through encryption, secure key management, and practical compliance strategies that help keep sensitive information safe.

Why Data Protection Matters

Every application stores data.

Examples include:

• Customer profiles

• Login credentials

• Payment information

• Business records

• Application secrets

• Session tokens

If this information becomes exposed, organizations can face:

• Financial losses

• Reputational damage

• Regulatory penalties

• Customer distrust

Data protection is no longer optional.

It is a fundamental requirement of modern software development.

The Expanding Risk Landscape

Modern applications rarely exist on a single server.

Today’s ASP.NET Core applications often interact with:

• Cloud databases

• Microservices

• Message queues

• Third-party APIs

• Mobile applications

• Browser clients

Each connection introduces new opportunities for data exposure.

As systems become more distributed, protecting data becomes more challenging.

This builds naturally on concepts we explored in:

• Securing Microservices in ASP.NET Core

• Distributed Tracing with OpenTelemetry

• Fault-Tolerant Systems in ASP.NET Core

Security must exist throughout the entire application lifecycle.

Understanding Data Protection

Data protection focuses on ensuring information remains:

• Confidential

• Accurate

• Available

These goals align closely with the CIA Triad:

Confidentiality

Only authorized users can access information.

Integrity

Data cannot be altered without authorization.

Availability

Authorized users can access data when needed.

Strong protection strategies balance all three requirements.

Encryption: The Foundation of Data Protection

Encryption converts readable information into an unreadable format.

Without the correct key, encrypted data becomes useless to attackers.

For example:

Original:
CustomerPassword123

Encrypted:
Qm1kT3dQVnNQaW5GcXhaZw==

While this example is simplified, the principle remains the same.

Encryption protects sensitive information even if storage systems become compromised.

Data at Rest vs Data in Transit

When discussing encryption, two scenarios matter most.

Data at Rest

Data stored in:

• Databases

• Files

• Backups

• Cloud storage
  

Examples:

• SQL Server records

• Azure Blob Storage

• Backup archives
  

Data in Transit

Data moving between systems.

Examples:

• Browser to API

• API to database

• Service to service communication

• Message queue traffic
  

Both require protection.

Securing one without the other leaves gaps.

Encrypting Data in Transit

HTTPS should be mandatory for every ASP.NET Core application.

HTTPS uses TLS (Transport Layer Security) to encrypt communication.

Benefits include:

• Preventing eavesdropping

• Preventing data tampering

• Verifying server identity
  

ASP.NET Core makes HTTPS straightforward.

app.UseHttpsRedirection();

Microsoft documentation:

https://learn.microsoft.com/aspnet/core/security/enforcing-ssl

HTTP Strict Transport Security (HSTS)

HSTS tells browsers to always use HTTPS.

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

This prevents downgrade attacks where attackers attempt to force insecure connections.

Encrypting Data at Rest

Data at rest remains vulnerable if storage systems are compromised.

Common approaches include:

• Database encryption

• Disk encryption

• File encryption

• Application-level encryption
  

Each protects different layers of the system.

SQL Server Encryption

SQL Server supports:

• Transparent Data Encryption (TDE)

• Column encryption

• Always Encrypted
  

Official documentation:

TDE encrypts database files automatically.

Applications require minimal changes.

When Application-Level Encryption Is Necessary

Sometimes specific fields require stronger protection.

Examples include:

• National identification numbers

• Payment data

• Medical information

• API credentials
  

In these cases, encrypting sensitive values before storage provides additional security.

Example: AES Encryption

using System.Security.Cryptography;
using System.Text;

public static string Encrypt(
    string plaintext,
    byte[] key,
    byte[] iv)
{
    using var aes = Aes.Create();

    aes.Key = key;
    aes.IV = iv;

    using var encryptor =
        aes.CreateEncryptor();

    using var ms = new MemoryStream();

    using var cs = new CryptoStream(
        ms,
        encryptor,
        CryptoStreamMode.Write);

    using var sw = new StreamWriter(cs);

    sw.Write(plaintext);

    return Convert.ToBase64String(
        ms.ToArray());
}

This demonstrates the concept of application-level encryption.

Production implementations require additional safeguards and validation.

Introducing ASP.NET Core Data Protection

ASP.NET Core includes a built-in Data Protection system.

The framework uses it internally for:

• Authentication cookies

• Session data

• CSRF protection

• Temporary tokens
  

Official documentation:

This system simplifies secure encryption and key management.

Configuring Data Protection

Basic setup:

builder.Services
    .AddDataProtection();

The framework automatically generates and manages encryption keys.

Protecting Sensitive Values

Example:

public class SecretService
{
    private readonly IDataProtector _protector;

    public SecretService(
        IDataProtectionProvider provider)
    {
        _protector =
            provider.CreateProtector(
                "CustomerData");
    }

    public string Protect(string value)
    {
        return _protector.Protect(value);
    }

    public string Unprotect(string value)
    {
        return _protector.Unprotect(value);
    }
}

This approach avoids many common encryption implementation mistakes.

Why Key Management Matters

Encryption is only as strong as its keys.

Many breaches occur because keys are poorly managed.

Common mistakes include:

• Storing keys in source code

• Sharing keys between environments

• Never rotating keys

• Exposing keys in configuration files
  

Protecting encryption keys is often more important than protecting the encrypted data itself.

Understanding Key Rotation

Keys should not remain active forever.

Key rotation involves:

• Creating new keys

• Retiring old keys

• Re-encrypting data when appropriate
  

Benefits include:

• Reduced exposure

• Limited attack windows

• Improved compliance
  

ASP.NET Core Data Protection supports automatic key rotation.

Storing Keys Securely

Development environments often store keys locally.

Production environments require stronger solutions.

Options include:

• Azure Key Vault

• AWS KMS

• Hardware Security Modules (HSMs)

• Dedicated secret stores
  

Using Azure Key Vault

Azure Key Vault provides:

• Secure secret storage

• Key management

• Certificate management

• Access control
  

Official documentation:

Key Vault integrates well with ASP.NET Core applications.

Configuring Azure Key Vault

Example:

builder.Configuration
    .AddAzureKeyVault(
        new Uri(vaultUrl),
        new DefaultAzureCredential());

This removes sensitive secrets from application configuration files.

Protecting Configuration Data

Configuration often contains:

• API keys

• Database connection strings

• Service credentials
  

Never commit these values to source control.

Instead use:

• Secret managers

• Environment variables

• Key Vault solutions
  

ASP.NET Core Secret Manager

Data Protection in Distributed Systems

Modern applications frequently operate across multiple services.

Examples include:

• Microservices

• Background workers

• Message processors
  

These systems often need access to shared encryption keys.

Careful planning becomes essential.

Improper key distribution can create significant security risks.

Compliance Requirements

Many organizations must satisfy regulatory requirements.

Common examples include:

GDPR

Protects personal data for EU residents.

HIPAA

Protects healthcare information in the United States.

PCI DSS

Protects payment card information.

SOC 2

Focuses on security and operational controls.

Compliance requirements often influence data protection strategies.

Encryption Alone Does Not Guarantee Compliance

A common misconception is:

“We encrypted the data, so we’re compliant.”

Compliance involves much more.

Organizations must also consider:

• Access controls

• Audit logging

• Data retention

• Incident response

• Monitoring
  

Encryption is only one piece of the puzzle.

Auditing and Monitoring

Data access should be traceable.

Important events include:

• Login attempts

• Data modifications

• Key access

• Permission changes
  

Audit trails support:

• Security investigations

• Compliance reporting

• Incident response
  

Least Privilege Access

Not every user should access every piece of data.

Apply least privilege principles:

• Grant only required permissions

• Remove unnecessary access

• Review permissions regularly
  

This aligns closely with the Zero Trust concepts discussed in our previous article.

Protecting Backups

Backups often contain the same sensitive data as production systems.

Organizations sometimes secure production databases while neglecting backups.

Backups should be:

• Encrypted

• Access controlled

• Monitored

• Retained appropriately
  

A compromised backup can be just as damaging as a compromised database.

Data Retention and Deletion

Keeping data forever creates unnecessary risk.

Questions to consider:

• How long should data be retained?

• When should records be deleted?

• Are retention requirements documented?
  

Compliance frameworks frequently require documented retention policies.

Real-World Example: Customer Management Platform

Imagine a SaaS application storing:

• Customer profiles

• Billing information

• Authentication data
  

A strong protection strategy might include:

• HTTPS everywhere

• Database encryption

• Azure Key Vault

• ASP.NET Core Data Protection

• Audit logging

• Automated key rotation
  

If a database backup were stolen, encryption would help prevent attackers from accessing sensitive information.

Common Data Protection Mistakes

Several mistakes appear repeatedly.

Hardcoded Secrets

Secrets should never exist in source code.

Weak Key Management

Protecting data while exposing keys defeats the purpose.

Lack of Rotation

Long-lived keys increase risk.

Unencrypted Backups

Backup systems require the same protections as production.

Excessive Access

Too many users often have unnecessary permissions.

Avoiding these mistakes significantly improves security.

How This Fits Your ASP.NET Core Journey

So far, we’ve explored:

• Microservice security

• Zero Trust Architecture

• Distributed tracing

• Chaos engineering

• Fault tolerance
  

Data protection builds on all of these topics.

Security focuses on who can access systems.

Data protection focuses on safeguarding the information those systems manage.

Together they form a critical foundation for modern cloud-native applications.

Closing Thoughts

Protecting data is one of the most important responsibilities developers have.

ASP.NET Core provides powerful tools for:

• Encryption

• Key management

• Secret storage

• Data protection
  

Combined with proper compliance practices, monitoring, and access controls, these capabilities help organizations secure sensitive information and reduce risk.

Security threats will continue to evolve.

Strong data protection practices ensure your applications remain prepared.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture guides, security best practices, and real-world development strategies. Join the Substack Chat and connect with developers building secure and reliable modern applications.

Subscribe now

In this guide, we’ll explore how to secure ASP.NET Core microservices using Zero Trust principles and practical security best practices.

Why Microservices Change the Security Landscape

In a traditional monolithic application, security boundaries are relatively simple.

Users interact with a single application. That application communicates with a single database. Most communication happens internally.

Microservices introduce a very different environment.

A single user request may pass through:

• API Gateway

• Authentication Service

• Product Service

• Inventory Service

• Payment Service

• Notification Service

• Message Queue

Each service creates a potential attack surface. Every API endpoint becomes a possible entry point. Every service-to-service call becomes a security concern.

This is why securing microservices requires a different mindset.

The Problem with Traditional Network Trust

Historically, many organizations relied on perimeter-based security.

The model was simple:

• Protect the network boundary

• Trust everything inside

This approach worked reasonably well when systems lived inside a single corporate network.

Modern cloud-native systems rarely operate this way.

Today we have:

• Cloud infrastructure

• Hybrid environments

• Remote workforces

• Third-party integrations

• Distributed services

The network perimeter has effectively disappeared.

Trusting everything inside the network is no longer sufficient.

What Is Zero Trust Architecture?

Zero Trust follows a simple principle:

Never trust. Always verify.

Every request must be validated regardless of where it originates.

This applies to:

• Users

• Services

• Devices

• Applications

• APIs

Being inside the network does not automatically grant trust.

Every interaction must continuously prove its legitimacy.

Microsoft’s Zero Trust guidance

Core Principles of Zero Trust

Zero Trust is built around three core ideas.

Verify Explicitly

Always authenticate and authorize every request.

Do not rely on network location.

Do not assume trust.

Use Least Privilege Access

Grant only the permissions required.

Nothing more.

This limits the damage caused by compromised accounts or services.

Assume Breach

Design systems as though attackers are already inside.

This encourages stronger monitoring, segmentation, and verification.

Why ASP.NET Core Fits Zero Trust Well

ASP.NET Core provides several built-in security capabilities:

• Authentication middleware

• Authorization policies

• Identity integration

• JWT support

• OAuth integration

• OpenID Connect support

These features make ASP.NET Core an excellent platform for implementing Zero Trust principles.

Official documentation

Authentication vs Authorization

These concepts are often confused.

Authentication answers:

Who are you?

Authorization answers:

What are you allowed to do?

Both are essential.

A user may be authenticated successfully but still lack permission to perform specific actions.

JWT Authentication for Microservices

JSON Web Tokens (JWTs) are commonly used in microservices environments.

A user authenticates once.

The identity provider issues a token. The token accompanies subsequent requests.

Example:

Authorization: Bearer eyJhbGciOi...

Services validate the token before processing requests. This eliminates the need for centralized session storage.

Configuring JWT Authentication

ASP.NET Core provides built-in support.

builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer(options =>
    {
        options.Authority =
            "https://identity.example.com";

        options.Audience = "orders-api";
    });

This validates incoming access tokens automatically.

Securing APIs with Authorization Policies

Role-based authorization works well for many scenarios.

Example:

[Authorize(Roles = "Administrator")]
public IActionResult DeleteOrder()
{
    return Ok();
}

However, microservices often require more granular controls.

Policy-based authorization provides greater flexibility.

Policy-Based Authorization

Example:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "CanProcessPayments",
        policy =>
        {
            policy.RequireClaim(
                "permission",
                "payments.process");
        });
});

Controller:

[Authorize(Policy = "CanProcessPayments")]
public IActionResult ProcessPayment()
{
    return Ok();
}

This approach scales well across complex systems.

Service-to-Service Authentication

Zero Trust applies to services too.

One common mistake is assuming internal services can trust each other automatically.

Example:

API Gateway
     ↓
Orders Service
     ↓
Inventory Service
     ↓
Payment Service

Every service should verify the identity of the caller.

This prevents attackers from moving laterally through compromised systems.

Machine-to-Machine Authentication

Service communication often uses OAuth 2.0 client credentials flow.

Instead of users authenticating:

• Services authenticate themselves
  

Example workflow:

Inventory Service
     ↓
Identity Provider
     ↓
Access Token
     ↓
Payment Service

This creates secure service-to-service communication.

OAuth documentation

Mutual TLS (mTLS)

Mutual TLS strengthens service authentication.

Normally:

• Client verifies server
  

With mTLS:

• Client verifies server

• Server verifies client

Both parties prove their identities.

This significantly improves security for internal service communication.

API Gateways and Security

Most microservices architectures include an API gateway.

The gateway becomes a central security layer.

Responsibilities often include:

• Authentication

• Authorization

• Rate limiting

• Request validation

• Threat detection

Popular gateways include:

• YARP

• Kong

• Azure API Management

YARP documentation

Rate Limiting for Protection

Rate limiting protects APIs from abuse.

ASP.NET Core includes built-in rate limiting.

Example:

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter(
        "api",
        opt =>
        {
            opt.PermitLimit = 100;
            opt.Window = TimeSpan.FromMinutes(1);
        });
});

This reduces:

• Brute-force attacks

• Abuse

• Resource exhaustion
  

Protecting Secrets

Secrets are often one of the weakest links.

Common mistakes include:

• Hardcoded passwords

• Secrets in source control

• Shared credentials

Instead use:

• Azure Key Vault

• AWS Secrets Manager

• Environment variables
  

Azure Key Vault

Secret Rotation

Secrets should not live forever.

Implement regular rotation policies for:

• API keys

• Database credentials

• Certificates

• Service accounts
  

Automated rotation reduces risk significantly.

Securing Message-Based Systems

Many ASP.NET Core applications use:

• Azure Service Bus

• RabbitMQ

• Kafka

Security must extend to messaging systems.

Consider:

• Authentication

• Authorization

• Encryption

• Auditing

Message queues should never be treated as trusted by default.

This connects directly with our earlier article on Azure Service Bus.

Encrypt Data in Transit

All service communication should use TLS.

Without encryption:

• Credentials can be intercepted

• Data can be modified

• Sensitive information becomes exposed

HTTPS should be mandatory for every service endpoint.

Encrypt Sensitive Data at Rest

Data stored in:

• Databases

• Message queues

• Object storage

Should be encrypted.

This limits exposure if storage systems become compromised.

Logging Security Events

Security incidents rarely announce themselves.

Logs should capture:

• Authentication failures

• Authorization failures

• Suspicious activity

• Policy violations
  

These events become critical during investigations.

Distributed Security Monitoring

As discussed in our article on OpenTelemetry and distributed tracing:

https://www.asptoday.com/p/distributed-tracing-opentelemetry-aspnet-core

Observability plays a major role in security.

Tracing can reveal:

• Unexpected service calls

• Unauthorized access attempts

• Abnormal traffic patterns
  

Security and observability increasingly overlap.

The Principle of Least Privilege

Least privilege remains one of the most effective security controls.

Avoid:

• Administrator everywhere

• Shared service accounts

• Broad permissions
  

Instead grant only the permissions required for a specific task.

This limits the impact of compromised credentials.

Network Segmentation

Not every service should communicate with every other service.

Segmenting networks reduces attack paths.

Example:

Public APIs
     ↓
Business Services
     ↓
Database Layer

Restricted communication paths improve security.

Common Security Mistakes

Several mistakes appear repeatedly in microservices environments.

Blind Trust Between Services

Just because a request originates internally does not mean it is safe.

Shared Credentials

Shared service accounts make auditing and access control difficult.

Excessive Permissions

Services often receive more access than they need.

Missing Input Validation

Never trust incoming data.

Validate everything.

Hardcoded Secrets

Secrets should never be stored in source code.

Real-World Example: E-Commerce Platform

Imagine an online store.

Components include:

• API Gateway

• Orders Service

• Inventory Service

• Payments Service

• Notification Service

Zero Trust implementation would require:

• JWT authentication

• Service-to-service identity

• Authorization policies

• TLS encryption

• Secret management

• Distributed monitoring

Each interaction must prove legitimacy.

No component receives automatic trust.

Security and Resilience Work Together

This article connects closely with several recent topics:

• Fault-Tolerant Systems

• Advanced Retry Strategies

• Chaos Engineering

• Distributed Tracing

A resilient system that is insecure remains vulnerable.

A secure system that cannot survive failures remains unreliable.

Modern architecture requires both.

Preparing for Compliance Requirements

Many organizations must satisfy regulations such as:

• GDPR

• HIPAA

• PCI DSS

• SOC 2

Zero Trust principles help support compliance efforts by enforcing stronger access controls and auditability.

How This Fits Your ASP.NET Core Journey

So far, we’ve explored:

• Distributed messaging

• Sagas

• Retry strategies

• Fault tolerance

• Observability

• Chaos engineering

Security is the next critical layer.

Once systems become distributed, visibility alone is not enough.

Every service must verify identities, enforce permissions, and protect sensitive data continuously.

Closing Thoughts

Microservices create tremendous flexibility and scalability.

They also introduce significant security challenges.

Zero Trust Architecture provides a practical framework for addressing those challenges by eliminating assumptions of trust and requiring continuous verification.

By combining:

• Authentication

• Authorization

• Least privilege

• Service identity

• Encryption

• Monitoring

You can build ASP.NET Core microservices that remain secure even as systems grow increasingly distributed and complex.

In modern architecture, trust is not granted.

Trust is earned continuously.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture guides, security strategies, and real-world engineering practices. Join the Substack Chat and connect with developers building secure and resilient cloud-native applications.

Subscribe now

In this guide, we’ll explore chaos engineering in ASP.NET Core, how it works, when to use it, and how to safely test failure scenarios that improve reliability and resilience.

Why Testing Success Is Not Enough

Most application testing focuses on successful outcomes.

We verify that:

• APIs return expected responses

• Database operations complete successfully

• Authentication works correctly

• Business workflows function as expected

These tests are important.

But production environments rarely behave perfectly.

Real systems experience:

• Network interruptions

• Database outages

• Message queue failures

• Cloud service disruptions

• Slow dependencies

• Infrastructure failures

The challenge is that many of these situations are difficult to reproduce during normal testing.

Chaos engineering helps solve this problem.

What Is Chaos Engineering?

Chaos engineering is the practice of intentionally introducing failures into a system to observe how it responds.

The goal is not destruction.

The goal is learning.

By safely creating controlled failures, teams can identify weaknesses before customers experience them.

The concept was popularized by Netflix, which developed Chaos Monkey to randomly terminate production instances and verify that services remained available.

Official Chaos Monkey project:

Why Chaos Engineering Matters

Imagine your application depends on:

• A SQL database

• Redis cache

• Payment provider

• Email service

• Azure Service Bus

Everything works perfectly during development.

Then one day:

• Redis becomes unavailable

• Payment API starts timing out

• Network latency increases dramatically

What happens?

Many teams discover the answer only after customers start reporting issues.

Chaos engineering helps uncover these weaknesses before they become incidents.

Chaos Engineering Is Not Random Destruction

A common misconception is that chaos engineering means breaking things randomly.

Effective chaos engineering is controlled and scientific.

Every experiment begins with a hypothesis.

For example:

If Redis becomes unavailable, product pages should still load using database fallbacks.

Then you test the hypothesis.

If reality differs from expectations, you’ve found an improvement opportunity.

The Scientific Method for Reliability

Chaos engineering follows a structured process:

1. Define steady-state behavior

2. Create a hypothesis

3. Introduce controlled failure

4. Observe results

5. Improve the system

This makes chaos engineering an engineering discipline rather than a guessing exercise.

Understanding Steady State

Before introducing failures, you need to understand normal behavior.

Examples include:

• Average response times

• Error rates

• Throughput

• Queue depth

• Resource utilization

Without a baseline, it’s impossible to evaluate the impact of failure scenarios.

This is one reason observability is so important.

As discussed in our previous article on distributed tracing, visibility is critical when investigating system behavior.

Chaos Engineering and Distributed Tracing

Distributed tracing and chaos engineering work exceptionally well together.

Tracing helps answer:

• Which services were affected?

• Where did failures originate?

• How far did failures spread?

• Which dependencies became bottlenecks?

Using OpenTelemetry, engineers can visualize the impact of chaos experiments across an entire distributed system.

Common Failure Scenarios

Chaos engineering experiments often focus on realistic production failures.

Examples include:

• Service outages

• Network latency

• Packet loss

• Dependency failures

• Database connection exhaustion

• High CPU usage

• Memory pressure

• Message queue delays

These are failures that eventually happen in real systems.

The question is whether your application handles them gracefully.

Simulating API Failures

Suppose your application calls a payment provider.

Normally:

var response = await _paymentClient.ProcessAsync(payment);

What happens if:

• The API returns HTTP 500?

• Requests timeout?

• The service becomes unavailable?
  

Chaos testing allows you to simulate these scenarios safely.

Testing Timeouts

Timeouts are one of the most common production issues.

A dependency may not fail completely.

Instead, it becomes extremely slow.

Example:

await Task.Delay(TimeSpan.FromSeconds(30));

How does your application react?

Do users receive helpful feedback?

Or does everything become stuck waiting indefinitely?

Validating Retry Policies

Our previous article explored:

• Exponential backoff

• Jitter

• Idempotency
  

Chaos engineering helps verify those patterns actually work.

For example:

• Simulate API failures

• Observe retries

• Verify recovery
  

Many teams discover retry configurations are too aggressive or too conservative.

Testing reveals these weaknesses.

Circuit Breakers Under Stress

Circuit breakers are designed to prevent failing dependencies from overwhelming a system.

Example using Polly:

var circuitBreaker = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(
        5,
        TimeSpan.FromSeconds(30));

Chaos testing verifies:

• Does the breaker open correctly?

• Does traffic stop flowing?

• Does recovery happen automatically?
  

Without testing, assumptions remain unverified.

Database Failure Experiments

Databases are among the most critical dependencies.

Experiments may include:

• Connection failures

• High latency

• Deadlocks

• Resource exhaustion
  

Questions to ask:

• Does the application fail gracefully?

• Are users informed properly?

• Do background processes recover?
  

These are valuable insights before production incidents occur.

Testing Distributed Caching Failures

Many ASP.NET Core systems rely on Redis.

What happens if Redis becomes unavailable?

A well-designed system should:

• Continue operating

• Fall back to database queries

• Maintain acceptable performance
  

Chaos experiments validate these assumptions.

Message Queue Failures

Applications using Azure Service Bus or RabbitMQ should test scenarios such as:

• Delayed message delivery

• Queue unavailability

• Poison messages

• High backlog conditions
  

Questions include:

• Are messages retried correctly?

• Are dead-letter queues used properly?

• Does the system recover automatically?

Chaos Engineering and Saga Patterns

Sagas coordinate distributed transactions.

Failures can occur during:

• Inventory reservation

• Payment processing

• Shipment creation
  

Chaos testing helps verify:

• Compensation actions execute correctly

• Eventual consistency is maintained

• Workflows recover safely
  

This is especially valuable in complex business processes.

Infrastructure-Level Experiments

Not all chaos experiments target application code.

Infrastructure testing can include:

• Container restarts

• VM shutdowns

• Kubernetes pod failures

• DNS issues

• Network partitions
  

Modern cloud-native systems should tolerate these conditions.

Latency Injection

Sometimes dependencies do not fail.

They simply become slow.

Latency injection simulates this behavior.

Example:

app.Use(async (context, next) =>
{
    await Task.Delay(2000);
    await next();
});

This helps reveal:

• Timeout issues

• User experience problems

• Resource bottlenecks

Fault Injection Middleware

ASP.NET Core makes it easy to inject failures.

Example:

app.Use(async (context, next) =>
{
    if (Random.Shared.Next(100) < 10)
    {
        context.Response.StatusCode = 500;
        return;
    }

    await next();
});

This introduces controlled failures into requests.

Such experiments should only be used in non-production environments unless carefully managed.

Monitoring During Chaos Experiments

Observability is essential.

Monitor:

• Error rates

• Response times

• Queue depth

• Memory consumption

• CPU utilization

• Retry activity
  

Without visibility, chaos experiments provide little value.

Defining Blast Radius

One of the most important concepts in chaos engineering is blast radius.

Blast radius refers to the scope of impact.

Start small.

Instead of testing the entire platform:

• Test one service

• Test one dependency

• Test one workflow

Expand gradually as confidence increases.

Running Experiments Safely

Every chaos experiment should include:

• Clear objectives

• Success criteria

• Monitoring

• Rollback plans

Safety must always come first.

The goal is learning, not causing outages.

Common Mistakes

One mistake is introducing failures without clear hypotheses.

Another is performing experiments without sufficient observability.

Also avoid:

• Testing too much at once

• Running experiments without rollback procedures

• Ignoring lessons learned
  

The experiment is only valuable if it produces actionable insights.

Real-World Example: E-Commerce Platform

Imagine an online store.

Chaos experiments might simulate:

• Redis outage

• Payment provider latency

• Inventory service failure

Expected behavior:

• Cached data falls back to database

• Payments retry automatically

• Inventory failures trigger compensating actions
  

If the platform remains operational, confidence increases significantly.

The Relationship Between Chaos and Reliability

Chaos engineering is not about proving systems are perfect.

It is about discovering where they are fragile.

Every weakness uncovered is an opportunity to improve resilience.

Over time, systems become stronger because failures are explored proactively rather than reactively.

When NOT to Use Chaos Engineering

Small internal applications may not need extensive chaos testing.

Likewise, teams lacking:

• Monitoring

• Alerting

• Operational maturity
  

Should establish those foundations first.

Chaos engineering works best when observability already exists.

How This Fits Your ASP.NET Core Journey

So far, we’ve explored:

• Distributed messaging

• Saga patterns

• Retry strategies

• Fault-tolerant systems

• OpenTelemetry and distributed tracing
  

Chaos engineering brings these concepts together.

It validates whether resilience patterns actually work under realistic failure conditions.

This is where architecture moves from theory into real-world operational confidence.

Closing Thoughts

Failures are inevitable.

The most resilient systems are not those that avoid failure entirely.

They are the systems that have already practiced failure.

Chaos engineering provides a structured way to uncover weaknesses, validate assumptions, and strengthen ASP.NET Core applications before production incidents occur.

By combining:

• Observability

  Distributed tracing

• Retries

• Circuit breakers

• Sagas

• Fault injection
  

Teams can build systems that remain reliable even when the unexpected happens.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture guides, resilience strategies, and real-world engineering practices. Join the Substack Chat and connect with developers building modern cloud-native applications.

Subscribe now

In this guide, you’ll learn how distributed tracing works, why OpenTelemetry has become the industry standard, and how to implement practical tracing solutions in ASP.NET Core applications.

Why Traditional Logging Is No Longer Enough

Years ago, many applications were relatively simple.

A user made a request.

The request hit a web server.

The application queried a database.

A response was returned.

If something went wrong, logs were usually enough.

Modern systems are very different.

A single request may now travel through:

• API Gateway

• ASP.NET Core Web API

• Authentication Service

• Product Service

• Redis Cache

• SQL Database

• Message Queue

• Background Worker

Each component may have its own logs.

When failures occur, finding the root cause becomes difficult.

This is where distributed tracing becomes essential.

What Is Distributed Tracing?

Distributed tracing allows developers to follow a request as it moves through multiple systems.

Think of it as attaching a GPS tracker to every request.

Instead of viewing isolated logs, you can see:

• Where the request started

• Which services it visited

• How long each step took

• Where failures occurred

• Which dependencies caused delays

Distributed tracing provides a complete picture of request execution.

Understanding Traces, Spans, and Context

Distributed tracing revolves around three key concepts.

Trace

A trace represents the complete journey of a request.

For example:

User Request
 ├─ API Gateway
 ├─ Product Service
 ├─ SQL Database
 ├─ Redis Cache
 └─ Response

Everything belongs to a single trace.

Span

A span represents an individual operation.

Examples include:

• Calling a database

• Querying Redis

• Sending a message

• Invoking another API

Each trace contains multiple spans.

Context

Context links spans together.

Without context propagation, traces break apart and become useless.

OpenTelemetry automatically handles much of this process.

Why OpenTelemetry Has Become the Standard

Before OpenTelemetry, observability tools often used proprietary approaches.

Organizations frequently became locked into specific vendors.

OpenTelemetry was created to solve this problem.

It provides:

• Vendor-neutral instrumentation

• Standardized telemetry collection

• Cross-platform support

• Broad ecosystem integration

OpenTelemetry is now supported by major platforms including:

• Microsoft Azure

• AWS

• Google Cloud

• Grafana

• Datadog

• New Relic

Official project:

https://opentelemetry.io

Observability vs Monitoring

These terms are often confused.

Monitoring focuses on answering known questions.

Examples:

• Is the service running?

• How many requests failed?

• Is CPU usage high?

Observability helps answer unknown questions.

Examples:

• Why is checkout suddenly slow?

• Which dependency caused latency spikes?

• Which service introduced failures?

Distributed tracing is a core pillar of observability.

The Three Pillars of Observability

Modern observability typically includes:

• Logs

• Metrics

• Traces
  

Logs explain what happened.

Metrics show how often something happens.

Traces reveal where it happened.

Together they provide a complete operational picture.

Why Tracing Matters in ASP.NET Core

Consider an e-commerce application.

A customer clicks “Place Order.”

The request triggers:

1. Authentication

2. Inventory validation

3. Payment processing

4. Shipping creation

5. Notification service
   

A failure occurs.

Which step caused the issue?

Without tracing:

• Search logs manually

• Correlate timestamps

• Guess relationships
  

With tracing:

• View the entire workflow instantly
  

This becomes especially valuable in architectures we’ve discussed previously:

• ASP.NET Core and Azure Service Bus

• Saga Patterns

• Fault-Tolerant Systems

• Advanced Retry Strategies

Distributed tracing ties these systems together.

Installing OpenTelemetry

Start by adding required packages.

dotnet add package OpenTelemetry.Extensions.Hosting

dotnet add package OpenTelemetry.Instrumentation.AspNetCore

dotnet add package OpenTelemetry.Instrumentation.Http

dotnet add package OpenTelemetry.Instrumentation.SqlClient

These packages provide automatic instrumentation.

Configuring OpenTelemetry

In Program.cs:

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddSqlClientInstrumentation();
    });

This immediately starts collecting trace information.

Automatic Instrumentation

One of OpenTelemetry’s greatest strengths is automatic instrumentation.

Without changing business logic, you can collect traces from:

• Incoming HTTP requests

• Outgoing HTTP calls

• SQL queries

• Entity Framework operations

• gRPC services
  

This dramatically reduces implementation effort.

Viewing Traces Locally

During development, traces can be exported to the console.

builder.Services.AddOpenTelemetry()
    .WithTracing(builder =>
    {
        builder
            .AddAspNetCoreInstrumentation()
            .AddConsoleExporter();
    });

This helps developers understand how traces are structured.

Understanding Trace Hierarchies

Imagine this workflow:

Order Request
 ├─ Validate User
 ├─ Check Inventory
 │   ├─ Redis Cache
 │   └─ SQL Query
 ├─ Process Payment
 └─ Send Confirmation

Each operation becomes a span.

The complete tree becomes a trace.

This hierarchy makes bottlenecks easy to identify.

Adding Custom Spans

Automatic instrumentation is powerful.

But custom spans provide additional business insight.

Example:

private static readonly ActivitySource ActivitySource =
    new("OrderService");

public async Task ProcessOrderAsync()
{
    using var activity =
        ActivitySource.StartActivity("ProcessOrder");

    await Task.Delay(100);
}

This creates a custom span visible in trace visualizations.

Capturing Business Operations

Not everything revolves around technical dependencies.

Sometimes you want visibility into business workflows.

Examples:

• Calculate Discount

  Validate Coupon

• Generate Invoice

• Process Refund
  

Custom spans allow these operations to appear in traces.

Context Propagation

Tracing only works if context moves between services.

Consider:

API A
 ↓
API B
 ↓
API C

If trace context is lost between services:

• Visibility breaks

• Relationships disappear
  

OpenTelemetry automatically propagates context through standard HTTP headers.

This allows traces to remain connected.

Tracing HTTP Requests

Outgoing HTTP requests are automatically captured.

Example:

var response =
    await _httpClient.GetAsync("/products");

OpenTelemetry records:

• URL

• Duration

• Status code

• Parent trace

This creates a complete dependency map.

Tracing Database Calls

Database performance often becomes a bottleneck.

OpenTelemetry automatically traces:

await _dbContext.Products
    .Where(p => p.IsActive)
    .ToListAsync();

Useful information includes:

• Query duration

• Database dependency

• Success or failure

This greatly simplifies performance investigations.

Tracing Message-Based Architectures

Many modern ASP.NET Core systems rely on messaging.

Examples include:

• Azure Service Bus

• RabbitMQ

• Kafka

Distributed tracing becomes even more important because workflows become asynchronous.

Tracing helps developers understand:

• Message publication

• Message consumption

• Processing delays

• Queue bottlenecks
  

OpenTelemetry and ASP.NET Core APIs

Minimal APIs work seamlessly.

app.MapGet("/products", async () =>
{
    return Results.Ok();
});

Each request automatically generates trace information.

No additional code required.

Sampling Strategies

Not every trace needs to be collected.

High-volume systems can generate millions of traces daily.

Sampling helps control costs.

Common approaches:

• Always sample

• Never sample

• Percentage-based sampling

• Adaptive sampling
  

Example:

.SetSampler(new TraceIdRatioBasedSampler(0.1))

This collects approximately 10% of traces.

Exporting Trace Data

OpenTelemetry separates collection from storage.

Popular destinations include:

• Azure Monitor

• Jaeger

• Zipkin

• Grafana Tempo

• Datadog
  

This flexibility prevents vendor lock-in.

Visualizing Traces with Jaeger

Jaeger is one of the most popular tracing platforms.

Official website

It provides:

• Trace timelines

• Dependency graphs

• Span details

• Performance analysis
  

Developers can visually inspect entire request journeys.

Diagnosing Performance Problems

Suppose a page suddenly becomes slow.

Tracing reveals:

Request Duration: 3.8s

Authentication: 40ms
Product Service: 120ms
Redis Cache: 5ms
SQL Query: 3.4s

The bottleneck becomes obvious immediately.

Without tracing, finding this issue could take hours.

Tracing and Distributed Caching

Distributed caching often improves performance dramatically.

But cache misses can still cause problems.

Tracing helps identify:

• Cache hit rates

• Cache miss paths

• Database fallbacks
  

This pairs naturally with distributed caching architectures.

Tracing Fault-Tolerant Systems

In our previous article on fault tolerance, we discussed:

• Retries

• Circuit breakers

• Bulkheads

• Graceful degradation

Tracing makes these patterns visible.

You can observe:

• Retry attempts

• Circuit breaker activations

• Fallback executions
  

This turns resilience from theory into measurable behavior.

Tracing Saga Workflows

Saga patterns coordinate long-running distributed transactions.

Tracing allows developers to follow:

• Order creation

• Inventory reservation

• Payment processing

• Shipment generation
  

Across multiple services.

This provides enormous operational value.

Security Considerations

Be careful with trace data.

Avoid recording:

• Passwords

• Credit card numbers

• Personal information

• Authentication tokens
  

Telemetry should support troubleshooting without exposing sensitive data.

Microsoft guidance:

Common Mistakes

A frequent mistake is collecting traces without using them.

Another is tracing everything indiscriminately.

This creates:

• Storage costs

• Noise

• Analysis difficulties

Focus on meaningful visibility.

When Distributed Tracing Is Most Valuable

Distributed tracing provides the greatest value when systems include:

• Multiple services

• External APIs

• Message queues

• Background processing

• Cloud infrastructure
  

Simple applications may not require extensive tracing.

Complex systems almost always benefit.

Real-World Example

Imagine a food delivery platform.

A customer places an order.

The workflow touches:

• User Service

• Restaurant Service

• Payment Service

• Delivery Service

• Notification Service
  

A trace shows every step.

If delays occur, engineers can pinpoint the exact dependency causing problems.

This is the power of distributed tracing.

How This Fits Your ASP.NET Core Journey

So far, we’ve explored:

• Azure Service Bus

• Saga Patterns

• Distributed Caching

• Retry Strategies

• Fault-Tolerant Systems
  

Distributed tracing now provides the visibility layer that ties all these architectural patterns together.

Building distributed systems is only half the challenge.

Understanding them in production is the other half.

Closing Thoughts

Modern ASP.NET Core systems are increasingly distributed.

As complexity grows, traditional logging alone becomes insufficient.

OpenTelemetry provides a standardized, vendor-neutral approach to distributed tracing that helps developers understand exactly how requests move through their systems.

By implementing tracing early, teams gain:

• Faster troubleshooting

• Better performance visibility

• Improved reliability

• Stronger operational insight
  

As your applications scale, distributed tracing becomes less of a luxury and more of a necessity.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture guides, observability strategies, and real-world engineering patterns. Join the Substack Chat and connect with developers building modern cloud-native applications.

Subscribe now

In this guide, we’ll explore the key patterns, architectural decisions, and trade-offs involved in building resilient fault-tolerant systems with ASP.NET Core.

Why Fault Tolerance Matters

In small applications, failures are often manageable.

A user refreshes the page.
An administrator restarts the service.
The problem disappears.

But modern systems are different.

Applications now operate across:

• Multiple APIs

• Distributed databases

• Cloud services

• Message brokers

• External providers

• Containerized infrastructure

This means failures become inevitable.

At scale, the question changes from:

“Will failures happen?”

To:

“How will the system behave when they do?”

That shift is the foundation of fault-tolerant design.

What Is a Fault-Tolerant System?

A fault-tolerant system continues functioning even when parts of the system fail.

This does not mean:

• zero downtime

• perfect operation

• infinite reliability

Instead, fault-tolerant systems:

• degrade gracefully

• recover automatically

• isolate failures

• minimize user impact

The user experience remains stable even during internal problems.

Understanding Failure in Distributed Systems

Failures in distributed systems are normal.

Examples include:

• network interruptions

• slow APIs

• overloaded databases

• dropped messages

• DNS failures

• container crashes

• cloud outages

This connects directly with concepts from:

• Advanced Retry Strategies in ASP.NET Core

• Implementing Saga Patterns in ASP.NET Core

• ASP.NET Core and Azure Service Bus

Distributed systems must expect these conditions continuously.

Designing for Failure from the Beginning

One of the biggest mistakes developers make is treating resilience as something added later.

Fault tolerance must influence:

• architecture

• communication patterns

• deployment strategy

• state management

• monitoring

Systems designed for failure behave very differently from systems that merely react to failure.

The Fallacies of Distributed Computing

Many reliability problems come from false assumptions.

Developers often assume:

• networks are reliable

• latency is zero

• bandwidth is infinite

• services are always available

These assumptions break quickly in production environments.

Recognizing this reality is the first step toward resilient architecture.

Fault Tolerance vs High Availability

These terms are related but different.

High Availability

Focuses on:

• minimizing downtime

• ensuring services remain accessible

Fault Tolerance

Focuses on:

• surviving failures gracefully

• maintaining functionality during problems

You can have high availability without strong fault tolerance.

And vice versa.

Core Principles of Fault-Tolerant Design

Fault-tolerant systems typically rely on several key principles:

• redundancy

• isolation

• retries

• graceful degradation

• observability

• recovery automation

Each introduces trade-offs.

Retries as a Foundation

Retries are one of the simplest resilience patterns.

Transient failures often resolve automatically.

Retrying can recover from:

• temporary network issues

• overloaded services

• cloud throttling

This was covered deeply in Advanced Retry Strategies in ASP.NET Core

But retries alone are not enough.

The Danger of Aggressive Retries

Poorly designed retries can amplify failures.

If thousands of services retry simultaneously:

• traffic spikes

• failing systems collapse further

• cascading outages occur

This is why:

• exponential backoff

• jitter

• retry limits

Are essential in production systems.

Circuit Breaker Pattern

Circuit breakers prevent repeated calls to failing dependencies.

Without circuit breakers:

• services continuously hammer failing systems

With circuit breakers:

• failing dependencies are temporarily isolated

This allows recovery.

Implementing Circuit Breakers with Polly

var circuitBreakerPolicy = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(
        5,
        TimeSpan.FromSeconds(30));

After repeated failures:

• the circuit opens

• requests stop temporarily
  

Official Polly documentation.

Bulkhead Isolation Pattern

Bulkheads isolate failures between components.

The term comes from ships:

• compartments prevent flooding from sinking the entire vessel
  

In software:

• resource pools become isolated
  

Example:

• one failing service cannot exhaust all threads or database connections
  

Example Bulkhead Policy

var bulkheadPolicy = Policy.BulkheadAsync(
    maxParallelization: 10,
    maxQueuingActions: 20);

This limits concurrent resource usage.

Graceful Degradation

Fault-tolerant systems do not always fail completely.

Sometimes reduced functionality is acceptable.

Example:

• recommendation engine unavailable

• checkout still works
  

Users may lose non-critical features while core operations remain operational.

This dramatically improves perceived reliability.

Real-World Example: Streaming Platforms

Streaming services often degrade gracefully.

If recommendation systems fail:

• videos still stream
  

If subtitles fail:

• playback continues
  

This separation prevents small failures from becoming catastrophic outages.

Timeouts Prevent Resource Exhaustion

One dangerous issue in distributed systems is waiting forever.

Without timeouts:

• threads become blocked

• connections accumulate

• cascading failures spread
  

Timeouts protect system resources.

Example Timeout Policy

var timeoutPolicy = Policy.TimeoutAsync(
    TimeSpan.FromSeconds(5));

After 5 seconds:

• operation cancels automatically
  

Combining Resilience Policies

Modern systems usually combine:

• retries

• timeouts

• circuit breakers

• bulkheads
  

Example:

var policyWrap = Policy.WrapAsync(
    retryPolicy,
    circuitBreakerPolicy,
    timeoutPolicy);

This creates layered resilience behavior.

Idempotency and Safe Recovery

Retries introduce duplication risks.

A request may succeed internally while the client never receives the response.

If retried blindly:

• duplicate payments

• duplicate orders

• repeated operations
  

May occur.

This is why idempotency matters.

Designing Idempotent APIs

Clients send unique request identifiers:

Idempotency-Key: xyz789

Server stores processed keys.

Repeated requests:

• return existing results

• avoid duplicate processing
  

This pattern becomes essential in fault-tolerant workflows.

Event-Driven Resilience

Message queues improve fault tolerance significantly.

Instead of synchronous dependencies:

• messages become buffered

• services process asynchronously
  

This reduces direct coupling between systems.

Queue-Based Recovery

If a service becomes unavailable:

• messages remain queued

• processing resumes later
  

This prevents immediate system-wide failures.

Fault Tolerance and Saga Patterns

Distributed transactions create additional reliability challenges.

Saga patterns solve this through:

• compensating actions

• eventual consistency

• recovery workflows
  

This was explored in Implementing Saga Patterns in ASP.NET Core.

Fault-tolerant systems often rely heavily on Saga coordination.

Redundancy Improves Reliability

Redundancy means having backup resources.

Examples:

• multiple application instances

• replicated databases

• failover regions

• backup message brokers
  

Redundancy improves availability but increases:

• cost

• synchronization complexity

• operational overhead
  

Horizontal Scaling and Resilience

Fault-tolerant systems avoid single points of failure.

Horizontal scaling helps distribute load across:

• containers

• servers

• cloud instances
  

If one instance fails:

• others continue operating
  

This improves survivability dramatically.

Health Checks in ASP.NET Core

ASP.NET Core includes built-in health checks.

builder.Services.AddHealthChecks();

Expose endpoint:

app.MapHealthChecks("/health");

These help orchestrators:

• detect unhealthy services

• restart failed instances

• reroute traffic automatically
  

Official documentation

Observability Is Critical

Fault tolerance without observability is dangerous.

You must monitor:

• failures

• latency

• retries

• queue depth

• circuit breaker activity

• resource exhaustion
  

Otherwise:

• problems remain invisible
  

Logging and Distributed Tracing

Modern systems require:

• centralized logging

• correlation IDs

• distributed tracing
  

These tools help trace failures across services.

Platforms commonly used:

• OpenTelemetry

• Application Insights

• Seq

• Grafana

• Prometheus
  

Cascading Failures

One failing dependency can trigger widespread outages.

Example:

• database slows down

• API threads become blocked

• retries increase traffic

• queue processing stalls

• system collapses
  

Fault-tolerant systems isolate failures early.

Backpressure and Load Shedding

Sometimes systems must reject traffic intentionally.

This sounds counterintuitive, but controlled rejection is often safer than overload collapse.

Techniques include:

• rate limiting

• queue limits

• request throttling

ASP.NET Core supports built-in rate limiting

CAP Theorem Trade-Offs

Distributed systems cannot simultaneously guarantee:

• consistency

• availability

• partition tolerance
  

Trade-offs become necessary.

Fault-tolerant systems often prioritize:

• availability

• partition tolerance
  

While accepting eventual consistency.

Trade-Offs of Fault-Tolerant Design

Resilience introduces complexity.

More resilience means:

• more infrastructure

• more monitoring

• more operational overhead

• more architecture decisions
  

Simple systems are easier to understand.

Highly fault-tolerant systems are harder to build and maintain.

When Simplicity Is Better

Not every application requires advanced fault tolerance.

Internal tools with low traffic may not need:

• distributed queues

• regional failover

• complex resilience policies
  

Overengineering creates unnecessary operational burden.

Architecture should match business requirements.

Real-World Example: E-Commerce Checkout

Consider checkout processing.

A fault-tolerant flow might:

• queue orders asynchronously

• retry payment calls

• use idempotency keys

• coordinate inventory via Sagas

• isolate recommendation systems
  

Even during failures:

• customers still complete purchases
  

This is resilience in practice.

Fault Injection and Chaos Testing

Resilient systems should be tested under failure conditions.

Chaos engineering introduces:

• random outages

• latency spikes

• dependency failures
  

This validates recovery behavior before production incidents occur.

Netflix popularized this approach through Chaos Monkey.

The Human Side of Reliability

Fault tolerance is not only technical.

Teams also need:

• incident response plans

• operational runbooks

• monitoring alerts

• rollback procedures
  

Human processes are part of resilience engineering too.

Reliability Is an Ongoing Process

Fault tolerance is never “finished.”

As systems evolve:

• traffic grows

• dependencies change

• new failure modes emerge
  

Resilience requires continuous refinement.

How This Fits Your ASP.NET Core Journey

So far, you’ve explored:

• distributed messaging

• retries

• Sagas

• modular architecture

• distributed caching

• API evolution
  

This blog now ties those concepts together into a broader resilience strategy.

This is where architecture becomes production-grade engineering.

Final Thoughts

Failures are unavoidable in distributed systems.

The goal is not creating systems that never fail.

The goal is creating systems that:

• recover gracefully

• isolate failures

• maintain critical functionality

• minimize user impact
  

By combining:

• retries

• circuit breakers

• timeouts

• bulkheads

• graceful degradation

• observability
  

You can build ASP.NET Core systems that remain stable even under difficult real-world conditions.

True reliability comes from designing with failure in mind from the very beginning.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core architecture guides, distributed systems strategies, and real-world resilience engineering insights. Join the Substack Chat and connect with developers building reliable modern systems.

Subscribe now

In this guide, we’ll explore advanced retry strategies in ASP.NET Core using exponential backoff, jitter, and idempotent design to build systems that remain reliable under real-world conditions.

Why Retries Matter in Modern Applications

In simple applications running on one machine, failures are often straightforward.

A request succeeds or fails.

But modern ASP.NET Core applications are different.

They communicate with:

• External APIs

• Payment providers

• Message brokers

• Distributed databases

• Cloud services

• Microservices

And every network call introduces uncertainty.

Sometimes failures are temporary:

• A service is overloaded

• A network packet is lost

• A database connection pool is exhausted

• A container restarts

Retrying the operation a few moments later may succeed perfectly.

This is why retry strategies are critical in resilient architecture.

Understanding Transient Failures

Not all failures are permanent.

A transient failure is temporary and often resolves itself automatically.

Examples include:

• HTTP 503 Service Unavailable

• Network timeout

• Temporary DNS resolution issues

• Cloud throttling

• Deadlocks in databases

These failures are ideal candidates for retries.

Permanent Failures Should Not Be Retried

Retries are not always appropriate.

Some failures are permanent:

• Invalid credentials

• Bad requests

• Validation failures

• Missing resources

Retrying these repeatedly only wastes resources.

Good retry systems distinguish between:

• Transient failures

• Permanent failures

This is one reason resilience engineering requires careful design.

The Simplest Retry Strategy

The most basic retry logic looks like this:

for (int i = 0; i < 3; i++)
{
    try
    {
        await CallApiAsync();
        break;
    }
    catch
    {
        await Task.Delay(1000);
    }
}

This works, but it has serious problems.

Why Simple Retries Become Dangerous

Imagine thousands of clients retrying simultaneously.

If a service becomes overloaded:

• Every client retries immediately

• Traffic spikes even more

• The failing service collapses further
  

This creates a retry storm.

Instead of helping recovery, retries make things worse.

Introducing Exponential Backoff

Exponential backoff solves this problem.

Instead of retrying at a fixed interval, delays increase gradually.

Example:

• Retry 1 → wait 1 second
  

• Retry 2 → wait 2 seconds
  

• Retry 3 → wait 4 seconds
  

• Retry 4 → wait 8 seconds
  

This gives struggling systems time to recover.

Why Exponential Backoff Works

Exponential backoff:

• Reduces pressure on failing systems

• Spreads retry attempts over time

• Prevents traffic spikes

• Improves overall stability
  

Cloud providers strongly recommend this strategy.

Microsoft guidance

Implementing Exponential Backoff in ASP.NET Core

The most common solution is Polly.

Official site

Install:

dotnet add package Polly

Basic Polly Retry Policy

var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(3, retryAttempt =>
        TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

This creates:

• 2s delay

• 4s delay

• 8s delay
  

Using Polly with HttpClientFactory

ASP.NET Core integrates beautifully with Polly.

builder.Services.AddHttpClient("ApiClient")
    .AddPolicyHandler(retryPolicy);

This automatically applies retry behavior to outgoing HTTP requests.

The Problem with Predictable Retries

Even exponential backoff has a hidden issue.

If thousands of clients fail at the same moment:

• They all retry at identical intervals
  

Example:

• Everyone retries at 2 seconds

• Then everyone retries at 4 seconds
  

This creates synchronized retry waves.

Enter Jitter

Jitter introduces randomness into retry delays.

Instead of:

• Exactly 2 seconds
  

Clients wait:

• 1.7 seconds

• 2.4 seconds

• 2.1 seconds
  

This spreads traffic naturally.

Why Jitter Is Important

Jitter:

• Prevents synchronized retry spikes

• Smooths traffic patterns

• Reduces cascading failures

• Improves system recovery
  

In large distributed systems, jitter becomes extremely important.

Implementing Jitter with Polly

var random = new Random();

var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(5, retryAttempt =>
    {
        var exponentialDelay = Math.Pow(2, retryAttempt);

        var jitter = random.NextDouble();

        return TimeSpan.FromSeconds(exponentialDelay + jitter);
    });

Now retries become staggered naturally.

Retry Strategies and Distributed Systems

Retries are foundational in distributed systems.

They connect directly to:

• Service communication

• Messaging reliability

• Distributed transactions
  

This builds naturally on concepts from:

• Implementing Saga Patterns in ASP.NET Core

• ASP.NET Core and Azure Service Bus

• Building Modular Monoliths in ASP.NET Core
  

Distributed systems assume failure will happen.

Retries help systems recover gracefully.

Understanding Idempotency

Retries introduce another major challenge.

What happens if the first request actually succeeded, but the response was lost?

The client retries.

Now the operation executes twice.

This can cause serious issues.

Example:

• Double payments

• Duplicate orders

• Repeated emails
  

This is why idempotency matters.

What Is Idempotency?

An operation is idempotent if:

• Repeating it produces the same result
  

Examples:

• Updating a profile

• Setting a status value
  

Not naturally idempotent:

• Charging a credit card

• Creating a new order
  

Designing Idempotent APIs

One common approach uses idempotency keys.

Client sends:

Idempotency-Key: abc123

Server stores processed keys.

If the same request arrives again:

• Return previous result

• Do not process twice
  

Example Idempotency Middleware

public class IdempotencyMiddleware
{
    private readonly RequestDelegate _next;

    public IdempotencyMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task Invoke(HttpContext context)
    {
        var key = context.Request.Headers["Idempotency-Key"];

        if (string.IsNullOrEmpty(key))
        {
            await _next(context);
            return;
        }

        // Check if request already processed

        await _next(context);
    }
}

This pattern becomes critical in payment systems.

Retry Policies for Different Scenarios

Different systems require different retry behavior.

API Calls

Usually:

• Short retries

• Exponential backoff

• Jitter

Database Operations

Often:

• Fewer retries

• Shorter delays

• Deadlock handling

Messaging Systems

Can tolerate:

• Longer retries

• Queue persistence

• Delayed processing

Retrying Database Transactions

Entity Framework Core supports retry behavior.

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString,
        sqlOptions =>
        {
            sqlOptions.EnableRetryOnFailure();
        }));

This helps recover from transient SQL failures automatically.

Avoid Infinite Retries

Retries must always have limits.

Otherwise:

• Systems become stuck

• Resources get exhausted

• Failure cascades worsen
  

Always define:

• Maximum attempts

• Maximum delay

• Timeout limits

Combining Retries with Circuit Breakers

Retries and circuit breakers often work together.

Retries:

• Handle temporary failures
  

Circuit breakers:

• Stop repeated calls to failing services
  

This prevents overloaded systems from collapsing further.

Example Circuit Breaker

var circuitBreakerPolicy = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(5, TimeSpan.FromSeconds(30));

After repeated failures:

• Requests stop temporarily

• System gets time to recover
  

Retry Storms in Cloud Systems

Large cloud systems are especially vulnerable to retry storms.

Imagine:

• One dependency fails

• Thousands of services retry simultaneously
  

Traffic multiplies instantly.

This is why:

• Backoff

• Jitter

• Circuit breakers

Are essential together.

Real-World Example: Payment Processing

A payment API times out.

Did payment fail?

Or did payment succeed while the response was lost?

Without idempotency:

• Retry may double-charge customers
  

A resilient payment system:

• Uses retries

• Uses idempotency keys

• Stores transaction states carefully

This combination prevents catastrophic duplication.

Observability and Retry Monitoring

Retries should never become invisible.

You must monitor:

• Retry counts

• Failure frequency

• Circuit breaker activity

• Recovery times

Good observability helps identify unhealthy dependencies early.

Logging Retry Attempts

.WaitAndRetryAsync(3,
    retryAttempt => TimeSpan.FromSeconds(2),
    onRetry: (exception, timeSpan, retryCount, context) =>
    {
        logger.LogWarning(
            "Retry {RetryCount} after {Delay}",
            retryCount,
            timeSpan);
    });

This provides operational visibility.

Common Mistakes to Avoid

One major mistake is retrying everything blindly.

Another is retrying too aggressively.

Also avoid:

• Ignoring idempotency

• Infinite retries

• Missing timeout policies

• Combining retries with long-running synchronous operations
  

Retries must be intentional.

When Retries Should NOT Be Used

Retries are inappropriate when:

• Validation fails

• Authentication fails

• Business rules fail

• Data is invalid

These are not transient problems.

Retrying them only wastes resources.

Resilience Is About Accepting Failure

One of the biggest mindset shifts in distributed architecture is realizing:

Failures are normal.

Resilient systems:

• Expect failures

• Prepare for failures

• Recover gracefully from failures
  

This is the foundation of modern cloud-native architecture.

How This Fits Your Architecture Journey

So far, you’ve explored:

• Messaging systems

• Distributed transactions

• Saga coordination

• API evolution

• Modular architectures

Retry strategies now add:

Reliability and fault tolerance

This is where systems stop being merely functional and start becoming production-ready.

Closing Thoughts

Retries seem simple at first.

But in distributed systems, retry behavior directly impacts:

• Stability

• Scalability

• Reliability

• User experience
  

By combining:

• Exponential backoff

• Jitter

• Idempotency

• Circuit breakers
  

You can build ASP.NET Core applications that remain resilient even under failure conditions.

Failures will always happen.

The goal is not eliminating them.

The goal is surviving them gracefully.

Join The Community

Enjoyed this article? Subscribe to ASP Today for practical ASP.NET Core insights, distributed systems patterns, and real-world architecture guidance. Join the Substack Chat and connect with developers building resilient modern systems.

Subscribe now

In this guide, we’ll explore how Saga patterns help ASP.NET Core applications manage distributed transactions safely, reliably, and at scale.

Why Distributed Transactions Become Difficult

In a traditional monolithic application, transactions are usually straightforward.

You wrap operations in a database transaction:

using var transaction = await _dbContext.Database.BeginTransactionAsync();

try
{
    await _dbContext.SaveChangesAsync();

    await transaction.CommitAsync();
}
catch
{
    await transaction.RollbackAsync();
}

Everything succeeds or everything rolls back.

Simple.

But modern systems rarely live inside a single database anymore.

Today’s applications often involve:

• Multiple services

• Independent databases

• Message queues

• External APIs
  

Now imagine this workflow:

1. Create an order

2. Reserve inventory

3. Process payment

4. Send confirmation

What happens if payment fails after inventory was reserved?

You can’t simply roll back everything with one database transaction anymore.

This is where Saga patterns become essential.

What Is a Saga Pattern?

A Saga is a way of managing distributed transactions across multiple services or modules.

Instead of one large transaction:

• Each step completes independently

• If something fails, compensating actions undo previous work
  

Think of it like a chain of small transactions working together.

Understanding the Core Idea

Imagine booking a vacation:

• Reserve flights

• Book hotel

• Rent a car
  

If hotel booking fails:

• Cancel the flight

• Cancel the car reservation

You don’t rewind time. You perform compensating actions.

That’s exactly how a Saga works.

Why Traditional Distributed Transactions Don’t Scale Well

Older distributed transaction systems relied on protocols like Two-Phase Commit (2PC).

While powerful, they introduce:

• Tight coupling

• Performance overhead

• Availability problems

Modern cloud-native systems prefer eventual consistency instead.

This aligns with many of the distributed architecture concepts we’ve explored earlier:

• ASP.NET Core Azure Service Bus

• Designing Data Pipelines in ASP.NET Core

• Building Modular Monoliths in ASP.NET Core

Saga patterns fit naturally into these systems.

Two Types of Saga Patterns

There are two common approaches.

Choreography-Based Sagas

In choreography:

• Services react to events

• No central coordinator exists

Each service listens for events and performs actions independently.

Example Flow

1. Order service publishes OrderCreated

2. Inventory service reserves stock

3. Payment service processes payment

4. Shipping service prepares shipment

Each service reacts automatically.

Benefits

• Loosely coupled

• Easy to extend

• Natural event-driven design
  

Challenges

• Harder to debug

• Workflow becomes distributed

• Complex flows become difficult to track
  

Orchestration-Based Sagas

In orchestration:

• A central coordinator controls the workflow
  

The orchestrator decides:

• What step runs next

• What happens on failure

• Which compensation actions execute
  

Example Flow

Saga Orchestrator
    ↓
Create Order
    ↓
Reserve Inventory
    ↓
Process Payment
    ↓
Ship Product

If payment fails:

Cancel Inventory Reservation
Cancel Order

Which Approach Should You Choose?

Smaller systems often start with choreography.

As workflows grow more complex, orchestration usually becomes easier to manage.

Most enterprise systems eventually lean toward orchestration because visibility and control become important.

Implementing Saga Patterns in ASP.NET Core

Let’s build a simplified orchestration example.

Step 1: Create Saga State

public class OrderSagaState
{
    public Guid OrderId { get; set; }

    public bool InventoryReserved { get; set; }

    public bool PaymentProcessed { get; set; }

    public bool ShipmentCreated { get; set; }
}

The Saga tracks progress across the workflow.

Step 2: Create the Orchestrator

public class OrderSaga
{
    private readonly InventoryService _inventoryService;
    private readonly PaymentService _paymentService;

    public async Task ExecuteAsync(OrderSagaState state)
    {
        try
        {
            await _inventoryService.ReserveAsync(state.OrderId);
            state.InventoryReserved = true;

            await _paymentService.ProcessAsync(state.OrderId);
            state.PaymentProcessed = true;
        }
        catch
        {
            await CompensateAsync(state);
        }
    }
}

Step 3: Compensation Logic

private async Task CompensateAsync(OrderSagaState state)
{
    if (state.PaymentProcessed)
    {
        await _paymentService.RefundAsync(state.OrderId);
    }

    if (state.InventoryReserved)
    {
        await _inventoryService.ReleaseAsync(state.OrderId);
    }
}

Compensation restores consistency.

Using Messaging Systems with Sagas

Most Saga implementations rely heavily on messaging systems.

This is where tools like:

• Azure Service Bus

• RabbitMQ

• MassTransit

become important.

Messaging enables:

• Reliable communication

• Asynchronous workflows

• Loose coupling

Saga Patterns with MassTransit

MassTransit provides strong Saga support for ASP.NET Core.

Official documentation

Install:

dotnet add package MassTransit

Configure MassTransit

builder.Services.AddMassTransit(x =>
{
    x.AddSagaStateMachine<OrderStateMachine, OrderState>();

    x.UsingInMemory((context, cfg) =>
    {
        cfg.ConfigureEndpoints(context);
    });
});

This simplifies orchestration significantly.

Long-Running Transactions

One major advantage of Sagas is handling long-running workflows.

Traditional transactions:

• Hold database locks

• Must complete quickly
  

Sagas:

• Run asynchronously

• Can span minutes or hours

This is critical in real-world distributed systems.

Eventual Consistency

Saga patterns embrace eventual consistency.

Instead of requiring every service to update instantly:

• Systems become consistent over time
  

This is one of the biggest mindset shifts when building distributed systems.

Failure Handling in Sagas

Failures are normal in distributed systems.

Networks fail.

Services go down.

Messages arrive late.

Saga patterns are designed with this reality in mind.

Retry Strategies

Retries are commonly used before compensation.

Policy
    .Handle<Exception>()
    .RetryAsync(3);

Libraries like Polly help implement resilience.

This connects naturally to upcoming reliability topics in the series.

Idempotency Matters

Messages may be delivered more than once.

Your handlers must safely handle duplicate processing.

Example:

if (order.Status == "Processed")
{
    return;
}

Without idempotency, duplicate events can create serious issues.

Real-World Example: E-Commerce Checkout

A checkout workflow may involve:

• Orders service

• Inventory service

• Payments service

• Shipping service
  

If shipping fails after payment succeeds:

• Refund payment

• Release inventory

• Cancel order

The Saga coordinates recovery automatically.

Sagas and Modular Monoliths

Saga patterns are not only for microservices.

They also work well inside modular monoliths.

Modules can:

• Publish events internally

• Coordinate workflows

• Remain loosely coupled

This creates clean internal architecture.

Monitoring and Observability