Implementing a Facade Pattern in a Layered .NET Architecture

A well-designed .NET application separates responsibilities across presentation, application, domain and infrastructure layers. That separation improves maintainability, yet it can leave controllers, background workers and user interface code with too many details to coordinate. A single request may need validation, pricing, inventory, payment, notifications and persistence, creating a wide dependency surface.

The Facade pattern provides a focused entry point to that workflow. In a layered architecture, a facade hides subsystem complexity behind an application-oriented interface while preserving the boundaries between layers. Used carefully, it makes business operations easier to call, test and evolve without turning the facade into an oversized service class.

Where a facade fits in a layered design

A facade generally belongs in the application layer. Its role is to coordinate use cases rather than define core business rules or communicate directly with a database. A web API controller can call PlaceOrderAsync, for example, without knowing which repositories, domain services or external gateways are involved.

A typical request travels through several boundaries:

• The presentation layer receives HTTP, messaging or user-interface input.
• The application layer validates the request and orchestrates a use case.
• The domain layer enforces business rules and changes domain state.
• The infrastructure layer persists data and calls external systems.

The facade is useful at the application boundary because it presents a cohesive API to the presentation layer. It should not become a shortcut around the domain model. If a controller starts creating entities, calculating discounts and issuing payment calls itself, the architecture has already lost a valuable separation of concerns.

A facade differs from a simple wrapper because it coordinates several operations or simplifies a complicated subsystem. It may use commands, queries, repositories and domain services internally, while exposing a smaller contract such as SubmitOrderAsync. The caller sees the business capability rather than the machinery required to deliver it.

Designing a clear application contract

Start with the use case, not with the classes already present in the solution. “Create an order” or “Generate an invoice” is a stronger facade boundary than “call five services”. The contract should describe an outcome meaningful to the client and should avoid leaking infrastructure types such as Entity Framework entities, database transactions or SDK response objects.

For example, a request and result can be defined as immutable records:

public sealed record PlaceOrderRequest(
    Guid CustomerId,
    IReadOnlyCollection<OrderLineRequest> Lines,
    string PaymentToken);

public sealed record OrderLineRequest(
    Guid ProductId,
    int Quantity);

public sealed record PlaceOrderResult(
    Guid OrderId,
    decimal Total,
    string Status);

The interface expresses the application capability:

public interface IOrderFacade
{
    Task<PlaceOrderResult> PlaceOrderAsync(
        PlaceOrderRequest request,
        CancellationToken cancellationToken = default);
}

This contract should remain stable when the implementation changes from SQL Server to another store, or from one payment provider to another. It also gives API controllers a narrow dependency. A controller can translate HTTP concerns into the request object and translate the result into an HTTP response without learning how order placement works.

Validation needs a deliberate location. Basic shape checks, such as a positive quantity or a required customer identifier, can occur at the API boundary or through a validation pipeline. Rules that depend on business state, such as whether a product may be sold or whether a customer can exceed a credit limit, belong in the domain or application workflow. Keeping those categories distinct prevents the facade from becoming a collection of unrelated if statements.

Building the orchestration service in C#

A practical implementation injects abstractions for the operations it coordinates. The facade may load product information, create an order aggregate, request payment authorisation, save the result and publish an event. Each dependency should have a focused responsibility and should be represented by an interface owned by the appropriate layer.

public sealed class OrderFacade : IOrderFacade
{
    private readonly IProductReader _products;
    private readonly IOrderRepository _orders;
    private readonly IPaymentGateway _payments;
    private readonly IUnitOfWork _unitOfWork;

    public OrderFacade(
        IProductReader products,
        IOrderRepository orders,
        IPaymentGateway payments,
        IUnitOfWork unitOfWork)
    {
        _products = products;
        _orders = orders;
        _payments = payments;
        _unitOfWork = unitOfWork;
    }

    public async Task<PlaceOrderResult> PlaceOrderAsync(
        PlaceOrderRequest request,
        CancellationToken cancellationToken = default)
    {
        var productIds = request.Lines.Select(line => line.ProductId).ToArray();
        var products = await _products.GetAvailableAsync(
            productIds, cancellationToken);

        var order = Order.Create(
            request.CustomerId,
            request.Lines,
            products);

        var payment = await _payments.AuthoriseAsync(
            request.PaymentToken,
            order.Total,
            cancellationToken);

        order.MarkPaymentAuthorised(payment.TransactionId);

        await _orders.AddAsync(order, cancellationToken);
        await _unitOfWork.SaveChangesAsync(cancellationToken);

        return new PlaceOrderResult(
            order.Id,
            order.Total,
            order.Status.ToString());
    }
}

The example keeps orchestration visible, but the domain aggregate still owns important decisions. Order.Create can reject unavailable products, invalid quantities or pricing inconsistencies. The payment gateway remains an infrastructure concern behind IPaymentGateway, and the facade does not depend on a concrete vendor SDK.

Transactions require particular care. A local database transaction cannot automatically roll back a successful payment authorisation. For workflows that cross system boundaries, a reliable design may use payment holds, compensating actions, an outbox record and asynchronous processing. The facade can initiate that workflow, while a message handler completes later steps. Making the boundary explicit is safer than pretending every external operation is part of one ACID transaction.

Registering dependencies and testing behaviour

Dependency injection in ASP.NET Core keeps the facade easy to replace and test. A typical registration uses scoped lifetime when the facade depends on a scoped database context or unit of work:

services.AddScoped<IOrderFacade, OrderFacade>();
services.AddScoped<IOrderRepository, OrderRepository>();
services.AddScoped<IProductReader, ProductReader>();
services.AddScoped<IPaymentGateway, PaymentGateway>();

The controller then has one application dependency:

[ApiController]
[Route("api/orders")]
public sealed class OrdersController : ControllerBase
{
    [HttpPost]
    public async Task<ActionResult<PlaceOrderResult>> Post(
        PlaceOrderRequest request,
        IOrderFacade facade,
        CancellationToken cancellationToken)
    {
        var result = await facade.PlaceOrderAsync(
            request, cancellationToken);

        return CreatedAtAction(
            nameof(Get),
            new { id = result.OrderId },
            result);
    }

    [HttpGet("{id:guid}")]
    public IActionResult Get(Guid id) => Ok();
}

In production code, injecting the facade through the constructor is generally preferable to method injection, because the controller’s dependency is visible in its type definition. The abbreviated example keeps the focus on the boundary. Exception handling, validation responses and authorisation should be implemented through established ASP.NET Core middleware or filters rather than repeated in every action.

Unit tests for the facade should verify collaboration and business outcomes. Tests can use fakes or mocks for the product reader, payment gateway and repository, then check that an invalid product prevents payment, a declined payment does not save an order, and a successful operation returns the expected identifier. Integration tests should cover the real dependency-injection graph, database transaction behaviour and message publishing.

A facade that requires a dozen mocks to test is often signalling excessive responsibility. Split independent workflows into separate application services or facades rather than creating one “system facade” for every feature. A useful boundary reduces cognitive load; it should not simply relocate complexity into a class with a more attractive name.

Comparing related architectural choices

The Facade pattern is sometimes confused with an adapter, mediator or gateway. An adapter changes one interface into another, such as converting a payment provider’s response into an application abstraction. A facade simplifies and coordinates several interfaces. A mediator routes a request to a handler, while a facade usually exposes a capability that may coordinate multiple handlers or services.

A command handler can serve as the implementation behind a facade, particularly in a CQRS design. The distinction is primarily about the public boundary. A public application facade can accept a request, apply cross-cutting policies and dispatch a command, while the handler owns the command’s execution. There is no requirement to use every pattern together; the best choice depends on workflow size and team conventions.

Australian organisations often need this clarity when applications run across Sydney, Melbourne or Australian Azure regions while integrating with local payment, logistics and identity providers. Teams may also need to consider the Privacy Act 1988 and the Australian Privacy Principles when customer information passes through application services or third-party systems. A facade can centralise consent checks, audit events and data-minimisation rules, although compliance responsibility still belongs across the system.

The local software market also commonly includes distributed teams and customers using mobile networks or the NBN from varied locations. Explicit cancellation tokens, timeouts, idempotency keys and asynchronous workflows help when a request is retried after a temporary connection failure. For an Australian business processing customer records, keeping sensitive payloads in an appropriate Australian region may support governance expectations, but region selection alone does not satisfy privacy obligations.

Operating the facade in a production system

A production-ready facade should make operational behaviour observable. Include a correlation identifier in logs, record workflow status transitions and emit metrics for duration, failure type and downstream dependency latency. Avoid logging payment tokens, identity documents or other sensitive customer data. Structured logging makes it easier to trace a request from an API in Sydney to a database, queue or external provider without exposing private values.

Idempotency is essential for workflows initiated by a browser, mobile application or unreliable network. If a client retries after a timeout, the facade should recognise an idempotency key and return the original result rather than creating a second order or charging a card twice. The key and resulting status can be stored with the application transaction, while a durable outbox can ensure that follow-up events are published after the database commit.

Security belongs at every boundary. Authenticate and authorise the caller at the API layer, then enforce ownership and business permissions inside the application workflow. A facade should never trust a customer identifier supplied by an unauthorised client merely because the request passed schema validation. Configuration for payment credentials and connection strings should come from a managed secret store, with access restricted by workload identity.

A layered .NET architecture benefits when the facade remains a small, stable entry point and the underlying services retain clear ownership of rules. The result is easier controller code, narrower tests and a safer path for replacing infrastructure. When the application grows, this boundary can support synchronous APIs, background jobs and message consumers without forcing each entry point to understand every detail of the business workflow.